MCP 懒加载代理 sehoon123/dsh-mcp-adapter

dsh-mcp-adapter

为 DeepSeek Harness 提供省上下文、抗崩溃的 MCP 接入：用一个懒加载代理工具，替代把所有服务商的 schema 全塞进上下文。零依赖。

DSH 原本的规则是一个插件 = 一个 MCP 服务商，服务商的每个工具都直接注册——于是它的完整 JSON schema 会出现在每一轮的提示词里，不管你用不用。接几个服务商，每个带几十个工具，对话还没开始就能烧掉 20k+ token。

这个插件换了个做法：只留一个 mcp 代理工具（约 200 token）。模型按需搜索工具，服务商只在真正用到时才连接，而你常用的工具可以提升回一等工具，调用依然零延迟。它只围绕一条压倒一切的要求来写：绝不能搞崩 DSH，不管 MCP 服务商怎么乱来。

灵感来自 pi-mcp-adapter 以及更广泛的「你可能并不需要 MCP」讨论；针对 DSH 的工具注册表重写，无运行时依赖，核心以可靠性优先。

用数字看问题

三个服务商——Burp（10 个工具）、Chrome DevTools（15 个）、一个检测平台（70+ 个）：

| | 原生 DSH（全部直连） | 用这个适配器（混合） |
| 每轮提示词 token | ~21,000 | ~3,200 |
| 启动时的服务商进程 | 3 个全在跑 | 首次使用前为 0 |
| 服务商挂了 | 带内报错 / 重试 | 快速失败，DSH 不受影响 |
| 3 MB 的工具结果 | 淹没上下文 | 截断 + 溢出到文件 |

70 个工具的服务商最要命：直连时每条消息都要花约 16k token，哪怕你只是在做 Web 测试。放到代理后面只花约 200 token，而且你不调用它，进程根本不会启动。

安装

git clone https://github.com/sehoon123/dsh-mcp-adapter.git
mkdir -p ~/.dsh/profiles/node_modules/@deepseek-ai
cp -R dsh-mcp-adapter ~/.dsh/profiles/node_modules/@deepseek-ai/dsh-mcp-adapter

~/.dsh/profiles/<profile>/cordis.patch.yml
- insert:
- id: mcp-adapter
name: '@deepseek-ai/dsh-mcp-adapter'

用标准 mcp.json 指向你的服务商（Claude Desktop、Cursor、pi 用的都是同一个文件——见配置），然后重启 dsh。不需要 API key，不需要守护进程，不需要 Docker。

我需要关掉 DSH 默认的 MCP 吗？

不用——没有什么全局开关要关。 DSH 默认不启用任何 MCP 服务商；每个服务商都是一个显式的 @deepseek-ai/dsh-mcp-client 你自己加的那一行。所以没有「默认 MCP」开关可以关掉。

这个适配器和原版 dsh-mcp-client 不会冲突。 它们注册工具时用的命名空间不同，所以两个都挂上也不会出问题：

| | 注册的工具名 |
| 原版 dsh-mcp-client | mcp__<server>__<tool>（双下划线） |
| 这个适配器 | mcp（代理）和 mcp_<server>_<tool>（单下划线，用于 directTools） |

唯一不该做的事，是把同一个服务器同时走两条路——那样你会同时拿到完整的 schema 转储和该服务器的代理，白白浪费你想省下的上下文。每个服务器只选一条路。两种干净的配置：

A —— 全部走适配器（推荐；上下文占用最低）。 删掉你的 dsh-mcp-client 行，把所有服务器都列进 mcp.json。把经常用的服务器用 directTools 提升为直连，让它们保持零延迟调用：

cordis.patch.yml — remove any - id: mcp-<server> (dsh-mcp-client) rows, keep only:
- insert:
- id: mcp-adapter
name: '@deepseek-ai/dsh-mcp-adapter'
// ~/.dsh/mcp.json
{
"mcpServers": {
"burp-suite": { "type": "http", "url": "http://localhost:9876/mcp",
"headers": { "Authorization": "Bearer <token>" }, "directTools": true },
"chrome": { "command": "npx", "args": ["-y", "chrome-devtools-mcp"],
"directTools": ["take_screenshot", "click", "navigate"] },
"falcon": { "command": "npx", "args": ["-y", "@crowdstrike/falcon-mcp"] }
}
}

B —— 留几个服务器走原版，其余走适配器。 也可以，因为命名空间不冲突。比如 Burp 保留为 dsh-mcp-client 直连行，只把体积大、偶尔才用的服务器（Falcon 等）放到适配器后面。只要别把同一个服务器同时列在两处就行。

TL;DR：没有要禁用的东西；两者可以共存；只是别让同一个服务器走两条路。

模型怎么用它

模型只看到一个工具 mcp，带四个 action：

