DeepResearch MCP

<div align="center">

</div>

📚 概述

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

🌟 主要功能

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

🛠️ 架构

<div align="center">

┌────────────────────┐ ┌─────────────────┐ ┌────────────────┐ │ │ │ │ │ │ │ MCP Server Layer ├────►│ Research Service├────►│ Search Service │ │ (Tools & Prompts) │ │ (Session Mgmt) │ │ (Firecrawl) │ │ │ │ │ │ │ └────────────────────┘ └─────────┬───────┘ └────────────────┘ │ ▼ ┌─────────────────┐ │ │ │ OpenAI Service │ │ (Analysis/Rpt) │ │ │ └─────────────────┘

</div>

💻 安装

前提条件

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

设置步骤

1. 克隆仓库 bash git clone <repository-url> cd deep-research-mcp

2. 安装依赖 bash npm install

3. 配置环境变量 bash cp .env.example .env

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

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

4. 构建项目 bash npm run build

🚀 使用

运行 MCP 服务器

启动服务器以供 MCP 客户端连接：

bash npm start

使用示例客户端

针对特定主题以指定深度运行研究：

bash npm run client "Your research topic" 3

参数：

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

示例： bash npm run client "the impact of climate change on coral reefs" 3 complete

示例输出DeepResearch MCP 将生成一份全面的报告，其中包括：

• 执行摘要 - 研究发现的简明概述
• 引言 - 研究主题的背景和重要性
• 方法论 - 研究方法的描述
• 综合分析 - 对主题的详细审查
• 比较分析 - 关键方面的可视化比较
• 讨论 - 发现的解释及其影响
• 局限性 - 研究中的限制和空白
• 结论 - 最终见解和建议
• 参考文献 - 带有 URL 的完整来源列表

🔧 MCP 集成

可用的 MCP 资源

可用的 MCP 工具

🖥️ Claude 桌面集成

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

配置步骤

1. 复制示例配置 bash cp claude_desktop_config_sample.json ~/path/to/claude/desktop/config/directory/claude_desktop_config.json

2. 编辑配置文件

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

   json { "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 桌面

   保存配置后，重启 Claude 桌面使更改生效。

4. 与 Claude 桌面一起使用

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

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

📋 示例客户端代码

typescript 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 提供支持