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 → next_step
  → set_prereq → validate_env → readiness_check
  → use_sample | scaffold_app → bind_contract → recommend_surface
  → smoke_test_zeus → smoke_test_agent → diagnose_error

Prefer next_step over dumping the full checklist.

• Default (UI): start_project(sample=travel) → use_sample, which clones public demo_travel_sample when missing (optional project_name for the directory) and sets DEMO_TRAVEL_SAMPLE_DIR.
• API-only: user asks for an API/REST app → start_project(sample=api) → scaffold_app(app_kind=api, coding_language=python) (FastAPI POST /turn on kotenai-zeus-client). Other languages not scaffolded yet.
• Credentials from chat → process env / gitignored .env; set_prereq presence flags only.
• Integrating into an arbitrary existing repo is out of scope.

Read zeus-helper:// resources for glossary, verbs, policies, and catalog modes. Hosts can pick prompts first_green, smoke_question, and support_pack.

Default tools (core)

Live tools/list is the call contract. Default surface is 12 tools (ZEUS_DEV_HELPER_TOOLSETS=core).

Opt-in toolsets (static, comma-separated): catalog, lint, travel, support, handoff. all enables every set. Full when/args/side-effects map: docs/TOOLS.md.

Resources (always on): zeus-helper://checklist, zeus-helper://glossary/{topic}, zeus-helper://verbs/{name}, zeus-helper://policy/hash-boundary, zeus-helper://policy/req-id, zeus-helper://catalog/modes.

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.