Edge-Echo/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.

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: stdio + streamable-http, auto-reconnect, HMR hot-swap.

中文文档见 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 — 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:

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

Interactive installer

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).

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

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

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):

# $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, WhaleHub).

License

MIT — see 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":

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

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:

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:

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