Zeus Dev Helper

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.

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)

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

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.

# 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 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 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 '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://192.168.0.219:8080"
      }
    }
  }
}

Cursor

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

{
  "mcpServers": {
    "zeus-dev-helper": {
      "command": "uvx",
      "args": ["zeus-dev-helper-mcp"],
      "env": {
        "ZEUS_URL": "http://192.168.0.219: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. Replace the sample IP with your Zeus host.

Day-one coach path

doctor → (if user named URL/sample) set_prereq → start_project → next_step
  → 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. Two first-green paths (TravelPlan is not the only path):

• Travel + LLM (UI default): 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.
• Beer catalog UI: 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.
• Yelp demo UI: start_project(sample=demo_yelp) → use_sample(sample=demo_yelp) clones the LocalAI template demo_yelp when missing (utterances yelp-demo / demo_yelp) and sets DEMO_YELP_SAMPLE_DIR. When parent_dir is set, the clone is created in that directory. That checkout is the app: run it, and do not write a replacement or copy the beer sample. use_sample also downloads the public business photo set into frontend/public/business-images/<id>/{1,2,3}.png (no biz: prefix, no API key). Search POSTs /api/search and sends the live chat request for yelp-demo / _default as the session body. Search cards unwrap a hybrid {node, score} hit and a nested pipeline row. The business page GETs /api/business/{id} when the id is not in the bundled catalog. Review text is the source document, not a rev: doc key. set_prereq bucket is yelp-demo, scope _default. Do not clone demo_travel_sample. Bare sample=yelp stays the multi-agent handoff.
• 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. 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.
• 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 the core toolset (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
explain_scope	Live public :8080 chat_request.json summary: entity types, display fields, text-search fields, FK fields, and list/detail/search verbs. A failed stamp leaves entity types empty. fetch_chat_request stays template only
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), sample=catalog from explain_scope, or yelp demo clone (sample=demo_yelp, sets DEMO_YELP_SAMPLE_DIR; downloads public photos into frontend/public/business-images/<id>/, no API key; live search and business page, review text from the source document)
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
website_green	Install, start, and check the catalog page (named list card, page ids, search when Pour is on). A title-cased doc_key is not a search card. A describe 200 is not this check
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 a symptom, hop name, and result keys to a failure class and one generated-file change
sample_support_pack	Read-only paste for a beer, travel, or yelp-demo gate failure. Writes nothing and calls no Zeus API. Session ids stay in support_pack_from_turn

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.

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)
BUSINESS_IMAGES_BASE_URL	Optional CDN prefix for the yelp photo download (no trailing slash). Default is the public koten-yelp-demo-photos Space. No API key
ZEUS_DEV_HELPER_SKIP_YELP_IMAGES	Set to 1 to skip the yelp photo download during use_sample(sample=demo_yelp)
YELP_IMAGE_FETCH_WORKERS	Parallel downloads for that photo set. Default 8
ZEUS_DEV_HELPER_STATE_DIR	Checklist, prereqs, local metrics, the write-once sample creation logs (beer-sample-build.md, travel-sample-build.md, yelp-demo-build.md), and the support journals (beer-sample-support.md, travel-sample-support.md, yelp-demo-support.md). Default ~/.config/zeus_dev_helper
ZEUS_DEV_HELPER_TOOLSETS	Static toolsets: core (default), plus catalog,lint,travel,support,handoff or all

Boundaries

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

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.

License

BSD-3-Clause — see LICENSE.