dsh-project-mcp-bridge

English | 中文

一句话——让每个项目自己声明要用哪些 MCP 服务器。在项目根目录放一个 .dsh/mcp.json，该项目的所有会话就有了这些服务器的工具 （mcp__<serverName>__<toolName>），改文件即时生效——不用新开会话， 不用重启。

它是客户端桥接插件（消费 MCP 服务器）。不是 MCP 服务器，不是 DeepSeek 官方包。

30 秒上手

// 你的项目/.dsh/mcp.json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

然后，在该项目打开的任何会话里，模型可以直接调用 mcp__github__create_issue 等工具——与 Claude Code、Cursor、VS Code 相同的 mcpServers JSON 结构。 以后再改这个文件，运行中的会话约 1 秒内就会跟上。

安装一次：dsh plugin --profile web add dsh-project-mcp-bridge（重启一次）， 或见安装章节的免重启开发路径。

---

工作原理

agent 创建（agent/created）
  -> 读取 <会话 cwd>/.dsh/mcp.json
  -> 逐个服务器条目：
       - 若预设/宿主已有同名 serverName 且条目未设 "override": true
         -> 跳过（日志说明原因）
       - 否则做一次性 SCHEMA 同步：连接（stdio spawn 或
         streamable-http）+ 列出工具 + 以 mcp__<serverName>__<rawName>
         注册进 AGENT 层（仅该项目会话可见，优先级：项目 > 预设 > 宿主）
         + 随即关闭
  -> 不保留任何连接：空闲会话不占用任何子进程

第一次调用某服务器的工具（execute）
  -> 该 agent 的 controller 检查自己的按服务器连接
  -> 没有 -> 懒连接（日志提示 "connecting..."；这就是首次调用延迟）-> 调用
  -> 每次调用都重置一个按连接的空闲计时器（默认 5 分钟）；
     到时关闭连接、释放子进程；下次调用自动重连，对模型透明
  -> 连接意外死亡（onclose）-> 本 agent 丢弃死连接，下次调用重连
     ——无广播、无共享状态

连接是每 agent 独占、绝不池化：N 个会话调用同一服务器 = N 个独立 进程（隔离优先于共享）。从不调用某服务器的会话不占用任何进程。

安装

本包是 profile bundle：用 dsh CLI 安装，无需手动改任何配置文件。

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

dsh plugin 会在 profile 目录运行 pnpm，然后自动核对 dsh.profile.bundles：本包声明了 dsh.bundle.patch，会自动加入 profile 的 bundle 层。插件行由包自带的 cordis.patch.yml 提供——不需要手写任何 行。

装完重启一次 dsh web：bundle 层在启动时组合（只有用户补丁层和 settings.yaml 是热重载的）。重启之后，.dsh/mcp.json 的修改全部热生效 （见"配置热重载"）。

免重启开发路径（热安装）

如果你要反复改这个插件本身、希望改动不重启就生效，可以用用户补丁 行安装（而不是 bundle）。行内用包名引用（从 profile 的 node_modules 解析），可移植且热：

cd ~/.dsh/profiles/web
pnpm add dsh-project-mcp-bridge          # 装进 node_modules（不触发 reconcile）

然后在 ~/.dsh/profiles/web/cordis.patch.yml 追加：

- insert:
    - id: dsh-project-mcp-bridge
      name: 'dsh-project-mcp-bridge'     # 包名，不是 file:// 路径

用户补丁层热重载（约 4 秒），行会无需重启生效。注意：此路径不要用 dsh plugin add——那会同时注册 bundle，下次重启后产生重复行。日常使用 推荐 bundle 安装；此路径仅用于本机迭代。

项目配置

在项目根目录创建 .dsh/mcp.json（文件存在即 opt-in；没有该文件的项目 不受影响）：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" },
      "idleTimeoutMs": 300000
    },
    "local-api": {
      "url": "http://localhost:3000/mcp",
      "headers": { "Authorization": "Bearer ${MCP_TOKEN}" },
      "override": true
    }
  }
}

字段（与 dsh-mcp-client 同名）

字段	传输	必填	含义
transport	两者	—	推断：有 command → stdio；有 url → streamable-http；两者恰好其一
serverName	两者	是	工具命名空间（即 JSON 键）；[A-Za-z0-9_-]{1,32}
command	stdio	是	要 spawn 的可执行文件
args	stdio	否	参数
env	stdio	否	额外环境变量，合并到清理后的父环境之上
cwd	stdio	否	子进程工作目录（相对路径以项目根为基准）
url	http	是	MCP 服务器 URL
headers	http	否	额外请求头
toolCallTimeoutMs	两者	否	单次调用超时（默认 60000）
idleTimeoutMs	两者	否	空闲断开：连续这么多毫秒无调用即断开（默认 300000 = 5 分钟；0 = 永不空闲断开）
override	两者	否	即使预设/宿主已提供同名 serverName，也强制使用项目连接（默认 false）

env/headers 值中的 ${NAME} 占位符从宿主进程环境展开。

与预设/宿主级 MCP 的冲突语义

