🐳 DeepSeek-DSH-MCP

English | 中文

Give Claude Code / Codex a coding buddy that sticks around — powered by DeepSeek Harness.

An MCP server that drives DSH as a long-lived agent runtime instead of wrapping a CLI. Open a conversation, hand it a goal, and it writes code, runs scripts and spawns its own subagents — while you watch, cut in, and collect the result whenever you like. 🛠️

🧪 504 checks green · 🔌 MCP over stdio · 📜 MIT · 💬 Community: linux.do

📌 Read the Usage Notes first — the practical gotchas that will actually bite you: the ACP model-config trap, external MCP tools bypassing DSH's sandbox, the workspace/GUI registry cache, cost control, and a troubleshooting table.

📑 Contents

• ✨ Why it's different · ⚡ Why not just wrap the DSH CLI

• 🚀 Setup · 🧰 Tools

• 📋 Dispatch then collect · 🔔 Completion notifications · 🧵 Many conversations

• 🔐 Permissions · 🤫 Reasoning · 🕶️ Logging and privacy

• 🔒 The write lock · 🪟 GUI visibility

• ⚙️ Environment · 🧪 Tests · ⚠️ Known limitations

Claude / Codex  ──MCP(stdio)──▶  dsh-mcp
                                    │ newline-delimited JSON-RPC (ACP)
                                    ▼
                            dsh --profile dsh-mcp        ← one long-lived process per conversation
                                    │
                                    ├─ DSH's own tools (files, shell, search, skills, subagents, workflows)
                                    └─ dsh-mcp-client ─▶ your other MCP servers (e.g. IDA Pro)

Related MCP server: hermes-dsh-bridge

✨ Why it's different

⚡ Why not just wrap the DSH CLI?

DSH ships two programmable entry points. The sdk profile looks simpler, but its JSON-RPC surface has only 3 requests and 4 notifications — and it lacks three things that make an agent unusable in practice. The acp profile (Agent Client Protocol) has all of them. Everything below was verified against DSH 0.1.7-rc.2.

Core idea: the process is a cache, not the identity. A conversation's identity is DSH's sessionId, persisted under ~/.dsh/sessions. If the process is reaped, crashes, or the whole MCP server restarts, the next call transparently session/resumes it — history intact.

📦 Requirements

• Node.js ≥ 20

• DSH installed (@deepseek-ai/dsh), with working credentials under ~/.dsh

• A DSH profile named dsh-mcp derived from the shipped acp template, containing your own provider/model config (this repo deliberately ships no provider config)

🚀 Setup

1. Create the DSH profile

dsh dsh-mcp --from-default-profile acp

Then edit ~/.dsh/profiles/dsh-mcp/cordis.patch.yml and declare your provider and model. Start from profile-example/cordis.patch.yml.

⚠️ Two traps here (both learned the hard way):

1. ACP's model does NOT come from agent-default-model. It comes from the dsh-acp plugin's own config.provider / config.model, which the acp bundle hard-codes to deepseek-official. If you don't override the acp row, your sessions silently run on the wrong provider and fail with no API key for provider route "deepseek-official".

2. ACP's reasoning_effort defaults to empty (= "Provider default"), not to the maximum. This server explicitly sets it to max on every session/new and after every session/resume — because a fresh process does not remember the previous choice.

2. Register the server

Claude Code

claude mcp add dsh-mcp -- node /absolute/path/to/DeepSeek-DSH-MCP/bin/dsh-mcp.mjs

Codex (~/.codex/config.toml)

[mcp_servers.dsh-mcp]
command = "node"
args = ["/absolute/path/to/DeepSeek-DSH-MCP/bin/dsh-mcp.mjs"]

Generic MCP client

{
  "mcpServers": {
    "dsh-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/DeepSeek-DSH-MCP/bin/dsh-mcp.mjs"]
    }
  }
}

3. Try it

node test/smoke.mjs        # no LLM calls, verifies the whole plumbing

🧰 Tools

📋 Workflow: dispatch, then collect later

MCP tool calls block, so dsh_send does not block by default (wait=false): you get a receipt immediately, the turn runs in the background, and the sentinel file wakes you when it finishes. The whole flow:

1. dsh_send(conversation_id, prompt, wait=false)
     → { run_id: "run-abc123", background: true }        # returns in ~1 ms

2. …keep working on something else (verified: another conversation ran a full turn meanwhile)…

3. dsh_status(conversation_id)
     → state=running | elapsed=3.5s | current_tool=pwsh | out=37 chars

4. dsh_read(conversation_id, cursor)                      # peek mid-flight
     → [me] … | [turn] turn 1 started | [tool] pwsh [in_progress]

5. dsh_get(conversation_id, run_id)                       # collect the result
     → status=done, elapsed=20.3s, full answer

run_id is the receipt. Run records are memory-only, last 20 kept; under many concurrent runs old ones get evicted and dsh_get will fail — which is exactly why the completion sentinel below carries the result.

🔔 Workflow: get notified on completion (no polling)

