@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 的「双面包」插件，走官方客户端插件机制：

半边	文件	职责
宿主（Node）	packages/mcp-admin/src/index.ts	连接引擎（每服务器一个官方桥接实例、差异同步、mcp.json 监听）+ /mcp-admin/api/* 管理路由 + /mcp 命令
客户端（浏览器）	packages/mcp-admin/src/client/index.tsx	React 设置分节「MCP 服务器」，经 ctx.slots.inject("settings.section") 注册进原生设置面板，主题色用 --dsw-alias-* 令牌自动适配明暗

装载链路：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 插件。

目录结构

路径	作用
packages/mcp-admin/	插件包（宿主半边 + 客户端半边 + 构建产物 lib/）
cordis.yml	补丁覆盖层：把插件插入 web profile（--patch 用）
mcp.json	MCP 服务器清单（面板管理的就是它；内置演示 echo 服务器）
demo/mcp-echo-server.mjs	零依赖演示 MCP stdio 服务器（一个 echo 工具）
scripts/build-client.mjs	esbuild 打包客户端 bundle（window.__ModuleLoader__.load 工厂格式）
restart-harness.ps1	重启 3080 实例并挂载补丁（自检端口；日志 restart.log / instance.log）

快速开始（使用已发布的 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 秒超时。