Nichts0v0/dsh-mcp-manager

dsh-mcp-manager

在 DeepSeek Harness 的 Web 设置页里直接管理 MCP 服务器——运行时添加、编辑、启用/停用、重连、删除，带实时状态、自动重连和配置文件热同步。

功能简介

- Web 设置页 UI — 独立的"MCP 服务器管理"页面：服务器卡片（实时状态）、添加/编辑表单、两步确认的删除保护。
- OAuth 2.0 / RFC 9728 认证支持 — 原生支持 MCP OAuth 2.1 规范与 PKCE，自动发现认证元数据、浏览器授权登录、令牌自动刷新与凭证管理。
- 运行时连接 — 服务器即时连接/断开；工具以 mcp____ 全局注册，所有会话的 agent 都能调用。
- 实时状态 — 可达性探测让关闭的服务器显示 离线 而不是陈旧的"已连接"；卡住的连接 30 秒后判为超时。
- 自动重连 — 初始连接失败按指数退避重试（3s → 60s）；点"刷新"立即重试一次。
- 启用/停用 — 一键停用立即断开并卸载工具；重新启用即自动重连。
- 配置热同步 — $DSH_HOME/mcp-servers.json 被实时监听，外部修改约 1 秒内生效，无需重启。
- 主题与多语言 — 自动跟随 DSH 浅色/深色主题（含外观插件对 --dsw-alias- token 的覆盖）；UI 内置简体中文 / English。

截图

MCP 服务器管理设置页

安装

如果你是人类

方式一：npm 安装（最简单）：

dsh plugin --profile web add dsh-mcp-manager

方式二：源码安装：

1. 克隆并构建：

git clone https://github.com/Nichts0v0/dsh-mcp-manager.git
cd dsh-mcp-manager && npm install      # prepare 脚本会自动构建 lib/

2. 让 loader 能从 profile 解析该包（二选一）：
- 在包含克隆目录的父目录执行（无需写绝对路径）：

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

注意：本包没有 dsh.bundle 层，dsh plugin add 只会把它作为普通 pnpm 依赖安装（保证可解析），仍需第 3 步手动挂载插件行。
- 或用软链接把仓库目录本身链接到 profile 的 node_modules（不要直接复制整个仓库，会把开发用的 node_modules 也带进去）：
- Windows：mklink /J "%DSH_HOME%\profiles\web\node_modules\dsh-mcp-manager"  —— 把  换成你本地克隆的位置
- macOS/Linux：ln -s  $DSH_HOME/profiles/web/node_modules/dsh-mcp-manager

无论哪种方式，最后在 $DSH_HOME/profiles/web/cordis.patch.yml 挂载插件行：

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

重启 dsh web，并强制刷新浏览器页面（Ctrl+Shift+R）以加载新的 __DSH_BOOT__，然后打开 设置 → MCP 服务器 添加你的第一个服务器。

注：Web 面的 cordis.patch.yml 热重载未启用（DSH 共享 HMR 行是关的），改配置后需重启。

如果你是一个 AI agent

请按顺序执行，不要跳步：

1. 通读本 README（尤其是"功能简介"、"已知限制"和本节）。
2. 安装包（优先 npm）：在目标 profile 下运行 dsh plugin --profile  add dsh-mcp-manager（或在 $DSH_HOME/profiles/ 下 npm install dsh-mcp-manager，再用下面的源码方式处理文件布局）。
- 源码兜底：克隆本仓库 → cd dsh-mcp-manager → npm install --ignore-scripts && npm run build（产出自包含的 lib/index.js + lib/client.js，运行时零依赖）→ 把目录链接到 $DSH_HOME/profiles//node_modules/dsh-mcp-manager（Windows 用目录 junction，POSIX 用符号链接）。
3. 挂载插件行：在 $DSH_HOME/profiles//cordis.patch.yml 追加：

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

4. 重启 dsh web（Web 面配置热重载未启用），并提示用户强制刷新浏览器以看到设置页新入口。
5. 验证：GET http://127.0.0.1:3080/mcp-manager/api/health 应返回 {"ok":true,"name":"mcp-manager","version":"",...}。

使用简介

打开 设置 → MCP 服务器：

- 服务器卡片：显示名称、传输方式、状态徽章、端点与 OAuth 标记；停用的卡片变灰。
- 启用/停用开关：停用立即断开并卸载该服务器的工具。
- 重连：自动等待连接结果并刷新（等待时间可配置，默认 15 秒）。
- 编辑：可改传输方式 / URL / 命令 / Headers / OAuth 设置（serverName 不可修改）；保存后原地热更新连接。
- OAuth 授权：对于需要认证的 streamable-http 服务，选择 OAuth 2.0，点击 授权登录 (OAuth) 弹窗完成登录，并支持随时撤销/清除授权。
- 删除：位于编辑页顶部，两步确认（3 秒窗口）。
- 添加：streamable-http（URL + 可选 Headers 或 OAuth 2.0）或 stdio（命令 + 参数），可设连接等待超时。

状态说明

