DeepResearch MCP

<div align="center">

</div>

📚 概述

DeepResearch MCP 是一个基于模型上下文协议（MCP）构建的强大研究助手。它通过网络搜索、分析和生成全面报告来进行智能迭代研究。

🌟 主要特性

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

🛠️ 架构

<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 服务器

在标准 I/O 上启动服务器以供 MCP 客户端连接：

npm start

使用示例客户端

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

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

参数：

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

示例：

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": [
           "/绝对路径/to/您的/deep-research-mcp/dist/index.js"
         ],
         "env": {
           "FIRECRAWL_API_KEY": "您的-firecrawler-api-key",
           "OPENAI_API_KEY": "您的-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);

🔍 故障排除

常见问题

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

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

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

  • 增加工具调用中的超时参数
  • 使用具有较长超时的 complete-research 工具
  • 将研究分成较小的部分进行处理

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

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

📝 许可证

ISC

🙏 致谢

• 使用 Model Context Protocol 构建
• 由 OpenAI 和 Firecrawl 提供支持