Deep-research

深度研究 MCP 服务

AI 驱动的研究助手。 使用 Google Gemini 2.5 Flash，结合 Google 搜索溯源和 URL 上下文，开展迭代式深度研究。无需依赖网页抓取。

---

目录

• 功能
• 为什么构建此项目
• 工作流图
• 角色 Agent
• 工作原理
• 项目结构
• 要求
• 设置
• 用法
  • 作为 MCP 工具
  • 独立 CLI 用法
  • MCP Inspector 测试
• 配置
• 快速开始
• 示例输出
• 支持
• 参与贡献
• 路线图
• 许可证

本项目旨在提供一种最简单且最有效的深度研究 Agent 实现。它的设计便于理解、修改和扩展，目标是将代码库控制在 500 行代码（LoC）以内。

主要功能：

• MCP 集成： 作为模型上下文协议（MCP）服务/工具运行，实现与 Agent 的无缝集成。
• Gemini 2.5 Flash 流程： 通过环境变量标志启用长上下文推理、结构化 JSON 输出和工具调用（Google 搜索溯源、代码执行、函数）。
• 迭代式深入研究： 优化查询并分析结果，同时将习得的上下文传递到后续步骤。
• 深度与广度控制： 精确调整探索范围。
• 语义/递归拆分： 基于 Token 的分块，确保可靠的摘要和分析。
• 批处理 + 缓存： 对模型调用进行并发限制的批处理，并使用 LRU 缓存保存提示词和结果。
• 专业报告： 生成结构化 Markdown（摘要、目录、引言、正文、方法、局限性、关键收获、参考资料）。

为什么构建此项目

• 以 Gemini 为核心的现代流程： 基于 Gemini 2.5 Flash 构建，可选用工具（搜索溯源、代码执行、函数）。
• 精简、易懂的核心： 使用纯 TypeScript，便于审查和扩展。
• 确定性输出： 使用 Zod 验证 JSON，并采用一致的报告框架。
• 适用于 Agent： 提供简洁的 MCP 服务入口；可与 Inspector 和支持 MCP 的客户端配合使用。

工作流图

