# Deep Research MCP

这是一个本机运行的通用 MCP Server：先生成并审阅报告大纲，再把完整报告放入后台队列生成。任务状态保存在 SQLite 中，章节完成后会建立检查点，MCP 进程重启后可以继续未完成任务。

## 安装

需要 Python 3.11–3.13。建议在虚拟环境中安装：

```powershell
py -m venv .venv
.venv\Scripts\python -m pip install -e ".[test,ui]"
```

复制 `.env.example` 为 `.env`，至少设置 `DEEPSEEK_API_KEY`。`TAVILY_API_KEY` 可选；未设置时默认的 `baidu_tavily` 策略会降级为仅使用百度。

## 项目目录说明

```text
Deep Research/
├─ mcp_server.py                 # MCP 接口层：四个工具和 stdio 入口
├─ app.py                        # Web 界面层：可选 Streamlit 入口
├─ service/                      # 任务与持久化层
│  ├─ report_service.py          # 状态机、后台队列和报告生命周期
│  └─ report_store.py            # SQLite、章节检查点和任务恢复
├─ research/                     # 研究执行层
│  ├─ engine.py                  # 大纲、逐章研究和汇总编排
│  ├─ nodes.py                   # 模型、搜索、写作和引用节点
│  ├─ prompts.py                 # 大模型提示词
│  ├─ models.py                  # 章节、查询和报告状态模型
│  └─ utils.py                   # 搜索提供商与来源处理函数
├─ tests/                        # 自动化测试
├─ reports/                      # 本地报告产物（不会提交到 Git）
├─ configuration.py             # 环境变量及默认运行配置
├─ pyproject.toml                # Python 打包、依赖和命令入口
├─ requirements.txt              # 传统依赖清单
└─ .env.example                 # 环境变量模板
```

根目录只保留两个用户入口和公共配置。研究过程放在 `research`，长任务运行及恢复放在 `service`，避免为单个业务文件额外创建目录。

## 启动与客户端配置

安装后可直接启动 stdio Server：

```powershell
.venv\Scripts\deep-research-mcp.exe
```

通用 MCP 客户端配置示例：

```json
{
  "mcpServers": {
    "deep-research": {
      "command": "D:\\Deep Research\\.venv\\Scripts\\deep-research-mcp.exe",
      "env": {
        "DEEPSEEK_API_KEY": "由客户端安全注入",
        "TAVILY_API_KEY": "可选",
        "DEEP_RESEARCH_DATA_DIR": "D:\\Deep Research Data"
      }
    }
  }
}
```

不要把真实密钥提交到配置仓库。也可以在启动 MCP 客户端前通过系统环境变量提供密钥。

## 使用流程

下面按照项目目录的职责分别展示流程。先看整体关系，再按需查看各模块内部细节。

### 1. 项目整体调用关系

```mermaid
flowchart LR
    U[用户或 AI 客户端] --> E[入口层<br/>mcp_server.py / app.py]
    E --> S[任务层<br/>service/]
    S --> R[研究层<br/>research/]
    S <--> D[(SQLite)]
    R --> X[模型与搜索服务]
    S --> O[Markdown 报告]
```

入口层接收操作，`service/` 管理任务，`research/` 执行调研，最后由任务层保存状态和报告。

### 2. MCP 接口层：`mcp_server.py`

```mermaid
flowchart LR
    C[MCP 客户端] --> P[create_report_plan<br/>创建大纲]
    P --> U[update_report_outline<br/>修改并确认]
    U --> G[generate_report<br/>加入后台队列]
    G --> Q[get_report<br/>查询进度和结果]
    Q -. 未完成时继续查询 .-> Q
```

这一层只定义工具和参数，不执行具体搜索，也不直接操作数据库。四个工具最终都交给 `ReportService` 处理。

### 3. 任务与持久化层：`service/`

```mermaid
flowchart LR
    A[ReportService<br/>校验请求] --> B[后台任务队列]
    B --> C[逐章调用研究引擎]
    C --> D[ReportStore<br/>保存章节检查点]
    D --> E{全部完成?}
    E -->|否| C
    E -->|是| F[保存 Markdown<br/>状态 completed]
    C -. 失败 .-> G[状态 failed<br/>允许重试]
```

- `report_service.py` 管理状态机、后台队列、重试和报告输出。
- `report_store.py` 管理 SQLite；每章完成后保存一次，进程重启时可恢复未完成任务。

### 4. 研究执行层：`research/`

```mermaid
flowchart LR
    A[engine.py<br/>选择当前章节] --> B{需要研究?}
    B -->|是| C[nodes.py<br/>生成查询并搜索]
    B -->|否| D[nodes.py<br/>直接写作]
    C --> E[nodes.py<br/>撰写章节]
    D --> F[返回章节内容]
    E --> F
    F --> G[汇总章节<br/>处理引用]
```

- `engine.py` 决定节点执行顺序，一次只推进一个章节。
- `nodes.py` 调用模型完成大纲、查询、搜索、写作和引用处理。
- `prompts.py` 提供提示词，`models.py` 定义状态结构，`utils.py` 提供搜索及来源处理能力。

### 5. Web 界面层：`app.py`

```mermaid
flowchart LR
    A[输入研究主题] --> B[编辑并确认大纲]
    B --> C[启动后台生成]
    C --> D[刷新任务进度]
    D --> E[查看或下载报告]
```

Streamlit 和 MCP 是两个不同入口，但都会调用同一个 `ReportService`，因此共用任务状态、SQLite 和研究流程。

### 一次完整使用顺序

1. 调用 `create_report_plan(topic, options?)`，保存返回的 `report_id`。
2. 编辑返回的完整 `sections`，调用 `update_report_outline(..., confirm=true)`。
3. 调用 `generate_report(report_id)`；它只负责入队，会立即返回。
4. 定期调用 `get_report(report_id)` 查看进度。完成后使用 `include_content=true` 取得 Markdown，或读取 `output_path`。

`research=false` 的章节不会执行网络搜索。重复调用 `generate_report` 不会创建重复任务。失败任务在已有大纲的情况下可再次调用该工具重试，并从最后一个成功保存的章节继续。

### 可覆盖配置

`options` 只接受以下非敏感字段：

- `number_of_queries`
- `planner_provider` / `planner_model`
- `writer_provider` / `writer_model`
- `search_api` / `search_api_config`
- `max_tokens`

API Key 不属于工具参数，只能通过环境变量提供。

## 数据位置

设置 `DEEP_RESEARCH_DATA_DIR` 可以指定数据根目录。目录中包含：

- `reports.sqlite3`：任务、大纲、章节检查点、来源和错误状态；
- `reports/<report_id>/*.md`：完成后的 Markdown 报告。

默认路径为 Windows 的 `%LOCALAPPDATA%\deep-research-mcp`；其他系统使用用户本地数据目录。

## 验证

```powershell
.venv\Scripts\python -m pytest
.venv\Scripts\python -m mcp dev mcp_server.py
```

第二条命令启动 MCP Inspector，用于确认四个工具及其 JSON Schema。