MCP 服务器管理 nekojackie/dsh-mcp-manager

dsh-mcp-manager

在 DeepSeek Harness (DSH) 里管理 MCP 服务器：添加 / 启用 / 停用 / 移除 / 重连，用 OAuth 2.1 授权，靠定时续期与过期后自动续期让 token 一直有效，还能在一个设置页里浏览每个服务器暴露的全部工具及其描述。

本项目由 DeepSeek V4.1 Flash 生成 / This project was generated by DeepSeek V4.1 Flash.

功能 · 安装 · 使用 · OAuth 2.1 · 自动续期 · Agent 工具 · 架构 · 安全 · 测试 · 许可

English summary

A DSH plugin that owns the whole MCP server lifecycle: a Settings page under
Settings → Plugins → MCP Servers, six agent-callable tools (mcp_manager_), a loopback
HTTP bridge for the page, and a built-in OAuth 2.1 client (RFC 9728 discovery, RFC 8414/OIDC
metadata, RFC 7591 dynamic client registration, authorization code + PKCE S256, RFC 8707
resource, refresh, sign-out, paste-token fallback) with a token renewal policy that is editable
in the UI and also self-heals after expiry. Tokens live only in the Harness credential store.
Generated by DeepSeek V4.1 Flash; review before production use.

为什么需要它

DSH 官方的 @deepseek-ai/dsh-mcp-client 每个实例只连一个服务器，清单要手写进 cordis.patch.yml；它只支持静态 headers，不做 OAuth；token 过期后也不会续期，连接会一直带着过期令牌，直到下一次调用 401。这个插件把这三件事补齐，并且不重新实现 MCP 协议——它编排真正的 mcp-client 子插件，所以被管理的服务器在 Harness 里就是普通 MCP 工具。

功能

| 能力 | 说明 |
| 服务器管理 | 添加 / 编辑 / 启用 / 停用 / 重连 / 移除；stdio（command/args/env/cwd）与 streamable-http（url/headers）都支持 |
| 工具浏览 | 每个服务器展开后列出全部工具：公共名 mcp__<服务器>__<工具>、工具描述、入参名；页面与 agent 都能查 |
| OAuth 2.1 | 受保护资源发现、授权服务器元数据、动态客户端注册、授权码 + PKCE S256、一次性 state、resource 指示符、刷新、粘贴令牌兜底、退出授权 |
| 定时续期 | 后台按策略检查（默认每 5 分钟），在到期前（默认 10 分钟）自动换令牌并重连；策略可在页面上改 |
| 过期后自动续期 | 已过期的令牌下一轮必续；更关键的是 401 自愈——某次 mcp__ 调用被判未授权时立即换令牌重连，下一次调用恢复正常 |
| 失败退避 | 续期失败按 30s → 60s → 120s …（上限为检查间隔）重试，不会每轮都打授权服务器 |
| 如实状态 | connected / no-tools / disabled / error / connecting，不猜测"连接成功" |
| 给 agent 的能力 | 6 个工具：mcp_manager_list / add / remove / set_enabled / tools / oauth |
| 凭证安全 | OAuth token 只写进 DSH 凭据库，不进配置、不进日志、不进页面 |

安装

方式 1：一条命令

git clone https://github.com/nekojackie/dsh-mcp-manager.git
dsh plugin --profile <profile> add /path/to/dsh-mcp-manager
dsh <profile>

dsh plugin add 会在 profile 里装包，并自动把 bundle 写进 dsh.profile.bundles； mcp-manager 这行配置由 bundle 自带的 patch 插入，不用手写 YAML。

- <profile> 是 ~/.dsh/profiles/<名字> 的名字，桌面版一般是 desktop；
- dsh 不在 PATH 时用应用目录下的 resources/runtime/cli/bin/dsh （Windows 是 dsh.cmd）；
- 装完在 设置 → 插件 里能看到 MCP Server Manager（行 id mcp-manager，状态 active），旁边的 MCP 服务器 页签就是本插件的界面。

方式 2：让 DSH 自己装

把下面整段发给 DSH 助手即可，它自己会克隆、安装、重启并汇报：

帮我安装并启用 DSH 插件：https://github.com/nekojackie/dsh-mcp-manager

