# dsh-mcp-bridge

**Install six curated MCP servers into DSH in one command — and find out which of them actually work on your machine.**

### When you need this

- You want your DSH agent to have MCP tools (browser automation, session memory, file access) without hand-writing six configs and getting the quoting wrong
- A server will not start and you cannot tell whether it is the config, the package or your network
- You want a list that says which servers are genuinely reachable, rather than another copy of the upstream docs

Every curated server is started, handshaken and its tool count checked in CI — `everything` answers with 13 tools, `memory` with 9, `filesystem` with 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)


One install gives your dsh agent a set of MCP servers that are started and queried on every push — not a raw YAML you have to figure out. Every curated server has a machine-readable definition in `servers/`, and `scripts/verify-servers.mjs` checks each one's connectivity, so "verified" is a CI-guaranteed claim, not marketing.

Tools appear to the model as `mcp__<serverName>__<toolName>` (same server-qualified shape as Claude Code / Codex). The bridge itself is DSH's built-in [`@deepseek-ai/dsh-mcp-client`](https://github.com/deepseek-ai/deepseek-harness): stdio + streamable-http, auto-reconnect, HMR hot-swap.

> 中文文档见 [README.zh.md](README.zh.md)。


## Feedback

Installs are visible in the download counts; whether this helps is not. If you use it, one line
about the actual task is worth more than a star — **particularly if it did not work**, which is
the case that never gets reported:

- what you were trying to do
- whether it did it
- what was missing or wrong

[Tell me in an issue](../../issues/new?template=usage.yml) — or if something is already broken,
just open a normal bug report.

## Requirements

This package is a **configuration layer**, not a plugin of its own. Its `cordis.patch.yml`
inserts entries that point at `@deepseek-ai/dsh-mcp-client`, which the host provides.

- **`@deepseek-ai/dsh-mcp-client` must be installed in the profile you are adding this to**,
  at the version matching your DSH line.
- It is declared as a permissive optional peer (`>=0.1.0-rc.6`) rather than a dependency.
  Pinning it previously forced an old copy into the tree whose own peers
  (`dsh-tools@^0.0.1-rc.1`) conflict with current DSH releases, which made installation fail
  on version resolution. Reported as issue #2.

If installation fails, check that the client version in your profile matches your DSH version:

```bash
npm view @deepseek-ai/dsh-mcp-client versions --json | tail -20
```

## Interactive installer

```sh
npx dsh-mcp-bridge init          # pick servers interactively
npx dsh-mcp-bridge list          # catalog + verification status
npx dsh-mcp-bridge validate      # list the MCP entries already in a profile
```

`init` writes real `insert:` entries into the profile's **user patch layer**
(`$DSH_HOME/profiles/<name>/cordis.patch.yml`), so your selection survives plugin
upgrades and coexists with your own patches. It warns about servers that need
environment variables or a placeholder path to edit.

## Why not just configure the MCP servers yourself?

Because the fiddly parts are not the YAML — they are everything around it.

- The user patch layer **overrides** existing entries; naming a new id there fails with
  `patch: entry "x" not found`. New servers need `insert:`.
- Config nested one level too shallow parses to `config: null`, and the server silently never starts.
- A server that connects but exposes no tools looks exactly like a working one until you ask the model.

This bundle ships working shapes, an installer that writes them correctly (`init`), inspectors
(`list`, `validate`) and a verifier that actually connects.

## Quick start

Prereqs: `dsh` and `pnpm` on PATH (`dsh plugin` forwards to pnpm; install with `npm i -g pnpm`).

```sh
dsh plugin --profile web add dsh-mcp-bridge
# local checkout:  dsh plugin --profile web add ./dsh-mcp-bridge
dsh web        # restart the profile
```

The demo server (MCP official `everything`) is enabled by default — no API key, pure local `npx`. After restart, ask your model to "call the everything server's echo tool with hello" and it should use `mcp__everything__echo`.

> First run downloads the server packages via `npx`; subsequent runs are cached.

