OpenRouter Agents MCP 服务器

一个用于 OpenRouter 的模型上下文协议 (MCP) 服务器实现，提供复杂的调研代理功能。此服务器允许您的对话式 LLM 将调研任务委托给 Claude 调研协调器，该协调器使用由各种 OpenRouter 模型驱动的不同专业代理。

🚀 新 Beta 分支 (2025 年 3 月 29 日)

OpenRouter Agents MCP 服务器技术概述

OpenRouter Agents MCP 服务器实现了一个用于 AI 驱动调研的复杂协调系统。本摘要重点介绍了最新 beta 版本（2025 年 3 月 29 日）中的关键技术组件和功能。

核心架构

• 模型上下文协议 (MCP)：完全实现，包括 STDIO 和 HTTP/SSE 传输
• 多代理协调：具有规划、调研和上下文代理角色的分层系统
• 向量嵌入数据库：带有 pgvector 的 PGLite 用于语义知识存储
• 轮询负载均衡：在不同模型之间分配调研任务，以获得最佳结果
• 自适应回退系统：当主要调研失败时，降级到低成本模型

调研能力

• 多阶段规划：Claude 3.7 Sonnet 将复杂查询分解为专门的子问题
• 并行执行：跨多个 LLM 并发调研，以获得全面的结果
• 上下文感知优化：第二阶段规划，识别并填补初始调研中的空白
• 语义知识库：向量搜索查找相关的过去调研，以增强新查询
• 自适应合成：上下文代理将发现与可定制的受众级别和格式集成

最近的增强

• 跨模型弹性：全面的错误处理使调研能够持续进行，即使个别模型出现故障
• 动态缓存：基于查询复杂性的智能 TTL 和缓存优化
• 数据库弹性：具有指数退避的数据库操作重试逻辑
• 防御性编程：整个代码库中的空安全操作
• 增强的用户反馈：具有详细错误恢复的评分系统
• 全面测试：验证了所有五个 MCP 工具的功能

该 beta 版本通过架构增强提高了可靠性和调研质量，同时保持了原始实现的即插即用简单性。该系统与 VS Code 中的 Cline 和 Claude Desktop App 无缝集成，在独立的软件包中提供企业级调研功能。

这些改进提供了更可靠和强大的调研体验，同时保持了服务器的易用性。要尝试 beta 版本：

git clone https://github.com/wheattoast11/openrouter-deep-research-mcp.git
cd openrouter-agents
git checkout beta
npm install

🌟 支持此项目

如果您觉得这个项目有帮助，请考虑在 GitHub 上给它一个 star！您的支持有助于使这个项目变得更好。

欢迎您的反馈和贡献！

前提条件

