dsh-mcp-server-manager

DeepSeek Harness（Web 界面）的 MCP 服务器管理插件。

功能

• 设置页：在「设置」左侧导航新增一栏 MCP 服务器，可以新增 / 编辑 / 删除 MCP 服务器；
  • 支持两种连接类型：本地程序（stdio，例如 npx 启动的服务器）和远程地址（streamable-http），连接类型为双按钮选择；
  • 支持环境变量（stdio）与请求头（HTTP），值在界面中隐藏存储（只显示“已设置 / 未设置”）；
  • 每台服务器有「测试连接」按钮，保存前可以先验证配置；远程地址保存前校验必须为 http(s)://；
  • 列表每行显示实时连接状态（已连接 / 连接中 / 连接失败 + 完整错误原因，可一键复制）、工具数量，并提供手动连接 / 断开按钮；
• 启动自动连接：dsh 启动时自动连接设置里定义的所有服务器（手动断开的除外）；连接失败按退避策略重连（0.5s→30s，最多 10 次）后停在错误状态，可在设置里手动重连；
• 按会话启用：每个会话的顶部标题栏有一个 MCP 按钮（带已启用数量角标），点开弹窗勾选该会话要启用的服务器；
  • 勾选 / 取消勾选立即生效：勾选即把该服务器的工具挂到当前会话、AI 马上能用；取消即从该会话移除工具（连接本身保持）；
  • 弹窗里每台已启用的服务器显示连接状态和工具数量；
• 新会话默认不启用任何服务器；子会话（fork 出来的）诞生时复制父会话当时的启用列表快照，之后各自独立；
• 记录持久化：每个会话启用了哪些服务器会被保存，下次打开/恢复这个会话无需重新设置；
• 修改与删除：修改服务器参数保存后立即用新配置重连；删除服务器时，所有会话的启用记录自动移除它、连接立即断开；
• 工具详情弹窗显示原始工具名（不带 mcp__<serverId>__ 前缀；AI 侧工具名仍带前缀以避免跨服务器同名冲突）；
• 界面中英双语，跟随 DSH 界面语言。

目录结构

dsh-mcp-server-manager/
├── package.json     # npm 包元数据（dsh.bundle 声明配置档层，dsh.client 声明浏览器端）
├── cordis.patch.yml # bundle 补丁：向配置档插入 mcp-manager 插件行（安装后自动生效）
├── lib/
│   ├── index.js     # 宿主端：设置命名空间、会话记录存储、动态连接管理、RPC 服务
│   └── client.js    # 浏览器端：设置页 + 会话 MCP 按钮弹窗（中英双语）
└── README.md

安装

本插件是一个普通的 npm 插件包，不会修改你正在运行的 DSH。安装分两步：

1. 把插件装进 web 配置档

本插件是一个 bundle 型插件（package.json 声明了 dsh.bundle），安装后会被 dsh 自动加入 web 配置档的层列表并激活，无需手动改任何配置文件。

在 dsh-mcp-server-manager 所在目录执行：

dsh plugin --profile web add ./dsh-mcp-server-manager

然后重启 dsh web，刷新浏览器页面即可。设置里会出现「MCP 服务器」，每个会话顶部会出现 MCP 按钮。