1. 把仓库克隆到任意目录（例如 ~/.dsh/plugins/dsh-mcp-manager；没有 git 就下载 ZIP 解压）；
2. 执行 dsh plugin --profile <当前 profile> add <该目录绝对路径>；如果 dsh 命令不可用，改用 plugin_manager 的 install_bundle，target 指向该目录；
3. 重启 DSH，确认「设置 → 插件」里插件行是 active、并出现「MCP 服务器」页签；
4. 用 mcp_manager_list 把当前 MCP 服务器清单贴给我；
5. 不要改动我已有的 MCP 服务器配置。

这是 AI 生成的插件，OAuth token 会写进 DSH 凭据库，安装前可以先看一眼下面的「安全说明」。

使用

设置界面

设置 → 插件 → MCP 服务器（与 "全部" 页签并列）：

- 每张卡片：名称、传输方式、命令或 URL、状态点、工具数、启用开关、刷新 / 重连 / 编辑 / 移除；
- 展开卡片：该服务器的每个工具 + 描述 + 入参；
- 自动续期设置（可折叠）：启用开关、检查间隔（秒）、提前续期（秒）、"过期后仍自动续期"、保存 / 恢复默认；
- 授权成功后卡片会自己跟上：已授权 → 正在连接… → 工具数量，不需要手点刷新。

直接改配置

清单与续期策略都保存在本插件这一行的 config 里：

- id: mcp-manager
name: dsh-mcp-manager
config:
refreshIntervalMs: 300000 # 检查周期，0 = 关闭，默认 5 分钟 refreshLeadMs: 600000 # 提前多久续期，默认 10 分钟 refreshOnExpiry: true # 过期后仍自动续期（默认开） servers:
- name: demo # ^[A-Za-z0-9_-]{1,32}$，同时是工具前缀 enabled: true transport: stdio command: npx
args: ['-y', '@modelcontextprotocol/server-everything']
env: {}
cwd: ''
toolCallTimeoutMs: 60000
failOnStartupError: false
- name: docs
enabled: true
transport: streamable-http
url: http://127.0.0.1:3000/mcp
headers: {}
oauth:
enabled: true # 需要 OAuth 时
scopes: [] # 留空 = 用服务器元数据里的 required_scopes
clientId: '' # 留空 = 动态客户端注册

服务器字段：name enabled transport command args env cwd url headers toolCallTimeoutMs failOnStartupError oauth{enabled,scopes,clientId,clientSecret,resourceMetadataUrl,authorizationServer}。

OAuth 2.1 授权

受 OAuth 保护的 streamable-http 服务器（其 /.well-known/oauth-protected-resource 会声明 authorization_servers 与 required_scopes）不再需要手工复制 token：

1. 编辑服务器，勾选 使用 OAuth 授权，保存；
2. 卡片上点 授权（浏览器） → 插件完成发现 + 动态注册 + PKCE，返回授权链接并在浏览器打开；
3. 在授权页同意后回跳到 http://127.0.0.1:<DSH 端口>/api/dsh-mcp-manager/oauth/callback；
4. 插件换取 token（存进凭据库）、重连该服务器，工具随即出现。

| 其它操作 | 行为 |
| 粘贴令牌 | 已有 access token 时的兜底；存为非过期授权 |
| 刷新令牌 | 立即用 refresh_token 换新并重连 |
| 全部续期 | 对所有已授权服务器强制续期一遍 |
| 退出授权 | 删除本地授权记录并断开 |

- 授权链接 10 分钟有效、state 一次性；重复打开会提示"已使用"，重新点授权即可（会顶掉旧尝试）。
- 令牌过期前 60 秒内的下一次连接也会兜底刷新。
- 刷新失败（invalid_grant）会清掉本地记录并把状态显示为未授权，不会静默失联。

自动续期

| 触发 | 行为 |
| 定时 | 每 refreshIntervalMs 检查，expiresAt 进入 refreshLeadMs 窗口即续期 + 重连 |
| 已过期 | 过期但仍有 refresh_token 的授权，下一轮必定续期 |
| 过期自愈 | mcp__ 调用返回 401/unauthorized/invalid_token/token expired 等时，立刻续期 + 重连（每台 30s 最多一次，最多 3 次，30/60/120s 退避） |

页面会显示当前策略、上次续期时间、下次检查时间，以及"上次续期触发：定时 / 过期后自愈 / 手动"。

智能体工具

