STARWARCLOUD STARWAR.AI
返回市场
深度研究mcp服务器

深度研究mcp服务器

作者：ssdeanx59 星标更新：2025-08-12
安装使用来源：spider==github.com

项目介绍

深度研究 MCP 服务器

Node.js TypeScript Gemini API MCP License: MIT

您的AI驱动的研究助手。 使用Google Gemini 2.5 Flash与Google搜索基础和URL上下文进行迭代深度研究。无需依赖网络抓取。

目录

本项目的目的是提供一个最简单但最有效的深度研究代理实现。它设计得易于理解、修改和扩展，目标是代码量不超过500行。

关键特性：

  • MCP集成： 作为模型上下文协议（MCP）服务器/工具运行，实现无缝代理集成。
  • Gemini 2.5 Flash流水线： 长上下文推理、结构化JSON输出以及通过环境标志启用工具（Google搜索基础、代码执行、函数）。
  • 迭代深入： 查询优化 + 结果分析，学习上下文向前传递。
  • 深度和广度控制： 精确调整探索范围。
  • 语义/递归分割： 令牌感知分块，用于强大的总结和分析。
  • 批处理 + 缓存： 限制并发的批处理模型调用，并在提示/结果之间使用LRU缓存。
  • 专业报告： 生成结构化的Markdown报告（摘要、目录、简介、正文、方法论、局限性、关键学习、参考文献）。

为什么这个项目

  • 以Gemini为中心的现代流水线： 围绕Gemini 2.5 Flash构建，可选工具（搜索基础、代码执行、函数）。
  • 最小且易于理解的核心： 纯TypeScript；易于审计和扩展。
  • 确定性输出： 使用Zod验证的JSON和一致的报告框架。
  • 代理就绪： 清晰的MCP服务器入口；与检查器和MCP感知客户端兼容。

工作流程图

