星战科技xingzhan.cloud
返回市场
开放路由深度研究MCP

开放路由深度研究MCP

作者：wheattoast1132 星标更新：2025-11-16
安装使用来源：spider==github.com

项目介绍

Star on GitHub

OpenRouter Agents MCP Server

npm version GitHub Packages

概述

适用于多代理人工智能研究的生产就绪型MCP服务器，集成OpenRouter。完全符合MCP规范2025-06-18，并准备了针对2025年11月规范更新的支持。

主要特性

  • 多代理编排： 计划 → 并行化 → 合成工作流程，具有自适应并发性
  • 异步操作： 长运行研究任务的作业系统与SSE流传输
  • 知识库： 使用PGlite + pgvector的混合BM25+向量搜索
  • 模型支持： 动态目录支持Anthropic Sonnet-4、OpenAI GPT-5、Google Gemini等
  • 生产强化： 速率限制、请求大小限制、多层次认证（JWT/API密钥）
  • MCP兼容性： 100%符合规范，支持服务器发现和扩展元数据
  • 三种模式： AGENT（简单）、MANUAL（精细）或ALL（两者兼有）

安装/运行

  • 安装（项目依赖）
npm install @terminals-tech/openrouter-agents
  • 全局安装（可选）
npm install -g @terminals-tech/openrouter-agents
  • 使用npx运行（无需安装）
npx @terminals-tech/openrouter-agents --stdio
# 或守护进程
SERVER_API_KEY=devkey npx @terminals-tech/openrouter-agents

新功能（v1.6.0 - 2025年11月12日）

  • MCP SDK 1.21.1： 完全符合MCP规范22025-06-18
  • 2025年11月准备： 服务器发现端点（.well-known/mcp-server）和扩展元数据
  • 生产强化： 速率限制（每IP每分钟100次请求），10MB请求大小限制
  • 增强安全性： 支持OAuth2/JWT，改进的安全头
  • 健康监控： 新的/health端点用于生产监控
  • 全面合规报告： 100% MCP规范合规验证

变更日志 → | 合规报告 →

快速开始

  1. 前提条件
  • Node 18+（推荐20 LTS），npm，Git，OpenRouter API密钥
  1. 安装
npm install
  1. 配置（.env）
OPENROUTER_API_KEY=your_openrouter_key
SERVER_API_KEY=your_http_transport_key
SERVER_PORT=3002

# 模式（选择一个；默认ALL）
# AGENT  = 仅代理 + 始终在线操作（ping/status/jobs）
# MANUAL = 单个工具 + 始终在线操作
# ALL    = 代理 + 单个工具 + 始终在线操作
MODE=ALL

# 编排
ENSEMBLE_SIZE=2
PARALLELISM=4

# 模型（按需覆盖） - 更新为最新的成本效益模型
PLANNING_MODEL=openai/gpt-5-chat
PLANNING_CANDIDATES=openai/gpt-5-chat,google/gemini-2.5-pro,anthropic/claude-sonnet-4
HIGH_COST_MODELS=x-ai/grok-4,openai/gpt-5-chat,google/gemini-2.5-pro,anthropic/claude--sonnet-4,morph/morph-v3-large
LOW_COST_MODELS=deepseek/deepseek-chat-v3.1,z-ai/glm-4.5v,qwen/qwen3-coder,openai/gpt-5-mini,google/gemini-2.5-flash
VERY_LOW_COST_MODELS=openai/gpt-5-nano,deepseek/deepseek-chat-v3.1

# 存储
PGLITE_DATA_DIR=./researchAgentDB
PGLITE_RELAXED_DURABILITY=true
REPORT_OUTPUT_PATH=./research_outputs/

# 索引器
INDEXER_ENABLED=true
INDEXER_AUTO_INDEX_REPORTS=true
INDEXER_AUTO_INDEX_FETCHED=true

# MCP特性
MCP_ENABLE_PROMPTS=true
MCP_ENABLE_RESOURCES=true

