MCP 工具桥 ZeroStub/dsh-mcp-bridge

dsh-mcp-bridge

MCP 工具接入 DeepSeek Harness——不用改 harness 本身。

Русский · English

为什么需要

DeepSeek Harness 没有 MCP——发行包里的任何一个包都没有客户端、没有服务端、也没有传输层。智能体能做什么，全都在 Cordis 组合里声明：工具集由预设决定，想接别人的服务器，官方没给路子。

Codex 遇到这种情况就省事多了：它自己就是 MCP 客户端，OpenClaw 则给它起一个 loopback MCP 服务器。这里只能自己写客户端。

dsh-mcp-bridge 是个 cordis 插件：从 OpenClaw 配置里读 mcp.servers，连上每个启用的服务器，再通过 ctx.tools.register 注册它的工具。模型看到的就是 harness 的普通工具。

效果

命名跟 OpenClaw 一致：mcp__<服务器>__<工具>。

mcp__vault__list mcp__search__query_text mcp__shell__list_hosts
mcp__vault__read mcp__search__similar mcp__shell__read_file

同一套安装里实测三个服务器：16 个工具走 streamable HTTP，7 个走 stdio，18 个走 legacy SSE——一共 41 个。

安装

包必须放在 harness 配置档的 node_modules 里——否则 @deepseek-ai/ 这些 peer 依赖解析不到。软链接不行：Node 按包的真实路径解析依赖。

cp -r . ~/.openclaw/extensions/dsh/node_modules/dsh-mcp-bridge

把下面这行加进承载智能体工具的组合（config/agent-presets/<预设>/agent.cordis.yml）：

- id: mcp-bridge
name: dsh-mcp-bridge
config:
configPath: ~/.openclaw/openclaw.json
toolPrefix: mcp__

注意：工具活在 agent-plane，不在 host-plane。 这行写进 config/cordis.patch.yml 能正常加载，但智能体一个工具都拿不到——host 补丁里没有任何 tool- 插件。

预设每个进程只挂载一次，所以这行要等下次启动 host 才生效，新开会话不算。

配置

| 字段 | 默认值 | 含义 |
| configPath | ~/.openclaw/openclaw.json | 从哪读 mcp.servers |
| servers | [] | 白名单；留空表示全部启用 |
| excludeServers | [] | 黑名单 |
| toolPrefix | mcp__ | 名称前缀 |
| timeoutMs | 60000 | 连接和 tools/list 的超时 |
| callTimeoutMs | 120000 | 单次调用的超时 |

筛选规则：服务器满足 enabled !== false、有 command 或 url、且没被排除，才会被选中。工具按服务器自己的 toolFilter.include / toolFilter.exclude 过滤。headers 和 env 里的 ${VAR} 引用从进程环境变量展开。

传输层

| 传输方式 | 工作方式 |
| stdio | 子进程，逐行 JSON-RPC |
| streamable-http | POST JSON-RPC；响应为 JSON 或 text/event-stream；会记住 mcp-session-id |
| sse（旧版） | GET 流声明 POST 端点；响应在同一流中返回 |

不启动 harness 也能验证

cd ~/.openclaw/extensions/dsh
node node_modules/dsh-mcp-bridge/test/probe.mjs # инструменты каждого сервера
node node_modules/dsh-mcp-bridge/test/register.mjs # прогон apply() на фейковом контексте

probe 会打印传输方式和工具。register 走完整条链路——读配置 → 连接 → defineTool → 注册——在启动宿主之前就能发现 schema 违规。两者都依赖 @deepseek-ai/* 包，所以必须在配置档内运行。

离线测试（不启动 harness）：npm test。

踩坑

- harness 的 schema 比 JSON Schema 更严格。 defineTool 会拒绝 required: false（「must be true when present」），并且要求任何对象的 additionalProperties 必须显式为布尔值。转换器已经处理了这一点。
- 包的符号链接会破坏 peer 解析——需要在配置档的 node_modules 里放一份副本。
- 请求头里的 token 可能过期。 如果服务器返回 401，检查一下取值：Bearer ${TOKEN} 这种引用比字面量更可靠。
- 动态模式无法加载包。 cordis_define 只接受 JS 函数体：不能用 import、require、fetch、process，也不能联网（web.fetch 仅支持 GET）。传输层只能挪到 shell 辅助脚本里。

限制

- 不支持 OAuth 服务器：需要在请求头里放密钥，或者用本地进程。
- 每个进程只有一个实例；工具对 harness 全局可见，具体组成由智能体预设限定。
- 没有按智能体划分的作用域：mcp.servers 是共享的，而 tools.allow / tools.deny harness 并不执行——只能靠桥的 servers / excludeServers 和服务端的 toolFilter 来区分。
- 启动失败的服务器会被跳过并给出警告；宿主不会因此崩溃。

许可证

MIT——见 LICENSE。