Zeus Dev Helper MCP server

Zeus Dev Helper MCP

<!-- mcp-name: io.github.koten-ai/zeus-dev-helper -->

Stdio MCP server that coaches a coding agent and a human to a first successful Zeus Client app turn.

This is not a data-plane MCP. It does not run Explore/Verify verbs on your behalf, invent contract hashes, or perform Hub admin mutations. After the first-green smokes pass, data-plane and multi-agent work are handoffs only.

What it does

The server walks a first-app checklist: prereqs, live readiness on the public Zeus API, catalog templates, contract bind (copy a stamped hash only), surface/verb coaching, config lint, and smoke tests. Prefer a live Zeus stamp for catalogs. fetchchatrequest is always template only.

Hard constraints the tools enforce:

• Public Zeus API on port 8080 only (never Hub 9091 from the app path)
• Never invent contract_hash
• No secrets in tool results, checklist evidence, or support packs
• Semantic cache stays off

Install

pip install zeus-dev-helper-mcp
# or
uvx zeus-dev-helper-mcp

Optional extra for smoketestagent (pulls the Zeus Client package):

pip install "zeus-dev-helper-mcp[agent]"

Run

zeus-dev-helper-mcp
# or
python -m zeus_dev_helper_mcp

Prefer the published console script (uvx / pip install) so hosts do not need a source checkout.

Host install

Set ZEUSURL to your Zeus public API on port 8080 (never Hub :9091). Prefer the remote host you actually use. Use http://localhost:8080 only when Zeus runs on the same machine** as the MCP host.

# Remote Zeus (typical lab / shared engine) — put your host here
export ZEUS_URL=http://192.168.0.219:8080
# or: http://<zeus-host>:8080
#
# Same-machine Zeus only:
# export ZEUS_URL=http://localhost:8080

If the user names a URL or sample in chat, call setprereq with that zeusurl / bucket / scope (do not keep a stale localhost default). doctor reports stored vs effective URL routing (see ZDM-3).

Grok Build

grok mcp add treats flags like -m as its own unless they come after --. The uvx argument is the PyPI package zeus-dev-helper-mcp, not the MCP server id zeus-dev-helper.

grok mcp add zeus-dev-helper \
  -e ZEUS_URL=http://192.168.0.219:8080 \
  -- uvx zeus-dev-helper-mcp

From a local checkout after pip install -e ".[dev]", point command at this tree’s venv so the host can start the server even when it was launched without the venv activated:

grok mcp add zeus-dev-helper \
  -e ZEUS_URL=http://192.168.0.219:8080 \
  -- "$(pwd)/.venv/bin/python" -m zeus_dev_helper_mcp

Equivalent config:

[mcp_servers.zeus-dev-helper]
command = "uvx"
args = ["zeus-dev-helper-mcp"]
env = { ZEUS_URL = "http://192.168.0.219:8080" }
enabled = true

Then refresh MCP servers, or grok mcp doctor zeus-dev-helper.

Common failures:

• unexpected argument '-m' — missing -- before the python command
• uvx zeus-dev-helper / No solution found — wrong package name; use zeus-dev-helper-mcp
• No module named 'zeusdevhelper_mcp' / python: No such file or directory — the host did not inherit the venv; use the .venv/bin/python path above
• No module named 'mcp.server.fastmcp' — mcp 2.x renamed FastMCP; use Helper 0.6.0+ (mcp>=1.8.0,<3)

Claude Code / Claude Desktop

{
  "mcpServers": {
    "zeus-dev-helper": {
      "command": "uvx",
      "args": ["zeus-dev-helper-mcp"],
      "env": {
        "ZEUS_URL": "http://192.168.0.219:8080"
      }
    }
  }
}

Cursor

Add (or merge) .cursor/mcp.json in the project (or use Cursor’s global MCP settings):

Shortened. The full README is on GitHub.