@sduwall

dsh-wall-mcp-manager

Name: dsh-wall-mcp-manager
Availability: InStock
Author: sduwall

No description

Stars: 0
Language: JavaScript
Created: Aug 29, 2026
Updated: Aug 29, 2026

MCP

GitHub repo

Introduction

@sduwall/dsh-wall-mcp-manager

DSH（DeepSeek Harness）插件：集中管理 MCP 服务配置，并展示每个服务提供的工具、调用参数与返回契约。

插件类型：Cordis Bundle（npm 包）
依赖：@deepseek-ai/cordis、@deepseek-ai/cordis-plugin-loader、 @deepseek-ai/dsh-mcp-client、@deepseek-ai/dsh-settings、@deepseek-ai/dsh-tools （peer，由 DSH 运行时提供）、@deepseek-ai/schemastery
运行环境：Node.js ≥ 20（DSH 内置 Node ≥ 22）
硬依赖服务：loader、tools（inject: ['loader', 'tools']）
可选服务：settings（运行时改配置并热生效；缺失时按组合层配置工作）、 webServer（设置界面的配置桥；缺失时仍照常挂载 MCP，只是没有界面）

它做什么

本插件自己不实现 MCP 协议，只做两件事：

对账：把配置里的服务清单收敛成一组 @deepseek-ai/dsh-mcp-client 实例（一个实例 = 一个 MCP 服务）——新增则挂载、改了则更新、删了则卸载、没变则一动不动；
呈现：通过回环配置桥把「配置 + 挂载状态 + 工具契约」交给设置界面。

为什么是对账而不是「全拆重建」：重建会让所有 MCP 重连一次。用户改一个服务的备注文字，不该把另外五个的 stdio 子进程全杀掉重启。判定依据是实例配置指纹 （toMcpConfig 的输出序列化），因此只改 description 这类非 mcp-client 字段不触发重连。

工具命名与 serverName

MCP 工具在 DSH 里的公开名是 mcp__<serverName>__<原始工具名>。因此：

servers 用字典而非数组，键即 serverName，让「重名」在数据结构上就不可能（serverName 在所有活动 mcp-client 实例之间必须唯一，重复会在挂载阶段抛错）；
serverName 受 [A-Za-z0-9_-]{1,32} 约束（与 mcp-client 内部常量一致），非法名称在插件侧就被拦下并在界面显示原因，而不是只留一行日志；
改名等于换一个服务：工具名会整体变化，模型侧的引用也随之改变。对账时先卸载不再需要的 serverName、再挂载新的，避免改名瞬间在唯一性检查上撞车。

界面按 mcp__<serverName>__ 前缀归组工具（最长前缀优先，正确区分 fs 与 fs_ro），不反解析工具名——publicToolName 在需要字符替换或截断时会追加哈希，其源码明确 "the public name is never parsed to recover it"，但 serverName 段不会被改写。

配置

配置命名空间为 dsh-wall-mcp-manager（settings 命名空间只允许小写 kebab-case，不带 npm scope），形如：

dsh-wall-mcp-manager:
  servers:
    filesystem:
      enabled: true
      transport: stdio
      description: 本地文件访问
      command: npx
      args:
        - -y
        - '@modelcontextprotocol/server-filesystem'
        - D:/workspace
      env:
        LANG: zh_CN
      secretEnv:             # 凭据类环境变量；没有凭据就整段省略，不要写成 {}
        API_TOKEN: xxx
      cwd: ''
      toolCallTimeoutMs: 60000
      failOnStartupError: false
    weather:
      transport: streamable-http
      url: https://mcp.example.com/mcp
      headers:
        X-Trace: 'on'
      secretHeaders:         # 凭据类请求头
        Authorization: Bearer xxx

