dsh-mcp-management
Verifieddsh-mcp-management · v1.0.0 · MIT · Web UI
MCP 管理(全局 / 项目):直接编辑 mcp.yml,项目级 MCP 挂在会话自己的 Agent 作用域里,改完热生效
Install
dsh plugin add dsh-mcp-management Confirm the layer applied with dsh --profile default --dump-config — see the install guide.
Source
Tags
Creators
Readme
dsh-mcp-management
DSH 的 MCP 管理:设置页里一个面板管两级 MCP —— 全局(profile 的 mcp.yml)和项目(<项目>/.dsh/mcp.yml)。不建 preset、不改 cordis.patch.yml,面板里加完就热生效。
| 作用域 | 文件 | 谁能用 |
|---|---|---|
| 全局 | <DSH_HOME>/profiles/<profile>/mcp.yml |
所有项目、所有会话 |
| 项目 | <项目>/.dsh/mcp.yml |
只在该工作目录打开的会话 |
快速开始
两条安装路径,装完都是「设置 → MCP」那一页:
A. 插件页按名字安装(已发布到 npm 的版本,普通用户走这条)
侧栏「插件」→ 添加插件 → 输入 dsh-mcp-management → 安装 → 立即启用 → 按提示重启 DSH
B. 本仓库 link 安装(改源码立即生效,开发用这条)
pwsh -NoProfile -File scripts\install.ps1
# 重启 DSH → 设置 → MCP(浏览器记得 Ctrl+Shift+R)
面板用法:顶部 全局 / 项目 两个 tab;每台服务器一行,行首是 MCP 自己的名字(完整工具前缀 mcp__<name>__* 收在 title 里,鼠标停一下才出现),行尾是测试(真起进程 / 真发一次 tools/list,报工具数与延迟)、启停、编辑、删除。传输方式、目标(命令或 URL)不占列表,在「编辑」里看;停用的行整行变暗、按钮变成「启用」。
加服务器两条路:添加 MCP(逐字段填)和 粘贴 JSON 导入(别人给的 mcpServers 配置整段贴进来)。
项目 tab 顶部可以选目录:默认取会话的工作目录,也能从已知项目里挑,或者手填绝对路径(选择记在 localStorage)。
从 JSON 导入
点 粘贴 JSON 导入,整段贴进去,输入停 400ms 后宿主就地解析并给出预览(识别格式、台数、每台的目标、同名冲突、被跳过的条目),确认后再点「导入」落盘并立刻重挂。
外层形状全认 —— 因为拿到的是哪种事先不知道:
| 别人给的形状 | 例子 |
|---|---|
mcpServers 映射(Claude Desktop / Cursor / Cline / Continue) |
{"mcpServers":{"ida":{"command":"…","args":["--stdio"]}}} |
servers 映射或数组(VS Code 系) |
{"servers":{"web":{"type":"http","url":"…"}}} |
| 服务器数组 | [{"name":"ida","command":"…"},{"name":"web","url":"…"}] |
| 数组里塞映射 | [{"ida":{"command":"…"}}] |
| 裸名称映射(键就是名字) | {"ida":{"command":"…"}} |
| 单台服务器对象 | {"name":"ida","command":"…"} |
内层字段也做了兼容:type / transportType / transport 同义词(stdio http sse remote …,SSE 按 streamable-http 存并给出提示)、baseUrl / serverUrl / uri → url、command 写成数组(首项是命令、其余进 args)、args 写成字符串、env 写成 ["K=V"] 数组、disabled: true → enabled: false、cordis 的 config: 包裹。名字里的非法字符(.、空格、中文)会被折成 _ 并提示。
文本层面还顺手容忍:Markdown 代码围栏、BOM、整行 // 注释、尾随逗号。整段不是 JSON 会直接报错,单条有问题只跳过那一条,其余照常导入。
同名处理默认是跳过并在预览里列出来;勾上 同名覆盖 则用 JSON 里的定义替换已有的那台。
文件状态与处理
.dsh/mcp.yml 有四种状态,面板都对应给出动作:
| 状态 | 表现 | 能做什么 |
|---|---|---|
missing |
提示文件不存在 | 「创建文件」,第一次保存也会自动建父目录 |
empty |
文件在但 0 台服务器 | 直接「添加 MCP」 |
ok |
正常列表 + 挂载了几个会话 | 测试 / 启停 / 编辑 / 删除 |
invalid |
红色报错带 YAML 错因 | 「重新加载」,或「覆盖重建」;上一份可用挂载不会被掐断 |
文件格式
servers:
- name: ida # 工具前缀 mcp__ida__*
transport: stdio # stdio | streamable-http(省略时:有 url 即 http,否则 stdio)
command: 'D:\tools\ida\idalib-mcp.exe'
args: ['--stdio']
cwd: 'D:\work\my-project'
env: { IDADIR: 'D:\tools\ida' }
toolCallTimeoutMs: 300000
enabled: true # 省略即 true;false = 保留配置不连接
- name: web
transport: streamable-http
url: https://example.test/mcp
headers: { Authorization: 'Bearer ...' }
示例里的路径都是占位,换成自己的。顶层也可以是裸列表(- name: ... 直接作为数组元素),读的时候会自动认。旧的 cordis 写法(- id: ... / name: '@deepseek-ai/dsh-mcp-client' / config: { serverName, ... })照样能读,保存时统一成上面的简洁结构。
生效时机
| 动作 | 何时生效 |
|---|---|
| 保存 / 删除 / 启停 | 立刻重挂 |
| 新会话 | agent/created 时挂,最多等 1.2s,不卡创建 |
| 插件重载 | 给所有现存会话补挂一次 |
| 直接编辑文件 | 文件轮询(900ms)后重挂;写坏了保留上一份可用挂载 |
工具清单是按 step 组装的,所以新挂上的 MCP 在下一轮请求里出现,同一轮不会突然多出工具。
代价:每个打开的会话各连一份 —— 同一个项目开 N 个会话就是 N 个 MCP 子进程(这是 Agent 作用域隔离换来的);会话关掉,进程随之退出。
旧条目迁移
profile 的 cordis.patch.yml 顶层如果还挂着 name: '@deepseek-ai/dsh-mcp-client' 的行(含 insert: 包裹的),全局 tab 会出现黄色提示,点「迁移到 mcp.yml」把它们搬进 mcp.yml 并从补丁里摘掉(补丁先备份成 .bak-migrate)。
设置里的图标
设置面板左侧导航的图标由宿主 @deepseek-ai/dsh-client-ui-settings-general 硬编码:navIcon(id) 只给 account / models / agent-presets / plugins / archived-sessions 画图标,其余 id(包括本面板的 mcp-management)一律回退默认齿轮;settings.section 的注册选项里没有 icon 字段可传。
所以图标由浏览器半自己补:用的是 MCP 官方 mark(modelcontextprotocol.io 的 favicon 图形:三条圆头弧线拼成的 M 形),只留描边、去掉官方图里的黑底方块,颜色走 currentColor。
| 环节 | 做法 |
|---|---|
| 认领 | watchNav() 盯着 body,设置面板渲染后按导航文案(t("nav"),即 “MCP”)找到那颗按钮,打 data-mcp-nav |
| 画图 | CSS ::before + mask-image: url("data:image/svg+xml,…"),16×16、background-color: currentColor |
| 收尾 | [data-mcp-nav] > svg{display:none} 把宿主给的齿轮藏掉;面板关掉重开、切语言都会重新认领 |
| 降级 | 拿不到 DOM 时什么都不做,图标退回齿轮,面板功能不受影响 |
要换成自己的图形:改 src/client/client.js 里的 MCP_MARK_SVG(单色 SVG,任何填充色都会被 mask 替换成 currentColor),刷新浏览器即可,不用改宿主。
配置
写在 profile 补丁的 loader 行上,全部可省略:
| 字段 | 默认 | 含义 |
|---|---|---|
globalFile |
<profile>/mcp.yml |
全局清单 |
projectFile |
.dsh/mcp.yml |
项目清单(相对项目目录) |
patchFile |
<profile>/cordis.patch.yml |
只有迁移旧条目时才用到 |
profileDir |
$DSH_HOME/profiles/$DSH_PROFILE |
上面几个默认值的基准目录 |
debugFile |
空 | 填路径则把运行时挂载快照写到那里,排查「为什么没挂上」 |
仓库结构
src/host/ 宿主半:ESM,按职责拆开,无构建步骤
index.js 插件入口:解析路径 → 建 runtime → 接事件 → 注册 RPC
constants.js 插件身份 / 版本 / RPC 通道 / 作用域 / 两个 YAML 文件头
paths.js globalFile / projectFile / patchFile / debugFile 的解析
yaml.js js-yaml 按需加载(含 !!js 标量)+ 从 profile node_modules 兜底
servers.js mcp.yml 的读 / 规范化 / 写 / 表单校验
import.js 别人给的 MCP JSON → server 对象(宽松解析 + 形状兼容)
entries.js 「服务器 → mcp-client loader 行」+ 内存 EntryTree
runtime.js 全局挂载、每会话挂载、文件热更新、调试快照
migrate.js 旧 cordis.patch.yml 顶层 mcp-client 行的识别与摘除
probe.js 「测试」按钮的真连通探测(stdio / streamable-http)
rpc.js /api/mcp-management 的动作实现与分发
src/client/
client.js 浏览器半:单文件 ModuleLoader 模块(不能拆,没有打包步骤);含设置导航的 MCP 图标
scripts/
install.ps1 link 安装 / 卸载(幂等,自动备份 profile;-DryRun 只看不改)
patch-lines.ps1 profile 补丁里本插件条目的改名 / 补齐 / 摘除
patch-lines.test.ps1 上面那套行级操作的单测(含真实 profile 只读夹具)
profile-manifest.ps1 profile 的 dependencies / dsh.profile.bundles 增删
profile-manifest.test.ps1 上面那套的单测
check.mjs 包名 / 补丁行 / 模块 id / 版本 / 入口形状的一致性自检
verify-install.mjs 装没装上 + 两个 mcp.yml 读没读到(从 profile 入口 import 真插件)
tests/ apply / host / import / client / parity 五组测试 + 行为基线快照
docs/architecture.md 挂载模型、数据流、RPC 协议、命名、已知边界
开发
npm test # 42 个用例:装配 + 功能 + JSON 导入 + 面板接线 + 导航图标 + 行为基线
npm run check # 静态自检:包名 / 补丁行 / 模块 id / 版本 / 入口文件 / 行为基线快照
npm run test:patch # profile 补丁行迁移的单测(PowerShell)
npm run test:manifest # profile 依赖与 bundles 的单测(PowerShell)
改代码的注意点:
- 不要给
src/client/client.js加import:宿主只按package.json的exports["./client"]取一个脚本地址,没有打包步骤,它必须保持单文件 + tab 缩进。 - 宿主半是普通 ESM,可以随便拆,但
__internals的键是测试与排错依赖的稳定面,别随手删。 - 依赖(
js-yaml、@modelcontextprotocol/sdk)只在package.json的dependencies里声明,仓库本身不装node_modules:link 安装时yaml.js/probe.js先正常解析、失败退回<profile>/node_modules;从注册表安装时它们会随包一起落到 profile 里,直接就能解析到。 - 插件有四个必须一致的名字:
package.json的name、cordis 的name/insert.id(mcp-management)、client.js的load({ id })、RPC 前缀/api/mcp-management。改一处就跑npm run check。mcp__<name>__*这个工具前缀来自每个 MCP 自己的name,与插件名无关。
发布到 npm(让插件页「输入名字」就能装)
插件页的「添加插件」对话框接受包名(可带 @版本)、Git 地址、压缩包、本地绝对路径。输入包名后它会先 pnpm view 查一遍(inspect)、再 pnpm add,所以「按名字装」的前提只有一条:这个名字在某个注册表上存在,且包本身过得了下面四道检查。
| 检查 | 触发条件 | 包该给的 |
|---|---|---|
already-installed |
名字已在 profile 的 dependencies / dsh.profile.bundles / 安装锚点里 |
装之前先把 link 那份卸掉(见步骤 6) |
not-found |
问过的每个注册表都没有这个名字 | npm publish 到 npm 官方源(或私有源) |
not-a-bundle |
包里没有 dsh.bundle 声明 |
dsh.bundle.patch 指向真实存在的 cordis.patch.yml |
incompatible-version |
engines.dsh 与当前 DSH 运行时不匹配(有它时 peer 检查被忽略) |
engines.dsh 写成本插件真支持的范围 |
package.json 里已经按这四条配好:去掉了 private(npm 拒收 private 包),带上 publishConfig / license / repository / keywords,dsh.bundle.patch + exports["./client"] + dsh.client.platform: "web" 齐备,engines.dsh 是 >=0.2.1-rc.3(当前 app-boot 运行版本),js-yaml / @modelcontextprotocol/sdk 进了 dependencies —— 注册表装的副本没有 profile 那层兜底,得自己带。
步骤
自检 + 看包内容(不发任何东西):
npm run check # 包名 / 补丁行 / 模块 id / 版本 / 入口 / 行为基线 npm test # 42 个用例 npm run pack:check # npm pack --dry-run:确认 src、cordis.patch.yml、README 都在 tarball 里登录 npm(一次性):
npm login # 或 npm config set //registry.npmjs.org/:_authToken=$env:NPM_TOKEN npm whoami发布(第一次就是
1.0.0):npm publish # 包名不带 scope,--access public 可省;要发到私有源就加 --registry https://npm.example.test/确认注册表真能查到(插件页 inspect 走的就是这条路):
npm view dsh-mcp-management version npm view dsh-mcp-management dsh.bundle.patch # 能打出来,说明 dsh.bundle 在包里npmmirror 会自动同步,通常几分钟;没同步完就在插件页把安装源切到 npm 官方源。
把本机这份 link 安装卸掉(否则 inspect 直接答
already-installed):pwsh -NoProfile -File scripts\install.ps1 -Uninstall在插件页装:
侧栏「插件」→ 添加插件 → 输入 dsh-mcp-management → 安装源选 npm 官方 → 安装 → 立即启用装完 profile 的
package.json会多出"dsh-mcp-management": "1.0.0"(注册表目标用 saveExact,写精确版本),dsh.profile.bundles末尾多一项,插件行由包里的cordis.patch.yml提供 —— profile 自己那份cordis.patch.yml只剩可选的 config 覆盖(例如- id: mcp-management上写patchFile)。提示restart-required就重启 DSH,再浏览器硬刷新。验证(不吃界面也能看):
npm run verify # 从 <profile>/node_modules/dsh-mcp-management 真 import,并读两个 mcp.yml升级:页面上没有版本选择器,spec 直接写全即可。
# 改 version,同时改 src/host/constants.js 的 PLUGIN_VERSION(npm run check 会拦不一致) npm run check; npm publish # 插件页:卸载后重装,或包名写 [email protected]
私有源:插件页的安装源支持手填 http(s) 地址(Verdaccio / 公司源都行),管理器也可以把 registry + fallbackRegistries 钉在 profile 补丁里;自己搭源时 npm publish --registry <URL> 即可,别的地方不用改。
安装到 profile(link 方式 / 开发用)
一个插件要在 DSH 里真正跑起来,profile 的四处必须同时对上 —— 只改前两处中的一处,就会出现「插件页显示没打开、设置里却还有面板」的状态:
| 位置 | 作用 | 漏了会怎样 |
|---|---|---|
package.json dependencies |
pnpm 装不装、node_modules 里有没有 |
插件页报文件不可读,加载失败 |
package.json dsh.profile.bundles |
插件页的开关;也是应用 bundle patch(本包的 cordis.patch.yml)的前提 |
显示「未启用」,补丁不生效 |
cordis.patch.yml 条目 |
插件行的 config(patchFile 等) |
用默认路径(一般也对,但 config 丢失) |
node_modules/<旧包名> 符号链接 |
旧 bundle 是否还能被解析 | 旧插件继续加载,和新插件抢同一个面板 |
pwsh -NoProfile -File scripts\install.ps1 -DryRun # 先看它打算改什么(不写文件、不跑 pnpm)
pwsh -NoProfile -File scripts\install.ps1 # 四处一起改,然后 pnpm install
# 重启 DSH(profile 没开 HMR,bundles 变更要重启)+ 浏览器硬刷新
npm run verify # 或者看链接:node scripts\verify-install.mjs
profile 选哪个:-ProfileName 参数 → $env:DSH_PROFILE → 默认 desktop(DSH 自己的默认名,不是 web;dsh web 只是启动命令,profile 名仍是 desktop)。脚本第一行输出会写明 profile 与「profile 名来自 …」;指到不存在的 profile 会直接报错而不是静默新建。DSH_HOME 同理:-DshHome → $env:DSH_HOME → %USERPROFILE%\.dsh。其它脚本一律沿用这套解析(verify-install.mjs --profile/--home、两个 .test.ps1 的 -ProfileName/-DshHome 或同名环境变量),没有写死 desktop 之外的名字。
脚本做的事:依赖里加 "dsh-mcp-management": "link:<本仓库>"(并补 js-yaml / @modelcontextprotocol/sdk)、把包名追加进 dsh.profile.bundles、把 cordis.patch.yml 里的 - id: mcp-management 条目补齐(块里的自定义 config 原样保留)、删掉 node_modules 里指向旧目录的符号链接(非符号链接只告警)。写之前把 package.json / cordis.patch.yml 备份成 *.bak-install-<时间戳>。
验证安装(装上了没有 / 读到 mcp.yml 没有)
三档,从便宜到贵。前两档不用开界面,最后一档才看面板。
1. 包本身没坏
npm test # 42 个用例
npm run check # 包名 / 补丁行 / 模块 id / 版本 / 入口 / 行为基线
2. 装进 profile 了,而且真读到了清单
npm run verify # 默认 $DSH_HOME/profiles/$DSH_PROFILE + 当前目录
node scripts/verify-install.mjs --profile desktop --dir G:\path\to\proj
node scripts/verify-install.mjs --json # CI / 管道
它检查的是运行时会真的走的那条路,而不是仓库源码:<profile>/node_modules/<包名>(link 或 pnpm 装的实体入口)里 import 插件 → 用补丁行上的 config 跑 resolvePaths → 对两个清单文件真跑一遍 readServersFile(面板 tab 显示的就是这个返回值)。两种安装都验:补丁条目可以在 profile 的 cordis.patch.yml(link),也可以在包自己的 bundle patch(插件页按名字装)。逐项输出,退出码 0 才算过:
[ OK ] profile 依赖里有本插件 — dsh-mcp-management: link:G:/.../dsh-mcp-management
[ OK ] dsh.profile.bundles 里已启用 — 6 个 bundle
[ OK ] node_modules 链接指向仓库 — G:\...\dsh-mcp-management
[ OK ] 从 profile 入口 import 成功 — ...\node_modules\dsh-mcp-management\src\host\index.js
[ OK ] 导出形状正确(name / inject / apply / __internals) — inject: connection, loader
[ OK ] 补丁里有 mcp-management 条目(profile 或包内 bundle patch) — profile + bundle;config: {"patchFile":"C:\\...\\cordis.patch.yml"}
[ OK ] 全局 mcp.yml(<profile>/mcp.yml) 读到了 — ok / 1 台(github)
[ OK ] 项目 mcp.yml(G:\...\proj) 读到了 — empty / 0 台
global / project 那两行的 ok / N 台(名字...) 就是「读到了之前配好的 mcp.yml」的直接证据;invalid 会连带打印 YAML 错因,missing 说明路径压根不在一块(config 的 globalFile / projectFile 指错了,或者项目还没建 .dsh/mcp.yml)。
3. 面板 / 会话里真的活着
# 改完 bundles 或补丁必须重启(profile 没开 HMR),浏览器再 Ctrl+Shift+R
| 看哪里 | 应该看到 |
|---|---|
| 设置 → MCP,全局 tab | 之前配的那台(如 github),行首就是名字 github,行尾四个操作(悬停看到 mcp__github__*);传输方式 / 目标在「编辑」里 |
| 同一行点测试 | 真起进程 / 真发 tools/list,回工具数与延迟 —— 这是「配置真能用」的终判 |
| 设置 → MCP,项目 tab | 本工作目录的 .dsh/mcp.yml(空文件就显示 empty,缺文件显示 missing) |
| 会话工具列表 | 出现 mcp__github__*;下一轮请求才刷新(工具清单按 step 组装) |
想留证据:在补丁行的 config 里加 debugFile: C:\temp\mcp-debug.json,重启后运行时的挂载快照(含每个会话可见的 mcp__* 工具)会写进去。
4. 全新 profile 演练(不碰自己那份)
# 造一个只有空补丁的干净 profile,装进去,再验证
$tmp = Join-Path $env:TEMP 'dsh-fresh'; $prof = Join-Path $tmp 'profiles\test'
New-Item -ItemType Directory $prof -Force | Out-Null
'{"name":"dsh-profile-test","private":true}' | Set-Content (Join-Path $prof 'package.json') -Encoding utf8
'[]' | Set-Content (Join-Path $prof 'cordis.patch.yml') -Encoding utf8
Copy-Item "$env:USERPROFILE\.dsh\profiles\desktop\mcp.yml" (Join-Path $prof 'mcp.yml') # 想验「读旧配置」就带上
pwsh -NoProfile -File scripts\install.ps1 -DshHome $tmp -ProfileName test -DryRun # 先看改什么
pwsh -NoProfile -File scripts\install.ps1 -DshHome $tmp -ProfileName test # 真装(跑 pnpm install)
node scripts\verify-install.mjs --home $tmp --profile test
[] 这种空补丁也能装:补块前会把裸 [] / null / --- 摘掉,否则 [] 后面接 - insert: 是无效 YAML。
排错
- 面板里有了但会话里没工具:看「挂载失败」提示;再确认
name没和别的 MCP 撞(同一作用域内唯一)。 already in use:cordis.patch.yml里的旧 mcp-client 行没迁移,和我们挂的实例抢同一个serverName。- 想确认真的连上了:点服务器行上的「测试」,它真起进程、真发
tools/list。 - 改了文件没反应:点「刷新」;文件监视是 900ms 轮询,网络盘更慢。
- 想留下证据:配置
debugFile,运行时的挂载快照(含每个会话可见的mcp__*工具)会写进去。 - 插件页显示没打开,但设置里还有面板:
dsh.profile.bundles里没这个包、或node_modules里还有别的同名链接 —— 重跑scripts\install.ps1,然后重启 DSH。