# deepferry

**Repository Path**: nbcyf/deepferry

## Basic Information

- **Project Name**: deepferry
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-06
- **Last Updated**: 2026-08-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# deepferry

> 🚧 MVP 开发中 — 完整计划见 [openspec/project.md](openspec/project.md)。
>
> [English](README.md) | 简体中文

**deepferry** 让任意 LLM Agent 通过统一的 MCP 协议查询 MySQL、PostgreSQL 和 HTTP API（包括需要两步认证的 API），并在桌面表格应用中浏览结果。

> **ferry** = 在异构数据源之间摆渡数据。主动运输，而非静态桥梁。

## 为什么选择 deepferry？

你可以直接用 Python 脚本查询 MySQL、PostgreSQL 和 HTTP API——那为什么还要加一层 MCP 协议？因为**「能查到」和「能安全地开放给任意 Agent 查」是完全不同的两件事**。

| 裸 Python 给你的 | deepferry MCP 协议层额外提供的 |
|---|---|
| 5 行 traceback 错误 | 结构化 `{code, message, suggestion}` 错误，Agent 可编程处理 |
| 完整的文件系统访问（Agent 能读密码、改写配置） | 工具级权限边界——Agent 只能调用白名单操作 |
| 没有审计痕迹 | 每次查询自动记录 trace_id、scenario_id、session_id、agent_name |
| Agent 自己管理凭证、令牌 TTL、刷新循环 | 两步认证的生命周期完全封装——Agent 永远接触不到密码 |
| 每个 Agent 都要单独适配 | 任意 MCP 客户端（Claude Desktop、Cursor、自定义）即连即用 |

**后端才是产品。** Tauri 桌面应用只是本地可视化浏览的一个消费方——后端同时通过 stdio 服务 Claude Desktop、通过 Streamable HTTP 服务远程 Agent、通过 Docker 服务团队。桌面模式假设可信本地用户；服务端模式对不可信远程 Agent 强制执行 Admin 专属的数据源治理。

→ 完整论证见 [openspec/project.md](openspec/project.md) § 设计哲学，六层对比详见 [openspec/specs/mcp-server.md](openspec/specs/mcp-server.md) § MCP 协议层 vs 裸 Python。

## 快速开始

```bash
# 1. 克隆并初始化
git clone https://github.com/caiyfa/deepferry.git
cd deepferry
./setup.sh

# 2. 启动（任选一种）
make docker-up        # Docker：MySQL + PostgreSQL + MCP 服务器 + 前端
make dev              # 或：一键开发启动器（自动打开浏览器）
```

就这么简单。执行 `./setup.sh` 后，你的 AI Agent 就可以连接 deepferry——参见下方 [连接你的 Agent](#连接你的-ai-agent)。

### 环境要求

| 工具 | 用途 | 安装方式 |
|------|------|----------|
| Python 3.12+ | 本地开发、MCP 服务器 | `brew install python@3.12` 或 [python.org](https://python.org) |
| [uv](https://docs.astral.sh/uv/) | Python 依赖管理（推荐） | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
| Docker | 容器化部署（推荐快速开始） | [Docker Desktop](https://docker.com) |
| npm | 仅前端开发需要 | `brew install node` 或 [nodejs.org](https://nodejs.org) |

> **没有 Docker？** 你仍然可以用 `uv` 本地运行——参见下方 [本地开发](#本地开发)。

### 方式一：Docker（推荐）

一条命令，开箱即用——包含 MySQL、PostgreSQL、MCP 服务器和前端：

```bash
docker compose --profile full up -d --wait
```

启动内容包括：
- **后端 API**: http://localhost:8000（健康检查：`/health`）
- **前端 UI**: http://localhost:5173（React 数据浏览器）
- **MySQL**: `localhost:3306`（用户：`root`，密码：`testpass`）
- **PostgreSQL**: `localhost:5432`（用户：`postgres`，密码：`testpass`）

停止所有服务：

```bash
docker compose --profile full down
```

### 方式二：本地开发

```bash
# 安装依赖（首次运行）
./setup.sh

# 启动 MCP 服务器（stdio 模式——用于 AI Agent 集成）
uv run deepferry mcp-server --config config.toml

# 或 HTTP 传输（用于 API 访问）
uv run deepferry mcp-server --transport http --config config.toml
```

### 方式三：`dev.sh` 启动器

全栈开发，前端热更新：

```bash
./dev.sh            # 启动全部服务，打开浏览器
./dev.sh --rebuild  # 强制重新构建 Docker 镜像后再启动
```

需要 Docker + npm。Ctrl+C 停止前端；Docker 服务保持运行。

## 连接你的 AI Agent

deepferry 使用 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 协议。任何兼容 MCP 的客户端都可以连接。

### 自动配置（setup.sh）

```bash
./setup.sh
```

初始化脚本会自动检测你的 MCP 客户端（Claude Desktop、Cursor）并写入正确的配置。如果自动检测失败，会生成 `claude_desktop_config.json` —— 复制到你客户端的配置目录即可。

### 手动配置

**Claude Desktop** — 添加到 `claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "deepferry": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/deepferry", "deepferry", "mcp-server", "--config", "/path/to/deepferry/config.toml"]
    }
  }
}
```

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%/Claude/claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

**Cursor** — 添加到 `~/.cursor/mcp.json`（格式同上）。

配置后重启客户端。

## 命令一览

```bash
make help         # 显示所有命令
make docker-up    # 启动完整 Docker 栈
make docker-down  # 停止 Docker 栈
make dev          # 开发启动器（Docker 后端 + Vite 前端）
make test         # 运行测试套件
make lint         # Lint + 类型检查
make clean        # 清除构建产物
```

完整目标见 [Makefile](Makefile)。

## 技术栈

Python 3.12 · MCP · FastAPI · asyncmy/asyncpg · SQLAlchemy · DuckDB · httpx2 · Tauri 2.x · React · AG Grid · uv · ruff

## 项目进度

| 里程碑 | 时间线 | 状态 |
|--------|--------|------|
| M1: MCP + MySQL + PostgreSQL | Week 1-5 | ✅ 已完成 |
| M2: HTTP API + 两步认证 | Week 6-9 | ✅ 已完成 |
| M2.5: 编排引擎 + 审计 + 安全防护 | — | ✅ 已完成 |
| M3: 桌面应用 | Week 10-14 | 🟡 进行中（前端已构建，Tauri 打包待完成） |
| M4: DuckDB JOIN + 生产加固 | Week 15-18 | 🟡 部分完成（引擎已存在，联邦查询加固待完成） |

## 文档

- [项目概览](openspec/project.md) — 核心理念、架构、技术栈
- [能力 Spec](openspec/specs/) — 各模块详细规格
- [MVP 变更方案](openspec/changes/mvp-init/proposal.md) — 我们在构建什么、为什么
- [技术设计](openspec/changes/mvp-init/design.md) — 架构决策
- [实现任务](openspec/changes/mvp-init/tasks.md) — 按里程碑分解的任务

## 许可证

MIT