dsh-mcp — MCP 管理界面 + tool search：稳定工具列表、命中缓存、不撑爆上下文
English | 简体中文
支持版本：dsh 0.2.0-rc.2 —— 最新版本在 0.2.0-rc.2 上开发与验证，package.json → dsh.supported 同步声明。DSH 与插件两侧版本不匹配时，设置页会给出排查诊断（检查 bundle 是否已选中 → 重启 dsh web → 硬刷新 → 同步升级）。
设置页预览
为什么用 dsh-mcp？
解决的核心问题：
- MCP 工具全量注入烧 token：接入多个 MCP 服务器后工具可达上百个，每轮全量注入开销巨大。
search 按需检索模式让模型通过 mcp_tool_search 热注入所需工具，大幅节省 token。
- 工具列表反复更新破坏缓存：
tools/list_changed 通知会让同名工具被反复注销/重注册，系统提示词工具列表抖动、prompt cache 频繁失效。工具列表稳定化让未变化的工具保留原注册，最大化 cache 命中。
- 没有可视化管理入口：服务器配置、启停、工具勾选全靠手工改文件。Settings → MCP 一站式可视化完成。
功能优势：
- 可视化管理：服务器列表 / 新建 / 编辑 / 删除 / 测试连接 / 启停 / 刷新，全 UI 操作
- 进程级环境变量：全局 KV 配置（默认展开、支持批量添加）；stdio 服务器的子进程直接注入，streamable-http 服务器的请求头 value 写
变量名 或 ${变量名} 即可在连接时自动替换为配置值（如 Authorization: Bearer ${TOKEN}）；同名时服务器自身 env 优先
- JSON 全量配置：「JSON 维护配置」面板以一段 JSON 数组查看/编辑全部服务器配置，应用即保存（新增/更新/删除）
- 工具级精细控制：每个服务器展开工具列表，默认全选，可取消勾选只加载需要的部分
- 图片结果透传：MCP 工具返回的图片（截图/图表等）经附件服务投影为图片引用进入模型上下文，带严格预检与有界降级文案（PR #4）
- 双注入模式：
search（按需检索，省 token）与 full（全量注入）
- 零 npm 依赖：直接对接 DeepSeek Harness 内部能力，安装即用
- OAuth 认证支持：
streamable-http 服务器若走 MCP OAuth（授权码 + PKCE），服务器卡片点「OAuth 授权」按钮，由宿主打开系统浏览器完成授权，本页每 5 秒轮询授权状态；token 与 client 信息持久化、由 SDK 自动刷新（24 小时内活跃自动续期），失效后重新授权。授权完成前只显示「授权中」，授权失败会写明原因
- HTTPS 默认按系统证书校验：内网/公司 CA（只装在系统钥匙串里的根证书）无需再给
dsh web 加 NODE_OPTIONS=--use-system-ca，插件启动时把系统信任库并入 Node 默认根证书库
- 三种安装方式：npm / GitHub git 源 / 本地 link；中英文界面与文档
功能
- 托管 MCP 服务器注册表（host）：持久化定义（storage-domain
mcp_servers）、按服务器挂载
@deepseek-ai/dsh-mcp-client 实例、环境变量注入（明文入定义、secret 走 credentials）、
连接探测（test）。
- Web 设置管理页（client）：Settings → MCP，列表/编辑/删除/测试服务器。
- OAuth 认证（host，
lib/oauth.js）：streamable-http 服务器遇 401 + OAuth 挑战时走
授权码 + PKCE 流程，回环回调收码、token 持久化并按需自动刷新；设置页提供「OAuth 授权」按钮
（Remote oauthStart，浏览器由宿主用系统浏览器打开）与每 5 秒一次的 oauthStatus 轮询
（返回 pending / authorized / 失败原因），测试连接与挂载共用同一份 token。
- 系统证书校验（host，
lib/system-ca.js）：启动时把操作系统信任库的根证书并入 Node 默认库，
HTTPS 连接与 OAuth 发现/注册/token 交换因此按系统证书校验（Node < 24.9 时退回 undici Agent 定向 fetch）。
- Remote 自挂载：client 半部在
apply() 里自行 ctx.remote.$mount() 挂载 mcpManager
命名空间（原实现依赖 api-remotes 的 in-box 修改，独立版不再需要任何 in-box 包改动）。
- 读取声明式服务器（host，
lib/cordis-servers.js）：把 patch 层里原生声明的
@deepseek-ai/dsh-mcp-client 行一并展示到设置页（只读，见下节）。
声明式服务器（cordis.patch.yml）与优先级
DSH 原生支持在组合里直接声明 MCP 服务器：一行一台，name: '@deepseek-ai/dsh-mcp-client'，
放在 profile 级 $DSH_HOME/profiles/<profile>/cordis.patch.yml 或机器级
$DSH_HOME/cordis.patch.yml（机器级对所有 profile 生效，且按层级覆盖 profile 级同 id 行）。
- insert:
- id: mcp-github
name: '@deepseek-ai/dsh-mcp-client'
config:
transport: stdio # 或 streamable-http
serverName: github
command: npx
args: ['-y', '@modelcontextprotocol/server-github']
1.11.0 起，这些声明会出现在 Settings → MCP 列表中，标记「cordis 声明」，只读展示来源文件。
规则：
- 声明优先：同一
serverName 若已被 patch 层声明（且未 disabled），插件不再挂载存储里
的同名行——同名双挂载会撞工具注册表并让该服务器的工具整代回滚，页面会给出冲突说明。
- 只读：声明式服务器在本页不可启停/编辑，改配置请直接改
cordis.patch.yml（web/desktop
为 live reload，改完即生效；headless/sdk 等下次启动生效）。
- 导入 storages（镜像行）：启动与每次刷新会把声明导入存储 domain（id
cordis:<rowId>，
带 origin/declaredIn/declaredRowId 来源标记），只导入不覆盖——插件自建行永不被改写；
声明消失的镜像自动删除（镜像只是声明的副本，无主后不应堆积）；含 !!js 表达式的声明跳过导入并在页面标注
原因（值只能在 Loader 内求值）。镜像行永不挂载，挂载始终归组合。
- 接管 / 释放：点击「接管」后，插件在
cordis.patch.yml 的受管块内写入 id-targeted disabled: true
（首次写入前生成 .dsh-mcp.bak 备份；原子替换、幂等、可逆，只动该块），声明让出 serverName，改由插件挂载
同名行——由此启用 OAuth 授权、凭据托管、${VAR} 头替换、测试连接。挂载硬失败会自动回滚（移除受管块、
行退回镜像）并返回失败原因；「释放」把挂载交还声明行并删除插件行。缺少显式 id 或含 !!js 的声明不可接管。
- OAuth / 占位符限制（
needsPlugin）：声明行本身既不能携带 OAuth provider，也不能解析
${VAR}/裸变量名占位符——这两件事只有插件会做。因此这类声明只能由插件挂载：页面会把它们标为
挂载失败并说明原因（不是"连接中"），「释放」会让工具消失（确认框与结果告警都会提示），恢复只需
重新「接管」。
- OAuth 是显式开关（1.11.1 起）：服务器配置里的
oauth: true（设置页「使用 OAuth 授权」勾选，默认关）
才会挂 OAuth provider。用静态 token 或自定义头认证的服务器不要勾——否则它返回 401 时会被当成 OAuth
挑战，起 127.0.0.1:<port>/callback 回环回调。授权由设置页的按钮发起（见下节）：挂载阶段同一服务器
每个进程最多自动弹一次浏览器，未授权时页面显示「等待授权」并每 5 秒轮询状态，不报授权失败；
「测试连接」不再自动弹浏览器，而是返回需要授权的标记，由按钮打开授权页。升级时会按已有
OAuth 凭据自动迁移，真正需要 OAuth 的服务器不受影响。
- 热重载未提交时的安全降级：写入停用块后若原生工具 5 秒内没有注销（该 profile 的 patch 热重载未提交，
例如某个兄弟条目重建失败导致整代回滚），插件会登记接管但暂不挂载（管理行标记
pendingTakeover），
重启 dsh 后由插件挂载；「释放」在同样情况下会提示需要重启。此外，挂载前若发现同名 mcp__<server>__
工具已存在且不是本插件挂载的，一律跳过——任何情况下都不会与仍在挂载的声明行争抢同名工具。
- tool search 覆盖：检索/热注入与单工具开关按
mcp__ 前缀处理整个工具集，声明式服务器的
工具天然纳入，无需额外配置。
结构
dsh-mcp/
├── package.json name=dsh-mcp；dsh.bundle（自动注册）与 dsh.client 声明；零 npm dependencies
├── cordis.patch.yml bundle patch：安装后自动 insert 插件行（id/name = dsh-mcp）
├── lib/
│ ├── index.js host 半部（McpManagerService，源自 mcp-manager 构建产物）
│ ├── cordis-servers.js 读取 patch 层原生声明的 MCP 服务器（1.11.0）
│ ├── patch-writer.js 受管块写入器：接管时在 patch 文件里停用声明行（备份/原子/幂等）
│ ├── mcp-client.js vendored MCP 客户端（源自 @deepseek-ai/dsh-mcp-client，含工具列表稳定扩展）
│ ├── oauth.js MCP OAuth 客户端提供者（授权码 + PKCE、回环回调、token 持久化）
│ ├── system-ca.js 系统证书信任：把操作系统根证书并入 Node 默认库（1.14.0）
│ ├── probe.js vendored 连接探测（源自 mcp-client/src/probe.ts）
│ ├── transport.js vendored 传输工厂（源自 mcp-client/src/transport.ts）
│ └── client.js 浏览器半部（esbuild 打包，ModuleLoader wire format）
├── src/client/ 浏览器半部源码（TSX + CSS Modules + 本地 types + remote-contribution）
└── scripts/build.mjs 构建脚本（esbuild 取自 DSH checkout，见下）
构建
node scripts/build.mjs
- esbuild 从 DSH 源码 checkout 解析：
$DSH_SOURCE 未设置时尝试
~/.dsh/source/current。
- 运行时依赖（
@deepseek-ai/*、zod、@modelcontextprotocol/sdk）不装 npm 包，
从 $DSH_HOME/profiles/node_modules（DSH profiles 模块 fallback，$DSH_HOME 默认 ~/.dsh）解析；构建时经
nodePaths 指向同一目录。
- CSS Modules 由 esbuild onLoad 插件处理：样式注入
<style data-plugin="dsh-mcp" data-file="…">，默认导出 identity 类名映射。
测试
npm test
npm test 会自动适配环境：依赖 DSH 模块闭包（@deepseek-ai/*、js-yaml）的测试文件
（cordis-servers / patch-writer / takeover）在缺少本地 DSH 安装时会被跳过（公共 CI
即如此），本机（profile 的 node_modules 可达）则跑全量，并在输出里说明跳过了哪些文件。- 新增依赖 DSH 闭包的测试文件时，记得加进
scripts/test.mjs 的 NEEDS_DSH_CLOSURE 列表。
安装使用
1. 安装
方式一：Web 界面（推荐）
DSH Web → 设置 → 插件，填入包名 dsh-mcp（或本地目录的绝对路径）→ 安装。走的是与
dsh plugin add 相同的 pnpm 路径；1.13.0 起包内声明了 dsh.bundle，安装即自动注册为
profile 的 bundle 层（见第 2 节），不再需要手写注册行。
方式二：npm（发布到 npm 后）
dsh plugin --profile web add dsh-mcp
方式三：GitHub git 源
dsh plugin --profile web add github:ArvinQi/dsh-mcp
# 或
dsh plugin --profile web add git+https://github.com/ArvinQi/dsh-mcp.git
方式四：本地开发（link）
dsh plugin --profile web add link:<本仓库绝对路径>
注意：本地 link: 安装时，插件目录内含 node_modules -> $DSH_HOME/profiles/node_modules
symlink（本机开发用，不入库），否则 link: 安装的 symlink 被 realpath 后无法解析
@deepseek-ai/*。
2. 注册与生效（四种方式通用）
1.13.0 起自动注册，无需手写注册行。包内 package.json 声明了 dsh.bundle.patch，指向随包
发布的 <包目录>/cordis.patch.yml。DSH 在安装时会把包名写入
$DSH_HOME/profiles/<profile>/package.json 的 dsh.profile.bundles，该 patch 随即自动 insert
插件行（host 管理器与 client 设置页由同一行提供）：
# <包目录>/cordis.patch.yml —— 随包发布，bundle 被选中后自动生效
- insert:
- id: dsh-mcp
name: dsh-mcp
⚠️ 不要在自己的 $DSH_HOME/profiles/<profile>/cordis.patch.yml（或机器级
$DSH_HOME/cordis.patch.yml）里再 insert 同一行：同一 id 由两层声明会让 loader 组合失败。
这两个文件是用户 patch 层，和包内随包发布的 bundle patch 是两回事。
需要覆盖配置时用 id-targeted 条目（用户 patch 层在所有 bundle 层之后应用，且会替换整份
config，未列出的键回落到 Config 默认值）：
- id: dsh-mcp
config:
allowBrowserOnMount: true
从旧版（<1.13.0）升级的 profile：把原来那段 - insert: [{ id: dsh-mcp, name: dsh-mcp }]
换成上面的 id-targeted 覆盖，并让 dsh-mcp 进入 dsh.profile.bundles（Web 插件页把
dsh-mcp 显示为「已安装」后启用，或直接加进该数组）。
然后重启 dsh web，并硬刷新浏览器（Cmd/Ctrl + Shift + R）：
⚠️ 重启 + 硬刷新缺一不可：
- 设置页（client 半部）需要 client roster 生效，插件集变更必须重启
dsh web（刷新浏览器不够）；
- 重启后浏览器必须硬刷新（
Cmd/Ctrl + Shift + R），普通刷新可能仍使用缓存的旧页面。
3. 使用
打开管理页：重启后浏览器打开 DSH Web → 设置（Settings）→ MCP。
4. 常见问题排查
Q1：安装后设置页看不到「MCP」？
按顺序检查：
- 插件行是否已注册：
$DSH_HOME/profiles/web/package.json 的 dsh.profile.bundles 应含
dsh-mcp（Web 插件页里 dsh-mcp 应显示为「已安装 + 已启用」）。1.13.0 起安装自动写入；
旧版手工 insert 的 profile 按第 2 节改成 id-targeted 覆盖并把包选入 bundles——同一 id 由两层
声明不会生效。
- 是否重启了
dsh web：仅刷新浏览器不够——设置页入口来自 client roster，
插件集变更必须重启进程才进入 roster。
- 是否硬刷新了浏览器：重启后用
Cmd/Ctrl + Shift + R（Windows/Linux：Ctrl + Shift + R）
强制刷新；普通 F5 可能加载缓存的旧页面。
- 是否装到了正确的 profile：确认安装与注册都在
web profile
（dsh plugin --profile web add dsh-mcp + 该 profile 的 dsh.profile.bundles）；
装到其他 profile 则在其他 profile 的设置页查看。
- 是否为最新版本：npm 元数据缓存可能导致装到旧版，可强制指定版本
dsh plugin --profile web add dsh-mcp@latest（或 @1.8.0）。
Q2：设置页能看到「MCP」，但服务器列表为空/报错？
- 确认
dsh web 进程日志中 mcp-manager 没有初始化错误；
- 若升级过插件，请重启后硬刷新，避免旧 client bundle 与新版 host 不匹配
（典型现象：操作报
client api: ... 404 或 env is not iterable，都是新旧版本混用所致）；
- 报错形如
transport failure for /api/mcpManager/list: HTTP 404 表示宿主端没有注册
mcpManager 服务：多半是插件 host 半未生效（bundle 未被选入 dsh.profile.bundles，或装错
profile）或 client 与 host 版本不一致。请按 Q1 核对 bundles 与安装位置、重启后硬刷新；
仍不行则把 dsh web 与插件版本都升到最新再试。
Q3：MCP 工具没有出现在 agent 会话里？
- 确认对应服务器状态为「已连接」且工具已勾选（默认全选）；
- 注入模式为「按需检索」时，模型会通过
mcp_tool_search 检索后热注入，未检索到的工具不在
系统提示词中属正常现象；可切换到「全量注入」验证。
Q4：服务器配置了 Authorization 头却提示需要 OAuth 授权 / 挂载失败？
- 只要在请求头里配置了
Authorization（静态 Bearer/token），dsh-mcp 就不会把它当作 OAuth
服务器：真正的 OAuth（授权码 + PKCE）只对没有静态 Authorization 头的服务器启用，避免
401 被误当成 OAuth 挑战而打开浏览器授权。若你连的是需要静态 token 的服务器，确认请求头
正确即可；
- 若 https 内网域名报
fetch failed / unable to verify the first certificate，是宿主 Node
不信任公司内网 CA。1.14.0 起插件启动时已自动把系统信任库并入 Node 默认库（见「OAuth 服务器」下方的
系统证书说明），通常无需额外配置；仍失败时再检查系统钥匙串里是否装了该根证书，或临时用
NODE_OPTIONS=--use-system-ca / NODE_EXTRA_CA_CERTS 启动 dsh web 兜底，并重启宿主与硬刷新浏览器。
添加服务器：
- 点击「添加服务器」（表单在列表上方就地展开）
- 填写：服务器名称（
serverName，决定工具前缀 mcp__<serverName>__）、传输方式
（streamable-http 填 URL / stdio 填命令）、请求头、工具调用超时等
- 点「测试连接」确认连通性与工具列表，点「保存」
进程环境变量（注入模式下方，默认展开）：
- 配置全局键值对，供所有服务器使用：stdio 服务器的子进程直接注入，streamable-http 服务器用于请求头替换引用；secret 值写入凭据文档，留空保留原值
- process.env 优先：若变量在进程环境变量（
process.env）中已存在同名值，连接/展示时直接采用该值（不改名），
存储值仅作为兜底——请先在启动脚本里 export ADA_TOKEN=... 再重启 dsh web
- 支持「批量添加」（粘贴多行
NAME=value）与「添加变量」逐行添加
- 服务器请求头 value 可直接写变量名或
${变量名}（如 Authorization: Bearer ${GITLAB_TOKEN}），
连接时自动替换（优先级：服务器 env > 进程级 env > 系统环境变量）；stdio 子进程的环境与此一致，
同名时服务器自身 env 覆盖进程级 env
JSON 维护配置（MCP 配置模块右上角）：
- 以一段 JSON 数组查看/编辑全部服务器配置；应用后按列表全量替换（新增/更新/删除），
自动刷新列表与工具列表；JSON 面板展开时隐藏 UI 列表，应用后恢复
- 服务器级 env（含 secret 标记与 stdio 子进程注入）仍通过 JSON 配置维护
OAuth 服务器（streamable-http 走 MCP OAuth，如受 OAuth 保护的网关服务）：
- 正常填写 URL 并勾选「使用 OAuth 授权」；授权缺失时服务器卡片会出现 「OAuth 授权」按钮
（编辑页不再有自己的按钮，只保留勾选、一行说明与「授权中／授权成功」状态）
- 点击按钮由宿主打开系统浏览器（客户端
window.open 在 DSH 外壳里会被拒绝、只闪一下），
行上显示「授权中…」并每 5 秒检查一次授权状态；浏览器没起来时可以点行内的手动链接
- 授权成功后按钮消失、工具出现；失败会写明原因（如「授权失败: access_denied」），
回调消失则显示「授权未完成（可重试）」——授权完成前不会报失败
- token 与 OAuth client 信息持久化在凭据文档（按
serverName 隔离），由 MCP SDK 自动刷新
（24 小时内活跃自动续期）；失效后重新授权，授权一次后挂载与测试复用
- 已经
live 且有工具的服务器（静态 token 够用）不会被打上红色「未授权」，只保留一个普通授权按钮；
红色徽标/红色按钮只用于授权确实卡住挂载的服务器
- 第一次挂载（
allowBrowserOnMount，默认开）仍可能自动弹一次浏览器；把 profile 的
allowBrowserOnMount 设为 false 即可完全改为「按钮驱动」。非 OAuth 服务器不受影响，连接失败即时返回
HTTPS 内网证书：
- 插件启动时把操作系统信任库的根证书并入 Node 默认根证书库（
lib/system-ca.js），
streamable-http 连接、OAuth 元数据发现/注册/token 交换因此与浏览器、curl 的信任一致：
只要根证书装在系统钥匙串里（公司内网 CA、Zscaler/Sangfor 代理根等），就无需再设置
NODE_OPTIONS=--use-system-ca / NODE_EXTRA_CA_CERTS
- Node 自带根证书全部保留（并入而非替换，幂等）；宿主 Node 低于 24.9（无
tls.getCACertificates）时
退回用 undici Agent 携带系统根做定向 fetch，失败则维持原行为
日常管理：
- 启用 / 禁用：列表行按钮，禁用后该服务器所有工具即时注销，不再注入
- 刷新：重新拉取服务器状态与工具列表（服务器重启后可同步新工具）
- 测试连接：编辑页可随时测试
工具控制（省 token 的关键）：
- 注入模式：页面顶部切换
search（按需检索，默认）或 full（全量注入）
search 模式下，模型需要某 MCP 工具时调用 mcp_tool_search 检索并热注入当前对话
- 工具勾选：点「展开工具」查看该服务器全部工具（默认全选），取消勾选 = 不注入该工具，
即时生效，无需保存
验证效果：
- 在任意 agent 会话中，可用工具应包含
mcp__<服务器名>__<工具名>
search 模式下未检索到的工具不占系统提示词，节省 token 并提升 prompt cache 命中率- 工具内容未变化时，
list_changed 通知不会反复注销/重注册同名工具，工具列表保持稳定
版本注意
- host 半部
lib/index.js 是 mcp-manager 的构建产物（spec/types 已内联），改动请直接编辑
lib 下文件，或改回 TS 后重新用仓库工具链构建。
- 浏览器半部改
src/client/* 后重新 node scripts/build.mjs；host 半部改动无需重装
（link 安装直接生效）。
- 配置变更（bundles 增删、新插件行）需重启
dsh web 才进入 client roster。
- 每次发版都必须声明支持的 DSH 版本：在 CHANGELOG 对应条目与 GitHub Release notes 里加一行
- **支持版本**：dsh <版本>，并同步更新 package.json 的 dsh.supported 与 README 顶部的「支持版本」。
dshfind
