# dsh-mcp-bridge

**一条命令给 DSH 装好 6 个精选 MCP 服务器，并告诉你哪些在你机器上真的能用。**

### 什么时候需要它

- 想让 DSH 用上 MCP（浏览器自动化、会话记忆、文件访问），但不想手写六份配置、还要担心引号转义
- 某个 server 起不来，分不清是配置写错、包有问题，还是网络不通
- 想要一份「哪些 server 真的连得上」的清单，而不是再抄一遍上游文档

每个精选 server 都在 CI 里被真的启动、握手、数出工具数 —— `everything` 13 个工具，`memory` 9 个，`filesystem` 14 个。

![dsh-mcp-bridge](https://raw.githubusercontent.com/Edge-Echo/dsh-mcp-bridge/main/banner.svg)


[![npm version](https://img.shields.io/npm/v/dsh-mcp-bridge?color=4d6bfe&logo=npm)](https://www.npmjs.com/package/dsh-mcp-bridge)
[![npm downloads](https://img.shields.io/npm/dm/dsh-mcp-bridge?color=22d3ee)](https://www.npmjs.com/package/dsh-mcp-bridge)
[![license](https://img.shields.io/npm/l/dsh-mcp-bridge?color=4d6bfe)](LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/Edge-Echo/dsh-mcp-bridge?color=22d3ee)](https://github.com/Edge-Echo/dsh-mcp-bridge)


一条命令装上经过实战检验的 MCP server 集合——而不是让你自己去琢磨一份 YAML。每个精选 server 在 `servers/` 里有机器可读定义，`scripts/verify-servers.mjs` 会逐个检查连通性，所以「已验证」是 CI 保证的事实，不是宣传话术。

模型看到的工具名为 `mcp__<serverName>__<toolName>`（与 Claude Code / Codex 的服务器限定命名一致）。桥接层是 DSH 内置的 [`@deepseek-ai/dsh-mcp-client`](https://github.com/deepseek-ai/deepseek-harness)：支持 stdio / streamable-http、自动重连、HMR 热替换。

> English docs: [README.md](README.md).


## 反馈

下载量能看出装了多少次，看不出有没有用。如果你在用，**一句话说明你拿它做什么，比点个 star 有用得多**——尤其是**没跑通**的情况，那是最不会有人主动说的：

- 你想做什么
- 它做到了吗
- 缺什么、哪里不对

[开个 issue 说一句](../../issues/new?template=usage.yml) —— 如果是明确的 bug，直接开普通 issue 就行。

## 交互式安装器

```sh
npx dsh-mcp-bridge init          # 交互式选择服务器
npx dsh-mcp-bridge list          # 查看目录 + 验证状态
npx dsh-mcp-bridge validate      # 列出 profile 里已配置的 MCP 条目
```

`init` 会把真正的 `insert:` 条目写进 profile 的**用户 patch 层**
（`$DSH_HOME/profiles/<name>/cordis.patch.yml`）——所以你选的服务器能跨插件升级保留，
并和你自己的 patch 共存。需要环境变量或占位路径的服务器会给出警告。

## 为什么不自己配？

因为难的不是 YAML，而是它周围的一切。

- 用户 patch 层是**覆盖**语义：在那里写一个新 id 会报 `patch: entry "x" not found`，新服务器必须用 `insert:`。
- 配置少缩进一层会被解析成 `config: null`，服务器静默地永远不启动。
- 连上了但没暴露工具的服务器，和正常工作的服务器长得一模一样，直到你问模型。

这个包提供了可用的写法、会写对的安装器（`init`）、检查器（`list`、`validate`），以及一个真的会去连接的验证器。

## 快速开始

前置条件：`dsh` 与 `pnpm` 在 PATH 上（`dsh plugin` 内部转发 pnpm；未装可 `npm i -g pnpm`）。

```sh
dsh plugin --profile web add dsh-mcp-bridge
# 本地开发：  dsh plugin --profile web add ./dsh-mcp-bridge
dsh web        # 重启 profile
```

默认启用 MCP 官方 `everything` 演示 server（无 API key，纯本地 npx）。重启后让模型「调用 everything 服务器的 echo 工具，传 hello」，它应该会用 `mcp__everything__echo`。

> 首次运行会通过 `npx` 下载 server 包，之后有缓存。

## 精选目录

| Server | 能干什么 | 需要的配置 | 验证状态 |
|---|---|---|---|
| `everything` | 演示工具：echo、add、长任务、小图片 | 无（默认开启） | ✅ 13 个工具 |
| `memory` | 会话内知识图谱（实体/关系） | 无 | ✅ 9 个工具 |
| `filesystem` | 文件读写/搜索，**仅限显式授权的根目录** | 改 root 目录（args） | ✅ 14 个工具（给定真实目录时） |
| `github` | 仓库 / issue / PR | `GITHUB_TOKEN` | ⏸ 需配置 |
| `playwright` | 浏览器自动化（导航/点击/截图） | 首次需下载浏览器 | ⏸ 较重，CI 跳过 |
| `remote-http` | 自建 / 托管的 HTTP MCP server | URL（可选 token） | ⏸ 需配置 |

启用某个注释预设：在 profile 的 `cordis.patch.yml` 里取消对应注释块（HMR 热替换，无需重启），或直接改本包的 `cordis.patch.yml`。

## 自己验证目录

```sh
npm install          # 会带入 @deepseek-ai/dsh-mcp-client → MCP SDK
npm run verify       # 或：node scripts/verify-servers.mjs
```

逐个打印 `PASS` / `SKIP` / `FAIL`，有失败时退出码非 0。`VERIFY_TIMEOUT_MS=15000` 可调单 server 超时。单 server 排障：`node scripts/probe-server.mjs npx -y your-mcp-server`。

## 添加自己的 MCP server

每个 server 就是一条 `@deepseek-ai/dsh-mcp-client` 条目。推荐加到 profile 的用户 patch 层（HMR 即时生效）：

```yaml
# $DSH_HOME/profiles/<name>/cordis.patch.yml
- id: mcp-myserver
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: myserver          # 命名空间，进程内唯一（[A-Za-z0-9_-]{1,32}）
    transport: stdio              # 或 streamable-http
    command: npx
    args: ['-y', 'your-mcp-server']
    env:
      YOUR_TOKEN: !!js process.env.YOUR_TOKEN
```

或者：把定义放进 `servers/`（这样 `verify` 会覆盖它），并在本包 `cordis.patch.yml` 里加对应条目。

### 配置字段速查（来自 dsh-mcp-client）

| 字段 | 传输 | 必填 | 说明 |
|---|---|---|---|
| `transport` | 两者 | 是 | `"stdio"` 或 `"streamable-http"` |
| `serverName` | 两者 | 是 | 工具命名空间，存活实例内唯一 |
| `command` / `args` / `env` / `cwd` | stdio | command 必填 | 子进程规范 |
| `url` / `headers` | http | url 必填 | 端点 + 认证头 |
| `toolCallTimeoutMs` | 两者 | 否 | 单次调用超时，默认 60000 |
| `failOnStartupError` | 两者 | 否 | 连接失败时拒绝激活（默认 `false`） |
| `reconnect.*` | 两者 | 否 | 自动重连退避（默认开启） |

## 与 Reasonix / CodeWhale 联动

三者都是 agent harness——**MCP 就是共同语言**。你给 Reasonix / CodeWhale 配的任何 server 都能加到这里；自建的 `streamable-http` server 可以让 DSH、Reasonix、CodeWhale 共用一个进程。见 `servers/remote-http.json`。

## 排错（Windows）

- **headless 验证挂起**（`dsh --profile <name> "任务"`）：profile 需要在 `dsh.profile.bundles` 里手动加 `@deepseek-ai/dsh-headless`（`dsh plugin add @deepseek-ai/dsh-headless` 会因其未发布依赖 404 失败）。缺它时树能激活但没有 agent 消费任务。
- **Windows 下 `npx` 正常可用**：MCP SDK 使用 `cross-spawn`，能解析 `.cmd` shim，不需要 `npx.exe`。
- **server 连上了但没有工具**：看 profile 日志；`failOnStartupError: false` 时失败条目会静默激活但不注册工具。

## 发布（npm）

1. `npm version patch`（或手动改 `package.json`），提交，打 tag `vX.Y.Z`。
2. `git push origin main --tags`。
3. GitHub Actions（`publish.yml`）自动发布到 npm——需要 npm **trusted publisher**（OIDC）关联仓库。设置：npm → Access Tokens → Generate new token → *Publish with GitHub Actions*。

给仓库打上 GitHub topic **`dsh-plugin`**，这样会出现在社区列表里（[awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)、[WhaleHub](https://github.com/vvlife/whalehub-dsh)）。

## License

MIT — 见 [LICENSE](LICENSE)。

## 相关

属于 **dsh-toolkit 家族** —— 一组各自独立可用的小工具，面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)：

- [dsh-mcp-bridge](https://github.com/Edge-Echo/dsh-mcp-bridge) —— 一条命令装好 6 个精选 MCP server，CI 逐个验证
- [dsh-win-toolkit](https://github.com/Edge-Echo/dsh-win-toolkit) —— Windows 剪贴板、通知、hosts、端口检测
- [dsh-netassist](https://github.com/Edge-Echo/dsh-netassist) —— 网络与代理诊断，直接告诉你下一步
- [dsh-driftwatch](https://github.com/Edge-Echo/dsh-driftwatch) —— 两次会话日志的行为漂移报告
- [dsh-ledger](https://github.com/Edge-Echo/dsh-ledger) —— agent 到底动了哪些文件，且记录不可篡改
- [dsh-release-evidence](https://github.com/Edge-Echo/dsh-release-evidence) —— 每次发布一个可验证的证据包
- [mcp-netassist](https://github.com/Edge-Echo/mcp-netassist) —— 同一套网络检查，做成任意 MCP 客户端可用的服务器