| 状态 | 含义 |
|---|---|
| 已连接 (n 工具) | 工具已注册 |
| 连接中 | 正在握手 / 重连 |
| 服务器离线 | 曾连接成功，但服务器进程当前不可达（探测结果） |
| 连接错误 | 初始连接失败（显示原因）或 30 秒连接超时 |
| 已停用 | 已关闭——不连接、无工具 |

配置文件

$DSH_HOME/mcp-servers.json —— 所有 profile/会话共享：

{
"version": 1,
"servers": [
{
"serverName": "my-http-server",
"transport": "streamable-http",
"url": "http://127.0.0.1:8080/mcp",
"enabled": true
},
{
"serverName": "my-oauth-server",
"transport": "streamable-http",
"url": "https://api.example.com/mcp",
"authType": "oauth",
"enabled": true,
"oauth": {
"clientId": "client-id-123",
"scopes": ["read", "write"],
"tokens": {
"accessToken": "secret_access_token",
"refreshToken": "secret_refresh_token",
"expiresAt": 1787304425000
}
}
}
]
}

文件被实时监听：手工修改（增/删/改/启停）约 1 秒内生效；POST /mcp-manager/api/reload 可随时手动触发。

HTTP API

| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /mcp-manager/api/health | 存活 + 版本 + 存储路径 |
| GET | /mcp-manager/api/servers | 服务器列表（含探测后的实时状态） |
| GET | /mcp-manager/api/servers/ | 单个服务器 |
| POST | /mcp-manager/api/servers | 添加并连接 |
| POST | /mcp-manager/api/servers//update | 更新配置并热重连（serverName 不可改） |
| POST | /mcp-manager/api/servers//toggle | 启用/停用（{"enabled": true|false}） |
| POST | /mcp-manager/api/servers//reconnect | 断开后重连 |
| DELETE | /mcp-manager/api/servers/ | 断开并删除 |
| POST | /mcp-manager/api/reload | 从磁盘重新读取配置文件 |
| POST | /mcp-manager/api/oauth/discover | 探测 MCP 服务的 RFC 9728 OAuth 元数据 |
| POST | /mcp-manager/api/oauth/start | 生成用于浏览器登录的 PKCE 授权链接 |
| GET | /mcp-manager/api/oauth/callback | OAuth 重定向回调与令牌交换 |
| POST | /mcp-manager/api/oauth/revoke | 清除已保存的凭据并断开连接 |

安全

/mcp-manager/ API 可以启动 stdio 服务器——即执行任意命令——因此做了访问控制：

- 可选访问令牌。在 $DSH_HOME/mcp-servers.json 顶层设置 token：

{ "version": 1, "token": "使用一长串随机字符", "servers": [] }

生成：node -e "console.log(require('crypto').randomBytes(24).toString('hex'))"。
配置后所有请求（含 health）都必须携带 Authorization: Bearer ：

curl -H "Authorization: Bearer " http://127.0.0.1:3080/mcp-manager/api/servers

设置页顶部有"访问令牌"输入框——填入一次（保存在浏览器本地），之后自动附带。

- 网络暴露防护。当 dsh web 绑到非 loopback 地址（--host 0.0.0.0）且未配置令牌时，管理器会输出红色错误日志并拒绝所有 /mcp-manager/ 请求（403），直到设置令牌并重启。仅 loopback + 无令牌保持全开，符合单用户本机定位。
- 令牌比对使用常数时间比较（crypto.timingSafeEqual）。
- 令牌明文存在 mcp-servers.json——请保护好该文件（信任级别同 DSH 凭据存储）。

开发

npm install      # 仅构建期依赖；prepare 自动构建
npm run build    # esbuild：lib/index.js（host，全内联）+ lib/client.js（浏览器）
npm run watch    # 监听 client bundle（配合 dsh-client-hmr）

发布：改 package.json 的 version 后运行 npm publish（prepare 脚本会在打包前自动构建 lib/；发布包含 lib/、两份 README 和 LICENSE）。

运行时零依赖：host 半内联了 @deepseek-ai/dsh-mcp-client、MCP SDK 和 cross-spawn；浏览器半是 DSH 客户端模块系统托管的闭包工厂 bundle。

已知限制

- 初始失败是退避重试而非即时 — failOnStartupError 开启，首次连接失败显示 error 并最多每 60 秒重试一次；连接成功后由 mcp-client 自带重连处理断线。
- 可达性探测是 HTTP 层 — 对 streamable-http 服务器发 GET（2.5 秒超时，任何 HTTP 响应都算可达）；stdio 服务器不探测。
- 仅桥接 tools — MCP Resources/Prompts 未桥接（与官方 mcp-client 一致）。
- 鉴权只有令牌、默认仅 loopback — /mcp-manager/ 没有用户体系；对外暴露 --host 0.0.0.0 前请先配置 token（见"安全"一节；stdio 服务器可执行任意命令）。
- 部分 MCP 服务器只允许一个活动客户端（如 Godot MCP）——第一连接未释放时，第二连接会被拒绝并报错。

许可证

MIT