• Node.js (建议 v18 或更高版本) 和 npm
• Git
• 一个 OpenRouter API 密钥 (在 https://openrouter.ai/ 获取)

功能

• 使用 Claude 3.7 Sonnet 进行调研规划（思考模式）
• 由各种 OpenRouter LLM 驱动的多个调研代理
• 将模型轮询分配给调研任务
• 可配置的成本选项（高/低），以满足不同的调研需求
• 独立运行，没有外部数据库依赖项
• 内存缓存，实现快速响应时间
• 带有向量扩展的 PGLite，用于持久存储和相似性搜索

工作原理

1. 当您发送调研查询时，规划代理 (Claude 3.7 Sonnet) 会将其分解为多个专门的调研问题
2. 每个调研问题都分配给一个不同的调研代理，使用高成本或低成本 LLM
3. 来自所有代理的结果被合成为一份全面的调研报告
4. 结果缓存在内存中，并使用嵌入式向量搜索功能持久存储
5. 最终的上下文报告返回给您

安装 (Node.js / 标准)

这是与 VS Code 中的 Cline 等 MCP 客户端集成的推荐方法。

1. 克隆此存储库：

   git clone https://github.com/wheattoast11/openrouter-deep-research-mcp.git
   cd openrouter-agents
   

2. 安装依赖项：

   npm install
   

3. 从示例创建您的 .env 文件：

   cp .env.example .env
   

   (在 Windows 上，您可以使用 copy .env.example .env)

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

   OPENROUTER_API_KEY=your_api_key_here
   

   (确保此文件保存在项目的根目录中)

Cline / VS Code MCP 集成 (推荐)

要将此服务器与 VS Code 中的 Cline 一起使用，您需要将其添加到您的 MCP 设置文件中。

1. 找到您的 Cline MCP 设置文件：

   • 通常位于：c:\Users\YOUR_USERNAME\AppData\Roaming\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json (Windows) 或 ~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json (macOS)。相应地替换 YOUR_USERNAME。

2. 编辑 cline_mcp_settings.json 文件： 在主 mcpServers 对象中添加以下配置对象。请务必将 "YOUR_PROJECT_PATH_HERE" 替换为您克隆此存储库的绝对路径，并将 "YOUR_OPENROUTER_API_KEY_HERE" 替换为您的实际 API 密钥。

   {
     "mcpServers": {
       // ... 可能存在的其他服务器 ...
   
       "openrouter-research-agents": {
         "command": "cmd.exe", 
         "args": [
           "/c", 
           "YOUR_PROJECT_PATH_HERE/start-mcp-server.bat"
         ], 
         "env": {
           // 重要提示：替换为您的实际 OpenRouter API 密钥
           "OPENROUTER_API_KEY": "YOUR_OPENROUTER_API_KEY_HERE" 
         },
         "disabled": false, // 确保服务器已启用
         "autoApprove": [
           "conduct_research",
           "research_follow_up",
           "get_past_research",
           "rate_research_report",
           "list_research_history"
         ]
       }
   
       // ... 可能存在的其他服务器 ...
     }
   }
   

   • 为什么使用批处理文件？ 使用批处理文件可确保服务器以正确的环境和目录上下文启动。
   • 为什么 API 密钥在 env 中？ 虽然服务器使用 dotenv 加载 .env 文件，但在 env 块中提供密钥可确保服务器进程始终可以访问它。

3. 保存设置文件。 Cline 应该会自动检测到新的服务器配置。如果它没有立即出现，您可能需要重新启动 VS Code 或 Cline 扩展。

配置完成后，您将在 Cline 中看到 conduct_research 和其他调研工具可用。您可以像这样使用它们：

你能研究一下量子计算的最新进展吗？

或者指定成本偏好：

你能对气候变化缓解策略进行高成本调研吗？

可用模型

高成本模型

• perplexity/sonar-deep-research
• perplexity/sonar-pro
• perplexity/sonar-reasoning-pro
• openai/gpt-4o-search-preview

低成本模型

• perplexity/sonar-reasoning
• openai/gpt-4o-mini-search-preview
• google/gemini-2.0-flash-001

自定义

您可以通过编辑 .env 文件来自定义可用模型：

HIGH_COST_MODELS=perplexity/sonar-deep-research,perplexity/sonar-pro,other-model
LOW_COST_MODELS=perplexity/sonar-reasoning,openai/gpt-4o-mini-search-preview,other-model

您还可以在 .env 文件中自定义数据库和缓存设置：

PGLITE_DATA_DIR=./researchAgentDB
CACHE_TTL_SECONDS=3600

替代安装：用于 Claude Desktop App 的 HTTP/SSE

该服务器也可以作为独立的 HTTP/SSE 服务运行，以便与 Claude Desktop App 集成。

HTTP/SSE 安装步骤

1. 克隆此存储库（如果尚未完成）：

   git clone https://github.com/wheattoast11/openrouter-deep-research-mcp.git
   cd openrouter-agents
   

2. 按照标准安装（步骤 3 和 4）中的描述创建并配置您的 .env 文件。
3. 使用 npm 启动服务器：

   npm start
   

4. MCP 服务器将运行并通过 HTTP/SSE 在 http://localhost:3002 上访问（或在您的 .env 中指定的端口）。

Claude Desktop App 集成 (HTTP/SSE)

1. 打开 Claude desktop app。

2. 转到 Settings > Developer。

3. 单击 "Edit Config"。

4. 将以下内容添加到配置中的 mcpServers 数组：

   {
     "type": "sse",
     "name": "OpenRouter Research Agents (HTTP)", // 如果也使用 STDIO，则进行区分
     "host": "localhost",
     "port": 3002, // 或您配置的端口
     "streamPath": "/sse",
     "messagePath": "/messages"
   }
   

5. 保存并重新启动 Claude。

持久性与数据存储

此服务器使用：

• 内存缓存：用于高效的响应缓存（使用 node-cache）
• 带有 pgvector 的 PGLite：用于持久存储调研报告和向量搜索功能
  • 调研报告与向量嵌入一起存储，用于语义相似性搜索
  • 向量搜索用于查找与新查询相关的过去调研
  • 所有数据都本地存储在指定的数据目录中（默认：'./researchAgentDB'）

故障排除

• 连接问题：确保 Claude 的开发者设置与服务器配置匹配
• API 密钥错误：验证您的 OpenRouter API 密钥是否正确
• 未找到代理：如果规划失败，请确保 Claude 正确解析 XML
• 模型错误：检查指定的模型是否在您的 OpenRouter 帐户中可用

高级配置

服务器配置可以在 config.js 中修改。您可以调整：

• 可用模型
• 默认成本偏好
• 规划代理设置
• 服务器端口和配置
• 数据库和缓存设置

身份验证安全性

截至最新更新，API 密钥身份验证现在对于 HTTP/SSE 传输默认强制执行：

1. 在您的 .env 文件中为生产环境设置 SERVER_API_KEY 环境变量：

   SERVER_API_KEY=your_secure_api_key_here
   

2. 仅对于开发/测试，您可以通过设置以下内容来禁用身份验证：

   ALLOW_NO_API_KEY=true
   

这为生产部署提供了增强的安全性，同时保持了开发和测试的灵活性。

测试工具

该存储库包含几个测试工具来验证实现：

1. 基本工具测试：

   test-all-tools.bat
   

   此脚本单独测试所有五个 MCP 工具，以验证它们是否正常工作。

2. MCP 服务器测试：

   test-mcp-server.js
   

   测试 MCP 服务器实现，包括所有传输选项。

3. 调研代理测试：

   test-research-agent.js
   

   使用实际的 OpenRouter API 调用测试核心调研代理功能。

这些工具可帮助确保在进行任何修改后，所有组件都能正常运行。

许可证

MIT