zeus_dev_helper_mcp

Developer Helper MCP — first Zeus-powered app onboarding coach.

Not a data-plane MCP. Coaches: checklist → templates → live readiness & smoke → handoffs.

Design: docs/DESIGN.md (ZDH-2, frozen MVP) · docs/DESIGN-0.6.md (runtime coach)
Tool catalog: docs/TOOLS.md — when to call, args, side effects, do-not

Stack

• Python 3.11+
• Official mcp SDK (FastMCP on 1.x / MCPServer on 2.x, stdio)
• Registry name: io.github.koten-ai/zeus-dev-helper (PyPI: zeus-dev-helper-mcp)

Install

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

Optional agent-smoke extra (needs kotenai-zeus-client on PyPI):

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

Live Zeus on :8080 is the preferred catalog stamp. Offline min templates need a local zeus_chat_request clone (ZEUS_CHAT_REQUEST_DIR) or GITHUB_TOKEN for the private GitHub repo. Travel golden path needs DEMO_TRAVEL_SAMPLE_DIR when that sample is cloned.

Install (dev)

git clone https://github.com/koten-ai/zeus_dev_helper_mcp.git
cd zeus_dev_helper_mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
# Agent smoke (optional):
pip install -e ".[agent]"   # pulls kotenai-zeus-client

# Recommended: local catalog repo (private GH needs this or GITHUB_TOKEN)
export ZEUS_CHAT_REQUEST_DIR=../zeus_chat_request   # sibling clone
# or: export GITHUB_TOKEN=...   # Contents API for private zeus_chat_request
export ZEUS_URL=http://localhost:8080
export ZEUS_BUCKET=beer-sample ZEUS_SCOPE=_default
# Optional travel golden path (private sample):
# export DEMO_TRAVEL_SAMPLE_DIR=/path/to/demo_travel_sample

Run

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

Host install

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

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, point command at this repo’s venv so Grok can start the server even when the TUI was launched without the venv activated:

# from this repo, after `pip install -e ".[dev]"`
grok mcp add zeus-dev-helper \
  -e ZEUS_CHAT_REQUEST_DIR=/absolute/path/to/zeus_chat_request \
  -e ZEUS_URL=http://localhost:8080 \
  -- "$(pwd)/.venv/bin/python" -m zeus_dev_helper_mcp

Equivalent ~/.grok/config.toml (or .grok/config.toml with --scope project):

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

Then /mcps → r to refresh, 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 — Grok 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

Add to MCP servers config (example):

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

Hermes / OpenClaw

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.

Implemented tools (0.6.0)

Per-tool when / args / side effects: docs/TOOLS.md. Status inventory:

Day-one coach path

start_project → set_prereq → validate_env → readiness_check
  → use_sample | travel_golden_path | scaffold_app
  → bootstrap_scope / fetch_chat_request / bind_contract / catalog_diff
  → 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 | handoff_to_multi

Catalog rules (never invent hashes)

1. Live Zeus stamp + sync_chat_requests for production.
2. zeus_chat_request v2/min/* for offline templates.
3. fetch_chat_request always returns TEMPLATE ONLY warning.

Env

Boundaries

Tests

pip install -e ".[dev]"
pytest -q

Requires sibling ../zeus_chat_request with manifest.json for catalog tests.

PyPI and MCP Registry

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

Releases are tag-driven (vX.Y.Z). .github/workflows/release.yml tests, builds, creates a GitHub Release, publishes to PyPI (Trusted Publisher, environment pypi), then runs mcp-publisher against the official MCP Registry.

Before the first tag:

1. Create the GitHub Actions environment pypi on this repo.
2. On PyPI trusted publishing add a pending GitHub publisher:
   • Owner: koten-ai
   • Repository: zeus_dev_helper_mcp
   • Workflow name: release.yml
   • Environment name: pypi
3. Align versions in pyproject.toml, src/zeus_dev_helper_mcp/__init__.py, and server.json with the tag.
4. Merge to main, then git tag v0.6.0 && git push origin v0.6.0.

The GitHub source repo may stay private; PyPI and the MCP Registry require a public install path (pip / uvx). Keep repository in server.json only if you want clients to see the GitHub URL.

Related