wings1848/dsh-mcp-lazy

dsh-mcp-lazy

CI
npm
node
license
中文

一个面向 DeepSeek Harness 的惰性 MCP 网关。它在模型面前只放置一个工具，而不是 N 个 MCP 工具 schema：服务器在首次使用时启动，空闲后再次退出，其工具元数据缓存在磁盘上，因此 search 和 describe 永远不会启动任何进程。

一个工具取代 N 个：原生注册会在每次请求时发送每个工具 schema 并让每个服务器常驻；dsh-mcp-lazy 只发送一个恒定 schema，并在首次使用时启动服务器

为什么

@deepseek-ai/dsh-mcp-client 会在启动时连接每个已配置的服务器，并将其每一个工具都注册为原生工具。正如其自己的 README 所说，工具描述和输入 schema“在工具注册期间进入每一次请求”。因此，几个服务器就会在每次请求中耗费数千个 token，并且每个服务器都会常驻一个子进程——无论模型是否真的调用它们。

本插件将面向模型的接口保持为恰好一个工具，其 schema 永不改变；它按需从磁盘缓存中发现工具，并且只在某次调用需要时才启动服务器。

数字

针对 chrome-devtools-mcp@1.6.0（29 个工具）测量，双方以相同方式渲染——工具定义的 JSON 字节数，然后每 token 四个字节：

| | 每次请求 |
| --- | --- |
| 原生注册 | 21252 字节 ≈ 5313 tokens |
| 本网关 | 1525 字节 ≈ 381 tokens |
| 节省 | 92.8% |

网关的数字是恒定的：再配置十个服务器也不会改变它，因为它们的 schema 是按需读取的，而不是每次请求都发送。

诚实的制衡。 网关有固定的 1525 字节成本，因此只有当某个服务器渲染后的工具定义超过该值时它才划算。捆绑的 fixture 提供 7 个小工具，节省降至 1.7%。一个只有几个极小工具的服务器会让网关变成净亏损。在假设之前，先测量你自己的：

pnpm run measure:savings                                          # local fixture
node scripts/measure-token-savings.mjs --npx

安装

dsh plugin --profile  add dsh-mcp-lazy

这会将包安装到 profile 中，并注册其 bundle patch，从而插入 mcp-lazy 行。然后在 profile 的 cordis.patch.yml 中给它你的服务器：

- id: mcp-lazy
config:yaml
servers:
- serverName: chrome
transport: stdio
command: npx
args: ['-y', 'chrome-devtools-mcp@1.6.0']
lifecycle: lazy
- serverName: docs
transport: streamable-http
url: http://127.0.0.1:3000/mcp

重启该 profile。每个字段都在 docs/configuration.md 中有文档说明。

将服务器从 @deepseek-ai/dsh-mcp-client 迁移出去

在这个生态系统中，每个 MCP 配置的写入方都会生成一行 @deepseek-ai/dsh-mcp-client：
config-manager 面板硬编码了该包名，@hyzyn/dsh-codegraph 会写入一行受管记录，
而手写的配置也遵循同样的约定。这样的一行会把每个 MCP 工具注册为真实工具，
于是它的 schema 会进入每一个请求——而一个同时列在两处的服务器会抵消掉
本插件存在的意义，且不会报错，也没有任何可察觉的迹象。（mcp({})
状态输出确实会警告你——对于另一个插件原生提供的任何服务器，无论本插件是否也提供它——这通常就是你发现问题的方式。）

adopt 会替你完成迁移：
bash
dsh-mcp-lazy-adopt                 # 试运行：打印计划，不写入任何内容
dsh-mcp-lazy-adopt --write         # 执行迁移，并为每个文件创建带时间戳的备份

或者，无需离开会话，作为斜杠命令执行：

/mcp-adopt                         # 试运行
/mcp-adopt apply                   # 写入

该命令驱动的是同一个 CLI，因此计划、备份和写入走的是同一条代码路径；一次
成功的 apply 之后会跟着一次重新规划，其结果会展示给你，所以“它成功了吗？”的答案
是证据，而不是一句保证。它仍然需要人工输入：插件启动时不会运行任何东西。

它会读取实际挂载的内容（dsh --profile  --dump-config，因此四个补丁层
都会被组合起来），将每个原始行就地标记为 disabled: true，并把该服务器追加到
本插件的 servers 列表中。文件中的其他内容都不会被改动——注释、空行和
!!js 表达式都逐字节保留——而它无法安全迁移的行会被报告出来，
并附上原因，而不是靠猜测处理。请在宿主停止时运行它：web profile
会实时重新加载其补丁层，而 dsh-config-manager 会根据自己的状态重写同一个文件。

在应用之前先检查影响范围。 原生行通常位于home 补丁中，
而每个 profile 都会读取它，本插件的行则位于某个 profile 的补丁中。因此，禁用
前者也会把该服务器从其他所有 profile 中移除——而那些 profile
没有网关来接收它，所以它们只会失去这项能力。计划中会列出它们：