重要（依赖共享）：插件的运行时依赖（@deepseek-ai/*、zod、MCP SDK 等）声明为 peerDependencies，必须解析到 DSH 运行环境同一份安装，否则插件会和宿主各持一份 @deepseek-ai/cordis / dsh-typert-protocol，导致网关发现不到插件的 Remote 方法 （所有 RPC 报 HTTP 404）。本仓库的 node_modules 是指向 ~/.dsh/profiles/node_modules 的 junction（符号链接），保证这一点。 如果重新执行过 dsh plugin add 之后 RPC 又出现 404，请检查插件目录下的 node_modules 是否仍是 junction（dir 查看显示 <JUNCTION>）；若被 pnpm 替换成了 真实目录，删掉它并重新 mklink /J 指回 ~/.dsh/profiles/node_modules 后重启即可。

该命令等价于在 ~/.dsh/profiles/web 里执行 pnpm add ./dsh-mcp-server-manager，随后 dsh 会自动把声明了 dsh.bundle 的包写进该配置档的 dsh.profile.bundles 层列表 （查看 ~/.dsh/profiles/web/package.json 可以确认），启动时由 bundle 的 cordis.patch.yml 自动插入 mcp-manager 插件行。

如果之前用旧版本（未声明 dsh.bundle）装过、只收到过警告，重跑一次上面的 add 命令即可把它补进层列表，然后重启。

插件依赖的 @deepseek-ai/* 包与当前 DSH 版本匹配（0.1.0-rc.7）。 如果 pnpm 联网解析不到这些 rc 版本，可以加 --offline 参数重试（它们已经存在于 ~/.dsh/profiles/node_modules 中，离线安装通常会直接复用）。

手动方式（可选）

如果不想用 bundle 自动激活，也可以手动把它作为普通插件行加进 ~/.dsh/profiles/web/cordis.patch.yml（与 bundle 层二选一即可）：

- insert:
    - id: mcp-manager
      name: 'dsh-mcp-server-manager'

使用

1. 添加服务器：设置 → MCP 服务器 → 新增服务器。填好名称、连接类型和连接参数，可以先用「测试连接」验证，再保存。服务器名称必须唯一（保存时重名会被拒绝）。
2. 新会话界面选择：在"新会话"界面上，「标准模式」（智能体预设选择器）右侧有一个 MCP 下拉框（多选），可以勾选要接入本会话的服务器；没有当前空白会话时选择会暂存、空白会话出现后自动应用；会话开始后仍可用会话标题栏的 MCP 按钮调整。
3. 会话内调整：打开某个会话，点击标题栏的 MCP 按钮，勾选该会话要使用的服务器（可多选）。
4. 恢复旧会话：重新打开某个会话时，它之前勾选的服务器会自动恢复。
5. 查看工具：设置 → MCP 服务器 列表里每台服务器显示可用工具个数；点击服务器所在行弹出工具详情（名称、描述、参数）。

服务器日志开关

设置 → MCP 服务器 页面顶部有一个「显示 MCP 服务器日志」开关：

• 总开关：开 → 服务器进程自己打出来的日志会被捕获输出；关 → 完全不输出；
• 输出位置（总开关开启时可勾选）：终端（DSH 进程的标准错误输出，即你启动 dsh web 的终端）和/或 日志文件（每台服务器一个文件：~/.dsh/logs/mcp-servers/{服务器名称}.log，带时间戳和服务器名称前缀）；
• 每次连接启动时清空对应服务器的日志文件（每次重连/重启都是一份全新日志）；
• 每台服务器单独控制：列表里每台服务器旁有一个「日志」下拉（跟随总开关 / 开 / 关），默认跟随总开关；
• 只影响本地 stdio 服务器的进程输出；远程 HTTP 服务器没有本地进程；插件自身的连接失败等错误提示始终保留（不影响排障）；
• 切换开关会触发该服务器的连接重连（因为要改变子进程 stderr 的接管方式）。

连接模型（启动自动连接 + 单共享连接）

• 启动自动连接：dsh 启动后自动连接设置里定义的所有服务器（手动断开的除外），不需要任何会话启用；每台服务器在整个 harness 里只有一条连接；
• 会话启用某台服务器 = 把该服务器的工具注册到该会话自己的 agent 上下文（每会话独立一层）；取消启用 = 只移除该会话的工具，连接保持（不再因所有会话停用而关闭）；
• 手动「断开」会把该服务器标记为手动关闭，启动自动连接跳过它；点「连接」重新连上；
• 连接断开后按退避策略自动重连（0.5s→30s，最多 10 次），之后停在错误状态并在设置里显示原因；
• 「测试连接」复用共享连接：已有连接时报告该连接的状态；没有时才临时建立一条并报告；
• 修改服务器配置立即用新配置重连；删除服务器断开并清理所有会话记录。

数据存储

• 服务器定义：写在 DSH 的设置文件 ~/.dsh/settings.yaml 的 mcp.servers: 段（和模型设置等放在一起，你也可以直接改文件；环境变量 / 请求头的值也存这里，与 DSH 其他设置同等信任级别，仅界面隐藏显示）。
• 每个会话的启用记录：单独存在独立 JSON 文件 ~/.dsh/storages/mcp_sessions.json（由 DSH 的存储域设施管理，按会话 id 为键），不掺和设置文件。

工作原理（简述）

• 宿主端是一个 Cordis Service（mcpManager），通过 DSH 官方 API 网关的 source-mode 发现向浏览器暴露 Remote RPC（无需生成代码）；
• 服务器定义注册为设置命名空间 mcp.servers，增删改走 settings.mutate 路径操作，修改/删除会触发共享连接重连/断开与记录清理；
• 插件自己实现 MCP 桥（基于 MCP SDK）：每台服务器维护一条共享连接和一份工具目录；会话启用服务器时，把该服务器的工具注册到该会话自己的 agent 上下文（每会话独立一层，互不影响），工具调用走共享连接；
• 子会话（fork）在 session/created 时复制父会话的记录快照；
• 测试连接复用共享连接的状态；无连接时才临时连接并列出工具；
• 新会话界面的「智能体预设」芯片用外壳原版组件渲染：直接读取外壳平台 seed（@deepseek-ai/dsh-client-ui-primitives）里的 Menu 与图标，并沿用原版 seat 的 cubgiG_* 样式类（该 CSS 已由原包注入页面），因此芯片与下拉框和外壳原生 UI 完全一致；MCP 下拉框也用同一个原版 Menu（多选模式）。若 seed 不可用则自动降级为自绘样式。

已知限制

• 连接状态不是实时推送：会话弹窗内的状态通过轮询（约 1.5 秒一次）刷新；
• 首轮请求可能与工具就绪存在竞态：会话刚打开、服务器还在连接时，第一轮对话的工具列表可能还没有 MCP 工具，连上后下一轮即出现；
• 编辑已连接服务器后，「测试连接」报告的是共享连接（按已保存配置）的状态，不会用未保存的草稿去另开连接；
• 环境变量/请求头不支持点号（FOO.BAR）作为键名（会提示无效）；
• 服务器定义若在 settings.yaml 里被手改坏（缺必填字段等），插件会拒绝加载并给出错误提示，需要修正文件后重启；
• 本插件面向 Web 配置档（dsh web）；其他配置档未测试。

卸载

dsh plugin --profile web remove dsh-mcp-server-manager

remove 会同时把它从配置档的层列表（dsh.profile.bundles）里移除，重启后即完全卸载。 （如果当初用的是「手动方式」，还需把 cordis.patch.yml 里加的 mcp-manager 行删掉。） 已写入的 settings.yaml 的 mcp.servers: 段和 storages/mcp_sessions.json 会保留（可手动清理）。