Besides run_id, wait=false returns a sentinel_file path plus sentinel_file_posix (the Bash/MSYS form — use it directly; hand-converting Windows paths is the easiest way to make your waiter hang until timeout). When the turn ends — whether it succeeds, fails, or is cancelled — the service atomically writes a small file there containing the final status and result. So you neither poll nor block: wait for that file with a background task in your own host (Claude/Codex); the moment it appears, you're woken up.

# sent="$sentinel_file_posix"   ← copy it straight from the tool result
sent='/d/AI_MCP/DSH_MCP/.state/runs/<conversation_id>/<run_id>.json'
dl=$(( $(date +%s) + 2100 ))          # 35min safety net so a dead service can't hang you forever
until [ -f "$sent" ]; do
  [ "$(date +%s)" -ge "$dl" ] && { echo "TIMEOUT"; exit 1; }
  sleep 2
done
echo "DONE"                            # task exits → host wakes you → read the file to collect

Once the file exists: read it for status and result (preferred — immune to the in-memory window and survives restarts), or use dsh_get(conversation_id, run_id).

Design notes (especially under concurrent multi-session use):

• No cross-talk: the path is .state/runs/<conversation_id>/<run_id>.json, namespaced by conversation. run_id sequence numbers are counted per-conversation, so two conversations can mint the same run_id in the same millisecond — the per-conversation directory keeps them apart. Arm one background task per run; each completes and wakes you independently.

• Latch semantics: the file is written once and kept. Even if the run finishes before you arm the waiter, [ -f ] is immediately true — you never miss it.

• Atomic write: tmp + rename; if the file exists its contents are complete. Each run uses its own tmp, so concurrent writes never clobber.

• No server push: the service only answers requests over MCP (it sends no notifications). "Completion notification" is entirely the sentinel file plus your background waiter.

• ★ No reasoning in the sentinel: the payload carries the answer and thinking statistics only — result.thinking is stripped and replaced by thinking_omitted: true, because the project's rule is that reasoning never reaches disk. dsh_get(run_id) still returns it from memory while the record lives. DSH_MCP_SENTINEL_INCLUDE_REASONING=1 breaks that guarantee deliberately.

Cleanup: sentinels contain full answers, so the service prunes sentinels older than 7 days at startup (tune with DSH_MCP_SENTINEL_TTL_MS; 0 disables). Your waiter should still rm the file after consuming it.

🧵 Workflow: many conversations at once

1. dsh_list(only_running=true)
     - … | id=448b239b… | 🔵 running (9s, tool=pwsh, 40 chars this turn) | cwd=…
     - … | id=33427096… | 🔵 running (8s, 34 chars this turn)        | cwd=…
2. dsh_read(id,  cursor=0)      # read the first, note the cursor
3. dsh_read(id2, cursor=0)      # switch to the second
4. dsh_read(id,  cursor=<prev>) # switch back, deltas only

🤫 Reasoning: hidden by default

DSH separates reasoning from answer text at the model layer, and ACP exposes them as two independent streams. This server hides reasoning by default and returns only statistics (characters, duration, chunk count) — so the caller knows thinking happened without paying for it in context.

• reasoning=hide (default) — content dropped, stats returned

• reasoning=marker / summary / full — progressively more content (mind your context budget)

• dsh_read(include_reasoning=true) — live reasoning of the currently running turn only; it is never buffered and is discarded when the turn ends

🔐 Permissions

on_approval can be auto-allow, auto-deny, or ask (which exposes a pending approval for dsh_approval_decide to adjudicate).

🪟 Workspace visibility in the DSH GUI

Two different things — don't confuse them:

Verified experimentally (test/workspace-effect.mjs): two conversations in two desktop folders, given no path at all, each wrote its file into its own workspace, self-reported the correct working directory, and leaked nothing into the server's cwd / home / temp / the other workspace (24/24 checks).

Maintenance CLI:

node bin/dsh-mcp-workspaces.mjs --list                  # inspect the registry
node bin/dsh-mcp-workspaces.mjs --backfill              # register every session found on disk
node bin/dsh-mcp-workspaces.mjs --prune-temp            # drop temp-directory entries
node bin/dsh-mcp-workspaces.mjs --prune-empty           # drop empty workspaces whose path is gone
node bin/dsh-mcp-workspaces.mjs --purge-test-sessions   # delete test sessions (strict rules)

⚠️ Before restarting DSH, don't touch workspaces in the GUI — the server will write its in-memory state back over the file.

🕶️ Logging and privacy

Silent by default — not one byte is written.

1. MCP's stdout is the protocol channel; anything mixed in corrupts the stream.

2. This server is launched by Claude/Codex, so its stderr lands in their logs.

3. DSH's own stderr may carry model output including reasoning, so it is never forwarded by default.

Reasoning never reaches disk — with exactly one deliberate exception:

• Not in logs (silent by default), and the state file holds metadata only (id, cwd, permissions, counters) — a smoke-test assertion guards this.

