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.

What is in the box

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

Related MCP server: workiq-mcp-bridge

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

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