@mcfso/mcp-admin — DeepSeek Harness 的 MCP 工具插件（含原生管理面板）

让 DeepSeek Harness 正确使用
Model Context Protocol 服务器提供的工具：
连接外部 MCP 服务器，把每个工具注册为 Harness 的原生工具，模型直接以
mcp__<serverName>__<toolName> 的名字调用（与 Claude Code / Codex 的
服务器限定命名一致），并在 设置面板里提供图形化管理界面。

能力一览

• 原生设置面板：设置 → MCP 服务器，查看每台服务器的连接状态与工具数，
  添加 / 编辑 / 删除 / 启用 / 停用服务器 —— 改动即时生效，无需重启 Harness；
• 双来源配置：内联 config.servers（cordis.yml）+ 标准 mcp.json 文件
  （Claude Desktop / Cursor 同格式），自动合并、serverName 全局去重；
• 热加载：mcp.json 的外部编辑（编辑器、脚本）被监听并即时生效；
• /mcp 命令：聊天框输入 /mcp 提示面板入口；
• 连接、发现、命名契约、调用转发、断线重连、tools/list_changed 重同步等
  正确性细节全部由官方桥接
  @deepseek-ai/dsh-mcp-client 承担。

架构

本包是 Harness 的「双面包」插件，走官方客户端插件机制：

装载链路：cordis.yml 以包名 @mcfso/mcp-admin 挂载宿主半边；package.json
的 dsh.client 声明让 dsh-client-modules 在启动时发现本包，把编译好的
lib/client.js（exports["./client"]）通过 /plugins/<id>/client.js 提供给
浏览器，浏览器内核按启动清单（window.__DSH_BOOT__）将其挂载为客户端 cordis 插件。

目录结构

快速开始（使用已发布的 npm 包，推荐）

# 1. 把插件包装进 web profile（从 npm 官方源安装）
dsh plugin --profile web add @mcfso/mcp-admin

# 2. 在补丁层挂载（见本仓库 cordis.yml，核心两行）：
#    - id: mcp-admin
#      name: '@mcfso/mcp-admin'
#      config: { mcpJson: 'D:/dsh-mcp/mcp.json' }

# 3. 重启带补丁的实例
dsh web --patch D:/dsh-mcp/cordis.yml

浏览器 Ctrl+F5 硬刷新 http://127.0.0.1:3080 → 设置 → MCP 服务器。

从源码构建（开发）

cd D:\dsh-mcp
pnpm install
pnpm build
dsh plugin --profile web add "file:D:/dsh-mcp/packages/mcp-admin"   # 本地包覆盖安装
D:\dsh-mcp\restart-harness.ps1

面板使用

• 添加：名称（serverName，工具名将是 mcp__<名称>__<工具名>）、传输方式
  （stdio 本地进程 / Streamable HTTP）、command、args（每行一个）、cwd、
  env（每行 NAME=value，支持 ${VAR} 展开）、url、headers（每行 Name: value）；
• 状态灯：绿 = 已连接（N 个工具）；黄闪 = 连接中 / 已连接无工具；
  红 = 启动失败（卡片显示错误信息）；灰 = 已停用；
• 编辑 / 停用 / 删除：仅 mcp.json 里的服务器；来自 cordis.yml 的内联
  服务器带标签显示、只读；
• 所有改动写入 mcp.json 并即时生效（断开的服务器会按官方桥接的重连策略自动恢复）。

配置

mcp.json（面板管理，推荐）

{
  "mcpServers": {
    "echo": { "command": "node", "args": ["demo/mcp-echo-server.mjs"] },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    },
    "web": {
      "transport": "streamable-http",
      "url": "http://localhost:3000/mcp",
      "headers": { "Authorization": "Bearer ${MCP_TOKEN}" },
      "disabled": true
    }
  }
}

条目规则：transport 缺省按「有 url 即 HTTP、否则 stdio」推断（兼容 http/sse
别名）；cwd 相对 mcp.json 所在目录解析；env/headers 做 ${VAR} 展开
（官方桥接会清洗父进程环境，凭据必须这样显式传入）；disabled: true 停用；
键名含非法字符时用条目内 serverName 覆盖；透传 toolCallTimeoutMs /
failOnStartupError / reconnect（enabled/initialDelayMs/maxDelayMs/maxAttempts）。

cordis.yml 内联

与官方 dsh-mcp-client 配置一致，与 mcp.json 合并加载（内联条目不做 ${VAR}
展开，取环境变量用 !!js process.env.XXX），见 cordis.yml 中的注释示例。

常见问题

• 面板里看不到「MCP 服务器」：先 Ctrl+F5 硬刷新；确认实例是用
  restart-harness.ps1 起的（dsh web --patch D:/dsh-mcp/cordis.yml），
  手动跑不带 --patch 的 dsh web 不会加载插件；
• 启动报「client bundles not found」：客户端 bundle 未构建，跑 pnpm build 后重启；
• 服务器显示启动失败：默认连接失败只记录状态、不阻止 Harness 启动；
  要它失败即报错可勾选「连接失败时让插件加载报错」（failOnStartupError）；
• 工具调用失败：单次调用默认 60 秒超时（toolCallTimeoutMs），服务器返回
  isError 时模型会看到错误结果；
• 服务器崩了：默认自动重连（500ms 起指数退避到 30s，连续 10 次失败后放弃
  并注销工具），期间旧工具保持注册、调用失败直到恢复。

开发

pnpm typecheck   # 宿主半边（严格模式）+ 客户端半边类型检查
pnpm build       # tsc 编译宿主半边 + esbuild 打包客户端 bundle
pnpm demo        # 单独运行演示 MCP 服务器（Ctrl+C 退出）
D:\dsh-mcp\restart-harness.ps1   # 改完代码后重启实例（插件代码改动不走 HMR）

客户端 bundle 内容变化需要重启 Harness 才会进入启动清单
（dsh-client-modules 的包元数据在启动时扫描并缓存）。

已知限制

继承自官方桥接（见其 README）：只桥接 MCP 工具（Resources / Prompts 暂无
Harness 消费者）；图片 / 音频 / 资源内容块在模型上下文中退化为占位符（JSON
原文保留在执行返回值里）；首次连接/发现沿用 MCP SDK 的 60 秒超时。