字段	默认值	说明
`enabled`	`true`	停用则不挂载该服务（保留配置）
`transport`	`stdio`	`stdio`（本地子进程）或 `streamable-http`（远程 HTTP）
`description`	`''`	备注，仅本界面展示，不传给 mcp-client
`command`	`''`	stdio 必填：启动命令
`args`	`[]`	stdio：命令参数，逐项填写（不会按空格拆分）
`env`	`{}`	stdio：环境变量（明文，可在界面查看）
`secretEnv`	无	stdio：凭据类环境变量，`role('secret')`，永不出网
`cwd`	`''`	stdio：工作目录，留空继承 DSH 进程
`url`	`''`	streamable-http 必填：服务地址
`headers`	`{}`	streamable-http：请求头（明文，可在界面查看）
`secretHeaders`	无	streamable-http：凭据类请求头，`role('secret')`，永不出网
`toolCallTimeoutMs`	`60000`	工具调用超时（毫秒，≥1000）
`failOnStartupError`	`false`	启动失败是否让该实例整体失败

secretEnv / secretHeaders 在挂载时被合并进 env / headers（同名以凭据为准）—— 对 mcp-client 而言它们和普通环境变量、普通请求头没有区别，拆成两个字段只是因为明文项要能在界面查看编辑，而凭据项必须只写不读，两者需要不同的 role。

两个凭据字段没有默认值（显式 .default(undefined)）：界面判断「已配置 / 未配置」依据的是脱敏视图里的 set 标记，而它按「值是否为 undefined」判定；schemastery 会给每个 dict 无条件补上 {} 默认值，若不压回 undefined，从没填过的凭据槽位也会显示「已配置」。因此手写 yaml 时不要写 secretEnv: {}，没有凭据就整段省略。

为什么不照抄 mcp-client 的 Schema

mcp-client 自身的 Config 是 z.union([stdio, streamable-http])，但 settings 的 redactSecrets 只穿透 object / dict / array 三种容器，遇到 union 会原样返回整棵子树 （其源码注释明确 "a secret buried inside a union branch is not reachable and must not be modeled that way"）。若按 union 建模，凭据就会随 describe 原文出网。

因此这里用扁平 object + transport 判别字段，挂载时再由 toMcpConfig 按分支重新组装出合法的实例配置——只输出该分支该有的字段，多带一个别分支字段会被 union 直接拒绝。

半成品不影响其他服务

「填了一半的服务」在配置界面里是常态。校验失败（缺 command、名称非法、 transport 不支持）只让该项被跳过并在界面标出原因，不会让整份配置或其他服务失效。单个服务挂载失败（命令不存在、远端不可达）同样只记为该项的失败，绝不外溢成插件整体卸载。

设置界面

插件注册了 settings.section 一级页面「MCP 服务」。界面由浏览器端 bundle （lib/client.js）渲染，通过宿主自建的回环配置桥读写：

路由（均为 POST）	用途
`/api/dsh-wall-mcp-manager/describe`	脱敏配置视图（含 `revision` 与 schema）
`/api/dsh-wall-mcp-manager/mutate`	按 `{ ops, expectedRevision }` 精确改字段
`/api/dsh-wall-mcp-manager/servers`	每个服务的挂载状态（fiber 相位 / 跳过原因 / 失败原因）
`/api/dsh-wall-mcp-manager/tools`	按服务归组的工具清单，含参数与拆包后的返回 schema

