dsh-mcp-plus

Readme

# dsh-mcp-plus

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**DSH（DeepSeek Harness）增强型 MCP 客户端插件** —— 在 DSH 的设置界面里管理多台 MCP 服务器：增删改配置、实时查看连接状态，服务器的工具自动发现并注册给 Agent 使用。

![dsh-mcp-plus 设置页](docs/screenshots/overview.png)

## 特性

- 🖥️ **图形化管理**：在 DSH 设置 → 「MCP 服务器」页直接编辑 JSON 配置，无需手改 yml
- 🟢 **实时状态**：每台服务器一个状态圆点 —— 🟢 已连接 / 🟡 连接中（闪烁）/ ⚪ 未连接或已禁用
- 🎛️ **独立启停**：每台服务器支持 `enabled` 开关，禁用不删除，配置保留
- 🔁 **自动重连**：保存配置后自动重连并重新注册工具，无需重启 DSH
- 📋 **兼容主流格式**：直接粘贴 Claude Desktop 风格的 `mcpServers` JSON 即可导入

## 前置条件

| 依赖 | 版本要求 |
|---|---|
| DSH（DeepSeek Harness） | ≥ 0.1.2-alpha.1（host 半与 client 半均在该版本实测加载） |
| Node.js | ≥ 18 |
| pnpm | ≥ 9（构建时使用） |

## 安装

### 方式一：脚本安装（推荐）

克隆本仓库后，在项目根目录执行：

```bash
pnpm install && pnpm build
node scripts/install.mjs --profile web    # 装到 web profile
# node scripts/install.mjs --all          # 或装到所有 profile
```

然后在 profile 目录里刷新依赖并重启 DSH：

```bash
cd ~/.dsh/profiles/web
pnpm install
pnpm dsh web
```

### 方式二：npm 安装

```bash
cd ~/.dsh/profiles/web
pnpm add dsh-mcp-plus
```

包内自带 `dsh.bundle.patch` 声明，安装后把 `dsh-mcp-plus` 加进 profile 的 `dsh.profile.bundles` 数组即可激活。

## 使用

1. 启动 DSH，打开 Web 界面
2. 侧边栏点「设置」→ 顶部 tabs 选「MCP 服务器」
3. 点「修改配置(JSON)」，粘贴/编辑服务器配置，点「保存」

### 配置格式

支持以下三种形态（推荐第一种，与 Claude Desktop 配置兼容）：

```jsonc
// ① 对象映射:键即服务器名(推荐,可直接粘贴 Claude Desktop 的 mcpServers 内容)
{
  "chrome-devtools": {
    "command": "cmd.exe",
    "args": ["/c", "npx", "-y", "chrome-devtools-mcp@latest"],
    "env": {},
    "cwd": "",
    "enabled": true
  },
  "filesystem": {
    "command": "node",
    "args": ["path/to/mcp-server-filesystem/dist/index.js", "C:/允许访问的目录"]
  }
}

// ② 带包裹层的完整 Claude Desktop 格式(直接整段粘贴也行)
{ "mcpServers": { "服务器名": { "command": "...", "args": ["..."] } } }

// ③ 原生数组格式
[ { "transport": "stdio", "serverName": "名字", "command": "...", "args": ["..."] } ]
```

**字段说明**：

<!-- 截图位 3:JSON 编辑器(展示编辑态 + 底部保存栏)
![JSON 编辑](docs/screenshots/json-editor.png)
-->

| 字段 | 必填 | 说明 |
|---|---|---|
| `command` | ✅ | 启动 MCP 服务器的可执行文件 |
| `args` | — | 命令行参数数组 |
| `env` | — | 额外环境变量（`{ "KEY": "value" }`） |
| `cwd` | — | 子进程工作目录 |
| `enabled` | — | `false` = 保留配置但不连接（默认 `true`） |
| `serverName` | 数组形态必填 | 服务器名（对象形态用键名），`[A-Za-z0-9_-]{1,32}`，用作工具名前缀 |

保存后插件自动连接所有启用中的服务器，发现的工具以 `mcp__<服务器名>__<工具名>` 注册给 Agent。

## 状态说明

列表中每台服务器名字前的圆点表示实时连接状态：

- 🟢 **已连接** —— 工具已注册，Agent 可调用
- 🟡 **连接中**（闪烁）—— 正在启动/握手（`npx` 类命令首次冷启动可能需要较长时间）
- ⚪ **未连接** —— 连接失败（检查 command/args 是否正确，详见终端日志）
- ⚪ **已禁用** —— `enabled: false`，配置保留但不连接

## 开发

```bash
pnpm install
pnpm build        # 构建宿主半 + 浏览器半到 lib/
```

源码模式（`pnpm dsh`，带 tsx）启动还需要一个 patch 覆盖层，把 TS 入口挂进 profile。该文件写的是本机绝对路径，不入库，请自行在仓库根创建 `cordis.yml`：

```yaml
- insert:
    - id: dsh-mcp-plus
      name: 'file://<本仓库绝对路径>/src/dsh-mcp-plus.ts'
```

把 `<本仓库绝对路径>` 换成实际路径（正斜杠）后启动：

```bash
pnpm dsh web --patch ./cordis.yml
```

插件装进 profile 后走的是编译产物，不需要这个文件——`cordis.patch.yml` 里的 `name` 用的是包名。

项目结构：

```
src/
├── dsh-mcp-plus.ts   # 宿主半入口:连接管理、工具注册、生命周期
├── client.ts         # 浏览器半入口:设置页 UI(React)
├── config.ts         # 配置类型与校验(四种 JSON 形态规范化)
├── servers-store.ts  # servers.json 读写(~/.dsh/dsh-mcp-plus/servers.json)
└── http.ts           # HTTP 端点(UI 与宿主半的读写通道)
```

## License

MIT