使用说明

深度研究MCP服务器

你的人工智能研究助理。 使用Google Gemini 2.5 Flash结合Google搜索基础和URL上下文进行迭代式深入研究。不需要网络抓取依赖关系。

MCP集成： 作为模型上下文协议（MCP）服务器/工具运行，实现无缝代理集成。
Gemini 2.5闪蒸管道： 通过环境标志进行长上下文推理、结构化JSON输出和工具使用（谷歌搜索基础、代码执行、函数）。
迭代式深度潜水： 查询细化+带学习上下文的结果分析。
深度和宽度控制： 精确调整勘探范围。
语义/递归拆分： 令牌感知分块，用于健壮的摘要和分析。
批处理+缓存： 跨提示/结果使用LRU缓存进行并发限制的批处理模型调用。
专业报告： 生成结构化Markdown（摘要、ToC、引言、正文、方法论、局限性、关键学习、参考文献）。

为什么这个项目

双子座第一，现代流水线： 围绕Gemini 2.5 Flash构建，带有可选工具（搜索基础、代码执行、函数）。
最小、可理解的核心： 纯TypeScript；易于审计和扩展。
确定性输出： Zod验证了JSON和一致的报告框架。
代理就绪： 清理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代理

什么是Persona代理？

在……里面 deep-research，我们利用“角色代理”的概念来指导Gemini语言模型的行为。我们不是简单地给法学硕士一个任务，而是给它灌输一个具体的 角色、技能、个性、沟通风格和价值观。 这种方法有助于：

关注法学硕士的成果： 通过定义一个明确的角色，我们鼓励法学硕士产生与所需专业知识和观点相一致的回应。
提高一致性： 人物角色有助于在整个研究过程中保持一致的语气和风格。
提高任务特定绩效： 根据特定任务（如查询生成、学习提取、反馈）定制角色，优化LLM在该研究阶段的输出。

正在使用的角色示例：

专家研究策略师和查询生成器： 该角色用于生成搜索查询，强调策略思维、全面覆盖和查询公式的精确性。
专家研究助理和洞察提取器： 在处理网页内容时，这个角色专注于细致的分析、事实的准确性，并提取与研究查询相关的关键学习。
专家研究查询精炼师和战略顾问： 为了生成后续问题，这个角色体现了战略思维、用户意图理解以及引导用户提出更清晰、更有效的研究问题的能力。
专业博士级研究员（系统提示）： 这个应用于主系统提示的总体角色为整个研究过程定下了基调，强调专家级分析、逻辑结构和深入调查。

通过利用角色代理， 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 --递归特征与语义分裂
src/mcp-server.ts --MCP服务器入口点和类型
src/run.ts --CLI入口点

管道亮点：

使用Zod验证结构化JSON输出
并发限制批处理(generateBatch, generateBatchWithTools)
LRU缓存提示、SERP建议和报告
通过标志选择Gemini工具：谷歌搜索接地、代码执行、函数

项目结构

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

克隆存储库：
```
git clone [your-repo-link-here]
```
安装依赖项：
```
npm install
```

设置环境变量： 创建一个 .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

构建项目：
```
npm run build
```

用法

作为MCP工具

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

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

然后，您可以调用 deep-research 使用以下参数从任何MCP兼容代理中获取工具：

query （string，必填）：研究查询。
depth （数字，可选，1-5）：研究深度（默认值：中等）。
breadth （数字，可选，1-5）：研究广度（默认值：中等）。
existingLearnings （string[]，可选）：指导研究的现有研究成果。

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检验员测试

对于MCP服务器的交互式测试和调试，请使用MCP检查器：

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

MCP集成提示

环境：提供 GEMINI_API_KEY 发送到MCP服务器进程；通过env显示模型和工具标志。
无状态呼叫：服务器从env派生行为；使标志与您的客户资料保持同步。
延迟：实现批处理和合理 CONCURRENCY_LIMIT 平衡速度与速率限制。

配置

GEMINI_API_KEY --必填项
GEMINI_MODEL --默认为 gemini-2.5-flash
GEMINI_MAX_OUTPUT_TOKENS --默认为 65536
CONCURRENCY_LIMIT --默认为 5
ENABLE_GEMINI_GOOGLE_SEARCH --启用Google搜索限制工具
ENABLE_GEMINI_CODE_EXECUTION --启用代码执行工具
ENABLE_GEMINI_FUNCTIONS --启用函数调用

可选提供者（计划/幕后）：Exa/Tavily稍后可以集成；当前管道不需要防火墙。

快速启动

克隆并安装

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

创建 .env.local （参见设置)
以MCP服务器（检查器）运行

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

或作为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处理bug和功能请求。
讨论： 提出想法或提问。
安全： 不要将敏感信息公开；私下联系维护人员。

贡献

PR欢迎： 请先打开一个问题以进行重大更改。
标准： TypeScript 5.x，Node.js 22.x，PR前的lint/type检查。
检查： npm run build 和 tsc --noEmit 必须通过。
文件： 更新 README.md 和 .env.example 更改env/config时。

路线图

Exa搜索集成 （后面 ENABLE_EXA_PRIMARY)，谷歌为增强而停飞。
提供程序清理： Exa迁移后删除Firecrawl（需要明确批准）。
CI/CD： 为build/lint/test和badge添加GitHub操作。
示例： 添加示例报告和提示。

故障排除

缺少API密钥：确保 GEMINI_API_KEY 已设置 .env.local 并且过程从以下开始 --env-file .env.local.
型号/工具标志：如果接地或功能未激活，请验证 ENABLE_GEMINI_GOOGLE_SEARCH, ENABLE_GEMINI_CODE_EXECUTION, ENABLE_GEMINI_FUNCTIONS.
速率限制/延迟：较低 CONCURRENCY_LIMIT （例如3）或以较少的同时查询重新运行。
输出太长：减小深度/宽度或更低 GEMINI_MAX_OUTPUT_TOKENS.
架构解析错误：重新运行；管道验证/修复JSON，但极端提示可能会超出预算——修剪提示或减小块大小。

许可证

MIT许可证 -免费和开源。自由使用！

🚀 让我们深入研究一下！ 🚀

最近的改进（v0.3.0）

✨ 最新变化的亮点。另请参见路线图.

🧪 Enhanced Research Validation

✅ 输入验证：至少10个字符+3个单词
📈 输出验证：引文密度（每100字1.5+）
🔍 最近的来源检查（3+2019年后的参考）
⚖️ 冲突披露强制执行

🧠 Gemini Integration Upgrades

在Gemini 2.5 Flash上整合（长上下文，结构化JSON）
通过环境标志的可选工具：搜索基础、代码执行、函数
语义+递归拆分用于上下文管理
具有并发控制和缓存的强大批处理
通过语义搜索增强上下文管理
改进了错误处理和日志记录

🧹 Code Quality Improvements

🚀 添加了并发处理管道
删除了冗余的学术验证器模块
🛡️ 增强了跨接口的类型安全性
📦 优化的依赖关系（≈30%更小的节点模块）

🆕 New Features

📊 研究指标跟踪（来源/学习比率）

* 📑 Auto-generated conflict disclosure statements * 🔄 Recursive research depth control (1-5 levels) * 📈 Research metrics tracking (sources/learnings ratio) * 🤖 MCP tool integration improvements

演出

🚀 研究周期缩短30%
⚡ 初始研究周期缩短40%
📉 API错误减少60%
🧮 代币使用效率提高25%