只接受本机回环来源（127.0.0.1 / ::1 / ::ffff:127.*）。该桥能写入 MCP 的启动命令与凭据，权限等价于「在宿主上执行任意进程」；DSH 的 webserver 允许绑定 0.0.0.0，那种部署下不做来源校验等于把远程命令执行接口暴露到整个网段。
凭据永不出网：describe 走 redactSecrets: true，整字典标 secret 后连键名都不返回，界面只能显示「已配置 / 未配置」。凭据框留空保存表示不修改，这是既支持修改又不回传原文的唯一语义；要清除请点「清除凭据」。
删除需二次确认：点「删除」只置位待确认，界面就地展开确认条，说明将断开的连接、移除的工具数，以及凭据会被一并清除且无法恢复；再点「确认删除」才真正写入 unset。凭据从不回显，误删一次只能重新去拿密钥，这类不可逆操作不能一键完成。
写入按字段 set / unset（不整体替换），带 revision 乐观锁。整体替换会把浏览器从未见过的 secretEnv / secretHeaders 一并抹掉；乐观锁则保证手改 yaml 与界面并发修改不会互相覆盖。校验失败与修订冲突返回 ok:false，界面保留草稿供修正。
/servers 与 /tools 读的是运行时事实，不依赖 settings 服务，headless 之外的只读展示也可用。未提供数据源钩子时这两条路由干脆不注册（宁可 404 也不回假数据）。
工具卡片展示调用参数与返回契约。mcp-client 给每个工具的返回 schema 套了固定包装 { content, structuredContent }，界面会拆包：声明了 outputSchema 的工具展示其真实结构化字段，只返回文本块的工具明确说明。无法逐字段展开的形态（union / $ref）一律回落到「查看原始 Schema」，不猜、不编造字段。
「其他来源的 MCP 工具」区块列出带 mcp__ 前缀但不属于本插件配置的工具（例如部署配置里直接挂载的 mcp-client 实例），只能查看契约，不能在此修改其配置。

限制：界面依赖本机浏览器访问 DSH 的 Web 服务（回环校验）。通过远程地址访问 GUI 时无法读写配置，请改用 $DSH_HOME/settings.yaml。

DSH 官方「插件配置」页只渲染 dsh-host-apiproxy 中 WEB_SETTINGS_NAMESPACES 白名单内的命名空间，该白名单是包内硬编码常量，仓库外插件无法挂进去；本插件因此走自建路由桥接，并在设置页里完成同样的 Schema 校验与热生效。

热生效

保存配置后立即对账，无需重启 DSH：新增即时连接、修改重连该服务、删除断开连接。连续保存被串行化处理，避免 create / remove 交叉。

注意配置与运行时的时序不同：配置是保存即定，而 MCP 连接与工具注册要等子进程或远端握手完成。保存后界面会短轮询运行状态（约 8 秒），把提示从「正在连接…」推进到「已连接，注册 N 个工具」或具体失败原因，不需要手动刷新。

提示到达终态后 10 秒自动消失，计时从拿到连接结果那一刻起算，不是从点保存起算—— 握手可能耗时数秒，从点击起算会让提示在结果出来之前就消失。进行中的提示不计时也不可关闭，否则这次连接的结论就再也看不到了。多条提示按「服务 / 操作」归并排队共存：同一个服务的轮询文案原地改写（不会 8 秒堆出十几条），不同来源的提示各占一行。

状态徽章分两级，因为 fiber 的「运行中」不等于 MCP 已连上：mcp-client 在 failOnStartupError: false（本插件默认）下，握手失败也不会让实例失败，而是在后台按指数退避重连。所以徽章只在该服务注册出工具时才显示「已连接」，实例活着但握手未成时显示「未连接」。此时反复点「刷新状态」会一直得到同样的结果——那不是刷新失效，而是连接确实没建立，失败原因见 DSH 日志。

配置分三层解析（后者覆盖前者）：Schema 默认值 → cordis 组合层（cordis.patch.yml）→ settings.yaml 用户层。组合层适合部署级默认值，用户层适合随时可能变动的服务与凭据。

安装

dsh plugin --profile <profile> add @sduwall/dsh-wall-mcp-manager

本地源码目录安装亦可：dsh plugin --profile <profile> add ./dsh-wall-mcp-manager。

出厂默认 servers 为空，此时插件正常加载但不挂载任何 MCP，因此安装本身不会启动任何子进程或对外请求。

部署级默认值请写在 profile 自己的 cordis.patch.yml （$DSH_HOME/profiles/<profile>/cordis.patch.yml），而不是本包内的 cordis.patch.yml（后者属于 npm 包，升级会被覆盖）：

