使用说明（简明总览）

• 项目简介

  • 该仓库实现了一个基于 MCP 的研究服务器，核心是 Deep Research Agent，支持通过不同后端提供商执行长时间的研究任务，提供澄清流程、任务状态查询，以及通过 MCP 的工具接口暴露研究能力给外部 MCP 客户端使用。

• 主要功能点

  • 提供 MCP 工具：deep_research、research_status、research_with_context，遵循 MCP JSON‑RPC 风格与协议实现语义。
  • 支持多后端提供商：OpenAI（Responses API、Chat Completions API）与 Open Deep Research，且具备澄清工作流（clarification）。
  • 任务管理：对长时间任务进行轮询、状态查询、超时处理和回调支持。
  • 传输模式：stdio（默认）和 HTTP 流式传输，HTTP 支持通过 FastMCP 实现的流式通信。
  • 配置与 rebellion：通过 ~/.deep_research 配置文件和环境变量完成模型、超时、澄清相关设置的管理。
  • 提示和指令模板：通过提示管理系统（PromptManager）加载和格式化 YAML/资源中的提示模板。

• 安装步骤

  • 获取代码：克隆仓库并进入项目目录。
  • 安装依赖：使用 Python 环境安装依赖（例如 pip install -r requirements.txt）。
  • 配置环境：设置 OPENAI API Key、RESEARCH_PROVIDER、RESEARCH_MODEL、RESEARCH_BASE_URL 等环境变量，或通过 ~/.deep_research TOML 配置文件填写。
  • 启动服务器：
    • stdio 模式（默认，直接在本地作为子进程运行）：
      • python src/deep_research_mcp/mcp_server.py
    • HTTP 流式传输模式（对接 MCP 客户端的 HTTP 连接）：
      • python src/deep_research_mcp/mcp_server.py --transport http --host 127.0.0.1 --port 8080
  • 参考 Claude Code、Codex、Gemini 等客户端的集成说明将服务器注册为 MCP 服务端。

• 服务器配置（JSON，MCP 客户端需要） { "server_name": "deep-research-mcp", "command": "python", "args": ["/path/to/deep_research_mcp/src/deep_research_mcp/mcp_server.py"], "transport": "stdio" // 也可以使用 "http" 并在需要时提供 host/port 信息 }

  配置字段说明（简要注释，便于理解）

  • server_name: MCP 客户端显示的服务器名称，建议与仓库实际用途一致。
  • command: 启动服务器所使用的命令，此处为 Python。
  • args: 启动脚本的路径，指向 mcp_server.py 的实际位置。
  • transport: 传输模式，stdio 适用于本地编辑器/CLI，http 适用于远程/网络环境的流式传输。

• 基本使用方法

  • 启动后，客户端通过 MCP 调用工具 deep_research 来执行研究任务，结果包括最终报告、引用、以及研究元数据。
  • 如需澄清工作流，客户端可调用 research_with_context，并在会话中提供用户的回答以生成经过扩展的查询。
  • 对于长时间任务，可以通过 research_status 轮询查看任务状态。

• 额外说明

  • 服务端的配置与默认行为描述、以及各类提示模板均在代码中定义，可按需调整。
  • 如需在生产环境中运行，请注意 API Key 的安全性、请求超时、以及错误处理与回调逻辑。