dsh-web-mcp

🤖 AI-assisted project · A college student's learning project, with significant code generated by an LLM agent under human direction and review.

MCP bridge for DeepSeek Harness (DSH) web UI — exposes the cordis RPC API over HTTP /api/<endpoint> as stdio MCP tools. Any MCP client (Codex CLI, Claude Desktop, etc.) can drive DSH sessions and benefit from prompt-prefix cache reuse.

🌐 中文文档：README.zh.md

What is in the box

Five tools, all backed by DSH web's cordis RPC over HTTP /api/<endpoint>:

Tool	Purpose
dsh_list_workspaces	Enumerate every workspace known to the running DSH web UI.
dsh_create_session	Adopt a directory (creating the workspace if missing), then create a session bound to it. Selects the model in one shot. Returns sessionId.
dsh_send_message	Send a prompt and block until the assistant turn completes. Returns the assistant text plus per-turn token usage including cacheReadTokens / cacheWriteTokens.
dsh_get_session_stats	Fetch cached projections: tokenUsage, sessionStats, contextPressure.
dsh_resume_session	Verify a session is still alive and surface its current model. Subsequent dsh_send_message calls reuse the prompt prefix.

Requirements

• Python 3.10+
• A running dsh web instance on http://127.0.0.1:3080 (override with DSH_BASE_URL)
• uv (recommended) or pip

Install

git clone https://github.com/cv588888888888888888888ju/dsh-web-mcp.git
cd dsh-web-mcp
uv sync

Then run as a stdio MCP server:

uv run dsh-web-mcp

Wire up Hermes Agent

Register with hermes mcp add:

hermes mcp add dsh --command uv --args --directory C:\Users\chenty\Documents\feishu-bot\dsh-mcp run dsh-web-mcp

⚠️ Known pitfall (tested):

• Do not pass --env DSH_BASE_URL=... — it gets forwarded to dsh-web-mcp's argparse and fails with unrecognized arguments. Set DSH_BASE_URL as a user/system environment variable instead.
• A new session is required after registering (config loads at session start).
• If prompted Enable all 5 tools? [Y/n/select], answer Y.

Wire up Codex CLI

Edit %USERPROFILE%\.codex\config.toml (or ~/.codex/config.toml on other OS):

[mcp_servers.dsh]
command = "uv"
args = ["--directory", "C:\\path\\to\\dsh-web-mcp", "run", "dsh-web-mcp"]

# Optional, defaults to http://127.0.0.1:3080 if omitted
[mcp_servers.dsh.env]
DSH_BASE_URL = "http://127.0.0.1:3080"

Restart Codex CLI. The five dsh_* tools appear alongside the built-in tools.

Probe

probe.py is a developer-side smoke test that exercises all five tools end-to-end against the running DSH web UI:

uv run python probe.py

It prints a JSON blob per step; expected outcome is

{
  "ok": true,
  "step": "send_message",
  "reply_contains": "TASK_OK",
  "cacheReadTokens": 8192
}

Failure modes

• DSH web not reachable — the server starts but every tool returns {"ok": false, "error": "DSH web not reachable at ..."}. Make sure dsh web is running (dsh web --port 3080).
• DSH schema drift (rc.X → rc.Y) — unknown field errors come back as {ok: false, error: "dsh returned <code>: <msg>"}. The model schema in models.py is intentionally extra="allow" so additional fields pass through; reported mis-parses should be filed against models.py.
• Prompt timeout — dsh_send_message times out after timeout_s (default 120s); rerun with a larger value if your prompt is long.

Configuration

Environment variables read by dsh-web-mcp:

Var	Default	Description
DSH_BASE_URL	http://127.0.0.1:3080	DSH web base URL.
DSH_TIMEOUT_S	60	Per-request timeout in seconds (generous; a single LLM turn may take ~30s).
DSH_MCP_LOG	INFO	Python logging level (use DEBUG to see wire-level traffic).

CLI flags mirror the env vars: --base-url, --timeout, --check.

Why this exists

By default Codex CLI talks to the OpenAI / Azure providers directly. When MCP routing through DSH, the deepseek-v4-flash preset in DSH keeps system + tools + conversation prefix cached, so every subsequent turn in the same session reads 8K+ cached tokens and only pays uncached input for the new prompt + uncached output for the new reply — measured per tokenUsage.cacheReadTokens in dsh_send_message results.

Background

This project was built as a learning exercise by an undergraduate student exploring agent tooling. The bulk of the code was generated by an LLM coding agent (Codex CLI + DeepSeek) under human direction; every line was reviewed and the behavior verified end-to-end before publication. Bugs are likely given the author's experience level — please open issues.

Status

Pre-release. API surface follows DSH 0.1.0-rc.6 schema (rpc-map.d.ts); regenerate from source if you bump DSH.

License

MIT