• The async completion sentinel does persist the answer (it must, so a caller can collect offline) but strips result.thinking and marks thinking_omitted: true. A test asserts that even when reasoning=full is requested, no reasoning text appears in the sentinel — while dsh_get(run_id) still returns it from memory. Set DSH_MCP_SENTINEL_INCLUDE_REASONING=1 to break this on purpose.

• Sentinels are pruned after 7 days by default (DSH_MCP_SENTINEL_TTL_MS; 0 keeps them forever).

(DSH itself writes its own session log under ~/.dsh/sessions; that is what makes resume possible and is outside this server's control.)

⚙️ Environment variables

🧪 Tests

node test/run.mjs          # smoke only (no LLM calls)
node test/run.mjs --all    # everything
node test/cleanup.mjs      # suite teardown on its own (temp dirs only; --dry-run to preview)

The suite cleans up after itself: run.mjs always ends with cleanup.mjs, which removes test sessions and workspace registrations inside the OS temp directory only. Real project sessions and the repo's .state/ (your live conversation registry and sentinels) are never touched. To also remove Desktop\dsh-mcp-test-* artifacts, run node bin/dsh-mcp-workspaces.mjs --purge-test-sessions explicitly.

| multi | 19 | several instances and non-ASCII paths: reproduces "two instances share the registry and the later save drops the earlier instance's conversation", then proves that conversation is recoverable by id alone from the session store and actually usable; recovery never silently escalates privileges (a read-only conversation stays read-only); no .tmp residue; and CJK / emoji workspace paths create sessions, do real work, and place files in the right directory | | permission | 11 | ★ whether the permission tiers actually take effect (a safety property): it ignores our own return values (the very thing that used to lie) and reads the session's own record (permissions.preset / sandboxMode in the projection cache), checking all three tiers and that their recorded values differ. This suite caught a silent privilege escalation: a defaultPreset in the profile overrides DSH_PERMISSION_MODE at session creation | | list | 13 | the cost of dsh_list (measured): a default call with the on-disk probe takes ~1 s (it spawns a DSH process) while repeated calls hit a cache and drop to single-digit milliseconds; only_running=true and include_closed=false skip the probe with equivalent semantics (unopened on-disk sessions are simply excluded) |

Total: 504 checks, all green. (468 in-suite + 36 acceptance)

🔒 The write lock: one writer per conversation at a time

DSH conversations carry a cross-process write lock: it never expires while the holder lives, and no API can take it from a live holder — so whoever gets there first decides everything. This server turns that into "you can look, we can write":

Who holds it is reported by dsh_status.lock_holder; dsh_takeover handles the four cases:

Two measured footnotes. ① A crash leaves no orphan lock — SIGKILL the MCP and its children exit with it (their stdio pipe closes), releasing the lock automatically ✓; so stale-mcp really means "alive but wedged". ② Several instances: the registry is last-writer-wins (a later save drops conversations it never saw), but the session store is authoritative — any session on disk is recoverable by id alone; if you give instances different DSH_MCP_STATE files, point DSH_MCP_LOCKS_DIR at one shared directory, or they cannot see each other's holder registrations.

The full measurements (the A/B probe method, the evidence that the GUI opens read-only, why even archiving does not release the lock, and crash-vs-wedge) are in Usage Notes §3.5–3.12.

⚠️ Known limitations

1. No token-level streaming into model context — an MCP limitation, not DSH's. Callers get per-step results; humans can follow progress via stderr logs.

2. True mid-turn steering is impossible — ACP rejects concurrent prompts (a prompt is already in flight for this session). dsh_interject is the practical equivalent: cancel, then immediately start a new turn, history preserved.

3. Image prompts are unsupported — ACP advertises promptCapabilities: {image: false}.

4. Restarting the MCP server takes its children with it — when this service is restarted or killed, the DSH children it spawned exit too (their stdio is a pipe to us): in-flight turns are interrupted and no sentinel lands (judge by inspecting the workspace, don't just wait for the file). The good news: the write lock is released automatically, so a restart always gets it back. The service also pushes no MCP notifications; "completion notification" is the sentinel file plus the caller's background waiter.

5. A conversation that dies before its first successful turn may never have materialized on disk — resume then fails with a clear error. Safe after the first message.

6. No renaming — DSH's title subsystem has no external rename API (SessionTitleService.rename requires a live in-process session). Titles are auto-generated from the first message.

7. session/list returns only {sessionId, cwd} and excludes already-open sessions — titles are filled in by this server from DSH's projection cache.

8. "Never reap" costs memory (measured ~120 MB per conversation) — that is what buys "the GUI can never take the write lock". Two ways to spend less: ① DSH_MCP_MAX_LIVE (default 8 — over the cap, the least recently used process is reaped → bounded memory, locks still held where it matters); ② set DSH_MCP_IDLE_TTL_MS to a millisecond value (at the cost of the lock being takeable). To drop to zero right after a batch of work: dsh_release(all=true) ✓ (lossless, everything resumes on demand).

💬 Community

This project is announced and discussed on linux.do — usage questions, war stories and suggestions are all welcome there. Issues work too, but you'll usually get a faster answer in the community.

📜 License

MIT — see LICENSE.