MCP 惰性代理NeoXider/neoxider-mcp-hub

DeepSeek Capability Hub

用一个稳定的 MCP 工具替代你拥有的所有 schema——常驻上下文缩小 93.2%，工具选择准确率保持不变。两者均已实测。

Capability Hub 是一个面向 DeepSeek Harness 及其他 MCP 客户端的惰性 MCP 与技能代理。宿主只需看到一个紧凑的工具 capability_hub，而无需为每个已配置服务器中的每个工具 schema 付出上下文代价。

智能体会搜索一个轻量级目录，检查权限，唤醒一个受信任的服务器，通过 hub 调用它，并可以再次将其关闭。技能正文仅在选定之后才会加载。

实测上下文节省

以下数字由 bench/measure.mjs 生成，而非估算。
它通过 stdio 启动每个真实的、已发布的 MCP 服务器，请求 tools/list，并
统计宿主为每个工具注入的确切 JSON（name + description + inputSchema）的
token 数（o200k_base）。hub 也以相同方式测量，即启动它并读取其自身的
tools/list。

pnpm bench

| 服务器 | 用途 | 工具数 | 上下文 token 数 |
|---|---|---:|---:|
| @modelcontextprotocol/server-everything | MCP 参考服务器 | 13 | 1,075 |
| @modelcontextprotocol/server-memory | 知识图谱记忆 | 9 | 891 |
| @modelcontextprotocol/server-sequential-thinking | 结构化推理 | 1 | 851 |
| @playwright/mcp | 浏览器自动化 | 24 | 3,383 |
| 总计——经典 MCP | 四个服务器，始终常驻 | 47 | 6,200 |
| 总计——Capability Hub | 一个代理工具 | 1 | 422 |

永久成本下降 93.2%，即 14.7 倍。 这是无论任务是否涉及工具，你在每一轮对话中
都要为之付出的那部分提示词成本。

节省幅度随你的目录增长

无论你配置多少个服务器，hub 都只发布一个 schema，因此经典方案一侧呈线性增长，而 hub 一侧仅随每个条目增加一行目录描述——
并且一旦列表退化为仅名称，便不再增长。以下每个 hub 数字均为实测
通过针对该规模的目录启动真实服务器，而非基于预测：

| 配置的服务器数 | 经典 token 数 | Hub 常驻 | 节省 |
|---:|---:|---:|---:|
| 4 | 6,200 | 430 | 93.1% |
| 10 | 15,500 | 584 | 96.2% |
| 20 | 31,000 | 826 | 97.3% |
| 30 | 46,500 | 468 | 99.0% |
| 60 | 93,000 | 595 | 99.4% |

30 处的下降是降级机制触发了：完整描述不再符合预算，列表回退为名称，常驻成本大约减半。

诚实的另一半

Hub 并非免费：经典配置一次性预先支付的成本，Hub 在运行时、当 agent 实际打开某个能力时才支付。不存在单一的“每任务”数字——本 README 的早期版本发布过一个，而那是把最昂贵的可能路径当作典型情况来呈现。三种场景：

| 场景 | 路径 | Hub token 数 | 对比 6,200 |
|---|---|---:|---:|
| idle — 任务不需要任何能力 | 仅常驻 schema | 422 | 节省 93.2% |
| direct — 任务打开一个能力 | 带查询的 search + tools | 554 | 节省 91.1% |
| cautious — 还会审查权限、读取完整列表 | search + inspect + enable + tools | 1,195 | 节省 80.7% |

direct 这一行仍然计入了一次 search，而内联目录列表通常使这次调用变得不必要——这是一个保守选择，因为偏差应当不利于我们自己的数字。

direct 路径之所以便宜，有两个原因，它们早已存在于代码中，而基准测试却一直忽略：tools 会自行启动服务器，因此 enable 不在关键路径上；并且 tools 接受查询，当 agent 已经知道自己想要什么时，成本为 60 个 token 而非 558 个：

{"action":"tools","name":"playwright","query":"click"}

盈亏平衡点约为一次会话中 47 次直接发现，或者如果 agent 每次都走谨慎路径，则为 8 次。低于该值时 Hub 胜出；高于该值时静态配置更便宜。因此，当你有很多服务器且每个任务只涉及其中少数几个时，Hub 是合适的取舍；而当每个任务都使用你拥有的所有工具时，它则是错误的选择。

有三项设计决策直接来自这些测量：

- enable 过去会返回完整工具列表，而文档中的下一步是 tools——因此该工作流为同一份列表支付了两次费用，1,567 个 token 而非 780 个。现在 enable 返回一个计数和一个指向下一操作的指针。
- 面向模型的 JSON 采用紧凑序列化。缩进不是信息，而且美化打印在相同负载上测得多出 31% 的 token。
- 能力列表随工具描述一起提供，而不是隐藏在 search 调用之后——关于这带来了什么，见下面的准确率表。