⚠ the row being disabled lives in the home layer ~/.dsh/cordis.patch.yml, which every profile reads.
3 other profile(s) do not mount dsh-mcp-lazy, so they would lose codegraph with no replacement:
default, dsh-tui, headless.

如果它们需要，就在那些 profile 中挂载 dsh-mcp-lazy，或者把该行移到 web 自己的层中。

如果其中任何一个需要该服务器，在应用之前也把此插件挂载到那里（或移动该行）。

一个确实被移动的服务器到达时只带有此插件实现的字段。另一个插件的两个字段在此处未实现——reconnect 和 failOnStartupError——把它们带过来是错误而非无操作，因此设置了其中任何一个的行都会被报告为 unsupported-field 并原样留在原地：没有半移动，也不会因为一个看起来已配置却什么都不做的设置而导致加载失败。拼错的字段名也会以同样的方式被报告。每行的 id 会被丢弃，因为它命名的是加载器行而非服务器。

模型看到的内容

一个工具，始终是同样的 11 个参数：

mcp({ search: "screenshot" })          # 查找工具——读取缓存，不启动任何东西
mcp({ describe: "take_screenshot" })   # 完整的参数 schema
mcp({ tool: "take_screenshot" })       # 调用它——这才是启动服务器的操作
mcp({ tool: "echo", server: "docs" })  # 区分两个服务器共用的名称
mcp({ connect: "chrome" })             # 连接并刷新缓存，但不调用
mcp({ instructions: "chrome" })        # 服务器自己的使用说明
mcp({})                                # 状态：工具数量、连接状态、缓存年龄

这 11 个中有 7 个是上面的操作。另外 4 个用于塑造 search，其他任何情况都不需要：

| 参数 | 含义 | 默认值 | 限制 |
| --- | --- | --- | --- |
| regex | 将 search 视为正则表达式而非字面文本。 | false | — |
| includeSchemas | 在结果中包含每个匹配项的参数摘要。 | true | — |
| limit | 返回多少个匹配项。 | 12 | 40；被限制在 1–40 之间，绝不报错 |
| offset | 跳过这么多个匹配项，用于翻页浏览长结果。 | 0 | — |

默认情况下，这一个工具就是整个面向模型的表面。directTools 是可选项，它把选定的服务器工具提升为真正的原生工具——关于它接受什么，以及为什么默认是廉价的选择，请参见 docs/configuration.md。

文档

| | |
| --- | --- |
| docs/configuration.md | 每个字段、四种生命周期模式、输出上限 |
| docs/troubleshooting.md | 失败的服务器、冷缓存、名称解析 |
| docs/development.md | 构建、测试、为什么 link-dsh 是必需的 |
| docs/design.md | 为什么插件是这个形态：恒定的工具表面、缓存、生命周期、envFrom 以及 adopt 命令 |
| docs/parity-pi-mcp-adapter.md | 针对 pi-mcp-adapter v2.33.0 的逐模块对比，以及由此发现的缺陷 |

已知限制

v1 的边界，直白地说：

- 仅支持工具。 不支持 MCP 资源、提示词、采样或引导。仅订阅 tools/list_changed。
- 不支持 OAuth。 身份验证通过明文 headers 条目或环境变量进行。
- 图像和音频结果不会被转发。 它们会被投影为一行元数据条目（类型和字节数）。转发像素需要本插件未实现的附件存储。
- 没有审批门。 MCP 调用遵循你的 DSH 权限预设。
- 没有配置互操作。 它只读取 DSH 原生配置；不会导入 .mcp.json、Cursor、Claude Code、Codex 或 VS Code 的服务器列表。
- 正则守卫刻意收窄。 256 字符上限加上嵌套量词检查，这不会捕获像 (a|aa)+ 这样的重叠选择分支，或像 aaa*b 这样的多项式回溯。完整的分析器将意味着第二个运行时依赖。
- 不支持 SSE 或 unix-socket 传输。 仅支持 stdio 和 streamable-http。
- npx 不会被解析到底层二进制文件，因此通过 npx 启动的服务器会多消耗一个 Node 父进程。
- 通过 args 传递的密钥会落入子进程的 argv，ps 和 /proc//cmdline 可以读取它。这条路径之所以存在，只是因为某些服务器只接受以这种方式传入的令牌；仅使用 envFrom 可以让该值不进入 argv。

开发
bash
pnpm install
pnpm test          # builds, relinks the peer packages, runs 388 tests
pnpm run check     # typecheck, lint, build, then type-check the test sources

参见 CONTRIBUTING.md。

Star 历史

许可证

MIT — 参见 LICENSE。连接监督器、传输工厂和环境清理规则源自 @deepseek-ai/dsh-mcp-client；单代理工具网关、元数据缓存和加权搜索排名源自 pi-mcp-adapter。两者均为 MIT；其声明转载于 THIRD_PARTY_NOTICES.md。