Skip to main content
Glama

MCP Nexus

CI npm version License

**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)

文档

开发

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 数据目录)中。路由器本身不会向任何地方发送信息。如果您配置了外部嵌入提供程序,则只会把能力文本(标题/描述/关键词)发送到该服务,绝不会发送参数、密钥或分析数据。原始的工具参数永远不会被持久化。

许可证

Apache-2.0

Available Tools

4 tools
describe_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

    A3.8/5.0

    Scored across 4 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables dynamic aggregation of multiple MCP servers into a unified endpoint with middleware, orchestration, and gateway capabilities.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables 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 npm
      MIT