dsh-mcp-manager

中文 | English

一个 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__<serverName>__<rawName>，对模型而言动态管理的服务器与静态行毫无区别

安装

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

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

卸载

dsh plugin --profile <name> 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__<name>__<tool>
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__<serverName>__<rawName>，超长/非法字符时按 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 一致）
• 配置页当前每次打开时读取一次列表，操作成功后刷新；不会主动订阅其它浏览器标签页的实时变化

---

English

A DeepSeek Harness (DSH) plugin bundle adding runtime MCP server management.

The official @deepseek-ai/dsh-mcp-client mounts one static plugin row per MCP server in cordis.yml — adding or removing a server means editing the composition and restarting the host. This bundle adds the missing management plane: a persisted JSON server registry plus six mcp_manage_* agent tools that add, remove, enable/disable, and reconnect MCP servers at runtime. Bridged tools use the exact mcp__<serverName>__<rawName> naming contract of dsh-mcp-client, so dynamically managed servers look identical to static rows to the model.

Install

dsh plugin --profile <name> add /path/to/dsh-mcp-manager

Restart the profile afterwards.

Uninstall

dsh plugin --profile <name> remove dsh-mcp-manager

• Removing the dependency drops the bundle from dsh.profile.bundles automatically (reconcile) — no manual manifest edits.
• After restarting the profile (dsh web etc.): the six mcp_manage_* tools are unregistered, every managed connection closes, and the Settings → MCP page disappears.
• The registry file $DSH_HOME/mcp-manage/servers.json is not removed — it holds your servers plus env/headers, which may contain secrets. Keep it to restore the configuration on reinstall (servers reconnect automatically), or delete the $DSH_HOME/mcp-manage/ directory for a full cleanup.

Tools

mcp_manage_list / mcp_manage_add / mcp_manage_remove / mcp_manage_set_enabled / mcp_manage_reload / mcp_manage_tools — see the tables above; each returns a concise text summary, and errors carry actionable hints (fix + reload).

Registry

$DSH_HOME/mcp-manage/servers.json (override with the plugin's dataDir config; ~ supported). env values, headers values, and url support ${VAR} expansion from the host process environment. Writes are atomic (tmp + rename). Hand edits apply on next host restart or mcp_manage_reload; the file is not watched.

Behavior

Deterministic public names (hash-suffixed on lossy normalization, identical algorithm to dsh-mcp-client); fast-fail on namespace conflicts; credential-shaped env scrubbing (*KEY*/*TOKEN*/*SECRET*/*PASSWORD* and DSH_*) with explicit env merged after; exponential-backoff reconnect with a stability-reset budget and give-up + manual reload; tools/list_changed generation swap; isError results mapped to the tool error path; fully effect-scoped lifecycle.

Security

mcp_manage_add lets the agent spawn arbitrary commands (stdio transport) — the same trust level as the session's bash tool; gate the tool group behind your permission presets if needed. ${VAR} expansion reads the dsh host environment.

Test

pnpm install && pnpm test   # 22 integration tests against a bundled toy stdio MCP server