@dsh-mixxed/dsh-client-ui-settings-mcp

English | 中文 · ·

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

功能简介

• Web 设置页 UI — 独立的"MCP 服务器管理"页面：服务器卡片（实时状态）、添加/编辑表单、两步确认的删除保护。
• 运行时连接 — 服务器即时连接/断开；工具以 mcp__<serverName>__<tool> 全局注册，所有会话的 agent 都能调用。
• 工具列表 — 服务器卡片可展开，查看该服务器当前暴露的工具名称与描述。
• 实时状态 — 可达性探测让关闭的服务器显示 离线 而不是陈旧的"已连接"；卡住的连接 30 秒后判为超时。
• 自动重连 — 初始连接失败按指数退避重试（3s → 60s）；点"刷新"立即重试一次。
• 启用/停用 — 一键停用立即断开并卸载工具；重新启用即自动重连。
• 配置热同步 — $DSH_HOME/ui-settings-mcp.json 被实时监听，外部修改约 1 秒内生效，无需重启。
• 主题与多语言 — 自动跟随 DSH 浅色/深色主题（含外观插件对 --dsw-alias-* token 的覆盖）；UI 内置简体中文 / English。

截图

安装

如果你是人类

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

dsh plugin --profile web add @dsh-mixxed/dsh-client-ui-settings-mcp

本包声明了 dsh.bundle，因此 dsh plugin add 安装后会自动把它追加到 profile 的 dsh.profile.bundles 层栈——下次启动时插件行自动挂载，无需手动编辑 cordis.patch.yml。

从旧版本（未声明 bundle）升级：请删除 $DSH_HOME/profiles/<name>/cordis.patch.yml 中旧的 ui-settings-mcp 挂载行——bundle 层现在会提供它，两者并存会挂载两次。

方式二：源码安装：

1. 克隆并构建：

   git clone https://github.com/dsh-mixxed/dsh-client-ui-settings-mcp.git
   cd dsh-client-ui-settings-mcp && npm install && npm run build   # lib/ 由 esbuild 生成（发布时 prepack 自动构建）

2. 在包含克隆目录的父目录安装到 profile（无需写绝对路径）：

   dsh plugin --profile web add ./dsh-client-ui-settings-mcp

   本地包同样声明了 dsh.bundle，上面的自动挂载同样生效。

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

注：Web 面的 cordis.patch.yml 热重载未启用（DSH 共享 HMR 行是关的），改配置后需重启；插件集变更（新增行）也需要重启，客户端 pkgMeta 缓存才能发现新包。

如果你是一个 AI agent

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

1. 通读本 README（尤其是"功能简介"、"已知限制"和本节）。
2. 安装包（优先 npm）：在目标 profile 下运行 dsh plugin --profile <profile> add @dsh-mixxed/dsh-client-ui-settings-mcp（或在 $DSH_HOME/profiles/<profile> 下 npm install @dsh-mixxed/dsh-client-ui-settings-mcp，再用下面的源码方式处理文件布局）。
   • 源码兜底：克隆本仓库 → cd dsh-client-ui-settings-mcp → npm install --ignore-scripts && npm run build（产出自包含的 lib/index.js + lib/client.js，运行时零依赖）→ 在克隆目录的父目录执行 dsh plugin --profile <profile> add <克隆目录路径>（或把目录链接到 $DSH_HOME/profiles/<profile>/node_modules/@dsh-mixxed/dsh-client-ui-settings-mcp——Windows 用目录 junction，POSIX 用符号链接）。
3. 无需手动挂载行 — 包声明了 dsh.bundle，dsh plugin add 会自动把它加入 profile 的 bundle 层（可用 dsh --profile <profile> --dump-config 验证 ui-settings-mcp 行已出现）。
4. 重启 dsh web（Web 面配置热重载未启用），并提示用户强制刷新浏览器以看到设置页新入口。
5. 验证：GET http://127.0.0.1:3080/ui-settings-mcp/api/health 应返回 {"ok":true,"name":"ui-settings-mcp","version":"<x.y.z>",...}。

使用简介

打开 设置 → MCP 服务器：

• 服务器卡片：显示名称、传输方式、状态徽章和端点；停用的卡片变灰。
• 工具列表：点击卡片上的"查看工具 (n)"展开该服务器的实时工具名称与描述。
• 启用/停用开关：停用立即断开并卸载该服务器的工具。
• 重连：自动等待连接结果并刷新（等待时间可配置，默认 15 秒）。
• 编辑：可改传输方式 / URL / 命令 / Headers（serverName 不可修改）；保存后原地热更新连接。
• 删除：位于编辑页顶部，两步确认（3 秒窗口）。
• 添加：streamable-http（URL + 可选 Headers）或 stdio（命令 + 参数），可设连接等待超时。

状态说明

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

配置文件

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

{
  "version": 1,
  "servers": [
    { "serverName": "my-server", "transport": "streamable-http", "url": "http://127.0.0.1:8080/mcp", "enabled": true }
  ]
}

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

HTTP API

| 方法 | 路径 | 用途 | |---|---|---| | GET | /ui-settings-mcp/api/health | 存活 + 版本 + 存储路径 | | GET | /ui-settings-mcp/api/servers | 服务器列表（含探测后的实时状态） | | GET | /ui-settings-mcp/api/servers/<name> | 单个服务器 | | POST | /ui-settings-mcp/api/servers | 添加并连接 | | POST | /ui-settings-mcp/api/servers/<name>/update | 更新配置并热重连（serverName 不可改） | | POST | /ui-settings-mcp/api/servers/<name>/toggle | 启用/停用（{"enabled": true|false}） | | POST | /ui-settings-mcp/api/servers/<name>/reconnect | 断开后重连 | | DELETE | /ui-settings-mcp/api/servers/<name> | 断开并删除 | | POST | /ui-settings-mcp/api/reload | 从磁盘重新读取配置文件 |

安全

/ui-settings-mcp/* API 可以启动 stdio 服务器——即执行任意命令——因此按绑定地址做了访问控制：

• 默认仅 loopback。dsh web 绑到 127.0.0.1（默认）时 API 开放，符合单用户本机定位。
• 网络暴露防护。当 dsh web 绑到非 loopback 地址（--host 0.0.0.0）时，管理器会输出红色错误日志并拒绝所有 /ui-settings-mcp/* 请求（403）——stdio 服务器可执行任意命令，因此不提供远程管理通道。
• 单个 MCP server 的认证（如 Authorization 头）在添加/编辑表单的 Headers 字段里按服务器单独配置；管理 API 本身不需要令牌。

开发

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

发布：改 package.json 的 version 后运行 npm publish（prepack 脚本会在打包前自动构建 lib/；发布包含 lib/、cordis.patch.yml（dsh.bundle patch 层）、两份 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 — /ui-settings-mcp/* 没有用户体系或远程管理通道；web 服务器绑到非 loopback 地址时所有请求被拒绝（见"安全"一节；stdio 服务器可执行任意命令）。
• 部分 MCP 服务器只允许一个活动客户端（如 Godot MCP）——第一连接未释放时，第二连接会被拒绝并报错。

许可证

MIT