The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Zeus Dev Helper listing page.
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.
| Package | zeus-dev-helper-mcp |
| Registry name | io.github.koten-ai/zeus-dev-helper |
| Transport | stdio |
| Python | 3.11+ |
| MCP SDK | mcp (FastMCP on 1.x / MCPServer on 2.x) |
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:
contract_hashOptional extra for smoke_test_agent (pulls the Zeus Client package):
Prefer the published console script (uvx / pip install) so hosts do not need a source checkout.
Set ZEUS_URL 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.
If the user names a URL or sample in chat, call set_prereq with that zeus_url / bucket / scope (do not keep a stale localhost default). doctor reports stored vs effective URL routing (see ZDM-3).
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.
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:
Equivalent config:
Then refresh MCP servers, or grok mcp doctor zeus-dev-helper.
Common failures:
unexpected argument '-m' — missing -- before the python commanduvx zeus-dev-helper / No solution found — wrong package name; use zeus-dev-helper-mcpNo 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 aboveNo module named 'mcp.server.fastmcp' — mcp 2.x renamed FastMCP; use Helper 0.6.0+ (mcp>=1.8.0,<3)Add (or merge) .cursor/mcp.json in the project (or use Cursor’s global MCP settings):
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. Replace the sample IP with your Zeus host.
Prefer next_step over dumping the full checklist. Two first-green paths (TravelPlan is not the only path):
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. Checklist 1.2 stays open until this process has LLM_API_KEY, XAI_API_KEY, or OPENAI_API_KEY. smoke_test_agent reads that variable. Standalone clones pin kotenai-zeus-client>=2.4.0,<2.5 so run_turn can recover a fenced pipeline inside the SDK.start_project(sample=beer) → use_sample(sample=beer) writes demo_beer_sample (FastAPI BFF + static page). Search matches travel: rt.agent.run_turn with chat_request omitted so catalog.load_for_turn merges the live SCOPE BRIEF and MINI-SCHEMA. The key is required even when has_llm_key=false. Put it in the app .env. Leave config.json llm.api_key_env as that variable name. verify_local_setup keeps checklist 3.2 open until that file check passes. The BFF does not build a pipeline body. Do not clone demo_travel_sample.start_project(sample=demo_yelp) → use_sample(sample=demo_yelp) clones demo_yelp when missing (utterances yelp-demo / demo_yelp) and sets DEMO_YELP_SAMPLE_DIR. set_prereq bucket is yelp-demo, scope _default. Do not clone demo_travel_sample. Bare sample=yelp stays the multi-agent handoff.start_project(sample=api) → scaffold_app(app_kind=api, coding_language=python) (FastAPI POST /turn on kotenai-zeus-client). Other languages not scaffolded yet..env; set_prereq presence flags only. has_llm_key=true does not count as the key. Pass the user’s Zeus URL into set_prereq(zeus_url=…). Do not paste the secret into llm.api_key_env.Read zeus-helper:// resources for glossary, verbs, policies, and catalog modes. Hosts can pick prompts first_green, smoke_question, and support_pack.
core)Live tools/list is the call contract. Default surface is 12 tools (ZEUS_DEV_HELPER_TOOLSETS=core).
| Tool | Job |
|---|---|
doctor | Health. detail=health|env|compat|cache|all (env/compat/cache fold lint-toolset checks) |
start_project | Init checklist; sample=travel (UI default), sample=beer (catalog UI, run_turn), sample=demo_yelp (clone demo_yelp), or sample=api |
next_step | Current item plus recommended tools and resource links |
set_prereq | Store non-secret prereqs (presence flags only; has_llm_key is not the key) |
readiness_check | Live gates: healthz / readyz / version, auth, bootstrap. Marks 1.2 done only when the URL is set and, on a run_turn path, the process has an LLM key |
scaffold_app | CLI or FastAPI (app_kind=cli|api) ZeusRuntime app; python only |
use_sample | Travel UI clone, beer catalog UI (run_turn, chat_request omitted), or yelp demo clone (sample=demo_yelp, sets DEMO_YELP_SAMPLE_DIR) |
bind_contract | Copy a stamped contract.hash only; refuses empty / local compute |
recommend_surface | Intent → Client surface + do-not list |
smoke_test_zeus | No LLM: readiness plus a read-only describe |
smoke_test_agent | One Client run_turn. Needs [agent] extra and LLM_API_KEY, XAI_API_KEY, or OPENAI_API_KEY in this process |
diagnose_error | Map HTTP / body / error codes to a failure class |
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.
Secrets stay in the process environment. set_prereq stores presence flags only. Tool results redact secret values.
| Variable | Purpose |
|---|---|
ZEUS_URL | Public Zeus API base URL (port 8080). Remote host first; localhost only when Zeus is local |
ZEUS_BUCKET / ZEUS_SCOPE / ZEUS_COLLECTION | Scope for bootstrap and auth probes |
ZEUS_MODE | Default catalog mode (analytics) |
ZEUS_AUTH_MODE | Auth mode (none, basic, bearer) |
ZEUS_USERNAME / ZEUS_PASSWORD | Basic auth (never logged) |
ZEUS_BEARER_TOKEN | Bearer auth (never logged) |
LLM_API_KEY / XAI_API_KEY / OPENAI_API_KEY | Process key for checklist 1.2, validate_env, and smoke_test_agent. The app .env needs the same name for Pour / uvicorn. config.json llm.api_key_env stays the name. A stored has_llm_key flag does not count |
ZEUS_CHAT_REQUEST_DIR | Local directory of min catalog templates; auto-set when list_catalog_modes / fetch_chat_request locate or clone public zeus_chat_request |
DEMO_TRAVEL_SAMPLE_DIR | Local sample directory for use_sample / travel_golden_path |
DEMO_YELP_SAMPLE_DIR | Local demo_yelp directory for use_sample(sample=demo_yelp) |
ZEUS_DEV_HELPER_STATE_DIR | Checklist, prereqs, and local metrics (default ~/.config/zeus_dev_helper) |
ZEUS_DEV_HELPER_TOOLSETS | Static toolsets: core (default), plus catalog,lint,travel,support,handoff or all |
| This MCP | Not this MCP |
|---|---|
| Onboarding coach to first green | Data-plane Explore/Verify tools |
| Catalog templates plus readiness and smoke | Inventing or locally computing contract_hash |
Verb explain / lint / draft (posted=false) | POSTing find / search / get / pipeline |
| Detective URL templates | Hub scrape or Hub admin mutations |
| Multi / data-plane handoffs | Multi-agent job runtime |
| Local checklist and metrics | Shipping secrets in evidence or support packs |
From a local checkout:
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.
BSD-3-Clause — see LICENSE.