flowchart TB
    subgraph 输入
        Q[用户查询]
        B[广度参数]
        D[深度参数]
    end

    DR[深度研究] -->
    SQ[SERP查询] -->
    PR[处理结果]

    subgraph 结果[结果]
        direction TB
        NL((学习))
        ND((方向))
    end

    PR --> NL
    PR --> ND

    DP{深度 > 0？}

    RD["下一个方向：
    - 前期目标
    - 新问题
    - 学习"]

    MR[Markdown报告]

    %% 主流程
    Q & B & D --> DR

    %% 结果到决策
    NL & ND --> DP

    %% 循环流程
    DP -->|是| RD
    RD -->|新上下文| DR

    %% 最终输出
    DP -->|否| MR

    %% 样式
    classDef 输入 fill:#7bed9f,stroke:#2ed573,color:black
    classDef 处理 fill:#70a1ff,stroke:#1e90ff,color:black
    classDef 递归 fill:#ffa502,stroke:#ff7f50,color:black
    classDef 输出 fill:#ff4757,stroke:#ff6b81,color:black
    classDef 结果 fill:#a8e6cf,stroke:#3b7a57,color:black

    class Q,B,D 输入
    class DR,SQ,PR 处理
    class DP,RD 递归
    class MR 输出
    class NL,ND 结果

角色代理

什么是角色代理？

在deep-research中，我们利用“角色代理”的概念来指导Gemini语言模型的行为。与其简单地向LLM提示任务，我们赋予它特定的角色、技能、个性、沟通风格和价值观。这种方法有助于：

  • 聚焦LLM的输出： 通过定义明确的角色，我们鼓励LLM生成符合所需专业知识和视角的响应。
  • 提高一致性： 角色帮助在整个研究过程中保持一致的语气和风格。
  • 增强任务特定性能： 将角色定制到特定任务（例如，查询生成、学习提取、反馈）可以优化LLM在研究阶段的输出。

角色代理使用的示例：

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

通过利用角色代理，deep-research旨在从Gemini语言模型中获得更有针对性、一致性和高质量的研究成果。

如何工作

核心模块：

  • src/deep-research.ts — 协调查询、批处理、分析和综合
    • generateSerpQueries() 使用Gemini根据提示和先前的学习提出SERP样式的查询
    • processSerpResult() 分割内容，启用工具的Gemini调用批处理，提取学习和引用
    • conductResearch() 对语义块进行分析通过
    • writeFinalReport() 构建最终的专业Markdown报告
  • src/ai/providers.ts — GoogleGenAI封装Gemini 2.5 Flash，批处理，令牌控制，可选工具
  • src/ai/text-splitter.ts — 递归字符和语义分割器
  • src/mcp-server.ts — MCP服务器入口点和类型
  • src/run.ts — CLI入口点

流水线亮点：

  • 使用Zod验证的结构化JSON输出
  • 限制并发的批处理（generateBatch，generateBatchWithTools）
  • 提示、SERP提案和报告的LRU缓存
  • 通过标志启用的Gemini工具：Google搜索基础、代码执行、函数

项目结构

deep-research-mcp-server/
├─ src/
│  ├─ ai/
│  │  ├─ providers.ts           # Gemini封装，工具，批处理，缓存
│  │  └─ text-splitter.ts       # 语义/递归分割器
│  ├─ mcp-server.ts             # MCP服务器入口/类型
│  ├─ deep-research.ts          # 协调器：查询 → 分析 → 综合
│  ├─ prompt.ts                 # 系统 + 模板
│  ├─ feedback.ts               # 精炼/反馈循环
│  ├─ output-manager.ts         # 报告/输出格式化
│  ├─ progress-manager.ts       # CLI进度
│  ├─ terminal-utils.ts         # CLI辅助工具
│  ├─ types.ts                  # Zod模式/类型
│  └─ utils/                    # JSON/清理辅助工具
├─ dist/                        # 构建输出
├─ .env.example                 # 环境模板
├─ package.json                 # 脚本/依赖
└─ README.md

需求

设置

Node.js

  1. 克隆仓库：

    git clone [your-repo-link-here]

  2. 安装依赖：

    npm install

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

    # 必需
GEMINI_API_KEY="your_gemini_key"

# 推荐默认值
GEMINI_MODEL=gemini-2.5-flash
GEMINI_MAX_OUTPUT_TOKENS=65536
CONCURRENCY_LIMIT=5

# Gemini工具（按需启用）
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兼容的代理使用以下参数调用deep-research工具：

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

示例MCP工具参数（JSON形状）：

{
  "name": "deep-research",
  "arguments": {
    "query": "2025年多代理研究代理的状态",
    "depth": 3,
    "breadth": 3,
    "existingLearnings": [
      "工具使用改善了基础",
      "批处理减少了延迟"
    ]
  }
}

const mcp = new ModelContextProtocolClient(); // 假设MCP客户端已初始化

async function invokeDeepResearchTool() {
  try {
    const result = await mcp.invoke("deep-research", {
      query: "解释区块链技术的原则",
      depth: 2,
      breadth: 4
    });

    if (result.isError) {
      console.error("MCP工具错误：", result.content[0].text);
    } else {
      console.log("研究报告：\n", result.content[0].text);
      console.log("来源：\n", result.metadata.sources);
    }
  } catch (error) {
    console.error("MCP调用错误：", error);
  }
}

invokeDeepResearchTool();

独立CLI用法

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

npm run start "你的研究查询"

示例：

npm run start "人工智能研究代理的最新发展是什么"

MCP检查器测试

为了交互式测试和调试MCP服务器，使用MCP检查器：

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搜索基础工具
  • 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

  1. 创建.env.local（参见[设置](#设置））

  2. 作为MCP服务器运行（检查器）

npx @modelcontextprotocol/inspector node --env-file .env.local dist/mcp-server.js
  1. 或作为CLI运行
npm run start "2025年多代理研究代理的状态"

示例输出

# 摘要
研究目标、范围、方法和关键发现的简洁概述。

# 目录
...

# 引言
背景和框架。

# 正文
有证据支持的部分，附带引用。

# 方法论
如何找到和分析来源。

# 局限性
假设和风险。

# 关键学习
要点和收获。

# 参考文献
访问URL的规范化引用。

支持

  • 问题： 使用GitHub问题报告错误和功能请求。
  • 讨论： 提出想法或提问。
  • 安全： 不要在公共问题中报告敏感披露；私下联系维护者。

贡献

  • 欢迎PR： 请先为重大更改打开一个问题。
  • 标准： TypeScript 5.x，Node.js 22.x，在PR之前进行lint和类型检查。
  • 检查： npm run build 和 tsc --noEmit 必须通过。
  • 文档： 当更改环境/配置时更新README.md和.env.example。

路线图

  • Exa搜索集成（通过ENABLE_EXA_PRIMARY），Google基础用于增强。
  • 提供商清理： 在Exa迁移后移除Firecrawl（需要明确批准）。
  • CI/CD： 添加GitHub Actions用于构建/lint/测试和徽章。
  • 示例： 添加样本报告和提示。

故障排除

  • 缺少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）

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

<details> <summary><strong>🧪 增强的研究验证</strong></summary>
  • ✅ 输入验证：至少10个字符 + 3个单词
  • 📈 输出验证：引用密度（每100字1.5+）
  • 🔍 最近来源检查（3+ 2019年后引用）
  • ⚖️ 冲突披露强制执行
</details> <details> <summary><strong>🧠 Gemini集成升级</strong></summary>
  • 统一使用Gemini 2.5 Flash（长上下文，结构化JSON）
  • 通过环境标志启用可选工具：搜索基础，代码执行，函数
  • 语义 + 递归分割用于上下文管理
  • 坚固的批处理，具有并发控制和缓存
  • 通过语义搜索增强上下文管理
  • 改进的错误处理和日志记录
</details> <details> <summary><strong>🧹 代码质量改进</strong></summary>
  • 🚀 添加了并发处理流水线
  • 移除了冗余的学术验证模块
  • 🛡️ 跨接口增强了类型安全性
  • 📦 优化了依赖项（约30%更小的node_modules）
</details> <details> <summary><strong>🆕 新功能</strong></summary>
  • 📊 研究指标跟踪（来源/学习比率）
</details> * 📑 自动生成冲突披露声明 * 🔄 递归研究深度控制（1-5层） * 📈 研究指标跟踪（来源/学习比率） * 🤖 MCP工具集成改进

性能：

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