内容
<div align="center">
# dsh-mcp ⚡
### Fast and cheap — the heavy work runs on deepseek-v4-flash.
### An execution layer for MCP agents — powered by a local DeepSeek Harness.
Agentic coding tools are expensive and slow for one reason: the parent model
reads files one by one. `dsh-mcp` flips that — **the parent agent keeps the
reasoning, the local DeepSeek Harness does the heavy lifting**: batch reads,
edits, and command runs, priced at deepseek-v4-flash rates, on your machine.
**Works with any MCP client · tested end-to-end with Claude Code**
**🌐 [English](README.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja-JP.md)**
</div>
---
## Why: fast and cheap, by design
**The pain.** Long-horizon, multi-file work is where agentic tools bleed money
and time: the parent model grinds through every file itself — one `Read` per
file, exploration loops, context that grows and drifts. You pay the parent's
per-token rates for the *reading*, and you wait for the model to do it
*serially*.
**The fix.** One `delegate_to_dsh` call hands the whole token-heavy subtask to
a fresh, focused DeepSeek Harness agent running **deepseek-v4-flash** inside
your workspace. All the file I/O happens there — batched, local, cheap. The
parent stays in the loop for what actually needs a brain: **planning,
diagnosis, decisions, verification**.
Measured on 100 SWE-bench-style long-horizon tasks (heterogeneous model setup:
parent = deepseek-v4-pro, DSH = deepseek-v4-flash; arm B runs the same parent
model without the plugin):
| | with `dsh-mcp` | raw agent |
|---|---|---|
| **Accuracy** | **100/100 · 100%** | 89/100 · 89% |
| **Avg. wall time** | **76s** | 120s |
| **Statistical significance** | — | Fisher p < 0.001 |
Faster, more accurate — and the accuracy gap is now statistically significant
(p = 3.7×10⁻⁴ at n=100), not just directional. The expensive reads now run on
deepseek-v4-flash. [Full report](tests/bench/bench-report.md) ·
[Reproduce it](#benchmark)
## How it works
*The prompt used to generate this is in
[`docs/architecture-image-prompt.md`](docs/architecture-image-prompt.md).*
- **A standard MCP stdio server.** Any client that speaks MCP can use it —
Claude Code is the client we validated end-to-end (real API calls, subdir
launches, Chinese, spaces in paths).
- **Parent-agent model.** Each delegation is one self-contained subtask; DSH is
a stateless worker (fresh process per call — no session to corrupt).
- **Zero config, works out of the box.** The DSH CLI is auto-discovered (env override →
sibling checkout → child checkout → installed under `%USERPROFILE%\.dsh`).
- **Windows-first.** `process.execPath` + explicit argv, `shell: false` — no
quoting bugs, no `.cmd` shims, spaces-in-paths just work.
## Quick start
**Step 1 — build once**
```powershell
cd dsh-mcp
npm install
npm run build # → dist\index.js
```
**Step 2 — register with your MCP client (Claude Code shown as the example)**
```powershell
claude mcp add dsh `
--transport stdio `
--env DEEPSEEK_API_KEY=sk-... `
-- node D:\path\to\dsh-mcp\dist\index.js
claude mcp list # confirm "dsh" is listed
```
This is a standard MCP server — the same `dist\index.js` also works with
OpenAI Codex, Cursor, VS Code and any other MCP client (see
[Deployment](#deployment)).
**Step 3 — restart Claude Code, then make your first delegation**
Claude Code loads MCP servers at startup, so restart it inside any project.
Then just ask, in plain words:
> Have DSH read this project's README.md and package.json, and report the
> project name and the first paragraph of the README. Don't read the files
> yourself — delegate everything.
You'll see Claude call `delegate_to_dsh`, and the answer comes back in
seconds. DSH runs in **your** project root — never in the `dsh-mcp` directory.
> `delegate_to_dsh` not showing up? Re-run `claude mcp list` — if the server
> failed to start, it will report an error there. Jump to
> [Troubleshooting](#troubleshooting).
## Benchmark
> 100 long-horizon, multi-file tasks in two batches (01–50: bug fixes,
> refactors, migrations, implement-from-spec, test-driven, audit; 51–100:
> harder — deep data flows, async races, state machines, parsers, caches,
> cross-process state) · automated ground-truth verification (run assertions +
> stdout checks; clean fixtures must fail, reference fixes must pass)
> · heterogeneous model setup: parent = deepseek-v4-pro on both arms, DSH =
> deepseek-v4-flash on arm A · full breakdown:
> [`tests/bench/bench-report.md`](tests/bench/bench-report.md)
> · **experiment note: the Claude Code in this benchmark runs on a
> deepseek-v4-pro kernel** (configured via the `ANTHROPIC_MODEL` env var) —
> the parent is a DeepSeek model, not an Anthropic model, on both arms. The
> delta is therefore exactly the plugin: the same DeepSeek parent, with vs.
> without `dsh-mcp`
> · dataset: [`tests/bench/tasks.mjs`](tests/bench/tasks.mjs)
| | with `dsh-mcp` | raw agent |
|---|---|---|
| **Accuracy** | **100/100 · 100%** | 89/100 · 89% |
| **Avg. wall time** | **76.5s** | 120.2s |
| **Total wall time** | 7647s | 12019s |
| **Failures** | 0 | 11 |
**What the numbers say**
- **Every raw-agent failure is a "finished half" failure.** 5 of 11 are
cross-file jobs (renames, log migrations, util splits) where the raw agent
changed references but left the old file behind, or migrated 3 of 5 files;
5 are single-point jobs where it fixed one bug out of two, escaped 3 of 5
HTML chars, deduped but didn't sort. DSH verifies inside the delegation and
catches the leftovers before handing back.
- **Multi-file investigation stays the biggest win** — batch "read N files +
analyze" in one delegation vs. file-by-file reads that lose early context.
- **Statistically significant now.** Fisher exact test on accuracy
(100% vs 89%, n=100): p = 3.7×10⁻⁴ (< 0.001). The 20-task pilot was
directional only; at 100 tasks the gap is real.
- **The harder batch (51–100) makes the plugin look better, not worse** —
arm A: 100% in both batches, avg 65s on the hard batch; arm B: 88% → 90%
but still leaves 11 failures overall.
- **Honest exception** — one shared-module extraction (10) was slower through
DSH (multi-file rewrite round-trips). Nothing like it reappeared in the hard
batch.
Reproduce:
```powershell
DEEPSEEK_API_KEY=sk-... node tests\bench\run-bench.mjs AB 01-50 # both arms, 100 tasks
DEEPSEEK_API_KEY=sk-... node tests\bench\run-bench.mjs AB 51-100 # (range filter)
DEEPSEEK_API_KEY=sk-... node tests\e2e-headless.mjs # real E2E (A/B/C/D)
DEEPSEEK_API_KEY=sk-... node tests\long-horizon-e2e.mjs # multi-delegation loop
```
> Keys only ever enter a temp `mcp.json` inside a sandbox, deleted on exit —
> never written to the repo, never printed.
## Tools
One tool family, split by responsibility so the parent agent picks by intent
(tool name + description are the model's decision input):
| Tool | Use it for | Constraint |
|---|---|---|
| `delegate_to_dsh` | generic self-contained tasks | none — everything is up to your task text |
| `dsh_investigate` | read-only analysis: read files, trace call flows, "find where X is used" | the agent is instructed to never modify files or run side-effecting commands |
| `dsh_fix` | modifying code: bug fixes, refactors, migrations, well-specified implementations | the agent verifies (when the task names a check) and lists every file it changed |
| `dsh_execute` | running commands: test suites, build scripts, environment queries | the agent reports full output + exit code, leaves source files alone |
| `dsh_status` | environment diagnostics: DSH resolution, CLI version, model config, timeout, key presence | no DSH child process, no API key required |
All delegation tools share one schema: `task` (required), `cwd` (optional),
`timeoutMs` (per-call override of `DSH_MCP_TIMEOUT_MS`) and `trackChanges`
(default true).
**Change tracking — the black box gets a tail.** DSH's headless CLI only
returns its final message: no diff, no file list. Every delegation therefore
snapshots your workspace before and after and appends a `[mcp]` block to the
result, so the parent can see what the delegation actually touched:
```text
<DSH final output>
[mcp] exitCode: 0
[mcp] durationMs: 45210
[mcp] cwd: D:\workspace\foo
[mcp] changedFiles: 2
[mcp] M src/store.js (modified)
[mcp] A src/store.test.js (added)
```
Use `trackChanges: false` (or `DSH_MCP_TRACK_CHANGES=0`) to skip snapshots on
very large repositories. Dependency/build dirs (`node_modules`, `.git`,
`dist`, `build`, `coverage`, …) and hidden dirs are always excluded.
> Category constraints are enforced via task templates, not the CLI — DSH's
> headless mode has no read-only flag. Change tracking is the safety net: if
> `dsh_investigate` did modify something anyway, the `[mcp] changedFiles`
> list exposes it and the parent can check the files itself.
## Deployment
`dsh-mcp` is a **standard MCP stdio server**. Any client that speaks MCP can
host it — Claude Code, OpenAI Codex, Cursor, VS Code, Claude Desktop, or your
own tooling. The server and the `dsh` tool family are identical everywhere;
only the registration step differs. Claude Code is the client we validated
end-to-end.
### Claude Code (one command — the example)
```powershell
claude mcp add dsh `
--transport stdio `
--env DEEPSEEK_API_KEY=sk-... `
-- node D:\path\to\dsh-mcp\dist\index.js
claude mcp list
```
### OpenAI Codex
Codex loads MCP servers from its config at `%USERPROFILE%\.codex\config.toml`
(project-level: `.codex\config.toml`). Append:
```toml
[mcp_servers.dsh]
command = "node"
args = ["D:\\path\\to\\dsh-mcp\\dist\\index.js"]
env = { DEEPSEEK_API_KEY = "sk-..." }
```
Restart `codex`, then just ask — e.g. "Use the dsh_investigate tool to read
the README and package.json and report the project name." Codex cannot see
inside DSH (it is a black box to the host), which is exactly why every
delegation returns the `[mcp] changedFiles` block — the parent learns what
the delegation touched even when the host is not Claude Code.
### Any other MCP client
Point your client at `dist\index.js` with the same env vars. Most clients
accept a JSON `mcpServers` block (Claude Code project-level config, Cursor
`mcp.json`, VS Code, Claude Desktop, …):
```json
{
"mcpServers": {
"dsh": {
"command": "node",
"args": ["D:\\path\\to\\dsh-mcp\\dist\\index.js"],
"env": { "DEEPSEEK_API_KEY": "sk-..." }
}
}
}
```
> Don't commit the key. The automation scripts delete their temp config before
> exiting.
### Where can DSH be installed?
DSH is located in exactly four places, checked in order — **the server never
looks at `PATH`**:
1. `DSH_ROOT` env var — explicit override, wins unconditionally
2. A sibling checkout next to this package: `..\deepseek-harness`
3. A child checkout inside this package: `.\deepseek-harness`
4. An installed CLI package under the DSH home:
`%USERPROFILE%\.dsh\profiles\node_modules\@deepseek-ai\dsh`
(`DSH_HOME` overrides the home directory)
So you can install DSH **anywhere** — a sibling checkout, a dedicated tools
directory, a different drive — and point `DSH_ROOT` at it. Either layout
works: a source checkout (build its CLI first: `pnpm install && pnpm run build`)
or an installed CLI package (`<root>\lib\bin.js`). Anything outside these four
locations is simply not discovered; the error message tells you to set
`DSH_ROOT`.
```powershell
# register with a DSH that lives in your own directory
claude mcp add dsh `
--transport stdio `
--env DEEPSEEK_API_KEY=sk-... `
--env DSH_ROOT=D:\tools\deepseek-harness `
-- node D:\path\to\dsh-mcp\dist\index.js
```
### Environment variables
| Variable | Meaning |
| --- | --- |
| `DEEPSEEK_API_KEY` | **Required.** Passed to DSH through the environment. |
| `DSH_ROOT` | Optional. Point at a DSH checkout / installed CLI. |
| `DSH_HOME` | Optional. DSH home (default `%USERPROFILE%\.dsh`). |
| `DSH_MCP_TIMEOUT_MS` | Optional. Child timeout; **unset = no timeout**. |
| `DSH_MCP_DEBUG=1` | stderr diagnostics (`[dsh-mcp] dshRoot=... cli=...`). |
### Troubleshooting
| Symptom | Fix |
| --- | --- |
| `Unable to locate DeepSeek Harness` | Set `DSH_ROOT`, or install the DSH CLI (`npx @deepseek-ai/dsh`) |
| `CLI build artifact is missing` | In the DSH checkout: `pnpm install && pnpm run build` |
| `DEEPSEEK_API_KEY is not configured` | Re-add with `--env DEEPSEEK_API_KEY=...`, restart Claude Code |
| Wrong workspace | Resolution: tool `cwd` → `CLAUDE_PROJECT_DIR` → `MCP_WORKSPACE_DIR` → server cwd |
| Delegation fails, can't tell why | Run `dsh_status` first — it reports DSH resolution, CLI version, model config, timeout and key presence |
## How to delegate
Every delegation tool takes one `task` argument (see [Tools](#tools) for
the full family). Each call spawns a **brand-new** DSH agent that runs in
your project workspace and returns its final result. DSH has no memory
across calls — that's the design (no session to corrupt) — and it sets the
one rule that matters:
> **Make every delegation self-contained.** Give DSH everything the subtask
> needs: the file paths, the context, the expected result. Never write
> "as above", "like before", or "that file I mentioned earlier" — DSH cannot
> see your conversation.
### Good vs. bad delegation
The same task, written two ways:
```text
❌ "Fix the bug in the store module and verify."
— Which module? What bug? Verify how? DSH has no memory of "the" bug.
✅ "In src/store.js, createOrder() (around line 42) computes the order total
without the tax field. Fix it so the total includes tax. Then run
node src/tests/order.test.js and report the output."
— Self-contained: file, bug, expected behavior, verification command.
```
### Three templates that cover most delegations
**1. Investigation — DSH reads the files, the parent reads the report**
```text
Read src/modules/a.js, b.js and c.js and report: (1) every exported
function signature, (2) all TODO/FIXME comments with line numbers,
(3) where each module is imported from. Don't modify anything.
```
**2. Fix + verify — the parent decides, DSH executes and checks**
```text
In src/utils.js, slugify(" hello ") returns "hello " instead of "hello"
(leading whitespace leaks through). Fix it, then run
node src/test/utils.test.js and report which assertions pass.
```
**3. Batch edit — one delegation instead of N read/edit round-trips**
```text
Across the project, replace every occurrence of config.port with
config.serverPort in all .js files (skip node_modules). List each file
you changed, one line per file.
```
### When to delegate — and when not to
| Delegate (token-heavy, self-contained) | Keep with the parent (needs context) |
|---|---|
| Read + summarize N files | Weighing two architectures |
| Multi-file rename / migration / refactor | Deciding what to build next |
| Run a suite / script and report output | A debugging conversation that evolves |
| Implement a well-specified function | Anything whose goal is still unclear |
### What a delegation looks like in a session
```text
You: The login flow is broken. Have DSH trace login.js → session.js → db.js
under src/auth/ and report where an error could be swallowed, with
line numbers. Don't read the files yourself.
DSH: Found it: src/auth/session.js:37 catches the error and returns null
instead of rethrowing, so login.js treats the failure as "not logged
in". Three files read, nothing modified.
```
## Cost model
Fast and cheap both come from the model on the DSH side: **deepseek-v4-flash**.
Early development ran entirely on flash (parent and DSH alike); the 100-task
benchmark above runs the heterogeneous combo **parent = deepseek-v4-pro[1m],
DSH = deepseek-v4-flash** (arm B uses the same pro parent without the plugin,
so the delta is the plugin). The Claude Code kernel in the benchmark is
DeepSeek's model — `ANTHROPIC_MODEL: deepseek-v4-pro[1m]` — not an Anthropic
one; the claims below only assume a strong parent, regardless of vendor.
- **Faster** — token-heavy subtasks (file reads, exploration loops) run batched
in DSH instead of serially in the parent session; measured −36% average wall
time (76.5s vs 120.2s).
- **Cheaper** — the heavy token spend runs at deepseek-v4-flash rates, and the
parent's token budget is minimized by delegation (pure reasoning).
- **Zero migration** — `delegate_to_dsh` is model-agnostic end to end.
## Verified
| Layer | Coverage | Status |
| --- | --- | --- |
| Unit | 42 vitest (DSH discovery / workspace / runner / change tracking / tools) | ✅ |
| Real E2E (Claude Code) | subdir launch · Chinese · spaces in path · real API | ✅ |
| Long-horizon | plan → investigate → decide → fix → read-back → verify | ✅ 5/5 |
| A/B benchmark | 100 tasks × 2 arms (accuracy + runtime, p<0.001) | ✅ |
| DSH write probe | headless profile can write files | ✅ |
## Design & limitations (V0.x)
- **Synchronous wait-for-result** — no streaming, no background, no polling
(ENGINEERING §0/§23). A long task is one longer MCP call; no timeout by
default.
- **Stateless workers** — each delegation is a fresh DSH process (fresh startup
cost; fine for simple tasks).
- **Concurrent delegations** edit the same workspace at their own risk — prefer
read-only / independent subtasks.
- **Windows-first**, MIT licensed. Docs & engineering rationale:
[`DSH_MCP_ENGINEERING(1).md`](DSH_MCP_ENGINEERING(1).md) (§0–§40).
## Disclaimer
`dsh-mcp` is an independent open-source project. It is **not affiliated with,
endorsed by, or sponsored by OpenAI, Anthropic, or DeepSeek**. DeepSeek Harness
is DeepSeek's open-source project; this adapter merely integrates with its CLI
over the MCP protocol. All product names and trademarks belong to their
respective owners.
## License
MIT
连接信息
猜你喜欢
暂无推荐服务器