dsh-plug-mcp

Readme

# dsh-plug-mcp

[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的
**MCP 服务管理器**：在 Web UI 的「设置 → 插件 → MCP」标签页中发现
GitHub 上的 MCP 服务仓库，查看详情后一键安装 / 移除。交互模式参考
[`dsh-plug-manager`](https://github.com/Casually/deepseek-harness-plugs-manage)
（插件市场）；Agent Skills 管理请见姊妹插件
[`dsh-plug-skills`](https://github.com/Casually/dsh-plug-skills)。

## 功能

- **设置 → 插件 → MCP**（Web UI）
  - **发现**：按 GitHub topic 搜索 MCP 服务仓库——`mcp-server` /
    `modelcontextprotocol`，可追加关键词、按最多 Star / 最近更新排序、
    翻页。
  - **详情弹窗**：仓库星标 / topics / 许可证 / README（内置安全 Markdown
    渲染，只放行 http(s) 链接，相对图片改写为 raw.githubusercontent.com），
    外加内容探测——`package.json`（npm 发布状态）/ `pyproject.toml`
    （PyPI 发布状态）/ README 中的 `npx`、`uvx`、`docker run` 线索，给出
    候选启动命令，点选即填入安装表单；也可完全手工填写。
  - **安装**：在用户 patch 层 `$DSH_HOME/cordis.patch.yml`（home 层，
    作用于所有 profile）追加一行 `@deepseek-ai/dsh-mcp-client` 配置
    （stdio：command / args / env；streamable-http：url / headers）。
    DSH 对用户 patch 层做 HMR 监视——**保存即热重载，通常无需重启**。
    写入前备份原文件（`$DSH_HOME/.plug-mcp-backups/`，保留 10 份），写入
    后回读解析校验，绝不写出无法启动的 YAML；编辑为文本级追加 / 删除，
    保留文件中的注释与 `!!js` 表达式。
  - **已安装**：列出 home 层与各 profile 层中的全部
    `@deepseek-ai/dsh-mcp-client` 行（服务名 / 传输方式 / 命令或 URL /
    env 键 / 所在层），自定义确认弹窗后一键移除。
  - **GitHub 代理**：直连 GitHub 受限时，可在页面上直接配置代理并测试
    连通性（见下文「代理配置」）。
- **本地 JSON API**（仅回环地址，由运行中的 web 服务器提供）：
  `/plug-mcp/search`、`/plug-mcp/repo`、`/plug-mcp/local`、
  `/plug-mcp/install`、`/plug-mcp/remove`、`/plug-mcp/proxy`、
  `/plug-mcp/proxy-test`。

## 代理配置

发现功能访问 `api.github.com` / `raw.githubusercontent.com`，候选探测还会
访问 `registry.npmjs.org` / `pypi.org`。出厂部署不挂载平台级 fetch
provider，本插件自行发起请求：默认直连（Node fetch）；**配置代理后经系统
`curl` 发出**，因此支持 `http` / `https` / `socks5` / `socks5h` / `socks4`
（Clash 的混合端口与 SOCKS 端口都可用）。

代理来源按优先级生效：

1. **持久设置**（UI「GitHub 代理」栏输入后点「应用」）——写入
   `DSH 主目录/plug-mcp.json`，立即生效且重启后保留；点「清除」移除；
2. **插件配置**——在 profile 的 `cordis.patch.yml` 中为本插件加
   `config.proxy`（持久生效）：
   ```yaml
   - id: plug-mcp
     name: dsh-plug-mcp
     config:
       proxy: http://127.0.0.1:7890
   ```
3. **环境变量**——`DSH_PLUG_MCP_PROXY`，或标准的 `HTTPS_PROXY` /
   `HTTP_PROXY` / `ALL_PROXY`（大小写均可）。

「测试连接」会请求 `api.github.com/zen` 验证当前生效通道并报告延迟。
特殊值 `direct` 可强制直连（同样会被持久保存）。

注意：代理只影响本插件的 GitHub / 注册表探测请求；MCP 服务运行时
（npx / uvx / docker）的网络由它们自己的配置管理。

## 数据与安全

- MCP 服务以标准 `@deepseek-ai/dsh-mcp-client` 行登记在
  `$DSH_HOME/cordis.patch.yml`（home 层，作用于所有 profile）。
- **每条 MCP 服务命令都是沙箱外的受信可执行代码**（等同于你亲手在
  shell 里跑 `npx -y …`）——只安装你信任源码的服务，http 类服务请确认
  目标地址。想换用 `!!js` 表达式（如 `!!js process.env.X`）引用环境变量
  时，直接编辑 patch 文件即可，本插件的解析 / 回写完整保留 `!!js` 标量。
- 所有安装 / 移除均由你本人在本地界面点击触发，宿主进程直接执行文件
  操作，不经过 agent、不额外审批；操作结果即时反馈。
- patch 文件每次修改前自动备份；文本级编辑失败或回读校验不通过时放弃
  写入，原文件不动。

## 安装

要求宿主有 `curl`（macOS / 主流 Linux 自带）才能使用代理功能；
`dsh plugin` 命令要求 PATH 中有 `pnpm`。MCP 服务运行时按你选择的启动
方式自备 `npx`（Node）/ `uvx`（uv）/ `docker`。

```sh
# npm 安装（推荐）
dsh plugin --profile web add -w dsh-plug-mcp

# GitHub 源码（最新 main；也可 #vX.Y.Z 锁 tag）
dsh plugin --profile web add -w github:Casually/dsh-plug-mcp

# 本地目录（开发自用，在本目录的父目录下执行）
dsh plugin --profile web add -w ./dsh-plug-mcp
```

经 `dsh plugin` 命令安装后**重启 DSH**（`dsh web`）以组合新 bundle。
安装完成后，「MCP」标签页出现在设置 → 插件 下。

## 卸载

```sh
dsh plugin --profile web remove dsh-plug-mcp
```

重启 DSH 以移除该层。已登记的 MCP 服务不受影响（它们是配置，不是插件
的一部分）；如需清理，先在「已安装」页移除。

## 开发说明

- 运行时依赖仅 `js-yaml`（与 harness 同源的 YAML 方言：`!!js` 表达式
  标量按 include 的 `entryListSchema` 原样往返）。
- 宿主插件是纯 ESM；GitHub 抓取默认直连，代理经系统 curl；30 秒超时、
  5 MB 响应上限、10 万字符文本上限。
- 浏览器端以预构建形式交付（`client.js`，`window.__ModuleLoader__`
  格式），仅依赖平台的 `react` wire 模块。
- 给自己仓库打上 `mcp-server` topic 标签，即可出现在「发现」中。

## 许可证

MIT