实测工具选择准确率

如果模型随后选错了工具，节省上下文就毫无价值。因此这一点也被测量了，针对本地以温度 0 运行的 Qwen3.8-27B——28 个已知答案的任务，其中 6 个完全不需要工具，调用工具会被判为失败。

pnpm bench:accuracy
| 条件 | 常驻 | 总体 | 无工具任务 | 误调用 | 平均轮次 | 平均提示词 |
|---|---:|---:|---:|---:|---:|---:|
| classic — 47 个 schema 常驻 | 6,200 | 96.4% | 83.3% | 1 | 1 | 7,269 |
| hub，模糊目录 | 422 | 82.1% | 83.3% | 1 | 3.00 | 2,818 |
| hub，列表未内联 | 328 | 85.7% | 100% | 0 | 3.54 | 3,047 |
| hub，按发布状态 | 533 | 96.4% | 100% | 0 | 1.96 | 1,873 |

在常驻上下文只有十二分之一的情况下达到相同准确率——而且总 token 更少。 每个任务 1,873
个提示词 token，对比 7,269，且是在多轮协议每一轮上求和。代理本应为额外往返付出的代价并未出现。

classic 设置的唯一失败值得点名：当被问到 “97 是质数吗？” 时，常驻 47 个工具的
模型伸手去用了 sequentialthinking。每个拥有可用目录的 hub 条件在无工具任务上都得了 100%。

模糊目录那一行是同样的代码、同样的服务器——只有描述不同。把你的目录写得能被找到；这值大约 14 分。

hub 各行是针对活跃子进程的多轮测试，所以边缘任务会在不同运行之间浮动几分。
在三次运行中，classic 条件每次都精确复现为 96.4%，发布版 hub 得分在 96.4–100% 之间；
两个消融行始终低于这两者，从未高于。

与 Tool Search 正面对比

以上所有内容都是把这个代理与静态配置比较，而静态配置无法支撑“比其他惰性方法更好”的
主张。所以它们也被测量了——同样的 28 个任务、同样的模型，以及一个按 Anthropic 的 Tool Search
Tool 和 Claude Code 的 MCP Tool Search 工作方式构建、带真实语义检索的 tool_search 条件。

pnpm bench:head-to-head

| 98 个工具 | 常驻 | 总体 | 无工具 | 误调用 | 平均提示词 |
|---|---:|---:|---:|---:|---:|
| classic | 12,422 | 92.9% | 83.3% | 1 | 14,701 |
| toolSearch | 75 | 92.9% | 100% | 0 | 1,384 |
| hub | 709 | 92.9% | 100% | 0 | 2,125 |

请诚实地看待这一点：准确率上打平，而 Tool Search 是更紧凑的设计。 常驻 75 个 token 对比 709，
而且它不会随目录增长，因为它的常驻表面只是一个查询字符串。本项目的表面则带有一个 action 枚举、
一个 payload 字段和一份内联的能力列表。

两种惰性方法都确实胜过静态列表：提示词 token 约为其五分之一，并且在六个正确答案是什么都不调用的
任务上达到 100%，而 classic 为 83.3%。

这个代理仍然保有一席之地的地方，是这些数字都未覆盖的维度——它让能力保持停止，而不只是隐藏，
并且它承载了搜索工具不发表意见的权限、配置和人工批准。这个比较在一种方式上对我们有利而有失公平，
这一点在报告中已明确说明：Tool Search 索引假定每个服务器都已被枚举，而且它的嵌入模型没有计入成本。
两种量表的完整表格、失败分析和现有技术部分见
docs/context-economy.md。

每个工具的原始测量数据提交在 bench/snapshots/ 下，token 报告在
bench/results.json，准确率报告在
bench/accuracy.json，对比结果在
bench/head-to-head.json，因此每张表都可以在无需网络访问的情况下重新推导出来。

证明它确实是动态的

上表展示了模型不必承载的内容。这里展示的是另一半——一个启动时无人加载的能力，可以被意图发现、打开、用于一次真实的工具调用，然后再次关闭。其中没有任何内容是模拟的：子进程就是已发布的 @playwright/mcp 包。

pnpm proof

host-visible tools          capability_hub

search (by intent)              72 tokens   playwright found, enabled=false
inspect (permissions)          121 tokens   permissions listed, still stopped
enable (starts process)         22 tokens   real child process, 24 tools live
tools (schemas withheld)       558 tokens   names + descriptions, schemasIncluded=false
tools (narrowed by query)       60 tokens   matched 1 of 24
tools (one schema, opt-in)     144 tokens   schema returned only when asked
call (real child tool)         107 tokens   browser_navigate executed
disable (stops process)         11 tokens   wasEnabled=true
search (after disable)          72 tokens   enabled=false again