| 工具 | 作用 |
| mcp_manager_list | 列出受管服务器：传输、地址、状态、工具数、启动错误 |
| mcp_manager_add | 新增或替换（同名覆盖）一台服务器；含 oauth 设置 |
| mcp_manager_remove | 移除服务器及其配置 |
| mcp_manager_set_enabled | 启用 / 停用（保留配置） |
| mcp_manager_tools | 列出已注册的 MCP 工具：公共名、描述、入参名，可按服务器过滤 |
| mcp_manager_oauth | status / authorize / paste-token / refresh / refresh-all / signout |

架构

lib/index.js Host 半边：清单校验与持久化（configEditor）、子插件编排（ctx.plugin 真 mcp-client）、 6 个 agent 工具、12 条回环桥接路由（11 POST + GET 回调）、续期定时器与 401 自愈 lib/oauth.js OAuth 2.1 引擎：仅 node:crypto + 全局 fetch；发现 / 注册 / PKCE / 换取 / 刷新 / 凭据读写 lib/client.js Web 半边：settings.plugins.tab 页签，纯 JS（无构建、无 Harness 内部包依赖） docs/.md 实现契约（v1 基础 / OAuth / 定时续期 / 可编辑策略），Host 与 Web 两半的字段与接口 fixtures/.mjs 本地测试夹具：假 MCP 服务器（stdio / HTTP）、OAuth 授权服务器 + 受保护 MCP、引擎端到端断言

数据流：页面 ⇄ POST /api/dsh-mcp-manager/（仅回环）⇄ Host；Host 用 configEditor 写 profile patch 并触发 Loader 重载，用 ctx.plugin() 把每个启用的服务器实例化为一个真正的 mcp-client，用
ctx.tools.schemas() 汇总 mcp__* 工具。

安全说明

- OAuth token 只进 DSH 凭据库 ~/.dsh/.credentials.yaml，记录键 mcp-manager/<slug> （服务器名 docs → mcp-manager/docs）。不写进 cordis.patch.yml、不返回给页面、不进 agent 上下文、不写日志。
- 页面拿到的只有：是否已授权、过期时间、scope、clientSecretSet（是否已保存）。
- 桥接路由只接受回环请求；除 OAuth 回调（GET，仅回环）外均只接受 POST。
- clientSecret、headers、env 属于配置，会留在 profile patch 里——共享机器请优先用凭据中心的环境变量。
- 授权页会展示 client_id 与 PKCE challenge；请不要把授权链接转发给别人。

已知限制

- OAuth 仅实现授权码 + PKCE 流程；依赖授权服务器支持动态客户端注册，否则需在表单里填 clientId。
- client_credentials、设备码等流程不支持。
- 过期自愈依赖错误文本能看出是鉴权问题（401/403/unauthorized/invalid_token/token expired 等）；服务端如果只回自定义错误，则只能等下一轮定时续期。
- 修改清单或续期策略都会重载插件，因此所有服务器会重连一次；"重连"按钮是单服务器路径。
- 停用的服务器不续期。
- 续期成功会重连该服务器（旧连接带着旧令牌），会有约半秒的重连窗口。
- 页面外观未做逐像素比对；逻辑与桥接行为有端到端测试。

开发与测试

仓库自带夹具，不需要外网：

1) OAuth 引擎端到端（会自己起授权服务器与受保护 MCP）
node fixtures/oauth-mcp-rig.mjs 8792 &
node fixtures/verify-oauth-engine.mjs 8792
→ 44 项断言：发现 / 动态注册 / PKCE / state / 回调换取 / Bearer 注入 / 过期刷新 / invalid_grant 清库 / 粘贴令牌 / 退出 / 重放拒绝

2) 无鉴权的 MCP 服务器（stdio 与 HTTP），用来验证管理器本身
node fixtures/mock-mcp-server.mjs # stdio
node fixtures/mock-mcp-http.mjs 8791 # streamable-http，路径 /mcp

语法检查：node --check lib/index.js、node --check lib/client.js、node --check lib/oauth.js （三个文件都没有构建步骤）。

兼容性

- 开发与验证环境：DSH 0.2.1-rc.2、Node 24 / Windows 11；使用 Node >= 20 的语法与 API。
- 依赖 Harness 提供的 @deepseek-ai/dsh-mcp-client（运行时动态导入，不打包）。
- 回环回调天然适配桌面端；远程/容器部署时授权回跳地址需能访问 127.0.0.1:<端口>。

许可

MIT

声明

本项目由 DeepSeek V4.1 Flash 生成，包含 AI 生成的代码与文档。它按"现状"提供，不附带任何担保；涉及 OAuth 凭证、远程服务器与配置写入，请在正式环境使用前自行审阅并做好备份。