项目级 MCP 桥接KYinCode/dsh-project-mcp-bridge

dsh-project-mcp-bridge

.dsh/mcp.json，该项目的所有会话就有了这些服务器的工具
（mcp____），改文件即时生效——不用新开会话，
不用重启。

它是客户端桥接插件（消费 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）
-> 读取 /.dsh/mcp.json
-> 逐个服务器条目：
- 若预设/宿主已有同名 serverName 且条目未设 "override": true
-> 跳过（日志说明原因）
- 否则做一次性 SCHEMA 同步：连接（stdio spawn 或
streamable-http）+ 列出工具 + 以 mcp____
注册进 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 为什么是插件的活"。