dsh-mcp-bridge

dsh plugin --profile web add dsh-mcp-bridge

dsh-mcp-bridge

一条命令给 DSH 装好 6 个精选 MCP 服务器，并告诉你哪些在你机器上真的能用。

什么时候需要它

• 想让 DSH 用上 MCP（浏览器自动化、会话记忆、文件访问），但不想手写六份配置、还要担心引号转义
• 某个 server 起不来，分不清是配置写错、包有问题，还是网络不通
• 想要一份「哪些 server 真的连得上」的清单，而不是再抄一遍上游文档

每个精选 server 都在 CI 里被真的启动、握手、数出工具数 —— everything 13 个工具，memory 9 个，filesystem 14 个。





一条命令装上经过实战检验的 MCP server 集合——而不是让你自己去琢磨一份 YAML。每个精选 server 在 servers/ 里有机器可读定义，scripts/verify-servers.mjs 会逐个检查连通性，所以「已验证」是 CI 保证的事实，不是宣传话术。

模型看到的工具名为 mcp__<serverName>__<toolName>（与 Claude Code / Codex 的服务器限定命名一致）。桥接层是 DSH 内置的 @deepseek-ai/dsh-mcp-client：支持 stdio / streamable-http、自动重连、HMR 热替换。

English docs: [README.md](README.md).

反馈

下载量能看出装了多少次，看不出有没有用。如果你在用，一句话说明你拿它做什么，比点个 star 有用得多——尤其是没跑通的情况，那是最不会有人主动说的：

• 你想做什么
• 它做到了吗
• 缺什么、哪里不对

[开个 issue 说一句](../../issues/new?template=usage.yml) —— 如果是明确的 bug，直接开普通 issue 就行。

交互式安装器

npx dsh-mcp-bridge init          # 交互式选择服务器
npx dsh-mcp-bridge list          # 查看目录 + 验证状态
npx dsh-mcp-bridge validate      # 列出 profile 里已配置的 MCP 条目

init 会把真正的 insert: 条目写进 profile 的用户 patch 层

（$DSH_HOME/profiles/<name>/cordis.patch.yml）——所以你选的服务器能跨插件升级保留，

并和你自己的 patch 共存。需要环境变量或占位路径的服务器会给出警告。

为什么不自己配？

因为难的不是 YAML，而是它周围的一切。

• 用户 patch 层是覆盖语义：在那里写一个新 id 会报 patch: entry "x" not found，新服务器必须用 insert:。
• 配置少缩进一层会被解析成 config: null，服务器静默地永远不启动。
• 连上了但没暴露工具的服务器，和正常工作的服务器长得一模一样，直到你问模型。

这个包提供了可用的写法、会写对的安装器（init）、检查器（list、validate），以及一个真的会去连接的验证器。

快速开始

前置条件：dsh 与 pnpm 在 PATH 上（dsh plugin 内部转发 pnpm；未装可 npm i -g pnpm）。

dsh plugin --profile web add dsh-mcp-bridge
# 本地开发：  dsh plugin --profile web add ./dsh-mcp-bridge
dsh web        # 重启 profile

默认启用 MCP 官方 everything 演示 server（无 API key，纯本地 npx）。重启后让模型「调用 everything 服务器的 echo 工具，传 hello」，它应该会用 mcp__everything__echo。

首次运行会通过 npx 下载 server 包，之后有缓存。

精选目录

Server · 能干什么 · 需要的配置 · 验证状态

everything · 演示工具：echo、add、长任务、小图片 · 无（默认开启） · ✅ 13 个工具

memory · 会话内知识图谱（实体/关系） · 无 · ✅ 9 个工具

filesystem · 文件读写/搜索，仅限显式授权的根目录 · 改 root 目录（args） · ✅ 14 个工具（给定真实目录时）

github · 仓库 / issue / PR · GITHUB_TOKEN · ⏸ 需配置

playwright · 浏览器自动化（导航/点击/截图） · 首次需下载浏览器 · ⏸ 较重，CI 跳过