- id: dsh-wall-mcp-manager
  config:
    servers:
      filesystem:
        transport: stdio
        command: npx
        args: ['-y', '@modelcontextprotocol/server-filesystem', 'D:/workspace']

注意：patch 会整体替换被命中行的 config，覆盖时要把需要的键全部写出。

运行时挂载 mcp-client 时引用的包名是一个字符串，静态配置检查（verify-cordis-config）看不见它。插件因此导出 MCP_PACKAGE 常量，便于组合方把它声明为依赖。

开发与测试

npm test
# 等价于
node tests/inventory.test.mjs && node tests/mcp-bridge.test.mjs \
  && node tests/client-bundle.test.mjs

测试直接运行文件（避免 node --test 在受限沙箱下的子进程限制）。本地需让 @deepseek-ai/cordis、@deepseek-ai/schemastery、@deepseek-ai/dsh-settings 可解析（可将 node_modules/@deepseek-ai 目录联结到 DSH 安装自带的运行时）。

测试的意图：

纯函数测试（inventory.test.mjs）：配置校验、mcp-client 配置翻译（联合分支多带字段会被拒绝）、挂载计划与指纹（算错会让每次保存都重连 MCP）、返回 schema 拆包、工具前缀归组（错了会把工具挂到别的服务名下）。
配置桥测试（mcp-bridge.test.mjs）：凭据原文与键名都不出网、逐字段写入不抹掉界面从未见过的凭据、回环来源限制、多级 path、修订冲突拒绝、只读存储与 Schema 约束在桥上同样生效、settings 缺失时只读路由照常工作。用真实 settings 实现 + 内存路由表驱动，不绑定端口（被测对象是路由逻辑，listen 只会引入沙箱网络权限依赖）。
客户端 bundle 测试（client-bundle.test.mjs）：在 VM 沙箱里执行浏览器 bundle，验证 __ModuleLoader__ 握手 id、inject（缺了 slots，bundle 会在真实运行时 FAILED）、槽位注册，以及 draftToOps —— 那是界面改动翻成 mutate 操作的唯一出口，一旦它在凭据框留空时多写一个 secretEnv，宿主侧再怎么脱敏也救不回来。

目录结构

dsh-wall-mcp-manager/
├── package.json          # 插件包声明（dsh.bundle.patch → cordis.patch.yml，dsh.client → 浏览器 bundle）
├── cordis.patch.yml      # Bundle 配置入口（插件条目与默认配置，出厂 servers 为空）
├── lib/
│   └── client.js         # 浏览器端 bundle：设置界面「MCP 服务」页面（settings.section）
├── src/
│   ├── index.js          # Cordis 插件入口：Config Schema + 服务清单对账（挂载/更新/卸载）
│   ├── inventory.js      # 纯函数层：配置校验与翻译、挂载计划与指纹、返回 schema 拆包、工具归组
│   └── mcp-bridge.js     # 回环配置桥路由：describe / mutate / servers / tools
└── tests/                # 纯函数测试 + 配置桥测试（真实 settings）+ 客户端 bundle 契约测试

发布

本包以 scoped 包 @sduwall/dsh-wall-mcp-manager 发布到 npm 公共 registry。

npm config set registry https://registry.npmjs.org   # 镜像 registry 不能发布
npm login                                            # 需具备 @sduwall scope 的发布权限
npm pack --dry-run                                   # 核对 tarball 文件清单
npm publish                                          # publishConfig.access=public，scoped 包才不会被当作私有包

prepublishOnly 会在发布前自动跑一遍 npm test，测试不通过则中止发布。

注意包内不带 scope 的三处标识是有意为之，改动会破坏兼容：settings 命名空间 dsh-wall-mcp-manager（只允许小写 kebab-case）、cordis.patch.yml 的 id、配置桥路由前缀 /api/dsh-wall-mcp-manager。而 cordis.patch.yml 的 name 与 lib/client.js 的 __ModuleLoader__.load({ id }) 必须与包名逐字符一致（含 scope），否则 patch 被静默跳过、bundle 注册失败。