# 提示策略
PROMPTS_COMPACT=true
PROMPTS_REQUIRE_URLS=true
PROMPTS_CONFIDENCE=true
  1. 运行
  • STDIO（用于Cursor/VS Code MCP）：
node src/server/mcpServer.js --stdio
  • HTTP/SSE（本地守护进程）：
SERVER_API_KEY=$SERVER_API_KEY node src/server/mcpServer.js

Windows PowerShell示例

  • STDIO
$env:OPENROUTER_API_KEY='your_key'
$env:INDEXER_ENABLED='true'
node src/server/mcpServer.js --stdio
  • HTTP/SSE
$env:OPENROUTER_API_KEY='your_key'
$env:SERVER_API_KEY='devkey'
$env:SERVER_PORT='3002'
node src/server/mcpServer.js

一键演示脚本

开发（HTTP/SSE）：

SERVER_API_KEY=devkey INDEXER_ENABLED=true node src/server/mcpServer.js

STDIO（Cursor/VS Code）：

OPENROUTER_API_KEY=your_key INDEXER_ENABLED=true node src/server/mcpServer.js --stdio

MCP客户端JSON配置（无需手动启动）

您可以在支持JSON服务器清单的MCP客户端中直接注册此服务器。

最小示例：

  1. STDIO传输（推荐用于IDE）
{
  "servers": {
    "openrouter-agents": {
      "command": "npx",
      "args": ["@terminals-tech/openrouter-agents", "--stdio"],
      "env": {
        "OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}",
        "SERVER_API_KEY": "${SERVER_API_KEY}",
        "PGLITE_DATA_DIR": "./researchAgentDB",
        "INDEXER_ENABLED": "true"
      }
    }
  }
}
  1. HTTP/SSE传输（守护进程模式）
{
  "servers": {
    "openrouter-agents": {
      "url": "http://127.0.0.1:3002",
      "sse": "/sse",
      "messages": "/messages",
      "headers": {
        "Authorization": "Bearer ${SERVER_API_KEY}"
      }
    }
  }
}

全局安装包（或通过npx），MCP客户端可以自动启动服务器。请参阅您的客户端文档以了解如何放置此JSON（例如，~/.config/client/mcp.json）。

工具（高价值）

  • 始终在线（所有模式）：ping，get_server_status，job_status，get_job_status，cancel_job
  • AGENT：agent（单入口点用于研究/跟进/检索/查询）
  • MANUAL/ALL工具集：submit_research（异步），conduct_research（同步/流），research_follow_up，search（混合），retrieve（索引/SQL），query（SELECT），get_report_content，list_research_history
  • 作业：get_job_status，cancel_job
  • 检索：search（混合BM25+向量，可选LLM重排序），retrieve（索引/SQL包装器）
  • SQL：query（仅SELECT，可选explain）
  • 知识库：get_past_research，list_research_history，get_report_content
  • 数据库操作：backup_db（tar.gz），export_reports，import_reports，db_health，reindex_vectors
  • 模型：list_models
  • 网络：search_web，fetch_url
  • 索引器：index_texts，index_url，search_index，index_status

工具使用模式（针对LLMs）

使用tool_patterns资源查看描述有效链路的JSON配方，例如：

  • 搜索 → 抓取 → 研究
  • 异步研究：提交，通过SSE /jobs/:id/events流式传输，然后获取报告内容

注意事项

  • 数据存储在本地PGLITE_DATA_DIR下（默认./researchAgentDB）。备份是tarball，在./backups中。
  • 使用list_models来发现当前提供商的能力和ID。

架构概览

查看docs/diagram-architecture.mmd（Mermaid）。如果已安装Mermaid CLI，可以将其渲染为SVG：

npx @mermaid-js/mermaid-cli -i docs/diagram-architecture.mmd -o docs/diagram-architecture.svg

或者使用脚本：

npm run gen:diagram

架构图（品牌版）

如果图像在您的查看器中无法渲染，请直接打开docs/diagram-architecture-branded.svg。