mcp({ action: "list" }) // what servers exist
mcp({ action: "search", query: "screenshot" }) // find tools by keyword
mcp({ action: "describe", server: "chrome", tool: "take_screenshot" }) // see its params
mcp({ action: "call", server: "chrome", tool: "take_screenshot", args: { … } }) // run it

search 和 describe 由离线元数据缓存作答，所以模型不用连任何东西就能摸清整套工具。只有 call（以及针对尚未缓存的服务器的 describe）才会真正建立连接。

全新安装时缓存是空的，所以第一次 search 会先透明地预热它从未编目过的服务器（每个服务器都有超时限制，失败就忽略），然后再作答。连不上的服务器会在结果里点名，而不是悄悄消失。

混合模式：把经常用的工具提升为直连

先搜索会多一次往返。对于你一直调用的那少数几个工具，时，设置 directTools，它们会注册成普通 DSH 工具——零搜索延迟——而长尾工具仍留在代理后面：

{
"mcpServers": {
"burp-suite": {
"type": "http",
"url": "http://localhost:9876/mcp",
"headers": { "Authorization": "Bearer …" },
"directTools": true // small server: promote everything
},
"chrome": {
"command": "npx",
"args": ["-y", "chrome-devtools-mcp"],
"directTools": ["take_screenshot", "click", "navigate"] // promote the hot path
},
"falcon": {
"command": "npx",
"args": ["-y", "@crowdstrike/falcon-mcp"]
// 70+ tools, occasional use → stays behind the proxy, process idle until used
}
}
}

提升后的工具显示为 mcp_<server>_<tool>，直接调用服务器。

可靠性

这里每个设计决策都服务于「别让 DSH 崩溃」。适配器用故意注入故障的方式测试过——服务器在调用中途崩溃、永久挂起、发出畸形帧、无故退出、或者根本起不来——每种情况下故障都会变成一个干净的错误值，绝不会变成异常逃进 harness。

- 单次结算的 JSON-RPC 核心。 每个请求只结算一次——收到回复、超时、或传输关闭时。超时后迟到的回复会被忽略，而不是抛出；管道断开会让挂起的请求 reject，而不是一直挂着。
- 处处硬超时。 每个请求都在 unref 过的定时器上有截止时间，所以沉默的服务器永远卡不住一轮，挂起的调用也永远不能独自撑住进程。
- 懒连接 + 单飞。 服务器只在首次使用时才联系，并发的首次使用共享一次连接尝试——绝不会爆发式启动进程。
- 熔断器。 连续连接失败后熔断器打开，并采用指数退避，所以挂掉的服务器（Burp 关了、二进制没装）会快速失败并给出清晰消息，而不是被反复捶打。
- 透明重连。 过期的 HTTP 会话（404）或断开的 stdio 管道会重连一次并重试调用。
- 空闲拆除。 连接超过超时未使用就关闭，释放子进程，下次使用时再重建。
- stdio 崩溃隔离。 子进程启动错误（ENOENT）、管道断开（EPIPE）、无帧洪流都在流边界被捕获并转成干净的关闭；SIGTERM→SIGKILL 升级保证关停。
- 输出护栏。 结果超过大小预算时保留头部预览，把全文溢出到 mode-0600 临时文件，并告诉模型怎么读剩下的——所以一个大的扫描结果不会撑爆上下文或这一轮。
- 防损坏状态。 畸形的 mcp.json 层会被跳过并给出警告（启动继续）；损坏的缓存降级为空；缓存写入是原子的（临时文件 + 重命名）且 0600。

配置

mcp.json 从这些位置读取，优先级从低到高（后面的文件每个服务器的配置会覆盖前一个，与 pi-mcp-adapter 保持一致，这样你就能复用已有的文件：

~/.config/mcp/mcp.json
~/.agents/mcp.json
~/.agents/mcp/mcp.json
~/.pi/agent/mcp.json (compatibility source)
$DSH_HOME/mcp.json (default ~/.dsh/mcp.json)
<cwd>/.mcp.json
<cwd>/.dsh/mcp.json

借用的 Pi 配置排在 harness 自己的文件之下：它只是兼容来源，不是权威。（如果顺序反过来，同时出现在两处的服务器会丢掉 DSH 独有的字段——Burp 条目上的 directTools: true 就被悄悄丢掉了。）

运维可见性：/mcp

代理会把工具 schema 对模型隐藏，这也会对你隐藏。/mcp 展示实际发生了什么：

🔌 MCP Adapter status

- burp-suite [http] — ⚫ idle (connects on first use)
• tools: 0
• promoted as direct tools: all
- chrome [stdio] — 🟢 connected
• tools: 29 (29 cached for offline search)
• promoted as direct tools: take_screenshot, click, navigate, evaluate_script, list_pages

