DeepResearch MCP

<div align="center">

</div>

📚 概述

DeepResearch MCP 是一个基于模型上下文协议 (MCP) 构建的强大研究助手。它通过网络搜索、分析和综合报告生成，对任何主题进行智能、迭代的研究。

🌟 主要特性

• 智能主题探索 - 自动识别知识差距并生成有针对性的搜索查询
• 全面内容提取 - 增强的网络抓取，改进了内容组织
• 结构化知识处理 - 在管理 token 使用量的同时，保留重要信息
• 学术报告生成 - 创建详细、结构良好的报告，包括执行摘要、分析和可视化
• 完整参考文献 - 正确引用所有来源，并附有编号的参考文献
• 自适应内容管理 - 自动管理内容，以保持在 token 限制内
• 错误恢复能力 - 从错误中恢复，并在无法进行完整处理时生成部分报告

🛠️ 架构

<div align="center">

┌────────────────────┐     ┌─────────────────┐     ┌────────────────┐
│                    │     │                 │     │                │
│  MCP 服务器层  ├────►│ 研究服务├────►│ 搜索服务 │
│  (工具 & 提示) │     │ (会话管理)  │     │  (Firecrawl)   │
│                    │     │                 │     │                │
└────────────────────┘     └─────────┬───────┘     └────────────────┘
                                     │
                                     ▼
                           ┌─────────────────┐
                           │                 │
                           │  OpenAI 服务 │
                           │ (分析/报告)  │
                           │                 │
                           └─────────────────┘

</div>

💻 安装

前提条件

• Node.js 18 或更高版本
• OpenAI API 密钥
• Firecrawl API 密钥

设置步骤

1. 克隆存储库

   git clone <repository-url>
   cd deep-research-mcp
   

2. 安装依赖

   npm install
   

3. 配置环境变量

   cp .env.example .env
   

   编辑 .env 文件并添加您的 API 密钥：

   OPENAI_API_KEY=sk-your-openai-api-key
   FIRECRAWL_API_KEY=your-firecrawl-api-key
   

4. 构建项目

   npm run build
   

🚀 使用

运行 MCP 服务器

在 stdio 上启动服务器以进行 MCP 客户端连接：

npm start

使用示例客户端

使用指定的深度对特定主题进行研究：

npm run client "您的研究主题" 3

参数：

• 第一个参数：研究主题或查询
• 第二个参数：研究深度（迭代次数，默认值：2）
• 第三个参数（可选）："complete" 以使用 complete-research 工具（一步完成）

示例：

npm run client "气候变化对珊瑚礁的影响" 3 complete

示例输出

DeepResearch MCP 将生成一份综合报告，其中包括：

• 执行摘要 - 研究结果的简明概述
• 引言 - 研究主题的背景和重要性
• 方法论 - 研究方法的描述
• 综合分析 - 对主题的详细检查
• 比较分析 - 关键方面的可视化比较
• 讨论 - 对发现的解释和意义
• 局限性 - 研究中的约束和差距
• 结论 - 最终见解和建议
• 参考文献 - 包含 URL 的完整来源列表

🔧 MCP 集成

可用的 MCP 资源

资源路径	描述
research://state/{sessionId}	访问研究会话的当前状态
research://findings/{sessionId}	访问会话的收集结果

可用的 MCP 工具

工具名称	描述	参数
initialize-research	启动新的研究会话	query: 字符串, depth: 数字
execute-research-step	执行下一步研究	sessionId: 字符串
generate-report	创建最终报告	sessionId: 字符串, timeout: 数字 (可选)
complete-research	执行整个研究过程	query: 字符串, depth: 数字, timeout: 数字 (可选)

🖥️ Claude Desktop 集成

DeepResearch MCP 可以与 Claude Desktop 集成，为 Claude 提供直接的研究能力。

配置步骤

1. 复制示例配置

   cp claude_desktop_config_sample.json ~/path/to/claude/desktop/config/directory/claude_desktop_config.json
   

2. 编辑配置文件

   更新路径以指向您的 deep-research-mcp 安装，并添加您的 API 密钥：

   {
     "mcpServers": {
       "deep-research": {
         "command": "node",
         "args": [
           "/absolute/path/to/your/deep-research-mcp/dist/index.js"
         ],
         "env": {
           "FIRECRAWL_API_KEY": "your-firecrawler-api-key",
           "OPENAI_API_KEY": "your-openai-api-key"
         }
       }
     }
   }
   

3. 重启 Claude Desktop

   保存配置后，重启 Claude Desktop 以使更改生效。

4. 与 Claude Desktop 一起使用

   现在，您可以使用以下命令要求 Claude 执行研究：

   你能研究一下气候变化对珊瑚礁的影响并提供一份详细的报告吗？
   

📋 示例客户端代码

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

async function main() {
  // 连接到服务器
  const transport = new StdioClientTransport({
    command: "node",
    args: ["dist/index.js"]
  });

  const client = new Client({ name: "deep-research-client", version: "1.0.0" });
  await client.connect(transport);

  // 初始化研究
  const initResult = await client.callTool({
    name: "initialize-research",
    arguments: {
      query: "人工智能对医疗保健的影响",
      depth: 3
    }
  });
  
  // 解析响应以获取 sessionId
  const { sessionId } = JSON.parse(initResult.content[0].text);
  
  // 执行步骤直到完成
  let currentDepth = 0;
  while (currentDepth < 3) {
    const stepResult = await client.callTool({
      name: "execute-research-step",
      arguments: { sessionId }
    });
    
    const stepInfo = JSON.parse(stepResult.content[0].text);
    currentDepth = stepInfo.currentDepth;
    
    console.log(`已完成步骤 ${stepInfo.currentDepth}/${stepInfo.maxDepth}`);
  }
  
  // 生成带有超时时间的最终报告
  const report = await client.callTool({
    name: "generate-report",
    arguments: { 
      sessionId,
      timeout: 180000 // 3 分钟超时
    }
  });
  
  console.log("最终报告:");
  console.log(report.content[0].text);
}

main().catch(console.error);

🔍 故障排除

常见问题

• 超出 Token 限制：对于非常大的研究主题，您可能会遇到 OpenAI token 限制错误。尝试：

  • 减少研究深度
  • 使用更具体的查询
  • 将复杂的主题分解为更小的子主题

• 超时错误：对于复杂的研究，该过程可能会超时。解决方案：

  • 增加工具调用中的超时参数
  • 使用具有更长超时时间的 complete-research 工具
  • 以较小的块处理研究

• API 速率限制：如果您遇到来自 OpenAI 或 Firecrawl 的速率限制错误：

  • 在研究步骤之间实施延迟
  • 使用具有更高速率限制的 API 密钥
  • 使用指数退避重试

📝 许可证

ISC

🙏 致谢

• 基于 模型上下文协议 构建
• 由 OpenAI 和 Firecrawl 提供支持