MCP 工具桥 Chhlafiu4312/dsh-mcp-bridge

dsh-mcp-bridge

ci
License: MIT

用一个文件将整个 MCP 生态系统连接到 DeepSeek Harness。零依赖。无需 SDK。

你的 DSH 智能体可以从任何 MCP 服务器获取所有工具——文件系统、GitHub、数据库、搜索、记忆，以及数千个社区服务器——作为它可以直接调用的原生工具：

You: Create a GitHub PR for the changes in ./app
Agent: [calls mcp_github_create_pull_request] ✓ PR #42 created

architecture

✨ 为什么人们使用它

| 🔌 一行代码接入 1000+ 工具 | MCP 生态系统是智能体最大的工具目录。这个桥接器将其全部接入 DSH。 |
| 🪶 零依赖 | 基于 stdio 的原始 JSON-RPC 2.0，约 400 行纯 JavaScript。无 SDK，无原生模块。 |
| 🌐 stdio + HTTP/SSE | 通过 command 连接本地服务器，通过 url 连接远程服务器（经由 mcp-remote 桥接）。 |
| 🔁 自动注册 | 服务器一连接，每个工具就变成 mcp__。 |
| 🧹 干净的生命周期 | 插件停止或更新时，子进程会被终止。 |
| 🛡️ 诚实的边界 | 不支持的 JSON-Schema 关键字会降级为开放输入——MCP 服务器始终是权威。 |

🚀 快速开始

A. dsh plugin add（推荐——该仓库是一个 dsh.bundle）

dsh plugin --profile web add "github:Chhlafiu4312/dsh-mcp-bridge#main"

然后重启 dsh web，并通过 DSH_MCP_SERVERS 配置服务器（见下文）。

B. 动态插件（单次会话，无需文件）

打开一个 DSH 会话，让你的智能体通过 cordis_define 运行桥接器（粘贴 plugin.js 中的代码），或者自己定义它——然后与它对话：

// code.host body — minimal form
return {
inject: ['subprocess', 'tools', 'timer'],
apply(ctx) {
// ... paste the body of plugin.js here ...
},
}

C. 永久方式（智能体预设）

1. create your preset directory
mkdir -p ~/.dsh/.agent-presets/mcp-agent

2. copy the repo files in
cp plugin.js ~/.dsh/.agent-presets/mcp-agent/
cp agent.cordis.yml.example ~/.dsh/.agent-presets/mcp-agent/agent.cordis.yml
cp preset.yml.example ~/.dsh/.agent-presets/mcp-agent/preset.yml

3. (optional) configure your servers
export DSH_MCP_SERVERS='[
{"id":"filesystem","command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","~/projects"]},
{"id":"github","command":"npx","args":["-y","@modelcontextprotocol/server-github"],"env":{"GITHUB_PERSONAL_ACCESS_TOKEN":"your_github_token"}}
]'

4. start a session on the mcp-agent preset — done

智能体会立即看到诸如 mcp_filesystem_list_directory、mcp_github_create_issue 等工具……外加 mcp_status 用于检查每个连接。

🔧 配置服务器是一个 JSON 数组。每个条目要么是 stdio，要么是 url：

