dsh-mcp
MCP 管理界面 + tool search：可视化配置、启用/停用、刷新 MCP 服务器并勾选工具，按需热注入检索结果；工具列表稳定命中缓存，不会使上下文膨胀。DeepSeek Harness 插件：MCP 管理界面 + tool search——工具列表稳定、便于缓存，不会使上下文膨胀。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add dsh-mcp@1.14.0Mcp 以 dsh-mcp 发布，当前版本为 1.14.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
English | 简体中文
支持版本：
dsh 0.2.0-rc.2—— 最新版本在0.2.0-rc.2上开发与验证，package.json→dsh.supported同步声明。DSH 与插件两侧版本不匹配时，设置页会给出排查诊断（检查 bundle 是否已选中 → 重启dsh web→ 硬刷新 → 同步升级）。
解决的核心问题：
search 按需检索模式让模型通过 mcp_tool_search 热注入所需工具，大幅节省 token。tools/list_changed 通知会让同名工具被反复注销/重注册，系统提示词工具列表抖动、prompt cache 频繁失效。工具列表稳定化让未变化的工具保留原注册，最大化 cache 命中。功能优势：
变量名 或 ${变量名} 即可在连接时自动替换为配置值（如 Authorization: Bearer ${TOKEN}）；同名时服务器自身 env 优先search（按需检索，省 token）与 full（全量注入）streamable-http 服务器若走 MCP OAuth（授权码 + PKCE），服务器卡片点「OAuth 授权」按钮，由宿主打开系统浏览器完成授权，本页每 5 秒轮询授权状态；token 与 client 信息持久化、由 SDK 自动刷新（24 小时内活跃自动续期），失效后重新授权。授权完成前只显示「授权中」，授权失败会写明原因dsh web 加 NODE_OPTIONS=--use-system-ca，插件启动时把系统信任库并入 Node 默认根证书库mcp_servers）、按服务器挂载
@deepseek-ai/dsh-mcp-client 实例、环境变量注入（明文入定义、secret 走 credentials）、
连接探测（test）。lib/oauth.js）：streamable-http 服务器遇 401 + OAuth 挑战时走
授权码 + PKCE 流程，回环回调收码、token 持久化并按需自动刷新；设置页提供「OAuth 授权」按钮
（Remote oauthStart，浏览器由宿主用系统浏览器打开）与每 5 秒一次的 oauthStatus 轮询
（返回 pending / authorized / 失败原因），测试连接与挂载共用同一份 token。lib/system-ca.js）：启动时把操作系统信任库的根证书并入 Node 默认库，
HTTPS 连接与 OAuth 发现/注册/token 交换因此按系统证书校验（Node < 24.9 时退回 undici Agent 定向 fetch）。apply() 里自行 ctx.remote.$mount() 挂载 mcpManager
命名空间（原实现依赖 api-remotes 的 in-box 修改，独立版不再需要任何 in-box 包改动）。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 等下次启动生效）。cordis:<rowId>，
带 origin/declaredIn/declaredRowId 来源标记），只导入不覆盖——插件自建行永不被改写；
声明消失的镜像自动删除（镜像只是声明的副本，无主后不应堆积）；含 !!js 表达式的声明跳过导入并在页面标注
原因（值只能在 Loader 内求值）。镜像行永不挂载，挂载始终归组合。cordis.patch.yml 的受管块内写入 id-targeted disabled: true
（首次写入前生成 .dsh-mcp.bak 备份；原子替换、幂等、可逆，只动该块），声明让出 serverName，改由插件挂载
同名行——由此启用 OAuth 授权、凭据托管、${VAR} 头替换、测试连接。挂载硬失败会自动回滚（移除受管块、
行退回镜像）并返回失败原因；「释放」把挂载交还声明行并删除插件行。缺少显式 id 或含 !!js 的声明不可接管。needsPlugin）：声明行本身既不能携带 OAuth provider，也不能解析
${VAR}/裸变量名占位符——这两件事只有插件会做。因此这类声明只能由插件挂载：页面会把它们标为
挂载失败并说明原因（不是"连接中"），「释放」会让工具消失（确认框与结果告警都会提示），恢复只需
重新「接管」。oauth: true（设置页「使用 OAuth 授权」勾选，默认关）
才会挂 OAuth provider。用静态 token 或自定义头认证的服务器不要勾——否则它返回 401 时会被当成 OAuth
挑战，起 127.0.0.1:<port>/callback 回环回调。授权由设置页的按钮发起（见下节）：挂载阶段同一服务器
每个进程最多自动弹一次浏览器，未授权时页面显示「等待授权」并每 5 秒轮询状态，不报授权失败；
「测试连接」不再自动弹浏览器，而是返回需要授权的标记，由按钮打开授权页。升级时会按已有
OAuth 凭据自动迁移，真正需要 OAuth 的服务器不受影响。pendingTakeover），
重启 dsh 后由插件挂载；「释放」在同样情况下会提示需要重启。此外，挂载前若发现同名 mcp__<server>__
工具已存在且不是本插件挂载的，一律跳过——任何情况下都不会与仍在挂载的声明行争抢同名工具。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
$DSH_SOURCE 未设置时尝试
~/.dsh/source/current。@deepseek-ai/*、zod、@modelcontextprotocol/sdk）不装 npm 包，
从 $DSH_HOME/profiles/node_modules（DSH profiles 模块 fallback，$DSH_HOME 默认 ~/.dsh）解析；构建时经
nodePaths 指向同一目录。<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 可达）则跑全量，并在输出里说明跳过了哪些文件。scripts/test.mjs 的 NEEDS_DSH_CLOSURE 列表。方式一：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_modulessymlink（本机开发用，不入库），否则link:安装的 symlink 被 realpath 后无法解析@deepseek-ai/*。
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），普通刷新可能仍使用缓存的旧页面。
打开管理页：重启后浏览器打开 DSH Web → 设置（Settings）→ MCP。
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 可能加载缓存的旧页面。web profile
（dsh plugin --profile web add dsh-mcp + 该 profile 的 dsh.profile.bundles）；
装到其他 profile 则在其他 profile 的设置页查看。dsh plugin --profile web add dsh-mcp@latest（或 @1.8.0）。Q2：设置页能看到「MCP」，但服务器列表为空/报错？
dsh web 进程日志中 mcp-manager 没有初始化错误；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 的服务器，确认请求头
正确即可；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 填命令）、请求头、工具调用超时等进程环境变量（注入模式下方，默认展开）：
process.env）中已存在同名值，连接/展示时直接采用该值（不改名），
存储值仅作为兜底——请先在启动脚本里 export ADA_TOKEN=... 再重启 dsh webNAME=value）与「添加变量」逐行添加${变量名}（如 Authorization: Bearer ${GITLAB_TOKEN}），
连接时自动替换（优先级：服务器 env > 进程级 env > 系统环境变量）；stdio 子进程的环境与此一致，
同名时服务器自身 env 覆盖进程级 envJSON 维护配置（MCP 配置模块右上角）：
OAuth 服务器（streamable-http 走 MCP OAuth，如受 OAuth 保护的网关服务）：
window.open 在 DSH 外壳里会被拒绝、只闪一下），
行上显示「授权中…」并每 5 秒检查一次授权状态；浏览器没起来时可以点行内的手动链接serverName 隔离），由 MCP SDK 自动刷新
（24 小时内活跃自动续期）；失效后重新授权，授权一次后挂载与测试复用live 且有工具的服务器（静态 token 够用）不会被打上红色「未授权」，只保留一个普通授权按钮；
红色徽标/红色按钮只用于授权确实卡住挂载的服务器allowBrowserOnMount，默认开）仍可能自动弹一次浏览器；把 profile 的
allowBrowserOnMount 设为 false 即可完全改为「按钮驱动」。非 OAuth 服务器不受影响，连接失败即时返回HTTPS 内网证书：
lib/system-ca.js），
streamable-http 连接、OAuth 元数据发现/注册/token 交换因此与浏览器、curl 的信任一致：
只要根证书装在系统钥匙串里（公司内网 CA、Zscaler/Sangfor 代理根等），就无需再设置
NODE_OPTIONS=--use-system-ca / NODE_EXTRA_CA_CERTStls.getCACertificates）时
退回用 undici Agent 携带系统根做定向 fetch，失败则维持原行为日常管理：
工具控制（省 token 的关键）：
search（按需检索，默认）或 full（全量注入）
search 模式下，模型需要某 MCP 工具时调用 mcp_tool_search 检索并热注入当前对话验证效果：
mcp__<服务器名>__<工具名>search 模式下未检索到的工具不占系统提示词，节省 token 并提升 prompt cache 命中率list_changed 通知不会反复注销/重注册同名工具，工具列表保持稳定lib/index.js 是 mcp-manager 的构建产物（spec/types 已内联），改动请直接编辑
lib 下文件，或改回 TS 后重新用仓库工具链构建。src/client/* 后重新 node scripts/build.mjs；host 半部改动无需重装
（link 安装直接生效）。dsh web 才进入 client roster。- **支持版本**：dsh <版本>，并同步更新 package.json 的 dsh.supported 与 README 顶部的「支持版本」。