flowchart TB
    subgraph Input
        Q[User Query]
        B[Breadth Parameter]
        D[Depth Parameter]
    end

    DR[Deep Research] -->
    SQ[SERP Queries] -->
    PR[Process Results]

    subgraph Results[Results]
        direction TB
        NL((Learnings))
        ND((Directions))
    end

    PR --> NL
    PR --> ND

    DP{depth > 0?}

    RD["Next Direction:
    - Prior Goals
    - New Questions
    - Learnings"]

    MR[Markdown Report]

    %% Main Flow
    Q & B & D --> DR

    %% Results to Decision
    NL & ND --> DP

    %% Circular Flow
    DP -->|Yes| RD
    RD -->|New Context| DR

    %% Final Output
    DP -->|No| MR

    %% Styling
    classDef input fill:#7bed9f,stroke:#2ed573,color:black
    classDef process fill:#70a1ff,stroke:#1e90ff,color:black
    classDef recursive fill:#ffa502,stroke:#ff7f50,color:black
    classDef output fill:#ff4757,stroke:#ff6b81,color:black
    classDef results fill:#a8e6cf,stroke:#3b7a57,color:black

    class Q,B,D input
    class DR,SQ,PR process
    class DP,RD recursive
    class MR output
    class NL,ND results

Persona Agent

什么是 Persona Agent？

在 deep-research 中，我们利用“Persona Agent”这一概念来引导 Gemini 大模型的行为。我们不会只是向大模型输入一项任务，而是赋予它特定的角色、技能、个性、沟通风格和价值观。这种方法有助于：

• **聚焦大模型的输出：**通过定义清晰的 Persona，我们鼓励大模型生成符合预期专业知识和视角的回答。
• **提升一致性：**Persona 有助于在整个研究过程中保持一致的语气和风格。
• **提升特定任务的表现：**根据具体任务（例如生成查询、提取所学内容、提供反馈）定制 Persona，可优化大模型在研究各阶段的输出。

Persona 使用示例：

• **专家研究策略师与查询生成器：**用于生成搜索查询，此 Persona 注重策略性思维、全面覆盖和精准的查询表述。
• **专家研究助手与洞察提取器：**处理网页内容时，此 Persona 注重细致分析、事实准确性，以及提取与研究查询相关的关键收获。
• **专家研究查询优化师与策略顾问：**用于生成后续问题，此 Persona 体现策略性思维、对用户意图的理解，以及引导用户提出更清晰、更有效研究问题的能力。
• **专业博士级研究人员（系统提示词）：**这一总体 Persona 应用于主系统提示词，为整个研究流程定下基调，强调专家级分析、逻辑结构和深入调查。

借助 Persona Agent，deep-research 力求让 Gemini 大模型产出更有针对性、更一致且质量更高的研究成果。

工作原理

核心模块：

• src/deep-research.ts — 编排查询、批处理、分析和综合
  • generateSerpQueries() 使用 Gemini 根据你的提示词和先前的学习内容提出 SERP 风格的查询
  • processSerpResult() 拆分内容，启用工具批量调用 Gemini，并提取学习内容和引用
  • conductResearch() 对语义分块进行多轮分析
  • writeFinalReport() 构建最终的专业 Markdown 报告
• src/ai/providers.ts — 用于 Gemini 2.5 Flash 的 GoogleGenAI 封装，支持批处理、令牌控制和可选工具
• src/ai/text-splitter.ts — RecursiveCharacter 和 Semantic 分块器
• src/mcp-server.ts — MCP 服务入口和类型
• src/run.ts — CLI 入口

流程亮点：

• 使用 Zod 验证结构化 JSON 输出
• 限制并发的批处理（generateBatch、generateBatchWithTools）
• 为提示词、SERP 提案和报告提供 LRU 缓存
• 可通过标志启用 Gemini 工具：Google Search Grounding、Code Execution、Functions

项目结构

deep-research-mcp-server/
├─ src/
│  ├─ ai/
│  │  ├─ providers.ts           # Gemini wrapper, tools, batching, caching
│  │  └─ text-splitter.ts       # Semantic/recursive splitters
│  ├─ mcp-server.ts             # MCP server entry/types
│  ├─ deep-research.ts          # Orchestrator: queries → analysis → synthesis
│  ├─ prompt.ts                 # System + templates
│  ├─ feedback.ts               # Refinement/feedback loop
│  ├─ output-manager.ts         # Report/output formatting
│  ├─ progress-manager.ts       # CLI progress
│  ├─ terminal-utils.ts         # CLI helpers
│  ├─ types.ts                  # Zod schemas/types
│  └─ utils/                    # JSON/sanitize helpers
├─ dist/                        # Build output
├─ .env.example                 # Environment template
├─ package.json                 # Scripts/deps
└─ README.md

要求

• Node.js v22.x
• Google Gemini API 密钥

设置

Node.js

1. 克隆仓库：

   git clone [your-repo-link-here]
   

2. 安装依赖项：

   npm install
   

3. **设置环境变量：**在项目根目录创建 .env.local 文件：

   # Required
   GEMINI_API_KEY="your_gemini_key"
   
   # Recommended defaults
   GEMINI_MODEL=gemini-2.5-flash
   GEMINI_MAX_OUTPUT_TOKENS=65536
   CONCURRENCY_LIMIT=5
   
   # Gemini tools (enable as needed)
   ENABLE_GEMINI_GOOGLE_SEARCH=true
   ENABLE_GEMINI_CODE_EXECUTION=false
   ENABLE_GEMINI_FUNCTIONS=false
   

4. 构建项目：

   npm run build
   

用法

作为 MCP 工具

要将 deep-research 作为 MCP 工具运行，请启动 MCP 服务：

node --env-file .env.local dist/mcp-server.js

然后，你可以使用以下参数，通过任何兼容 MCP 的 Agent 调用 deep-research 工具：

• query（字符串，必填）：研究查询。
• depth（数字，可选，1-5）：研究深度（默认：中等）。
• breadth（数字，可选，1-5）：研究广度（默认：中等）。
• existingLearnings（字符串数组，可选）：用于指导研究的现有研究发现。

MCP 工具参数示例（JSON 结构）：

{
  "name": "deep-research",
  "arguments": {
    "query": "State of multi-agent research agents in 2025",
    "depth": 3,
    "breadth": 3,
    "existingLearnings": [
      "Tool use improves grounding",
      "Batching reduces latency"
    ]
  }
}

const mcp = new ModelContextProtocolClient(); // Assuming MCP client is initialized

async function invokeDeepResearchTool() {
  try {
    const result = await mcp.invoke("deep-research", {
      query: "Explain the principles of blockchain technology",
      depth: 2,
      breadth: 4
    });

    if (result.isError) {
      console.error("MCP Tool Error:", result.content[0].text);
    } else {
      console.log("Research Report:\n", result.content[0].text);
      console.log("Sources:\n", result.metadata.sources);
    }
  } catch (error) {
    console.error("MCP Invoke Error:", error);
  }
}

invokeDeepResearchTool();

独立 CLI 用法

要直接从命令行运行 deep-research：

npm run start "your research query"

示例：

npm run start "what are latest developments in ai research agents"

MCP Inspector 测试

如需交互式测试和调试 MCP 服务，请使用 MCP Inspector：

npx @modelcontextprotocol/inspector node --env-file .env.local dist/mcp-server.js

MCP 集成提示

• 环境：向 MCP 服务进程提供 GEMINI_API_KEY；通过环境变量传递模型和工具标志。
• 无状态调用：服务根据环境变量确定行为；确保标志与客户端配置保持一致。
• 延迟：启用批处理，并设置合理的 CONCURRENCY_LIMIT，以平衡速度和速率限制。

配置

• GEMINI_API_KEY — 必填
• GEMINI_MODEL — 默认值为 gemini-2.5-flash
• GEMINI_MAX_OUTPUT_TOKENS — 默认值为 65536
• CONCURRENCY_LIMIT — 默认值为 5
• ENABLE_GEMINI_GOOGLE_SEARCH — 启用 Google Search Grounding 工具
• ENABLE_GEMINI_CODE_EXECUTION — 启用代码执行工具
• ENABLE_GEMINI_FUNCTIONS — 启用函数调用

可选提供商（计划中／由标志控制）：后续可集成 Exa/Tavily；当前工作流无需 Firecrawl。

快速入门

1. 克隆并安装

git clone https://github.com/ssdeanx/deep-research-mcp-server
cd deep-research-mcp-server
npm i && npm run build

2. 创建 .env.local（参见设置）

3. 作为 MCP 服务运行（Inspector）

npx @modelcontextprotocol/inspector node --env-file .env.local dist/mcp-server.js

4. 或作为 CLI 运行

npm run start "state of multi-agent research agents in 2025"

输出示例

# Abstract
Concise overview of the research goal, scope, method, and key findings.

# Table of Contents
...

# Introduction
Context and framing.

# Body
Evidence-backed sections with citations.

# Methodology
How sources were found and analyzed.

# Limitations
Assumptions and risks.

# Key Learnings
Bulleted insights and takeaways.

# References
Normalized citations to visited URLs.

支持

• 问题： 使用 GitHub Issues 报告错误和功能请求。
• 讨论： 提出想法或提问。
• 安全： 请勿公开提交涉及敏感信息的问题；请私下联系维护者。

贡献

• 欢迎提交 PR： 对于重大更改，请先创建 issue。
• 标准： TypeScript 5.x、Node.js 22.x；提交 PR 前运行 lint 和类型检查。
• 检查： npm run build 和 tsc --noEmit 必须通过。
• 文档： 更改环境变量／配置时，请更新 README.md 和 .env.example。

路线图

• 集成 Exa 搜索（由 ENABLE_EXA_PRIMARY 控制），使用 Google grounding 进行增强。
• 清理提供商： Exa 迁移完成后移除 Firecrawl（需要明确批准）。
• CI/CD： 添加用于构建、lint、测试的 GitHub Actions 和徽章。
• 示例： 添加示例报告和提示词。

故障排除

• 缺少 API 密钥：确保在 .env.local 中设置了 GEMINI_API_KEY，并使用 --env-file .env.local 启动进程。
• 模型／工具标志：如果 grounding 或函数未启用，请检查 ENABLE_GEMINI_GOOGLE_SEARCH、ENABLE_GEMINI_CODE_EXECUTION 和 ENABLE_GEMINI_FUNCTIONS。
• 速率限制／延迟：降低 CONCURRENCY_LIMIT（例如设为 3），或减少同时运行的查询数量后重试。
• 输出过长：降低深度／广度，或调低 GEMINI_MAX_OUTPUT_TOKENS。
• 架构解析错误：重新运行；工作流会验证并修复 JSON，但过于极端的提示词可能超出预算——请精简提示词或减小分块大小。

许可证

MIT License - 免费且开源，可自由使用！

---

🚀 深入探索研究吧！🚀

近期改进（v0.3.0）

✨ 最新变更亮点。另请参阅路线图。

🧪 增强研究验证

• ✅ 输入验证：至少 10 个字符 + 3 个单词
• 📈 输出验证：引用密度（每 100 个单词至少 1.5 条引用）
• 🔍 检查近期来源（至少 3 条 2019 年之后的参考资料）
• ⚖️ 强制披露利益冲突

🧠 Gemini 集成升级

• 统一使用 Gemini 2.5 Flash（长上下文、结构化 JSON）
• 通过环境变量标志启用可选工具：Search Grounding、Code Execution、Functions
• 使用语义与递归拆分来管理上下文
• 通过并发控制和缓存实现稳健的批处理
• 通过语义搜索增强上下文管理
• 改进错误处理和日志记录

🧹 代码质量改进

• 🚀 添加并发处理流水线
• 移除冗余的 academic-validators 模块
• 🛡️ 增强各接口的类型安全性
• 📦 优化依赖项（node_modules 缩小约 30%）

🆕 新功能

• 📊 研究指标跟踪（来源／学习成果比）

* 📑 自动生成利益冲突披露声明 * 🔄 递归研究深度控制（1-5 级） * 📈 研究指标跟踪（来源／学习成果比） * 🤖 改进 MCP 工具集成

性能：

• 🚀 研究周期提速 30%
• ⚡ 初始研究周期提速 40%
• 📉 API 错误减少 60%
• 🧮 Token 使用效率提高 25%