• 工具注册在 agent 层；分层注册表使同名工具遮蔽预设层与全局层—— 可见性优先级 项目 > 预设 > 宿主。
• 预设/宿主已提供的 serverName 默认跳过（每个 agent 对该服务只建一份 连接）；设置 "override": true 强制使用项目连接（接受双连接，项目版胜出）。
• override 不会关掉上层：项目连接是叠加上去的——上层（宿主/预设） 连接照常存活；agent 层的项目副本遮蔽同名工具（分层注册表），模型实际 调用的是项目连接。工具名不携带来源标记——插件在 override 覆盖了既有 上层注册时，日志会写明 shadows upper-layer registration(s); upper connections stay alive； 进程数量是另一个验证手段。
• 不同 serverName / 不同工具名天然共存。
• 注意——两种桥，两种哲学：官方 dsh-mcp-client 实例之间（宿主行、 预设行）同名 serverName 是进程级唯一，重复会导致挂载失败 （"pick a unique serverName"）——官方桥宁可用失败暴露配置错误，也不用 静默遮蔽。本插件的项目配置与上层同名时默认跳过，保证项目会话仍能 创建。实际含义：项目 vs 宿主/预设重复 → 跳过（本插件）；预设 vs 宿主 在 dsh-mcp-client 行之间重复 → 必须改名。

配置热重载

保存 .dsh/mcp.json 会为该项目所有运行中的会话重新解析并全量重建 每个会话的项目 MCP 表面：

• 新增服务器 → schema 同步 + 注册工具（运行中会话即时获得）
• 删除服务器 → 注销工具 + 关闭其连接
• 修改服务器 → 全量重建——注销全部、关闭全部连接、重读、重新注册。 不做指纹比较：改了就是重建。serverName 不变则公开工具名稳定，历史工具 调用可重放
• 删除配置文件 → 该项目的全部 MCP 工具卸载

无需新开会话。文件通过 fs.watchFile 轮询（约 500ms）+ 300ms 防抖检测， 并广播给该项目所有存活会话。被重配的服务器上正在执行的调用可能在重建 瞬间被中断。

连接死亡（v4）：服务器的进程若死亡，SDK 的 onclose 触发，该 agent 丢弃死连接；下一次调用自动重连（懒）——无需重启、无需新会话、无需 改配置。每个 agent 自管：无广播，一个会话里的死亡从不打扰另一个会话。 重连失败会以工具错误的形式浮现，下次调用再试。注意：重连后，服务器自身 的内部依赖（如浏览器连接）可能还需数秒就绪——该窗口内的调用可能以 服务器自己的错误失败；这是服务器行为，不是桥的缺陷。

空闲断开：连续 idleTimeoutMs 毫秒无调用即断开连接（默认 5 分钟； 按服务器配置，0 = 永不）。空闲会话不占子进程；下次调用自动重连 （仅多一次延迟）。

懒连接须知：工具 schema 只存在于服务器上，所以会话创建时每个被接受 的服务器会做一次短暂的 schema 同步（连接 + 列工具 + 注册 + 关闭）。从不 调用的服务器也只付出这一次短暂 spawn；之后不保留连接。若创建时 schema 同步失败（服务器没起来），该服务器的工具不会注册，直到下次配置变化或 新开会话。

环境变量降权

MCP 子进程使用官方 scrubbedParentEnv() 清理后的环境：剔除凭据形态的 变量名（匹配 KEY|PASSWORD|SECRET|TOKEN）与陈旧的 DSH_* 变量。 PATH、HOME 和区域设置保留，子进程正常运行；宿主环境里碰巧存在的 密钥不会被继承，只有条目显式声明的 env 会加回。这不是沙箱：恶意 配置仍能以你的用户身份执行代码、读取你的文件（见信任模型）。

信任模型 ⚠️

.dsh/mcp.json 是可执行内容——信任模型与 package.json 的 scripts 完全相同。git clone 的仓库可以自带 .dsh/mcp.json（正如可以自带恶意 postinstall），打开项目并创建会话时它就会执行。只打开你信任来源的 项目。插件缩小了爆炸半径（清理环境、可审计日志），但无法也不能让不 可信项目变安全。

日志

• ctx.logger（宿主 stdout——本部署不落盘）
• ~/.dsh/logs/dsh-project-mcp-bridge/dsh-project-mcp-bridge.log （追加式；每个环节——配置读取、跳过原因、连接、工具注册、关闭—— 都带时间戳与项目路径记录）

已知限制

• 只桥接工具能力：MCP 的 resources 与 prompts 不支持。
• 连接是每 agent 独占、绝不池化：N 个会话调用同一服务器 = N 个进程。 重服务器（如 chrome-devtools）每个活跃会话占一个进程——空闲超时让 不用的进程很快释放。会话创建时每个服务器还会付一次短暂的 schema 同步 spawn。
• 不支持 MCP 的流式/任务型执行（仅普通 call）。

延伸阅读

• 设计笔记：DSH 的哲学与本插件的对齐 · Design notes (English) —— DSH 为什么这样分层、 它的信任模型、热加载边界，以及"项目级 MCP 为什么是插件的活"。