/mcp refresh 会重新读取每个服务器的工具目录。

单服务器选项

| 字段 | 含义 |
| type | http / stdio（省略时根据 url 还是 command 推断） |
| url、headers | HTTP 传输端点和静态请求头（如 Authorization） |
| command、args、env、cwd | stdio 传输的启动参数 |
| disabled | 完全跳过这个服务器 |
| directTools | true（全部提升），或 ["name", "glob_*"]（提升一部分） |
| requestTimeoutMs | 覆盖这个服务器的单请求超时 |
| idleTimeoutMs | 这个服务器的空闲断开超时 |

插件选项（写在 cordis.patch.yml 里）

| 字段 | 默认值 | 含义 |
| servers | – | 内联服务器映射（合并到 mcp.json 之下） |
| readConfigFiles | true | 读取 mcp.json 文件；设为 false 则只用内联配置 |
| requestTimeoutMs | 60000 | 默认单请求超时 |
| idleTimeoutMs | 300000 | 默认空闲断开时间 |
| toolTimeoutMs | 120000 | mcp 工具自身的预算 |
| maxOutputBytes | 51200 | 内联输出的字节上限，超出则转存 |
| maxOutputLines | 2000 | 内联输出的行数上限，超出则转存 |
| proxy | true | 注册 mcp 代理工具 |

零依赖

"dependencies": {}。两种传输（stdio 和 Streamable HTTP + SSE）、JSON-RPC 核心、配置加载、元数据缓存、排序搜索、输出守卫，全部基于 Node 内置模块从零写起。DSH 插件会在不同的 node_modules 目录之间复制（npx/pnpm 缓存和 $DSH_HOME/profiles），在那里 npm 依赖可能解析不到，所以不依赖任何东西才能保证它在哪都能加载。参考实现 pi-mcp-adapter 引入了 MCP SDK 等一堆东西；这个没有。

测试

npm test # all three suites
node test/stdio.test.mjs # stdio transport vs a real child server
node test/http.test.mjs # HTTP/SSE transport vs a real node:http serverbash
node test/suite.test.mjs # config, cache, search, guard, manager (fault injection)

108 个测试全部通过。 这些测试套件会启动真实的 MCP 服务器（一个忠实还原的 mock，可以命令它崩溃、挂起、刷爆 stdout、忽略 SIGTERM、卡住响应体，或者用 CRLF 给 SSE 分帧），并断言各项可靠性不变量：请求总能落定，崩溃会 reject 而不是挂起，熔断器会打开，过期连接会重连，超大输出会溢出到 0600 文件，四服务器故障风暴产生零个未处理的 rejection。

测试套件为安全/可靠性审计中发现的每个问题都写了明确的回归测试：无界 stdout 洪水现在会被截断，子进程会被回收（不 OOM，不留孤儿）；HTTP 响应体读取期间的超时映射为 MCP_TIMEOUT（而不是裸的 AbortError）；CRLF 分帧的 SSE 能正确解析；stop() 在快速退出时立即返回，但对顽固子进程仍会 SIGKILL；长期存活的 AbortSignal 在大量请求中不会累积泄漏的监听器。

在真实 dsh 实例里用 Burp/Chrome/Falcon 形状的配置做了端到端验证：mcp 工具和提升后的直接工具都能注册，懒连接正常工作（空闲服务器保持空闲），四个动作全部成功，3 MB 结果溢出到临时文件，调用离线服务器返回干净的错误，同时 DSH 继续运行。

与 pi-mcp-adapter 的差异

采纳： 单代理概念、directTools 提升、用于搜索的离线元数据缓存、带临时文件溢出的输出防护，以及标准 mcp.json 优先级。

有意不同： 零运行时依赖（不用 MCP SDK）；可靠性优先的连接核心，带显式熔断器和单飞连接；通过 harness 自身工具所用的同一 inject 契约接入 DSH 工具注册表；更精简的表面——没有 OAuth 浏览器流程，没有交互式设置 UI，没有宿主配置自动发现。这些以后可以加，但要获得上下文开销低、可靠的 MCP 访问并不需要它们。

项目结构

lib/
├── index.js plugin entry: config load, wiring, registration
├── transport/
│ ├── jsonrpc.js single-settle JSON-RPC 2.0 core
│ ├── stdio.js child-process transport (crash/EPIPE-safe)
│ └── http.js Streamable HTTP + SSE transport
├── core/
│ ├── config.js layered mcp.json loader (corruption-safe)
│ ├── cache.js atomic 0600 metadata cache (offline search)
│ ├── search.js field-weighted tool ranking
│ ├── output-guard.js truncate + spill oversized results
│ └── server-manager.js lazy connect, single-flight, breaker, reconnect
└── tools/
└── proxy.js the mcp meta-tool + directTools promotion

License

MIT