Zeus Dev Helper MCP

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. fetch_chat_request 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 smoke_test_agent (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

Grok Build

grok mcp add treats flags like -m as its own unless they come after --.

grok mcp add zeus-dev-helper \
  -e ZEUS_URL=http://localhost: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://localhost: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://localhost:8080" }
enabled = true

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

Common failures:

• unexpected argument '-m' — missing -- before the python command
• No module named 'zeus_dev_helper_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://localhost:8080"
      }
    }
  }
}

Other stdio hosts

Point the host’s MCP stdio entry at uvx zeus-dev-helper-mcp (or python -m zeus_dev_helper_mcp from a venv) with the same env vars.

Day-one coach path

doctor → start_project → set_prereq → validate_env → readiness_check
  → list_catalog_modes → fetch_chat_request → explain → recommend_surface
  → use_sample | travel_golden_path | scaffold_app
  → bootstrap_scope / bind_contract / catalog_diff / explain_hash_boundary
  → recommend_surface / explain_verb / lint_verb_args / compat_check
  → lint_runtime_config / lint_app_code
  → smoke_test_zeus → smoke_test_agent → gap_report
  → (optional) recommend_data_plane_mcp | emit_mcp_config | handoff_to_multi

Prefer next_step over dumping the full checklist.

Tools

Live tools/list is the call contract. Names below are the coach surface.

Start and health

Checklist

Env and platform

Catalogs and contracts

Project on disk

Surface and verbs (coach only; does not POST find/search/get/pipeline)

Smoke and diagnose

Correlation and support

Motion, hooks, cache, glossary

Post-green handoffs

Gated on smoke 5.1 + 5.2 unless forced.

Environment

Secrets stay in the process environment. set_prereq stores presence flags only. Tool results redact secret values.

Boundaries

Dev install

From a local checkout:

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
# optional agent smoke:
pip install -e ".[agent]"
export ZEUS_URL=http://localhost:8080

pytest -q

MCP Registry

Official registry name: io.github.koten-ai/zeus-dev-helper. The registry hosts metadata only; the install artifact is the PyPI package zeus-dev-helper-mcp.