zeus-dev-helper-mcp 0.6.0__tar.gz

zeus_dev_helper_mcp-0.6.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.DS_Store
+.mypy_cache/
+.venv/

zeus_dev_helper_mcp-0.6.0/AGENTS.md

@@ -0,0 +1,36 @@
+# AGENTS — Developer Helper MCP
+
+**Mission:** Get a coding agent + human to a **first green** Zeus Client app turn.
+
+## Load order
+
+1. This file  
+2. [docs/TOOLS.md](docs/TOOLS.md) — Helper tool catalog (when / args / side effects / do-not)  
+3. [docs.koten.ai](https://docs.koten.ai/) (published docs; site may be placeholder while wiring)  
+4. [agent-index.yaml](https://github.com/koten-ai/koten_docs/blob/zeus-v1.0.0/agent-index.yaml) (machine index in source repo)  
+5. [For AI agents](https://docs.koten.ai/zeus-client/for-ai-agents)  
+6. [Using Zeus Client](https://docs.koten.ai/zeus-client/using-zeus-client)  
+7. [zeus_chat_request](https://github.com/koten-ai/zeus_chat_request) for templates  
+
+## Hard constraints
+
+- Public API **:8080** only (never Hub **:9091** from app path)  
+- Never invent `contract_hash`  
+- Catalogs: live stamp preferred; `fetch_chat_request` is **template only**  
+- No secrets in tool results or checklist evidence  
+
+## Tools to use first
+
+`doctor` → `start_project` → `list_catalog_modes` → `fetch_chat_request` → `explain` → `recommend_surface` → `next_step`
+
+Coach (0.6): `recommend_surface` / `explain_verb` / `lint_verb_args` / `suggest_verb_call` / `diagnose_error` / `compat_check` / `bind_contract` / `lint_runtime_config` / `describe_scope` / `recommend_motion` / `support_pack_from_turn` / `suggest_hooks` / `semantic_cache_status`. Does **not** rewrite V1 `scaffold_app` / `smoke_test_agent`. Semantic cache stays **off**.
+
+Travel sample: `use_sample` / `travel_golden_path` (set `DEMO_TRAVEL_SAMPLE_DIR` if cloned).
+
+After 5.1+5.2 green: `recommend_data_plane_mcp`, `emit_mcp_config`, `handoff_to_multi` — **handoffs only**.
+
+Design freeze: `docs/DESIGN.md`. Tool catalog: `docs/TOOLS.md`. Glossary: `explain(topic)`.
+
+## Not this MCP
+
+Data-plane tools, Hub admin mutations, multi-agent jobs (ZJA).

zeus_dev_helper_mcp-0.6.0/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+## 0.6.0
+
+### Fixed
+- Server import on **mcp 2.x** (`FastMCP` renamed to `MCPServer`). Supports 1.x and 2.x; pin is now `mcp>=1.8.0,<3`.
+- Grok host install: `grok mcp add` must pass `--` before `python -m` (otherwise Grok errors `unexpected argument '-m'`), and `command` must be the repo venv interpreter so the TUI can spawn the server without an activated venv.
+
+### Added
+- **ZDH-18** Surface router + V2 verb coach: `recommend_surface`, `explain_verb`, `lint_verb_args`, `suggest_verb_call`
+- **ZDH-19** `diagnose_error` ErrorCode / Zeus `error_class` plus 0.7 failure classes (`invalid_req_id`, `composite_req_id`, `pipeline_not_on_direct`, …); Detective URL templates only
+- `explain` topics: `zeus_runtime`, `turn_result`, `cheap_path`, `semantic_cache`, `req_id_policy`, `trace_class`, `direct`, `typeahead`, `pipeline`
+- `docs/DESIGN-0.6.md` increment (frozen `docs/DESIGN.md` pointer only)
+- Optional extra `[agent]` floor `kotenai-zeus-client>=2.3.0`
+- **ZDH-21** `compat_check` — `/version` + `/healthz` on `:8080`; static 0.7 feature gates (not a COMPAT matrix row)
+- **ZDH-22** `lint_chat_request`, `bind_contract`, `explain_hash_boundary`, `catalog_diff` — stamp extract only; never compute production hashes
+- **ZDH-24** `lint_runtime_config` + `lint_app_code` — env names not values; secrets redacted; V1 / hash-literal / Dockerfile smells
+- **ZDH-23** `explain_req_id_policy`, `detective_links`, `support_pack_from_turn` — URL templates + redacted ids/hops only
+- **ZDH-25** `describe_scope` — entity types + field names; no document samples
+- **ZDH-26** `recommend_motion` — 13 Zeus motions; does not generate a chat_request
+- **ZDH-27** `suggest_hooks` — tenant pin / deny pipeline / output_schema / OCR snippets (not executed)
+- **ZDH-28** `semantic_cache_status` — default off; optional `/v2/agent_memory/status` probe
+- Helper tool catalog: [`docs/TOOLS.md`](docs/TOOLS.md) (when / args / side effects / do-not; not a Zeus OpenAPI dump)
+- PyPI + official MCP Registry distribution: `server.json` (`io.github.koten-ai/zeus-dev-helper`), README `mcp-name` marker, tag-driven [`.github/workflows/release.yml`](.github/workflows/release.yml)
+
+### Notes
+- V1 `scaffold_app` / `smoke_test_agent` are **not** rewritten in this release ([ZDH-17](https://kotenai.atlassian.net/browse/ZDH-17) Cancelled)
+- Bootstrap/auth/catalog probes stay on existing `/v1` ([ZDH-20](https://kotenai.atlassian.net/browse/ZDH-20) Cancelled)
+- Verb tools never POST; they explain, lint, and draft
+
+## 0.5.0
+
+### Added
+- **ZDH-2** Product design freeze: `docs/DESIGN.md` (tool catalog, checklist, boundaries, metrics)
+- **ZDH-10** `travel_golden_path` + richer `use_sample` layout validation / README snippet for demo_travel_sample
+- **ZDH-11** `handoff_to_multi` + gated `start_project(goal=multi|sample=yelp)` until single-agent smokes green
+- **ZDH-12** `recommend_data_plane_mcp` + `emit_mcp_config` (scope-bound, read-only placeholder fragment)
+- **ZDH-13** Expanded `explain` glossary topics (≥30) with docs deep-links + aliases
+- Local privacy-safe metrics: `helper_metrics` + auto events on start/smoke green
+- Post-green hints on `next_step` after 5.1 + 5.2 done
+
+### Notes
+- Data Plane MCP package is **placeholder** until published — do not invent install packages
+- Multi-agent jobs remain **ZJA**; Helper only coaches graduation
+- demo_travel_sample may stay private; set `DEMO_TRAVEL_SAMPLE_DIR` when cloned
+
+## 0.4.0
+
+### Added
+- **P4** `scaffold_app`, `use_sample`, `write_env`, `verify_local_setup`
+- **P3** full `bootstrap_scope` (live GET bootstrap + chat_request summary)
+- **P6** `gap_report` + richer `next_step` (recommended_tools coach)
+- Minimal project template: `main.py`, `requirements.txt`, `.env.example`
+
+### Notes
+- Secrets never written by scaffold/write_env
+- `smoke_test_agent` still needs optional `[agent]` extra
+
+## 0.3.0
+
+- P5 `smoke_test_zeus`, `smoke_test_agent`, `diagnose_error`, `suggest_demo_prompts`
+
+## 0.2.0
+
+- P2 `set_prereq`, `readiness_check`
+
+## 0.1.0
+
+- P1 skeleton + P3b catalogs (`list_catalog_modes`, `fetch_chat_request`)

zeus_dev_helper_mcp-0.6.0/LICENSE

@@ -0,0 +1,5 @@
+Copyright (c) 2026 Koten AI. All rights reserved.
+
+This software is proprietary. Use, copy, modification, and distribution
+are permitted only under a separate written license from Koten AI.
+Unauthorized use is prohibited.

zeus_dev_helper_mcp-0.6.0/PKG-INFO

@@ -0,0 +1,278 @@
+Metadata-Version: 2.5
+Name: zeus-dev-helper-mcp
+Version: 0.6.0
+Summary: Developer Helper MCP — first Zeus-powered app onboarding coach (ZDH)
+Project-URL: Homepage, https://docs.koten.ai/zeus-client/dev-helper-mcp
+Project-URL: Documentation, https://docs.koten.ai/zeus-client/dev-helper-mcp
+Project-URL: Repository, https://github.com/koten-ai/zeus_dev_helper_mcp
+Project-URL: Changelog, https://github.com/koten-ai/zeus_dev_helper_mcp/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/koten-ai/zeus_dev_helper_mcp/issues
+Author: Koten AI
+License: Proprietary
+License-File: LICENSE
+Keywords: coach,koten,mcp,onboarding,zeus
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp<3,>=1.8.0
+Provides-Extra: agent
+Requires-Dist: kotenai-zeus-client>=2.3.0; extra == 'agent'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=5.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# zeus_dev_helper_mcp
+
+<!-- mcp-name: io.github.koten-ai/zeus-dev-helper -->
+
+**Developer Helper MCP** — first Zeus-powered app onboarding coach.
+
+| | |
+| --- | --- |
+| **Board** | [ZDH](https://kotenai.atlassian.net/jira/software/projects/ZDH/boards/45) |
+| **Epic** | [ZDH-1](https://kotenai.atlassian.net/browse/ZDH-1) |
+| **Skeleton** | [ZDH-3](https://kotenai.atlassian.net/browse/ZDH-3) |
+| **Catalogs** | [ZDH-14](https://kotenai.atlassian.net/browse/ZDH-14) → [zeus_chat_request](https://github.com/koten-ai/zeus_chat_request) |
+| **Docs** | [docs.koten.ai](https://docs.koten.ai/) · [Dev Helper MCP](https://docs.koten.ai/zeus-client/dev-helper-mcp) |
+
+> Not a data-plane MCP. Coaches: checklist → templates → live readiness & smoke → handoffs.
+
+**Design:** [`docs/DESIGN.md`](docs/DESIGN.md) (ZDH-2, frozen MVP) · [`docs/DESIGN-0.6.md`](docs/DESIGN-0.6.md) (runtime coach)  
+**Tool catalog:** [`docs/TOOLS.md`](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
+
+```bash
+pip install zeus-dev-helper-mcp
+# or
+uvx zeus-dev-helper-mcp
+```
+
+Optional agent-smoke extra (needs `kotenai-zeus-client` on PyPI):
+
+```bash
+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)
+
+```bash
+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
+
+```bash
+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 `--`**.
+
+```bash
+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:
+
+```bash
+# 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`):
+
+```toml
+[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):
+
+```json
+{
+  "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`](docs/TOOLS.md). Status inventory:
+
+| Tool | Status |
+| --- | --- |
+| `doctor` | Config + catalog reachability |
+| `start_project` / `get_checklist` / `next_step` / `gap_report` | **ZDH-8** coach walkthrough |
+| `mark_done` / `mark_blocked` | Checklist updates |
+| `set_prereq` / `validate_env` / `readiness_check` | **ZDH-4** |
+| `bootstrap_scope` | **ZDH-5** live bootstrap + chat_request summary |
+| `scaffold_app` / `use_sample` / `write_env` / `verify_local_setup` | **ZDH-6** |
+| `travel_golden_path` | **ZDH-10** travel sample golden path |
+| `smoke_test_zeus` / `smoke_test_agent` / `diagnose_error` | **ZDH-7** / **ZDH-19** ErrorCode + 0.7 classes |
+| `recommend_surface` / `explain_verb` / `lint_verb_args` / `suggest_verb_call` | **ZDH-18** Direct vs agent + V2 verb lint (does not POST; no Runtime scaffold rewrite) |
+| `compat_check` | **ZDH-21** version/feature gates on `:8080` (not a COMPAT row) |
+| `lint_chat_request` / `bind_contract` / `explain_hash_boundary` / `catalog_diff` | **ZDH-22** catalog coach — extract stamp only |
+| `lint_runtime_config` / `lint_app_code` | **ZDH-24** config + anti-example scan (secrets redacted) |
+| `explain_req_id_policy` / `detective_links` / `support_pack_from_turn` | **ZDH-23** correlation + redacted support pack |
+| `describe_scope` | **ZDH-25** schema-only live describe |
+| `recommend_motion` | **ZDH-26** 13 motions; no custom chat_request |
+| `suggest_hooks` | **ZDH-27** policy snippets (not a policy engine) |
+| `semantic_cache_status` | **ZDH-28** leave enabled=false; optional status probe |
+| `list_catalog_modes` / `fetch_chat_request` | **ZDH-14** |
+| `explain` / `suggest_demo_prompts` | **ZDH-13** glossary + prompts |
+| `handoff_to_multi` | **ZDH-11** multi-agent graduation (gated) |
+| `recommend_data_plane_mcp` / `emit_mcp_config` | **ZDH-12** data-plane handoff |
+| `helper_metrics` | Local time-to-green (privacy-safe) |
+
+### Day-one coach path
+
+```text
+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](https://github.com/koten-ai/zeus_chat_request) `v2/min/*` for offline templates.  
+3. `fetch_chat_request` always returns **TEMPLATE ONLY** warning.
+
+## Env
+
+| Variable | Purpose |
+| --- | --- |
+| `ZEUS_URL` | Public Zeus API (`:8080`) |
+| `ZEUS_BUCKET` / `ZEUS_SCOPE` / `ZEUS_COLLECTION` | Scope for bootstrap/auth probes |
+| `ZEUS_MODE` | default `analytics` |
+| `ZEUS_USERNAME` / `ZEUS_PASSWORD` | basic auth (not stored by set_prereq) |
+| `ZEUS_BEARER_TOKEN` | bearer auth |
+| `ZEUS_CHAT_REQUEST_DIR` | Local clone of zeus_chat_request |
+| `GITHUB_TOKEN` / `GH_TOKEN` | Private GitHub fetch |
+| `ZEUS_CHAT_REQUEST_REPO` | default `koten-ai/zeus_chat_request` |
+| `ZEUS_CHAT_REQUEST_BRANCH` | default `main` |
+| `DEMO_TRAVEL_SAMPLE_DIR` | Local clone of demo_travel_sample (ZDH-10) |
+| `KOTEN_DOCS_BASE_URL` | default `https://docs.koten.ai` |
+| `ZEUS_DEV_HELPER_STATE_DIR` | checklist / prereqs / local metrics |
+
+## Boundaries
+
+| This Helper | Not this Helper |
+| --- | --- |
+| Onboarding coach to first green | Data-plane Explore/Verify tools |
+| Catalog **templates** + readiness/smoke | Inventing `contract_hash` |
+| Multi / data-plane **handoffs** | ZJA job runtime / Hub admin mutations |
+| `KOTEN_DOCS_BASE_URL` | default `https://docs.koten.ai` (published site) |
+| `KOTEN_DOCS_BRANCH` | default `zeus-v1.0.0` (source branch for machine files) |
+| `ZEUS_DEV_HELPER_STATE_DIR` | checklist + prereqs state (default `~/.config/zeus_dev_helper`) |
+| `LLM_API_KEY` / `OPENAI_API_KEY` | presence checked by `validate_env` |
+
+## Tests
+
+```bash
+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`](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`](.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](https://pypi.org/manage/account/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
+
+| Repo | Role |
+| --- | --- |
+| [zeus_client_python](https://github.com/koten-ai/zeus_client_python) | SDK |
+| [zeus_chat_request](https://github.com/koten-ai/zeus_chat_request) | Min catalogs |
+| [docs.koten.ai](https://docs.koten.ai/) | Published platform docs |
+| [koten_docs](https://github.com/koten-ai/koten_docs) | Docs source + agent-index.yaml |
+| [Zeus](https://github.com/koten-ai/Zeus) | Engine |

zeus_dev_helper_mcp-0.6.0/README.md

@@ -0,0 +1,245 @@
+# zeus_dev_helper_mcp
+
+<!-- mcp-name: io.github.koten-ai/zeus-dev-helper -->
+
+**Developer Helper MCP** — first Zeus-powered app onboarding coach.
+
+| | |
+| --- | --- |
+| **Board** | [ZDH](https://kotenai.atlassian.net/jira/software/projects/ZDH/boards/45) |
+| **Epic** | [ZDH-1](https://kotenai.atlassian.net/browse/ZDH-1) |
+| **Skeleton** | [ZDH-3](https://kotenai.atlassian.net/browse/ZDH-3) |
+| **Catalogs** | [ZDH-14](https://kotenai.atlassian.net/browse/ZDH-14) → [zeus_chat_request](https://github.com/koten-ai/zeus_chat_request) |
+| **Docs** | [docs.koten.ai](https://docs.koten.ai/) · [Dev Helper MCP](https://docs.koten.ai/zeus-client/dev-helper-mcp) |
+
+> Not a data-plane MCP. Coaches: checklist → templates → live readiness & smoke → handoffs.
+
+**Design:** [`docs/DESIGN.md`](docs/DESIGN.md) (ZDH-2, frozen MVP) · [`docs/DESIGN-0.6.md`](docs/DESIGN-0.6.md) (runtime coach)  
+**Tool catalog:** [`docs/TOOLS.md`](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
+
+```bash
+pip install zeus-dev-helper-mcp
+# or
+uvx zeus-dev-helper-mcp
+```
+
+Optional agent-smoke extra (needs `kotenai-zeus-client` on PyPI):
+
+```bash
+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)
+
+```bash
+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
+
+```bash
+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 `--`**.
+
+```bash
+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:
+
+```bash
+# 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`):
+
+```toml
+[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):
+
+```json
+{
+  "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`](docs/TOOLS.md). Status inventory:
+
+| Tool | Status |
+| --- | --- |
+| `doctor` | Config + catalog reachability |
+| `start_project` / `get_checklist` / `next_step` / `gap_report` | **ZDH-8** coach walkthrough |
+| `mark_done` / `mark_blocked` | Checklist updates |
+| `set_prereq` / `validate_env` / `readiness_check` | **ZDH-4** |
+| `bootstrap_scope` | **ZDH-5** live bootstrap + chat_request summary |
+| `scaffold_app` / `use_sample` / `write_env` / `verify_local_setup` | **ZDH-6** |
+| `travel_golden_path` | **ZDH-10** travel sample golden path |
+| `smoke_test_zeus` / `smoke_test_agent` / `diagnose_error` | **ZDH-7** / **ZDH-19** ErrorCode + 0.7 classes |
+| `recommend_surface` / `explain_verb` / `lint_verb_args` / `suggest_verb_call` | **ZDH-18** Direct vs agent + V2 verb lint (does not POST; no Runtime scaffold rewrite) |
+| `compat_check` | **ZDH-21** version/feature gates on `:8080` (not a COMPAT row) |
+| `lint_chat_request` / `bind_contract` / `explain_hash_boundary` / `catalog_diff` | **ZDH-22** catalog coach — extract stamp only |
+| `lint_runtime_config` / `lint_app_code` | **ZDH-24** config + anti-example scan (secrets redacted) |
+| `explain_req_id_policy` / `detective_links` / `support_pack_from_turn` | **ZDH-23** correlation + redacted support pack |
+| `describe_scope` | **ZDH-25** schema-only live describe |
+| `recommend_motion` | **ZDH-26** 13 motions; no custom chat_request |
+| `suggest_hooks` | **ZDH-27** policy snippets (not a policy engine) |
+| `semantic_cache_status` | **ZDH-28** leave enabled=false; optional status probe |
+| `list_catalog_modes` / `fetch_chat_request` | **ZDH-14** |
+| `explain` / `suggest_demo_prompts` | **ZDH-13** glossary + prompts |
+| `handoff_to_multi` | **ZDH-11** multi-agent graduation (gated) |
+| `recommend_data_plane_mcp` / `emit_mcp_config` | **ZDH-12** data-plane handoff |
+| `helper_metrics` | Local time-to-green (privacy-safe) |
+
+### Day-one coach path
+
+```text
+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](https://github.com/koten-ai/zeus_chat_request) `v2/min/*` for offline templates.  
+3. `fetch_chat_request` always returns **TEMPLATE ONLY** warning.
+
+## Env
+
+| Variable | Purpose |
+| --- | --- |
+| `ZEUS_URL` | Public Zeus API (`:8080`) |
+| `ZEUS_BUCKET` / `ZEUS_SCOPE` / `ZEUS_COLLECTION` | Scope for bootstrap/auth probes |
+| `ZEUS_MODE` | default `analytics` |
+| `ZEUS_USERNAME` / `ZEUS_PASSWORD` | basic auth (not stored by set_prereq) |
+| `ZEUS_BEARER_TOKEN` | bearer auth |
+| `ZEUS_CHAT_REQUEST_DIR` | Local clone of zeus_chat_request |
+| `GITHUB_TOKEN` / `GH_TOKEN` | Private GitHub fetch |
+| `ZEUS_CHAT_REQUEST_REPO` | default `koten-ai/zeus_chat_request` |
+| `ZEUS_CHAT_REQUEST_BRANCH` | default `main` |
+| `DEMO_TRAVEL_SAMPLE_DIR` | Local clone of demo_travel_sample (ZDH-10) |
+| `KOTEN_DOCS_BASE_URL` | default `https://docs.koten.ai` |
+| `ZEUS_DEV_HELPER_STATE_DIR` | checklist / prereqs / local metrics |
+
+## Boundaries
+
+| This Helper | Not this Helper |
+| --- | --- |
+| Onboarding coach to first green | Data-plane Explore/Verify tools |
+| Catalog **templates** + readiness/smoke | Inventing `contract_hash` |
+| Multi / data-plane **handoffs** | ZJA job runtime / Hub admin mutations |
+| `KOTEN_DOCS_BASE_URL` | default `https://docs.koten.ai` (published site) |
+| `KOTEN_DOCS_BRANCH` | default `zeus-v1.0.0` (source branch for machine files) |
+| `ZEUS_DEV_HELPER_STATE_DIR` | checklist + prereqs state (default `~/.config/zeus_dev_helper`) |
+| `LLM_API_KEY` / `OPENAI_API_KEY` | presence checked by `validate_env` |
+
+## Tests
+
+```bash
+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`](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`](.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](https://pypi.org/manage/account/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
+
+| Repo | Role |
+| --- | --- |
+| [zeus_client_python](https://github.com/koten-ai/zeus_client_python) | SDK |
+| [zeus_chat_request](https://github.com/koten-ai/zeus_chat_request) | Min catalogs |
+| [docs.koten.ai](https://docs.koten.ai/) | Published platform docs |
+| [koten_docs](https://github.com/koten-ai/koten_docs) | Docs source + agent-index.yaml |
+| [Zeus](https://github.com/koten-ai/Zeus) | Engine |