remote-http · 自建 / 托管的 HTTP MCP server · URL（可选 token） · ⏸ 需配置

启用某个注释预设：在 profile 的 cordis.patch.yml 里取消对应注释块（HMR 热替换，无需重启），或直接改本包的 cordis.patch.yml。

自己验证目录

npm install          # 会带入 @deepseek-ai/dsh-mcp-client → MCP SDK
npm run verify       # 或：node scripts/verify-servers.mjs

逐个打印 PASS / SKIP / FAIL，有失败时退出码非 0。VERIFY_TIMEOUT_MS=15000 可调单 server 超时。单 server 排障：node scripts/probe-server.mjs npx -y your-mcp-server。

添加自己的 MCP server

每个 server 就是一条 @deepseek-ai/dsh-mcp-client 条目。推荐加到 profile 的用户 patch 层（HMR 即时生效）：

# $DSH_HOME/profiles/<name>/cordis.patch.yml
- id: mcp-myserver
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: myserver          # 命名空间，进程内唯一（[A-Za-z0-9_-]{1,32}）
    transport: stdio              # 或 streamable-http
    command: npx
    args: ['-y', 'your-mcp-server']
    env:
      YOUR_TOKEN: !!js process.env.YOUR_TOKEN

或者：把定义放进 servers/（这样 verify 会覆盖它），并在本包 cordis.patch.yml 里加对应条目。

配置字段速查（来自 dsh-mcp-client）

字段 · 传输 · 必填 · 说明

transport · 两者 · 是 · "stdio" 或 "streamable-http"

serverName · 两者 · 是 · 工具命名空间，存活实例内唯一

command / args / env / cwd · stdio · command 必填 · 子进程规范

url / headers · http · url 必填 · 端点 + 认证头

toolCallTimeoutMs · 两者 · 否 · 单次调用超时，默认 60000

failOnStartupError · 两者 · 否 · 连接失败时拒绝激活（默认 false）

reconnect.* · 两者 · 否 · 自动重连退避（默认开启）

与 Reasonix / CodeWhale 联动

三者都是 agent harness——MCP 就是共同语言。你给 Reasonix / CodeWhale 配的任何 server 都能加到这里；自建的 streamable-http server 可以让 DSH、Reasonix、CodeWhale 共用一个进程。见 servers/remote-http.json。

排错（Windows）

• headless 验证挂起（dsh --profile <name> "任务"）：profile 需要在 dsh.profile.bundles 里手动加 @deepseek-ai/dsh-headless（dsh plugin add @deepseek-ai/dsh-headless 会因其未发布依赖 404 失败）。缺它时树能激活但没有 agent 消费任务。
• Windows 下 npx 正常可用：MCP SDK 使用 cross-spawn，能解析 .cmd shim，不需要 npx.exe。
• server 连上了但没有工具：看 profile 日志；failOnStartupError: false 时失败条目会静默激活但不注册工具。

发布（npm）

1. npm version patch（或手动改 package.json），提交，打 tag vX.Y.Z。

2. git push origin main --tags。

3. GitHub Actions（publish.yml）自动发布到 npm——需要 npm trusted publisher（OIDC）关联仓库。设置：npm → Access Tokens → Generate new token → Publish with GitHub Actions。

给仓库打上 GitHub topic dsh-plugin，这样会出现在社区列表里（awesome-dsh-plugin、WhaleHub）。

License

MIT — 见 [LICENSE](LICENSE)。

相关

属于 dsh-toolkit 家族 —— 一组各自独立可用的小工具，面向 DeepSeek Harness：

• dsh-mcp-bridge —— 一条命令装好 6 个精选 MCP server，CI 逐个验证
• dsh-win-toolkit —— Windows 剪贴板、通知、hosts、端口检测
• dsh-netassist —— 网络与代理诊断，直接告诉你下一步
• dsh-driftwatch —— 两次会话日志的行为漂移报告
• dsh-ledger —— agent 到底动了哪些文件，且记录不可篡改

-

…(truncated)