dsh-mcp-client-manager
在 设置 → ANB 工具 →「MCP 客户端」 里管理挂在 @deepseek-ai/dsh-mcp-client 下的 MCP 服务器行:列出 / 添加 / 改写 / 启停 / 删除。点保存才写盘,写完不重启宿主。
MIT · 独立社区插件 · 与 DeepSeek、DeepSeek Harness 无隶属关系,亦未获其赞助或背书 安全口径 · 卸载与残留
中文 | English
这是什么,适不适合你
DSH 里挂 MCP 服务器,传统做法是手改 profile 的 cordis.patch.yml——写坏一次就起不来。本插件把这件事搬到设置面板:你在界面上点点,它在自己的层里写 YAML,不碰你的手写行。
典型情境:你要接一个新的 MCP 服务器(streamable-http 或 stdio),不想为了一行配置去编辑启动文件,更不想因为缩进错一次把宿主搞挂。
它不做什么:不做协议层探活,不做工具级权限控制,不改你的手写行(除凭据族字段与启停)。状态列不代表对方服务健康——断线重连期间工具仍会列出,调用才失败,这是 mcp-client 的既定行为。
安全口径(设计硬约束)
url永不回传浏览器 —— 面板只显示协议//主机/…,不含路径、查询串或任何 key 片段。- stdio 的 env 取值永不回传 —— 只回传键名与"已设置"。
- 凭据族字段留空 = 保留原值(未改不重写);要改必须整段重填:
url、command、env属此类。 serverName保存前查重(活动行 + 受管清单 + 本次草稿),重复会让后加载的那条加载失败。- 受管 id 强制
mcpx-前缀,并做三级 id 冲突检测(活动行 / 受管清单 / 手写层文本弱扫)——同 id 双声明会让官方把该行判成不可寻址并锁死开关。 - 密钥永不出宿主:受管清单文件权限
0600;集成测试断言url与env取值绝不出现在回传载荷里。
最容易搞错的一点:文件到底在哪
面板添加/删除的行,写在 $DSH_HOME\cordis.patch.yml($DSH_HOME 即 %USERPROFILE%\.dsh)——不在 profiles\<profile>\cordis.patch.yml 里。
profiles\<profile>\cordis.patch.yml 只会有两样东西:① 你手写的那几行;② 面板改写它们时由 DSH 官方配置编辑器追加的覆盖行。
面板顶部显示这个路径时是符号化的($DSH_HOME\…),不显示含用户名的绝对路径。
安装前准备
| 要求 | 取值 |
|---|---|
| 宿主 | 任一可用 DSH profile(下文以 web 为例) |
| Node.js | >=22.19(package.json 的 engines) |
| 构建 | 无:本包没有 prepare/构建脚本,也没有运行依赖 |
| 生效方式 | 本 profile 为 patchReload: live,且 bundles 变化在 HMR 监听范围内 → 通常无需重启;若设置里没出现「MCP 客户端」,重启一次 |
安装
方式 A · 本地目录(推荐:你手上这份 clone / 解压出来的目录)
侧栏 插件 → 添加插件 → 粘贴本仓库目录的本地绝对路径 → 安装。或命令行:
dsh plugin --profile web add "<本仓库绝对路径>"
方式 B · 从 npm 安装
dsh plugin --profile web add dsh-mcp-client-manager
方式 C · 直接从 GitHub 源安装
dsh plugin --profile web add github:yiyunet/dsh-mcp-client-manager
方式 B/C 的可用性取决于你的包管理器版本与
dsh plugin对 git 说明符的解析——推测(未实测);失败请回方式 A。
若 dsh 不在 PATH,可用 DSH 检出内的入口 node <DSH 检出>/apps/cli/lib/bin.js plugin …。
想撤掉它:见更新、回滚、卸载。
快速开始:添加一个能用的 MCP 服务器
装好不等于能用。四步的落点是工具真的出现在模型可用列表里。
- 给什么输入 —— 服务器名(
serverName)、传输方式(streamable-http或stdio),以及对应的url或command/args/env。 - 做什么操作 —— 设置 → ANB 工具 → MCP 客户端 → 添加 → 填表 → 保存。保存是唯一写盘时机。
- 结果出现在哪 —— 列表新增一行
mcpx-*;$DSH_HOME/cordis.patch.yml里出现对应行;该行挂载后工具以mcp__<serverName>__*出现在模型可用工具里。 - 怎样判断符合预期 —— 状态列显示 已启用,且悬停能看到"已发现 N 个工具"。"已启用 · 未发现工具"只说明行加载了但没发现工具,不算接通;"加载失败"看宿主日志。
日常使用
主线,端到端。 打开面板 → 找到目标行 → 按需改写/启停 → 保存 → 看状态列。
第二次及以后的最短路径。 只改一个字段时进去改那一个、保存即可;不需要重启宿主(面板的写盘由 HMR 监听)。
两条写回路径,互不越界:
- 受管行(行 id 前缀
mcpx-):新增 / 改写 / 启停 / 删除 → 写$DSH_HOME/cordis.patch.yml(全量重写)。 - 手写行:只能改写凭据族字段与启用/禁用;不能删除、不能改
serverName与transport(要改请手工编辑 profile patch)。改写走官方配置编辑器(原子写 + 失败回滚 + 被更高层覆盖则拒写),启停走官方插件管理。
手写行改写的落点(实测过一次,务必知道):官方配置编辑器只认顶层 - id: 行、明确排除 insert 行,而我们的行嵌在 - insert: [...] 里 —— 于是:
- 首次改写:在
profiles/<profile>/cordis.patch.yml末尾追加一条顶层覆盖行,原insert行不动;覆盖行在同文件内靠后 → 优先级更高 → 生效的是它。 - 之后再改同一行:原地更新,不会越堆越多。
- 该行会显示「手写 + 已覆盖」,并多出「撤销覆盖」按钮(调用官方语义把该行还原成
insert原值;只删config,不动同一行的disabled等其他键)。 - 后果:面板没改过的行,直接编辑
insert立刻生效;已被覆盖的行,改insert不生效,要先「撤销覆盖」。
设置面板
入口:设置 → ANB 工具 →「MCP 客户端」(英文界面:Settings → ANB 工具 → MCP client)。
「ANB 工具」栏目壳由本插件内置,随插件自带、不需要另装。壳是运行时单例:已有壳时让位、不重复登记;登记壳的插件被禁用后由本插件接管。只装本插件时栏目里只有一个标签(选中态),不出现空壳。
| 列 | 内容 |
|---|---|
| 服务名 | 名称;端点掩码与 stdio 命令收在悬停提示里(不占列宽) |
| 行 id | mcpx-* 或手写行的 id |
| 来源 | 受管/手写(手写行加注「原手写行」,被覆盖时显示「已覆盖」) |
| 状态 | 见下节八种取值 |
| 操作 | 修改 | 禁用/启用 | 不可删(手写行)或删除(受管行)| 撤销覆盖(已覆盖时) |
漂移即只读:若 $DSH_HOME/cordis.patch.yml 被外部改动(含换行符变化),面板停写并给两个处置按钮(重建 / 清空清单)。
出问题时怎么办
状态列怎么读
| 显示 | 含义 |
|---|---|
| 已启用 | 行已加载且发现了工具 —— 这是"确实连上了"的唯一证据 |
| 已启用 · 未发现工具 | 行已加载但没发现工具(服务端本来没有,或连接尚未完成) |
| 已启用 · 加载中 / 停止中 | 刚写入或正在卸载,等下一拍 |
| 已禁用 | 该行被关掉,不会连接 |
| 加载失败 | 行加载/连接失败,看宿主日志 |
| 未加载 | 配置在,但当前进程里没有这一行 |
| 配置冲突 | 该行 id 被多层声明,官方已锁其开关,需手工处理 |
常见误判
| 你看到什么 | 含义 | 下一步 |
|---|---|---|
| 状态"已启用"但调用工具报错 | 状态只说明行加载与工具发现,不代表链路健康 | 复现一次调用,看错误原文;断线重连期间工具仍会列出 |
| 改了配置没生效 | 受管行要按保存;手写行可能是"已被覆盖" | 受管行重新保存;手写行先「撤销覆盖」再改 insert |
| 面板整体变只读 | 自有层文件被外部改动(漂移) | 点「重建」或「清空清单」后重来 |
| 设置里找不到「MCP 客户端」 | 插件没加载或栏目没起来 | 重启一次宿主;再确认 dsh --profile web --dump-config 里有 mcp-client-manager |
| 保存时提示名称重复 | serverName 冲突会让后加载的那条失败 |
换一个 serverName |
| 保存时提示 id 冲突 | 同 id 被多层声明会让官方锁死该行 | 手工清掉重复声明后再保存 |
只读核对(⚠️ 输出含 key,别外传):
dsh --profile web --dump-config
更新、回滚、卸载
| 动作 | 怎么做 | 你的数据会怎样 |
|---|---|---|
| 更新 | 同一条安装命令重装 | 受管清单与手写行保留 |
| 卸载(GUI) | 侧栏 插件 → 找到本包 → 卸载 | 插件代码移除 |
| 卸载(CLI) | dsh plugin --profile web remove dsh-mcp-client-manager |
受管层生成文件与受管清单仍留在磁盘 |
| 清受管层 | 删除 $DSH_HOME\cordis.patch.yml |
受管 MCP 全消;手写行不受影响 |
| 清受管数据 | 删除 $DSH_HOME\mcp-manager |
不可恢复(含已保存的 url/env) |
卸载与残留什么
卸载不会自动清受管层与受管清单——那可能还有别的插件在用、或你还想留着配置。要清就按上表两行来,顺序建议先清层再清数据。
数据、权限与隐私
- 读什么 ——
$DSH_HOME/cordis.patch.yml、profiles/<profile>/cordis.patch.yml(读取你手写行用于展示与冲突检测)、受管清单$DSH_HOME/mcp-manager/servers.json。 - 是否外发及目标域名 —— 本插件自身不联网;面板与宿主之间走本机 RPC。被管理的 MCP 服务器是否联网由其自身决定。
- 是否落盘及位置 —— 受管清单
$DSH_HOME/mcp-manager/servers.json(0600);生成的 MCP 行$DSH_HOME/cordis.patch.yml;手写行改写落到profiles/<profile>/cordis.patch.yml。 - 谁可读写 —— 只有运行 DSH 的操作系统账户;清单文件权限
0600。 - 关键默认开关 —— 面板不探活;手写行默认不可删;漂移时自动转只读。
- 凭据存哪、是否进日志 ——
url与env取值存在受管清单里,不回传浏览器、不进 RPC 载荷;集成测试对这一点有断言。
兼容性:要求、已验证、仍未确认
- 要求 —— Node
>=22.19;DSH 提供settings.section壳能力与ctx.configEditor/ctx.pluginManager服务。 - 已验证 —— 在
patchReload: live的 profile 上免重启生效;host-smoke用临时目录当DSH_HOME真跑过 list / 新增 / 查重 / 启停 / 删除 / 手写行改写 / 漂移与逃生口 / RPC 信封与乐观锁。 - 仍未确认 —— 跨 DSH 版本矩阵未系统验证;从 git 源安装(方式 C)未实测。
验证与开发
node --check plugin-src/host/index.mjs # 语法预检,零副作用
node --check plugin-src/host/store.mjs
node --check plugin-src/host/validate.mjs
node --check plugin-src/host/adapter.mjs
node --check plugin-src/client/client.js
node --test test/validate.test.mjs test/store.test.mjs test/host-smoke.mjs
npm run verify # 包契约断言
⚠️ 测试必须点明文件:Node 24 下
node --test test会把test当模块加载而报MODULE_NOT_FOUND。
host-smoke.mjs 造一个假宿主(临时目录当 DSH_HOME)真跑一遍全流程,并断言密钥绝不出现在回传载荷里。无构建步骤、无运行依赖:宿主半侧只用 node:* 与 ctx 服务,浏览器半侧用官方 module-loader 工厂格式。
已知边界
- 只覆盖 mcp-client 行的
streamable-http/stdio两种传输;headers、reconnect、toolCallTimeoutMs、maxInstructionBytes等字段仍以文件为准(面板不动它们,改写时按"整段替换但带上现有键"处理)。 - 手写行不能删、不能改标识与协议(官方编辑服务的能力边界)。
- 状态列不是健康检查(见上文)。
- 漂移即只读:自有层文件一旦被外部改动,面板停写并给出手工处置。
文档索引
| 你想知道… | 看这里 |
|---|---|
| 装完一步步怎么确认它在工作 | docs/安装与验证.md |
| 它到底怎么写盘:两层文件、两条写回路径、RPC 接口表、漂移与撤销覆盖 | docs/架构与写回模型.md |
| 每个版本改了什么 | CHANGELOG.md |
| 文档总索引 | docs/README.md |
反馈
遇到问题或想要新功能,提一个 issue。报问题时写上 DSH 版本和插件版本(版本看包清单或 CHANGELOG.md,本文不重复记录)。
「装了没生效」与「配置被写坏」是两条完全不同的排查线,能分清就分开报。贴配置片段前请先删掉 token、API key 与内网地址——MCP 配置天然带凭证。
许可
MIT,见 LICENSE。作者 yiyunet。与 DeepSeek、DeepSeek Harness 无隶属关系,亦未获其赞助或背书。
No comments yet. Be the first to write one.