答案结晶视图

答案结晶架构图

它与典型的“代理链”有何不同：

  • 不仅仅是硬编码交接；计划被计算，然后并行代理进行搜索，然后合成步骤对共识、矛盾和空白进行推理。
  • 系统在其研究过程中索引所读内容，因此后续查询会更快更智能。
  • 注意力引导：明确的URL引用，[未验证]标签，以及信心评分。

最小令牌提示策略

  • 紧凑模式剥离前言至基本约束；其余部分推断。
  • 强制规则：明确的URL引用，不猜测ID/URL，信心标签。
  • 简短工具规格：使用简洁的参数名称并依赖服务器默认值。

常见用户旅程

  • “给我一份截至2025年7月的MCP状态执行摘要。”

    • 服务器计划子查询，获取权威来源，合成时带有引用。
    • 索引输出使相关的后续查询更快。

  • “查找具备视觉能力的模型，并优雅地路由图像。”

    • 发现并过滤/models，生成路由器模板，回退到文本模型。

  • “比较有界并行性的编排模式。”

    • 拉取OTel/Airflow/Temporal文档，产生MECE合成和代码指针。

Cursor IDE使用

  • 在Cursor MCP设置中添加此服务器，指向node src/server/mcpServer.js --stdio。
  • 直接在Cursor中使用新的提示（planning_prompt，synthesis_prompt）来构建任务。

常见问题（快速浏览）

  • 如何避免幻觉？
    • 严格的引用规则，[未验证]标签，检索过去的工作，实时索引。
  • 我能禁用功能吗？
    • 是的，通过上面列出的环境标志。
  • 它支持流式传输吗？
    • 是的，HTTP的SSE，MCP的stdio。

命令映射（快速参考）

  • 启动（stdio）：npm run stdio
  • 启动（HTTP/SSE）：npm start
  • 通过npx运行（限定范围）：npx @terminals-tech/openrouter-agents --stdio
  • 生成示例：npm run gen:examples
  • 列出模型：MCP list_models { refresh:false }
  • 提交研究（异步）：submit_research { q:"<query>", cost:"low", aud:"intermediate", fmt:"report", src:true }
  • 跟踪作业：get_job_status { job_id:"..." }，取消：cancel_job { job_id:"..." }
  • 统一搜索：search { q:"<query>", k:10, scope:"both" }
  • SQL（只读）：query { sql:"SELECT ... WHERE id = $1", params:[1], explain:true }
  • 获取过去的研究：get_past_research { query:"<query>", limit:5 }
  • 索引URL（如果启用）：index_url { url:"https://..." }
  • 微型UI（幽灵）：访问http://localhost:3002/ui以流式传输作业事件（SSE）。

包发布

无需克隆即可安装和运行：

npx @terminals-tech/openrouter-agents --stdio
# 或守护进程
SERVER_API_KEY=your_key npx @terminals-tech/openrouter-agents

发布（限定范围）

npm login
npm version 1.3.2 -m "chore(release): %s"
git push --follow-tags
npm publish --access public --provenance

验证 – MSeeP（多源证据及评估协议）

  • 强制引用：明确的URL，信心标签；未知标记为[未验证]。
  • 跨模型三角测量：计划分发给多个模型；合成评分共识与矛盾。
  • KB基础：本地混合索引（BM25+向量）检索过去的工作进行交叉检查。
  • 人类反馈：rate_research_report { rating, comment }存储到数据库；驱动后续行动。
  • 可重复性：export_reports + backup_db捕获审计工件。

质量反馈循环

  • 运行示例：npm run gen:examples
  • 审查：list_research_history，get_report_content {reportId}
  • 评价：rate_research_report { reportId, rating:1..5, comment }
  • 改善检索：reindex_vectors，index_status，search_index { query }

架构图（品牌版）

  • 查看docs/diagram-architecture-branded.svg（徽标链接到https://terminals.tech）。

支持者

Star on GitHub

Star History Chart