mcp-nexus
MCP Nexus
**MCP Nexus 是模型上下文协议(Model Context Protocol)的本地优先智能路由器。**您的 AI 工具链只需连接一个 MCP 端点——Nexus——而 Nexus 在后台管理您的所有真实 MCP 服务器:索引它们的工具、按需发现能力、惰性启动服务器、执行路由调用,并根据本地使用情况学习,从而不断优化排序结果。
Before With MCP Nexus
AI Harness AI Harness
├── GitHub MCP (30 tools) └── mcp-nexus (4 control tools)
├── Jira MCP (25 tools) ├── search_capabilities
├── Slack MCP (20 tools) ├──── describe_capabilities
├── Figma MCP (18 tools) ├──── execute_capability
... └──── search_servers
~90+ tool schemas in context │
(everything else stays indexed
on disk until actually needed)为什么
每新增一个 MCP 服务器,都会向模型的上下文之中加入其所有工具模式。等服务器数量达到十个时,您就会在模型几乎用不到的定义上浪费数万 Token,而工具选择的质量也会下降。
Nexus 翻转了这一模式:它不将每个下游模式都推入上下文,而是在磁盘上维护一个轻量级的能力索引,并为控制平面提供相对极小的入口。代理根据需求发现能力(search_capabilities),仅对所选择的能力查看精确模式(describe_capabilities),并通过 Nexus 执行(execute_capability)。所有状态——配置、索引、分析、学习到的序列——都保存在本地的 .mcp-nexus/ 目录中。
Related MCP server: MetaMCP
快速上手
# 1. Scaffold a project config
npx @fyrlabs/mcp-nexus init
# 2. Add downstream MCP servers (anything runnable over stdio)
npx @fyrlabs/mcp-nexus add github -- npx -y @modelcontextprotocol/server-github
# or import an existing config:
npx @fyrlabs/mcp-nexus import --from claude
# 3. Point your harness at Nexus (see docs/harness-setup.md)工具链配置(Claude Code、Cursor、Codex 以及其他 MCP 客户端):
{
"mcpServers": {
"mcp-nexus": {
"command": "npx",
"args": ["-y", "@fyrlabs/mcp-nexus"]
}
}
}Nexus 会通过从当前工作目录向上查找方式(walk up)自动找到 project-mcp.json,您也可以传参 --config ./path/to/nexus.json 指定配置文件。
随后,从代理的角度来看:
search_capabilities { "query": "find comments people left on my PR" }
→ github.review_comments.list score=0.94 ...
describe_capabilities { "capabilityIds": ["github.review_comments.list"] }
→ exact input schema
execute_capability { "capabilityId": "github.review_comments.list",
"arguments": { ... } }
→ forwarded verbatim to the right server, started on demand暴露给模型与保留在本地的内容
类别 | 暴露给模型 | 保留在本地 |
控制平面工具 | 4 个固定工具 | — |
能力元数据 | 仅在进行搜索时出现(较长的记录:id、标题、描述、风险度、分数) | 完整索引存储于 SQLite |
输入模式 | 仅描述所列的能力时的模式 | 在索引时持久化 |
使用分析与点击信号 | — | 本地事件 + 汇总 |
密钥 | 绝不暴露(环境变量在启动时解析,并可能产生日志中遭截断) | 在您的 shell / 环境变量中 |
亮点
本地优先。不依赖云服务、没有账号、没有远程网络。您只需要移除
.mcp-nexus/,所有学习到的状态都会被清除。安 启动生命周期。下游服务器仅按需启动,并在分层的空闲超时(热 / 温 / 冷)后自动停止。
混合搜索。基于加权字段进行 BM25 关键词词汇排序,支持精确 id/工具名匹配、别名展开(例如
pr→pull request,可配置),以及可插拔的EmbeddingProvider接口以可选加法语义搜索。自适应排序并自带解释。每个结果都包含信号分布说明;结构化的优先级能力优先于免学习获得的流行度;已被不可用标记的能力永远不会被推荐。
序列预测。系统会在本地学习重复出现的工具序列,并利用这些序列来提高“很可能下一个调用”的能力的优先级——预测结果永远不会自动执行。
零原生依赖。存储使用 Node.js 自带的
node:sqlite;安装此包无需编译任何当地代码。兼容多种 harness。任何支持 MCP stdio 的客户端都可以放在 Nexus 之前使用。
要求
Node.js ≥ 22.5(推荐 24 LTS)
文档
配置参考 — 所有字段、解析顺序、环境变量替换
CLI 参考 — 所有命令和标志参数
架构 — 模块、评分模型、存储结构
Harness 设置 — Claude Code、Cursor、Codex 及常规 MCP 客户端
examples/project-mcp.json— 带注解的入门配置示例
开发
git clone https://github.com/fyrlabs/mcp-nexus && cd mcp-nexus
npm install
npm run build # tsc -> dist/
npm run test # vitest (unit + integration, mirrors src/ structure under src/tests/)
npm run typecheck # strict tsc, no emit
npm run lint # eslint集成测试使用真实的 @modelcontextprotocol/server-everything 包作为下游 stdio 服务器,并通过完整运行时完成的调用——如果该包无法加载,测试将自动执行叙过程。
更多信息,请参阅 AGENTS.md 查看贡献规约(提交、版本、结构约定)。
隐私
Nexus 将配置缓存、索引和分析数据存储在 .mcp-nexus/(或您的 XDG 数据目录)中。路由器本身不会向任何地方发送信息。如果您配置了外部嵌入提供程序,则只会把能力文本(标题/描述/关键词)发送到该服务,绝不会发送参数、密钥或分析数据。原始的工具参数永远不会被持久化。
许可证
Available Tools
4 toolsdescribe_capabilitiesDescribe capabilitiesB
Return the full metadata and input schemas for the given capability IDs.
Inputs: capabilityIds (required).
execute_capabilityExecute capabilityA
Execute a downstream MCP capability by ID. The underlying server is started on demand and the arguments are forwarded verbatim.
Inputs: capabilityId (required), arguments.
search_capabilitiesSearch capabilitiesA
Search every indexed downstream MCP capability by natural language, keywords, tags, server id, or capability id. Returns lightweight metadata only.
Inputs: query (required), limit.
search_serversSearch serversA
Rank configured downstream MCP servers against a domain-level query. Useful before drilling into capability search.
Inputs: query (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clear operational role: searching servers, searching capabilities, describing schemas, and executing. search_servers and search_capabilities are adjacent but their descriptions clearly separate domain-level server ranking from capability-level search.
All tool names follow a consistent verb_noun snake_case pattern. The only minor inconsistency is 'capabilities' being plural in search/describe but singular in execute_capability.
Four tools is well-scoped for a gateway or meta-server: discover servers, discover capabilities, inspect schemas, and execute. There is no redundancy or unnecessary bloat.
The discover → describe → execute workflow is covered end-to-end. Minor gaps such as explicit list-all-server or dedicated server metadata retrieval are missing, but search_servers can largely cover discovery needs.
Maintenance
Related MCP Connectors
Connect MCP clients to 2,000+ AI models without managing provider API keys.
Every service you connect, one MCP endpoint for all your AI tools. Sign in once.
MCP federation gateway: route, govern and observe agent tools across clouds and MCP servers.
The OpenRouter for tools. One MCP connection gives any AI agent 254 hosted tools, pay per call.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceA unified hub for centrally managing and dynamically orchestrating multiple MCP servers/APIs into separate endpoints with flexible routing strategies.2,694Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables dynamic aggregation of multiple MCP servers into a unified endpoint with middleware, orchestration, and gateway capabilities.MIT
- AlicenseNot gradedqualityCmaintenanceEnables clients to connect once and access the union of multiple backend MCP servers' tools through a single unified interface, with namespaced tool routing, capability search, and health isolation.MIT
- AlicenseNot gradedqualityAmaintenanceEnables clients to connect through a unified MCP endpoint that aggregates and routes requests to multiple backend MCP resource servers, exposing their combined tools and resources with optional authentication and management.120 npmMIT