dsh-mcp-hub

Readme

# dsh-mcp-hub

dsh（DeepSeek Harness）内置 **MCP 服务器管理面板** —— 在会话视图环中提供「MCP」标签页，集中查看和配置当前 profile 的所有 MCP 服务器。

- **读取展示** `cordis.patch.yml`（profile 层）+ 各 bundle 层的 MCP 配置
- **实时工具注册表**：当前进程已连接的 `mcp__*` 工具
- **增删改 MCP 服务器**，保存即重写 `cordis.patch.yml`
- 原生 Harness 风格、无构建步骤、零运行时依赖

---

## 1. 特性

- **MCP 配置一览**：解析并展示 profile 的 `cordis.patch.yml` / `cordis.yml`，以及 `package.json.bundles` 里各 bundle 自带的最小化补丁文件（只读）
- **实时连接状态**：从当前进程的工具注册表反查出每个已连接的 MCP 服务器（`mcp__<server>__<tool>` 前缀），显示工具数量；标注「已配置但当前进程未连接」的服务器
- **可视化配置**：每台服务器一张卡片，可编辑 `serverName` / `transport` / `url`（或 `command`+`args`）/ `env` / `toolCallTimeoutMs`；支持新增、删除、保存
- **保存即生效**：保存时重写 `cordis.patch.yml`；新增的 MCP 通常立即热连接，已有项修改需重启 dsh 应用
- **本机安全**：RPC 路由仅接受 `127.0.0.1` / `localhost` 请求，endpoint 白名单校验

## 2. 安装

在 web profile 的 `package.json` 加：

```json
"dependencies": { "dsh-mcp-hub": "file:E:/dsh/dsh-mcp-hub" }
```

`dsh.profile.bundles` 加 `"dsh-mcp-hub"`，然后重启 `dsh web`。

## 3. 使用

1. 打开会话，在**视图环**（conversation view ring）找到 **「MCP」标签页**（order 20，位于「用量」之后）
2. 面板展示三块：
   - **当前进程已连接的 MCP**：点击 ▸ 展开看该服务器暴露的工具
   - **MCP 配置（cordis.patch.yml）**：可编辑的服务器卡片，保存后写回 profile
   - **来自 bundle（只读）**：各插件 bundle 里自带的最小化 MCP 补丁
3. 常用操作：
   - **新增**：点「＋ 添加服务器」填配置 → 保存
   - **改**：直接改卡片 → 保存
   - **删**：点卡片内「删除」 → 保存
   - **改是否生效**：新增的通常立即热连接；已存在服务器的修改需重启 dsh

## 4. 配置字段

| 字段 | 说明 | 示例 |
|---|---|---|
| **serverName** | 服务器标识（字母/数字/点/下划线/中划线）| `stock` |
| **transport** | 传输方式 | `streamable-http` / `sse` / `stdio` |
| **url** | 非 stdio 时的服务地址 | `http://192.168.1.108:8038/mcp` |
| **command** | stdio 时的启动命令 | `npx` |
| **args** | stdio 参数（空格分隔）| `-y @modelcontextprotocol/server-foo` |
| **env** | 环境变量（每行 `KEY=VALUE`）| `KEY=xxx` |
| **toolCallTimeoutMs** | 单次工具调用超时（毫秒，可选）| `300000` |

保存后 `cordis.patch.yml` 中每个服务器为 `mcp-<serverName>` 块的 `@deepseek-ai/dsh-mcp-client` 配置。

## 5. 架构

```
浏览器 (client.js)                         宿主 (index.js)
   MCP 标签页 (React)                         读取 cordis.patch.yml / bundle 补丁
   │  POST /api/mcp-hub/list                  解析 mcp-* 块 → 卡片
   │  POST /api/mcp-hub/save ←─────────────── 校验 → 重写 cordis.patch.yml
   └─────────(RPC envelope)─────────┐         实时工具注册表 (ctx.tools.schemas)
                                     └────────>  mcp__server__tool 前缀反查
```

- **宿主 `dsh/index.js`**：`/api/mcp-hub` RPC 路由（`list` / `save`），直接读写 `node:fs`（部署归属代码，不沙箱）
- **浏览器 `dsh/client.js`**：Lazy-CJS bundle（`window.__ModuleLoader__.load`），零构建，复用宿主 `react`
- 同源同壳（`client-request` / `server-response` envelope），hostname 仅限本机

## 6. 目录结构

```
dsh-mcp-hub/
├── dsh/
│   ├── index.js       # 宿主：RPC 路由、配置解析/重写、实时工具注册表
│   └── client.js      # 浏览器：MCP 标签页（React）
├── cordis.patch.yml   # bundle 补丁
├── package.json
├── LICENSE            # MIT
├── NOTICE             # 三方依赖声明
└── README.md
```

## 7. 许可证 / 三方依赖

- 插件本体：**MIT**（见 `LICENSE`）
- **零运行时依赖**（`dependencies: {}`）；React 由宿主提供，无内置第三方库（详见 `NOTICE`）

## 8. 回滚

```bat
:: 1) 从 web profile 的 dsh.profile.bundles 移除 "dsh-mcp-hub"
::    （及 package.json dependencies 里的 dsh-mcp-hub）
:: 2) 重启 dsh web
:: 3) （可选）手动编辑 cordis.patch.yml 撤销 mcp-hub 写入的块
```

## 9. 常见问题

- **保存后不生效**：新增服务器通常立即热连接；已存在项的修改需重启 dsh（页面有提示）。
- **显示"已配置但当前进程未连接"**：服务地址不可达或 MCP 服务器未随 dsh 启动，检查地址或重启。
- **stdio 服务器连不上**：确认 `command` 在 PATH 中、`args` 正确、`env` 无多余行（每行必须 `KEY=VALUE` 且 `=` 前为键名）。
- **保存报"无法读取 cordis.patch.yml"**：profile 下没有该文件，先确认 dsh 版本/位置（`$DSH_HOME/profiles/web/`）。