## Curated catalog

![dsh-mcp-bridge list](assets/screenshot-catalog.png)

| Server | What it gives you | Config needed | Verified |
|---|---|---|---|
| `everything` | Demo tools: echo, add, long-running ops, tiny image | none (default on) | ✅ 13 tools |
| `memory` | In-session knowledge graph (entities/relations) | none | ✅ 9 tools |
| `filesystem` | File read/write/search, **scoped to explicit roots** | root dir (edit args) | ✅ 14 tools (given a real dir) |
| `github` | Repos / issues / PRs | `GITHUB_TOKEN` | ⏸ needs config |
| `playwright` | Browser automation (navigate/click/screenshot) | first-run browser download | ⏸ heavy, excluded from CI |
| `remote-http` | Your own / hosted HTTP MCP server | URL (+ optional token) | ⏸ needs config |

To enable a commented preset, uncomment its block in the profile's `cordis.patch.yml` (hot-reloaded via HMR) or edit `cordis.patch.yml` in this package.

## Verify the catalog yourself

```sh
npm install          # brings @deepseek-ai/dsh-mcp-client → the MCP SDK
npm run verify       # or: node scripts/verify-servers.mjs
```

Prints `PASS` / `SKIP` / `FAIL` per server; exits non-zero on any failure. `VERIFY_TIMEOUT_MS=15000` tunes the per-server timeout. Single-server troubleshooting: `node scripts/probe-server.mjs npx -y your-mcp-server`.

## Adding your own MCP server

Each server is one `@deepseek-ai/dsh-mcp-client` entry. Either add it to the profile's user patch layer (recommended, HMR applies it without restart):

```yaml
# $DSH_HOME/profiles/<name>/cordis.patch.yml
- id: mcp-myserver
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: myserver          # namespace, unique per process ([A-Za-z0-9_-]{1,32})
    transport: stdio              # or streamable-http
    command: npx
    args: ['-y', 'your-mcp-server']
    env:
      YOUR_TOKEN: !!js process.env.YOUR_TOKEN
```

…or drop a definition into `servers/` (so `verify` covers it) and add the matching entry to `cordis.patch.yml` here.

### Config fields (from dsh-mcp-client)

| Field | Transports | Required | Meaning |
|---|---|---|---|
| `transport` | both | yes | `"stdio"` or `"streamable-http"` |
| `serverName` | both | yes | tool namespace, unique among live instances |
| `command` / `args` / `env` / `cwd` | stdio | command yes | child process spec |
| `url` / `headers` | http | url yes | endpoint + auth headers |
| `toolCallTimeoutMs` | both | no | per-call timeout, default 60000 |
| `failOnStartupError` | both | no | reject activation on connect failure (default `false`) |
| `reconnect.*` | both | no | auto-reconnect backoff (default on) |

## Linking up with Reasonix / CodeWhale

All three are agent harnesses — **MCP is the shared language**. Any server you run for Reasonix or CodeWhale can be added here, and a local `streamable-http` server you own can serve DSH, Reasonix and CodeWhale from one process. See `servers/remote-http.json`.

## Troubleshooting (Windows)

- **Headless verification hangs** (`dsh --profile <name> "task"`): the profile needs `@deepseek-ai/dsh-headless` in `dsh.profile.bundles` (add it manually; `dsh plugin add @deepseek-ai/dsh-headless` fails with 404 on its unpublished dependency). Without it the tree activates but no agent consumes the task.
- **`npx` is fine on Windows**: the MCP SDK uses `cross-spawn`, which resolves `.cmd` shims — no `npx.exe` needed.
- **Server connects but no tools**: check the profile logs; `failOnStartupError: false` means the entry activates without tools on failure.

## Releasing (npm)

1. `npm version patch` (or bump `package.json` manually), commit, tag `vX.Y.Z`.
2. `git push origin main --tags`.
3. GitHub Actions (`publish.yml`) publishes to npm — requires npm **trusted publisher** (OIDC) linked to the repo. Setup: npm → Access Tokens → Generate new token → *Publish with GitHub Actions*.

