HenC49/dsh-mcp-manager

dsh-mcp-manager

一个 DeepSeek Harness (DSH) 插件组合包：为 dsh 提供 运行时 MCP 服务器管理 能力。

官方的 @deepseek-ai/dsh-mcp-client 在 cordis.yml 中为每个 MCP 服务器挂一行静态插件行——增删服务器需要改配置并重启宿主。本插件补上缺失的管理面：

- 一个持久化的 JSON 服务器注册表（默认 $DSH_HOME/mcp-manage/servers.json，重启后自动重连）
- 六个 mcp_manage_ 智能体工具，可在会话中直接增、删、启停、重连 MCP 服务器
- Web UI 的 设置 → MCP 服务器 配置页面：可视化添加、编辑、启停、重连和删除服务器，并查看实时状态、错误与工具列表
- 桥接的工具沿用与 dsh-mcp-client 完全一致的命名契约 mcp____，对模型而言动态管理的服务器与静态行毫无区别

安装

dsh plugin --profile  add /path/to/dsh-mcp-manager   # 本地目录
dsh plugin --profile  add github:HenC49/dsh-mcp-manager # git 仓库安装（本包为纯手写 JS，无构建步骤）

安装后重启该 profile（dsh web 等）即可生效。重启后打开 Web UI 的设置面板，即可看到 MCP 服务器 页面；当前生产 Web profile 的 HMR 默认关闭，因此新增或更新插件包后需要重启宿主。

卸载

dsh plugin --profile  remove dsh-mcp-manager

- 移除依赖后，dsh.profile.bundles 中的该层会被自动剔除（reconcile 逻辑），无需手工编辑 profile manifest
- 重启该 profile（dsh web 等）后：六个 mcp_manage_ 工具注销、所有被管理服务器的连接关闭、Web 设置页的 MCP 服务器 入口消失
- 注册表文件 $DSH_HOME/mcp-manage/servers.json 不会被删除——它保存着你配置的服务器以及 env/headers（可能含敏感信息）：
- 计划重装并恢复原配置：保留即可，重装后自动重连
- 彻底清理：手动删除 $DSH_HOME/mcp-manage/ 目录

Web 配置入口

进入 设置 → MCP 服务器：

- 添加/编辑：支持 stdio 本地命令和 streamable-http 远程端点；参数、环境变量和请求头均采用每行一项的编辑方式
- 状态管理：查看连接状态、错误信息和已注册工具；可单独启用、停用、重连或删除，也支持全部重连
- 安全边界：页面调用的是宿主的同源 /mcp-manage/api/ 接口，接口使用 loopback/可信 Host 与 same-origin 检查，拒绝跨站请求
- 编辑服务器采用“删除旧配置并重新添加”的方式，因此保存后会立即重新连接并刷新工具列表

聊天中的 mcp_manage_ 工具仍然保留，适合自动化或无法使用 Web UI 的场景。

管理工具

| 工具 | 作用 |
|---|---|
| mcp_manage_list | 列出已管理的服务器：名称、状态、传输方式、启停、已桥接的工具名、注册表路径 |
| mcp_manage_add | 添加并立即连接一个 MCP 服务器（stdio 或 streamable-http），工具即刻注册为 mcp____ |
| mcp_manage_remove | 移除服务器：断开连接、注销工具、从注册表删除 |
| mcp_manage_set_enabled | 启用/停用服务器（停用断开连接并注销工具，配置保留） |
| mcp_manage_reload | 重连一个（按名）或全部（无名）已启用的服务器并重新发现工具 |
| mcp_manage_tools | 列出某个服务器当前暴露的工具名，便于直接调用 |

示例——直接在会话里说：

帮我添加一个 filesystem MCP 服务器，命令 npx -y @modelcontextprotocol/server-filesystem /Users/me/project

模型会调用 mcp_manage_add，工具立即生效，无需重启。

注册表文件

$DSH_HOME/mcp-manage/servers.json（可用插件配置 dataDir 改路径，支持 ~ 前缀）：

{
"version": 1,
"servers": {
"github": {
"enabled": true,
"transport": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" },
"toolCallTimeoutMs": 60000
},
"remote": {
"enabled": true,
"transport": "streamable-http",
"url": "https://mcp.example.com/mcp",
"headers": { "Authorization": "Bearer ${MCP_TOKEN}" }
}
}
}

- env 值、headers 值和 url 支持 ${VAR} 展开（取自 dsh 宿主进程环境；未设置的变量保留字面量，便于在报错中暴露问题）
- 文件可手工编辑；改动在下一次宿主重启或 mcp_manage_reload 后生效（本插件不监听文件变化）
- 每次变更都原子写入（临时文件 + rename）

插件配置

在 profile 的 cordis.patch.yml 中按行覆盖（补丁替换整行 config，需重述全部字段）：

- id: mcp-manage
name: 'dsh-mcp-manager'
config:
dataDir: ''                  # 默认 $DSH_HOME/mcp-manage
autoStart: true              # 宿主启动时自动连接已启用的服务器
defaultToolCallTimeoutMs: 60000
reconnect:
enabled: true
initialDelayMs: 500
maxDelayMs: 30000
maxAttempts: 10

行为细节