{
"id": "my-server", // 工具前缀：mcp__ "command": "npx", // 可执行文件（仅 stdio）
"args": ["-y", "server-pkg"], // 可执行文件之后的 argv
"cwd": "/abs/path", // 可选的工作目录
"env": { "KEY": "value" }, // 可选的环境变量
"url": "https://x.example/mcp", // 或者：通过 mcp-remote 使用远程 HTTP/SSE "disabled": false, // 保持配置但不激活
"allowTools": ["search_"], // 可选：仅注册这些工具
"denyTools": ["delete_"], // 可选：隐藏这些工具
"timeoutMs": 120000 // 可选的每服务器调用超时 }

| 字段 | 类型 | 含义 |
| id | string，必填 | 工具前缀 —— 工具会变成 mcp__ |
| command + args | string + string[] | stdio 服务器可执行文件及其 argv |
| url | string | 远程服务器（HTTP/SSE，通过 mcp-remote 桥接） |
| cwd | string | 工作目录（默认：进程的 cwd） |
| env | object | 额外的环境变量 |
| disabled | boolean | 在 mcp_status 中列出，但从不连接或验证 |
| allowTools / denyTools | string[] | 精确名称过滤器，可组合使用 —— 隐藏破坏性工具 |
| timeoutMs | number | 每服务器调用超时，单位为毫秒（默认 120000） |

通过 DSH_MCP_SERVERS（JSON）设置该数组，或编辑 plugin.js 中 resolveServers() 里的默认值。现成的示例：examples/servers.json —— filesystem、GitHub、fetch、memory、Postgres、remote。

🧠 工作原理

详细说明见 docs/ARCHITECTURE.md：

DSH tools registry MCP server (child process)
───────────────── ───────────────────────────
mcp__ ── tools/call ──▶ npx (stdio)
◀── text/JSON ──── └─ or mcp-remote (HTTP)

1. 启动（Spawn） —— 每个已配置的服务器作为受管理的子进程启动。
2. 握手（Handshake） —— 通过换行分隔的 JSON-RPC 2.0 进行 initialize + notifications/initialized。
3. 发现（Discover） —— tools/list 返回每个工具及其 JSON Schema。
4. 注册（Register） —— 每个工具都注册到 DSH 工具注册表中；schema 被清理为 DSH 参数 DSL。
5. 调用（Call） —— 模型调用该工具；桥接层转发 tools/call 并将文本内容渲染回来（120 秒协作式超时，并发安全）。
6. 拆除（Teardown） —— 停止插件会注销这些工具并终止每个进程。

🛣️ 路线图

- [ ] 带退避的自动重连
- [ ] 原生 streamable-HTTP 客户端（为 url 服务器去掉 mcp-remote 依赖）
- [ ] 针对破坏性工具的每服务器权限提示

🔒 安全说明

- MCP 服务器以你的权限运行 —— 只连接你信任的服务器。
- 文件系统服务器是有作用域的：只给它 agent 可以访问的目录。
- API 令牌通过 env 字段传递；在生产环境中优先使用密钥管理器或环境变量。
- 完整信任模型与加固建议：SECURITY.md。

❓ 常见问题

我可以使用自己的 MCP 服务器吗？ 可以——任何通过 stdio 或可流式 HTTP 讲 MCP 的东西都可以。把 command/args 指向它（远程服务器则用 url），它的工具就会以 mcp__ 的形式出现。

服务器崩溃时会发生什么？ 桥接器最多重试 3 次，退避间隔为 2s/5s/10s，并在新连接上重新注册工具。用 mcp_status 查看当前状态。

更改配置后需要重启 DSH 吗？ 对于 dsh plugin/预设安装，需要——配置在插件启动时读取。disabled: true 会让某个条目保持已配置但不连接。

为什么不用官方 MCP SDK？ SDK 会把一棵依赖树拖进一个只需要换行分隔 JSON-RPC 的插件里。零依赖让安装瞬间完成且易于审查（约 400 行）。

它支持资源和提示词吗？ 支持——声明了这些能力的服务器会自动获得 mcp__list_resources、mcp__read_resource、mcp__list_prompts 和 mcp__get_prompt 工具。

从 0.7.0 之前的安装升级？ npm 包已重命名为 dsh-mcp-connect——请一次性移除旧依赖，以免两层同时激活：dsh plugin --profile web remove dsh-mcp-bridge。

基于 npx 的服务器失败并报 EPERM / “root 拥有的文件”？ 你的 npm 缓存被旧的 sudo npm 运行污染了。要么一次性修复它：

sudo chown -R "$(id -u):$(id -g)" ~/.npm

要么按服务器绕过它，给 npx 一个可写的缓存：

{ "id": "filesystem", "command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
"env": { "npm_config_cache": "/path/to/writable/npm-cache" } }

🤝 贡献

欢迎提交 issue 和 PR。node scripts/demo.mjs 会针对本地 fixture 打印一份一次性演示记录——这是制作 README GIF 的原始素材。包含测试 fixture：test/mcp-http-test-server.cjs 是一个最小的可流式 HTTP MCP 服务器，你可以在本地运行它来端到端验证 HTTP 路径。

📄 许可证

MIT——见 LICENSE。

dsh-mcp-bridge（中文）

一个文件，把整个 MCP 生态接进 DeepSeek Harness。零依赖，不用 SDK。

你的 DSH agent 可以直接调用任何 MCP server 的全部工具——文件系统、GitHub、数据库、搜索、记忆，以及社区里成千上万的 server：

你：把 ./app 的改动提一个 GitHub PR
Agent：[调用 mcp_github_create_pull_request] ✓ 已创建 PR #42

✨ 亮点

- 🔌 一行配置接入 1000+ 现成工具（MCP 生态是 agent 最大的工具目录）
- 🪶 零依赖：原生 JSON-RPC 2.0 over stdio，约 400 行纯 JavaScript
- 🌐 同时支持 stdio（本地 command）与 HTTP/SSE（远程 url，经 mcp-remote 桥接）
- 🔁 工具自动注册为 mcp__
- 🧹 插件停止/更新时自动清理子进程
- 🛡️ 不支持的 JSON-Schema 关键字安全降级，MCP server 始终是最终校验方

🚀 快速开始

A. 动态插件（单会话，不改文件）：在 DSH 会话中用 cordis_define 粘贴 plugin.js 的代码并运行。
B. 永久挂载（agent preset）：

mkdir -p ~/.dsh/.agent-presets/mcp-agent
cp plugin.js ~/.dsh/.agent-presets/mcp-agent/
cp agent.cordis.yml.example ~/.dsh/.agent-presets/mcp-agent/agent.cordis.yml
cp preset.yml.example ~/.dsh/.agent-presets/mcp-agent/preset.yml
export DSH_MCP_SERVERS='[{"id":"filesystem","command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","~/projects"]}]'

然后用 mcp-agent 预设开新会话即可。工具命名规则：mcp__，另有 mcp_status 查看每个 server 的连接状态。

🔧 配置

server 配置是一个 JSON 数组，每项支持 id / command / args / cwd / env（stdio）或 url（HTTP，经 mcp-remote 桥接）。通过 DSH_MCP_SERVERS 环境变量或编辑 plugin.js 里的 DEFAULT_SERVERS 传入。示例见 examples/servers.json。

🧠 工作原理

spawn 子进程 → initialize 握手 → tools/list 发现工具 → 消毒 JSON Schema 并注册为 DSH 工具 → 模型调用时转发 tools/call → 渲染文本结果（120 秒协作超时、并发安全）→ 插件停止时注销工具并终止进程。

🛣️ 路线图 / 🔒 安全提示

路线图：resources/prompts 支持、断线自动重连、原生 streamable-HTTP 客户端、危险工具的逐服务器授权确认。安全：MCP server 以你的权限运行，只连接可信 server；filesystem server 只授予必要的目录；API token 走 env 字段，生产环境请用密钥管理器。

📄 License

MIT — 见 LICENSE。