Give the repo the GitHub topic **`dsh-plugin`** so it shows up in the community lists ([awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin), [WhaleHub](https://github.com/vvlife/whalehub-dsh)).

## License

MIT — see [LICENSE](LICENSE).


## A server that is not in the list

The catalog is a starting point, not a ceiling. `add` installs any npm-published MCP server into a
profile and then probes it, so the result is "it works" or "here is what broke":

```bash
npx dsh-mcp-bridge add @modelcontextprotocol/server-memory
npx dsh-mcp-bridge add some-mcp-server --name some --env SOME_API_KEY
```

```
Wrote memory (@modelcontextprotocol/server-memory) to ~/.dsh/profiles/web/cordis.patch.yml

Checking that it actually starts...
  OK — 9 tool(s) listed
```

If the probe fails, the entry stays written so you can fix it in place, and the message says where:

```
  FAILED at connect: MCP error -32000: Connection closed
  the entry is still written so you can fix it in place:
    ~/.dsh/profiles/web/cordis.patch.yml
```

Options: `--profile <name>` (defaults to the first profile), `--name <serverName>` (defaults to a
name derived from the package), `--args a,b` (extra arguments), `--env KEY1,KEY2` (environment
variables passed through from the environment), `--timeout <seconds>`.


## Removing a server

```bash
npx dsh-mcp-bridge remove memory --profile web
```

Removes one `- insert:` entry from the profile's patch layer, leaving every other entry and the
header comment alone. `--dry-run` shows what would be removed without writing; an unknown name exits
2 and lists the entries that are present. Restart the profile for it to take effect.


## When a server does not start

Installing is half the job. When a server never appears in your tool list, `doctor` starts each
one, completes the MCP handshake and lists its tools, so you can see *where* it broke:

```bash
npx dsh-mcp-bridge doctor
```

```
Diagnosing 7 curated server(s), 60s each…

  ✅ everything     16 tools
  ⏸  filesystem     needs configuration first — MCP error -32000: Connection closed
       → fill in its settings before diagnosing: npx -y @modelcontextprotocol/server-filesystem C:/path/to/allowed/root
  ⏸  github         needs GITHUB_TOKEN
  ✅ memory         9 tools
  ✅ playwright     25 tools
  ⏸  remote         needs MCP_TOKEN
  ✅ sequential-thinking 1 tools

4 ok, 3 skipped, 0 failed
```

Failed stages are reported separately because the advice differs:

| Stage | What it means | What to do |
|---|---|---|
| process could not be started | the command is not on PATH | check `npx` is installed |
| server did not complete the handshake | it started and died | run the printed command yourself and read the output |
| handshake worked, listing tools failed | protocol/version mismatch | try the newest release of that server |

Servers that are simply not configured yet are reported as **skipped**, not failed — a placeholder
path is not a bug.

Other commands: `list` (catalog), `init` (install), `validate` (what is in a profile).


## Related

Part of the **dsh-toolkit family** — small, independently useful pieces for
[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness):

- [dsh-mcp-bridge](https://github.com/Edge-Echo/dsh-mcp-bridge) — install six curated MCP servers, verified in CI
- [dsh-win-toolkit](https://github.com/Edge-Echo/dsh-win-toolkit) — clipboard, notifications, hosts, port checks on Windows
- [dsh-netassist](https://github.com/Edge-Echo/dsh-netassist) — network and proxy diagnosis with a concrete next step
- [dsh-driftwatch](https://github.com/Edge-Echo/dsh-driftwatch) — behaviour-drift reports between two session logs
- [dsh-ledger](https://github.com/Edge-Echo/dsh-ledger) — what the agent did to your files, provably unaltered
- [dsh-release-evidence](https://github.com/Edge-Echo/dsh-release-evidence) — one verifiable artifact per release
- [mcp-netassist](https://github.com/Edge-Echo/mcp-netassist) — the same network checks as an MCP server, any client