Deep Research MCP

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

安装

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

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

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

项目目录说明

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：

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

通用 MCP 客户端配置示例：

{
  "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. 项目整体调用关系

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`

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/`

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/`

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`

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

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

一次完整使用顺序

调用 create_report_plan(topic, options?)，保存返回的 report_id。
编辑返回的完整 sections，调用 update_report_outline(..., confirm=true)。
调用 generate_report(report_id)；它只负责入队，会立即返回。
定期调用 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；其他系统使用用户本地数据目录。

验证

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

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