OpenRouter 代理 MCP 服务器

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

🚀 新的 Beta 分支（2025 年 3 月 29 日）

OpenRouter Agents MCP 服务器技术概述

OpenRouter Agents MCP 服务器为 AI 研究实现了一套完善的编排系统。本摘要重点介绍了最新测试版（2025 年 3 月 29 日）中的关键技术组件和功能。

核心架构

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

研究能力

• 多阶段规划：Claude 3.7 Sonnet 将复杂查询分解为专门的子问题
• 并行执行：跨多个法学硕士项目进行并发研究，以获得综合结果
• 情境感知细化：第二阶段规划，识别并填补初步研究中的空白
• 语义知识库：向量搜索查找相关的过去研究以增强新查询
• 自适应合成：语境代理将研究结果与可定制的受众水平和格式相结合

最近的增强功能

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

测试版通过架构增强，提升了可靠性和研究质量，同时保留了原版实现的即插即用特性。该系统与 VS Code 中的 Cline 和 Claude 桌面应用程序无缝集成，以独立的软件包提供企业级研究功能。

这些改进在保持服务器易用性的同时，带来了更可靠、更强大的研究体验。要试用测试版，请执行以下操作：

🌟 支持这个项目

如果您觉得这个项目有帮助，请在 GitHub 上点个星！您的支持有助于完善这个项目。

我们随时欢迎您的反馈和贡献！

先决条件

• Node.js（建议使用 v18 或更高版本）和 npm
• Git
• OpenRouter API 密钥（从https://openrouter.ai/获取）

特征

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

工作原理

1. 当你发送研究查询时，规划代理（Claude 3.7 Sonnet）会将其分解为多个专门的研究问题
2. 每个研究问题都分配给不同的研究代理，使用高成本或低成本的法学硕士
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": { // ... potentially other existing servers ... "openrouter-research-agents": { "command": "cmd.exe", "args": [ "/c", "YOUR_PROJECT_PATH_HERE/start-mcp-server.bat" ], "env": { // IMPORTANT: Replace with your actual OpenRouter API Key "OPENROUTER_API_KEY": "YOUR_OPENROUTER_API_KEY_HERE" }, "disabled": false, // Ensure the server is enabled "autoApprove": [ "conduct_research", "research_follow_up", "get_past_research", "rate_research_report", "list_research_history" ] } // ... potentially other existing servers ... } }
   • **为什么要使用批处理文件？**使用批处理文件可确保服务器以正确的环境和目录上下文启动。
   • **为什么在env中设置 API 密钥？**虽然服务器使用dotenv加载.env文件，但在env块中提供密钥可确保服务器进程始终可以访问该文件。
3. 保存设置文件。Cline应该会自动检测新的服务器配置。如果它没有立即显示，你可能需要重启 VS Code 或 Cline 扩展。

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

或者指定成本偏好：

可用型号

高成本模型

• 困惑/声纳深度研究
• 困惑/声纳专业版
• 困惑/声纳推理专业版
• openai/gpt-4o-搜索预览

低成本模型

• 困惑/声纳推理
• openai/gpt-4o-mini-搜索-预览
• google/gemini-2.0-flash-001

定制

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

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

替代安装：Claude 桌面应用程序的 HTTP/SSE

该服务器还可以作为独立的 HTTP/SSE 服务运行，以便与 Claude 桌面应用程序集成。

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://localhost:3002 (或.env中指定的端口) 上的 HTTP/SSE 访问。

Claude 桌面应用程序集成 (HTTP/SSE)

1. 打开 Claude 桌面应用程序。
2. 前往“设置”>“开发者”。
3. 单击“编辑配置”。
4. 将以下内容添加到配置中的mcpServers数组中：
   { "type": "sse", "name": "OpenRouter Research Agents (HTTP)", // Differentiate if also using STDIO "host": "localhost", "port": 3002, // Or your configured port "streamPath": "/sse", "messagePath": "/messages" }
5. 保存并重新启动 Claude。

持久性和数据存储

该服务器使用：

• 内存缓存：用于高效的响应缓存（使用节点缓存）
• PGLite 和 pgvector ：用于持久存储研究报告和向量搜索功能
  • 研究报告与向量嵌入一起存储，用于语义相似性搜索
  • 向量搜索用于查找与新查询相关的过去研究
  • 所有数据都本地存储在指定的数据目录中（默认值：'./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 调用测试核心研究代理功能。

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

执照

麻省理工学院