- 命名契约：公开名 mcp____，超长/非法字符时按 SHA-256 身份哈希截断后缀——与 dsh-mcp-client 相同的确定性函数；同一服务器在静态行与本插件之间迁移，工具名不变
- 命名空间冲突：与其它插件（如静态 dsh-mcp-client 行）重名时快速失败并明确报错，不消耗重连预算
- 凭据防泄漏：stdio 子进程环境 = 宿主环境剔除凭据形状变量（KEY/TOKEN/SECRET/PASSWORD，不区分大小写）与全部 DSH_，再合并显式 env——与 dsh-subprocess 的擦洗启发式一致，显式传入的凭据得以保留
- 重连预算：断线后按指数退避重连（500ms 起、30s 封顶）；连接存活超过 maxDelayMs 则重置预算，连续失败超过 maxAttempts 次后停止并注销工具，等待 mcp_manage_reload
- 工具列表热同步：监听 MCP tools/list_changed 通知，整代换、失败保旧、冲突回滚整代
- 错误结果：MCP isError: true 的调用结果转为工具错误路径；文本块拼接为模型可见文本，图像/音频/资源块降级为占位符（与 dsh-mcp-client 一致）
- 生命周期：全部注册、连接、定时器都挂在插件 effect 上——卸载（含 HMR）时全部清理

安全注意

mcp_manage_add 可以让智能体在宿主进程中 spawn 任意命令（stdio 传输）。这与会话中已有的 bash 工具权限同级——如果部署上需要收紧，可在权限预设中对该组工具启用审批策略。env/headers 中的 ${VAR} 展开读取的是 dsh 宿主进程的环境变量，不要将宿主的敏感凭据变量名透传给不可信的 MCP 服务器。

测试

pnpm install
pnpm test    # 22 项集成测试：使用内置 toy stdio MCP 服务器覆盖桥接/管理/持久化/重连/热同步/销毁

已知限制

- 仅桥接 tools（MCP resources 与 prompts 同 dsh-mcp-client 一样暂缓）
- 注册表文件无文件监听，手工编辑后需 reload 或重启
- HTTP 传输的可达性错误按请求逐次暴露，不触发 stdio 式进程守护重启（与 dsh-mcp-client 一致）
- 配置页当前每次打开时读取一次列表，操作成功后刷新；不会主动订阅其它浏览器标签页的实时变化

英文

一个 DeepSeek Harness (DSH) 插件包，添加运行时 MCP 服务器管理。

官方的 @deepseek-ai/dsh-mcp-client 在 cordis.yml 中为每个 MCP 服务器挂载一个静态插件行——添加或移除服务器意味着编辑组合并重启宿主。本插件包补上了缺失的管理平面：一个持久化的 JSON 服务器注册表，外加六个 mcp_manage_ 智能体工具，可在运行时添加、移除、启用/禁用和重连 MCP 服务器。桥接工具使用与 dsh-mcp-client 完全相同的 mcp____ 命名契约，因此动态管理的服务器对模型而言与静态行看起来完全一致。

安装

dsh plugin --profile  add /path/to/dsh-mcp-manager

之后重启该 profile。

卸载

dsh plugin --profile  remove dsh-mcp-manager

- 移除依赖会自动将该插件包从 dsh.profile.bundles 中移除（reconcile）——无需手动编辑清单。
- 重启该 profile（dsh web 等）后：六个 mcp_manage_ 工具被注销，所有受管连接关闭，Settings → MCP 页面消失。
- 注册表文件 $DSH_HOME/mcp-manage/servers.json 不会被移除——它保存着你的服务器以及 env/headers，其中可能含有密钥。保留它可在重新安装时恢复配置（服务器会自动重连），或删除 $DSH_HOME/mcp-manage/ 目录以彻底清理。

工具
mcp_manage_list / mcp_manage_add / mcp_manage_remove / mcp_manage_set_enabled / mcp_manage_reload / mcp_manage_tools —— 参见上表；每个都返回简洁的文本摘要，错误会附带可操作的提示（修复 + 重载）。

注册表

$DSH_HOME/mcp-manage/servers.json（可通过插件的 dataDir 配置覆盖；支持 ~）。env 值、headers 值和 url 支持从宿主进程环境进行 ${VAR} 展开。写入是原子的（tmp + rename）。手动编辑会在下次宿主重启或 mcp_manage_reload 时生效；该文件不会被监视。

行为

确定性的公开名称（在有损规范化时附加哈希后缀，算法与 dsh-mcp-client 相同）；命名空间冲突时快速失败；对形似凭据的环境变量进行清理（KEY/TOKEN/SECRET/PASSWORD 和 DSH_），之后合并显式指定的 env；指数退避重连，带有稳定性重置预算，并在放弃后需手动重载；tools/list_changed 时进行代际切换；isError 结果映射到工具错误路径；完全按 effect 作用域管理生命周期。

安全性

mcp_manage_add 允许 agent 启动任意命令（stdio 传输）—— 与会话的 bash 工具处于同一信任级别；如有需要，可将该工具组置于你的权限预设之后。${VAR} 展开会读取 dsh 宿主环境。

测试

pnpm install && pnpm test   # 针对内置的玩具 stdio MCP 服务器运行 22 个集成测试