每一步都是经过断言的，而不仅仅是打印出来：如果暴露给宿主的工具超过一个，如果某个能力在 enable 之前就报告自己正在运行，如果子进程的 schema 出现在默认的 tools 列表中，如果 includeSchema 被忽略，如果查询没有缩小列表范围，或者如果在 disable 之后该能力仍被标记为正在运行，那么这次运行就会失败。回执写入 bench/dynamic-proof.json。

与静态配置的对比才是重点：那同样的 24 个 Playwright 工具在每一轮的每个提示中都要占用 3,383 个常驻 token，无论任务是否涉及浏览器。而在这里，在模型提出请求之前它们不花费任何代价，并且 24 个工具的名称一次性只花费 558 个 token——如果模型已经知道自己想要什么，则只需 60 个。

它为什么存在

大型静态 MCP 配置会浪费上下文，并让工具选择更加嘈杂。Capability Hub 保持面向模型的界面稳定：

search → inspect → enable → tools → call → disable

- 一个固定的 schema 始终留在 Harness 提示中。
- 子工具 schema 在被请求之前一直留在模型上下文之外。
- tools 默认返回名称和描述；完整 schema 需要主动选择加入。
- MCP 进程延迟启动，并且只在 hub 进程的生命周期内存在。
- 技能通过元数据被发现，并且一次只加载一个。
- 第三方新增内容进入人工审批队列；模型不能自行批准可执行代码。

快速开始
要求：Node.js 22.19+ 和 pnpm。

git clone https://github.com/NeoXider/neoxider-mcp-hub.git
cd neoxider-mcp-hub
pnpm install --frozen-lockfile
pnpm test
pnpm client -- --json '{"action":"search","query":"demo"}'

默认目录仅包含一个内置的 echo MCP 和一个示例 ML 技能。测试不会下载或执行第三方包。

DeepSeek Harness 设置

安装已发布的打包文件——无需编辑路径，也无需在你的机器上构建：

dsh plugin --profile web add https://github.com/NeoXider/neoxider-mcp-hub/releases/download/v0.7.0/neoxider-mcp-hub-0.7.0.tgz

重启 Harness。该 hub 作为单个面向模型的原生工具在宿主进程内运行：

capability_hub

目录和状态默认位于已安装包的 data/ 目录。若要将它们保存在其他地方，请在配置文件的 cordis.patch.yml 中设置该行的 catalogPath / stateDir 配置。

手动替代方案是通过内置 MCP 客户端启动一个 stdio 子进程：构建 hub，然后将 examples/dsh/cordis.patch.yml 合并到活动的 Harness Web 配置文件中，并调整绝对仓库路径。重启 Harness。

pnpm build

Harness 将暴露一个面向模型的工具：

mcp__capability_hub__capability_hub

从以下内容开始：

{"action":"search","query":"web research"}

面向模型的契约

公共 schema 有意设计为扁平结构，以便 LM Studio 等受限解码引擎能够可靠地编译它。调用参数以结构化的 arguments 对象传递；其余载荷（配置、提案）以 JSON 字符串传递。

发现并调用一个工具：

{"action":"tools","name":"web-search-neo"}

{
"action": "call",
"name": "web-search-neo",
"tool": "web_info",
"arguments": {"topic": "search_status"}
}

可用的操作：

| 操作 | 用途 |
|---|---|
| search | 搜索精简的能力元数据 |
| inspect | 查看单个能力、权限、配置和环境状态 |
| configure | 通过 payloadJson 设置允许列表中的非机密值 |
| enable / disable | 启动或停止一个受信任的 MCP |
| tools | 列出子工具；schema 仍为可选 |
| call | 通过 arguments 对象代理一次子工具调用（payloadJson 也可用，但两者不得同时使用） |
| skill.load | 加载一个已批准的本地技能正文 |
| propose | 从 payloadJson 存储一个不受信任的提案 |
| proposals | 列出待处理的提案 |
| catalog.reload | 重新加载已批准的目录状态 |

真实集成示例

以下内容包含可供审查的现成提案：

- Web Search Neo — 动态网络研究和浏览器工具。
- Unity CLI MCP — 官方 Unity CLI 传输。其工具列表仅在连接了带有 Unity Pipeline 的 Unity Editor 时才会填充。
这些文件是示例，而非可静默信任的默认值。批准前请审查路径、版本和权限。

人工把关的安装

模型创建的提案存储在 data/state/pending 下，无法执行。请通过单独的人工操作命令进行批准：

node dist/src/admin.js approve  --catalog .\data\catalog.json --state .\data\state --yes

然后调用 catalog.reload 和 enable。优先使用固定版本的软件包或不可变的 Git 修订版本；避免在已批准的条目中使用浮动的 latest 安装程序。

目录、密钥和技能

- MCP 传输：stdio 和 streamable-http。
- 模板：${catalogDir}、${packageDir} 以及显式加入允许列表的 ${config:key} 值。
- 密钥：仅限环境变量引用。类似密钥的模型配置键会被拒绝。
- 技能：已批准的本地 Markdown 文件，按需加载，限制为 256 KiB。解析后的路径必须保持在目录/软件包目录之下；外部目录需要显式审查过的 skill.allowedRoots 条目。
- 状态：运行时配置和提案会被 Git 忽略。

严格 Harness 模型冒烟测试

可复用的冒烟测试会创建一个隔离的临时 DSH_HOME，强制使用 read-only 权限预设，并启动一个新的无头会话。其隔离的 hub 状态仅包含 Web Search Neo 和 Unity CLI 示例的已批准元数据；这两个能力都不会启动。该冒烟测试通过单个外层 hub 工具精确验证七次调用——search、inspect、tools、call（使用 2 + 3 的 add）、skill.load、status、disable——随后是精确的助手令牌 CAPABILITY_HUB_SMOKE_OK。重试、其他工具、缺失结果、工具错误或额外的最终文本都会导致验证失败。

data/state/smoke-receipts 下的紧凑 JSON 回执记录了最终助手文本、目录可见性、选定的 Harness 提供方/模型、权限预设、操作序列以及模型生命周期。在加载 LM Studio 之前，冒烟测试会检查进程列表：已加载的匹配模型会被复用，且绝不会被冒烟测试卸载；由冒烟测试加载的模型会在 Harness 证据回执持久化之后被释放（以 TTL 作为回退）。

pnpm smoke:harness

对于更严格的仅限源码检出的证明，可选的外部冒烟测试使用固定的本地 @playwright/mcp@0.0.79 开发依赖。Qwen 必须发现它、检查它、显式启用它、列出收窄后的导航工具、在一个惰性的 data: 页面上调用 browser_navigate、加载捆绑的技能、观察子进程运行、禁用它，最后观察到一个空的已启用列表。该回执会拒绝重试、任何第二个外层工具、工具错误、不同的模型、未验证的页面标题，或仍然处于启用状态的子进程。浏览器是无头且隔离的，仅写入临时冒烟测试主目录之下，并且该命令绝不会下载软件包：

pnpm smoke:harness:external
普通的 pnpm smoke:harness 仍然是快速的打包/离线契约冒烟测试，并且
不需要 Playwright。

在没有模型覆盖的情况下，默认的 lmstudio 冒烟测试会读取 lms ls --json，并以确定性的方式选择已安装的、trainedForToolUse 的最小 LLM（先按大小，再按 modelKey）。其 modelKey 也用作 Harness API 模型标识符。该冒烟测试从不下载模型。上下文为 32K，空闲 TTL 回退为一小时。显式覆盖会保留所请求的模型并禁用自动选择：

$env:CAPABILITY_HUB_SMOKE_MODEL = "another-api-identifier"
$env:CAPABILITY_HUB_SMOKE_MODEL_KEY = "installed-lm-studio-model-key"
$env:CAPABILITY_HUB_SMOKE_RECEIPT = "C:\receipts\capability-hub.json"
pnpm smoke:harness

当 Harness 安装在 C:\AI\work\deepseek-harness-runtime 之外时，设置 CAPABILITY_HUB_SMOKE_DSH_ENTRY。对于非 LM-Studio 提供方，设置 CAPABILITY_HUB_SMOKE_PROVIDER，并在需要时设置 CAPABILITY_HUB_SMOKE_PROVIDER_CONFIG_JSON；该脚本不会安装提供方或模型。

有关信任边界，请参阅 SECURITY.md。

当前范围

- 工具调用会被代理；子 MCP 资源和提示尚未桥接。
- 重新连接是显式的：先 disable，再 enable。
- 远程技能下载、签名验证和沙箱化安装程序是未来工作。
- 具有不受限主机 shell 访问权限的模型可以绕过插件本地策略；请将 Harness 权限用作外部边界。

配套项目

想要一个紧凑的动画桌面视图来展示代理、上下文、模型、推理和聊天？请参阅 NeoXider Agent Deck。

贡献

欢迎提交 issue 和有针对性的 pull request。新的集成应包含一个固定版本的示例、一份明确的权限描述以及一个端到端测试。

MIT © NeoXider