Skip to main content
Glama
io.github.koten-ai/zeus-dev-helper

io.github.koten-ai/zeus-dev-helper

Official
by Koten-ai-org

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

Related MCP server: platform-mcp-stub

Install

verify_local_setup and smoke_test_agent import zeus_client in this Helper process. Install the agent extra into that environment. The app .venv does not satisfy the check.

pip install "zeus-dev-helper-mcp[agent]"
# or
uvx --from 'zeus-dev-helper-mcp[agent]' zeus-dev-helper-mcp

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 --from 'zeus-dev-helper-mcp[agent]' zeus-dev-helper-mcp

From a local checkout after pip install -e ".[dev,agent]", 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 = ["--from", "zeus-dev-helper-mcp[agent]", "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 uvx --from 'zeus-dev-helper-mcp[agent]' zeus-dev-helper-mcp

  • No module named 'zeus_client' — this Helper process has no agent extra. Installing kotenai-zeus-client into the app .venv leaves the check red. Restart the MCP server after installing the extra into the Helper environment.

  • 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": ["--from", "zeus-dev-helper-mcp[agent]", "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": ["--from", "zeus-dev-helper-mcp[agent]", "zeus-dev-helper-mcp"],
      "env": {
        "ZEUS_URL": "http://192.168.0.219:8080"
      }
    }
  }
}

Codex

The permission profile :workspace does not enable network. With sandbox_approval false, Codex does not ask to enable it. Pip then reports [Errno -2] Name or service not known. That is EAI_NONAME from the closed network. A package host that answers outside the sandbox can still look like a DNS failure inside it.

Set a top-level profile that extends :workspace and enables network. Do not also set sandbox_mode or [sandbox_workspace_write]. Start a new Codex thread after the change. Leave the network proxy off unless localhost is allowlisted, because sandboxed commands still need local Zeus.

default_permissions = "workspace-net"

[permissions.workspace-net]
description = "Workspace writes plus outbound network so sandboxed commands can resolve package hosts."
extends = ":workspace"

[permissions.workspace-net.network]
enabled = true
[mcp_servers.zeus-dev-helper]
command = "uvx"
args = ["--from", "zeus-dev-helper-mcp[agent]", "zeus-dev-helper-mcp"]

Install the app requirements.txt from a process that already has network. That install does not put zeus_client on the Helper interpreter. Restart the MCP server after the Helper environment gains the agent extra.

Other stdio hosts

Point the host’s MCP stdio entry at uvx --from 'zeus-dev-helper-mcp[agent]' zeus-dev-helper-mcp (or python -m zeus_dev_helper_mcp from a venv that has the agent extra) 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 follows the beer creation procedure for public demo_travel_sample. The clone URL stays https://github.com/koten-ai/demo_travel_sample.git. A named tag that exists is cloned exactly; an omitted version or a missing tag uses the latest semver tag; main is used only when that repository has no semver tags. demo_travel_sample, demo_beer_sample, and demo_yelp are tagged 0.1.0. Pass use_sample(version=...) when the user names a version. The destination is sample_dir, or parent_dir plus project_name. A blank parent is the directory next to this Helper checkout. A foreign default directory moves to the next open sibling. An explicit foreign sample_dir returns foreign_sample_dir and writes nothing. A recorded checkout that answers GET /api/health stays in place. The entrypoint stays python -m travel_planner on port 5000 unless PORT is set. use_sample writes a mode 600 .env from the non-secret Zeus and LLM names, keeps populated values, and fills empties. A rewrite of an existing .env sets env_change. settings_written names which of ZEUS_AUTH_MODE, ZEUS_USERNAME, LLM_BASE_URL, and LLM_MODEL changed. settings_kept gives the populated values that stayed. ZEUS_PASSWORD, ZEUS_BEARER_TOKEN, and LLM_API_KEY stay presence-only in secret_presence. Restart the app before run_turn when env_change is true. ZEUS_USERNAME defaults to demo_1. The create path does not rewrite the Dockerfile or compose file. Checklist 1.2 stays open until this process has LLM_API_KEY, XAI_API_KEY, or OPENAI_API_KEY, because this page is search and has no Direct list. Checklist 3.2 stays open until that key is in the app .env. set_prereq(has_llm_key=true) does not count. After the app is on disk, checklist 5.1, 5.2, and 6.1 recommend website_green. Travel is one scope: smoke-green does not recommend handoff_to_multi and does not write jobs.host_url.

  • Beer catalog UI: start_project(sample=beer) → use_sample(sample=beer) clones public demo_beer_sample when missing and sets DEMO_BEER_SAMPLE_DIR. A named tag that exists is cloned exactly; an omitted version or a missing tag uses the latest semver tag; main is used only when that repository has no semver tags. The repository is tagged 0.1.0. That checkout is the app. Start it with Python 3.11 or newer. The use_sample run string uses python3 -m venv only when python3 is 3.11 or newer. Then pip install -r requirements.txt and python main.py (binds 127.0.0.1:8090). When that checkout has both a Dockerfile and a compose file, use_sample asks the agent to let the user choose Python or Docker before either command starts. website_green(serve_with=python|docker) records the choice. The helper does not run Docker. That requirements file installs kotenai-zeus-client>=2.5.3,<2.6 from PyPI. use_sample writes mode 600 .env from .env.example, keeps populated values, and adds missing template keys. A rewrite of an existing .env sets env_change. settings_written names which of ZEUS_AUTH_MODE, ZEUS_USERNAME, LLM_BASE_URL, and LLM_MODEL changed. settings_kept gives the populated values that stayed. ZEUS_PASSWORD, ZEUS_BEARER_TOKEN, and LLM_API_KEY stay presence-only in secret_presence. Restart the app before run_turn when env_change is true. It resolves LLM_API_KEY, LLM_BASE_URL, and LLM_MODEL together, and copies OPENAI_API_KEY or XAI_API_KEY only when the base URL and model match that provider. The clone keeps LLM_MODEL=grok-4.5-latest. run and next_action do not say to copy .env.example over that file. website_green does not run pip when the app .venv is older than 3.11. Lists are Direct and need no LLM key. Pour matches travel: rt.agent.run_turn with chat_request omitted so catalog.load_for_turn merges the live SCOPE BRIEF and MINI-SCHEMA. A helper-written catalog page uses max_rounds 4. Pour stays off until LLM_API_KEY, XAI_API_KEY, or OPENAI_API_KEY is in the app .env, including when has_llm_key=false. 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. Do not write a job for this one-scope page.

  • 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. A named tag that exists is cloned exactly; an omitted version or a missing tag uses the latest semver tag; main is used only when that repository has no semver tags. The repository is tagged 0.1.0. When parent_dir is set, the clone is created in that directory. Docker is the preferred yelp-demo elicitation option and is guide-only: DOCKER_BUILDKIT=1 docker compose up -d --build (UI http://localhost:3000, API http://localhost:5000). The helper does not run that command. The other option is one choice for both host processes: pip install -e . && python -m local_guide on port 5000 and cd frontend && npm install && npm run dev on port 5173. 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. When that body has no ## MINI-SCHEMA heading, parse bootstrap.chat_request. 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 clone (demo_beer_sample, python main.py, Direct lists, Pour run_turn with chat_request omitted), sample=catalog from explain_scope, or yelp demo clone (sample=demo_yelp, sets DEMO_YELP_SAMPLE_DIR; Docker is the preferred elicitation option, and the other option is both host processes; 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. With no path, the source is the live bootstrap chat_request. A directory pointer is not a catalog. 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

LLM_BASE_URL / LLM_MODEL

OpenAI-compatible endpoint and model. Offered defaults: Grok https://api.x.ai/v1 / grok-4.5-latest, OpenAI https://api.openai.com/v1 / gpt-5.6-sol, Anthropic https://api.anthropic.com/v1 / claude-opus-5-5, Gemini https://generativelanguage.googleapis.com/v1beta/openai/ / gemini-3.8-flash, or a base URL the user types. load_process_login reads both names from a mode-600 file

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), the support journals (beer-sample-support.md, travel-sample-support.md, yelp-demo-support.md), and the wish files (beer-sample-wish.md, travel-sample-wish.md, yelp-demo-wish.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,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.

Available Tools

17 tools
bind_contractC
Read-onlyIdempotent

Extract stamped contract.hash only. Refuse placeholders / compute_local (ZDH-22).

With no path, copy the hash from the live bootstrap chat_request. A helper chat_request.json directory pointer is not an unstamped catalog.

Inputs: mode, path, scope, bucket, +1 more. Returns: object

diagnose_errorB
Read-onlyIdempotent

Map a symptom to failure_class + one generated-file change.

Accepts symptom text, optional req_id, hop name, HTTP status, and the top-level keys of the hop result. Does not accept document bodies. Does not echo a password, session id, or document body. Includes Detective URL templates when req_id/chat_id are present. Does not scrape Hub.

Inputs: body, req_id, status, chat_id, +12 more. Returns: object

doctorA
Read-onlyIdempotent

Health / doctor. detail: health | env | compat | cache | all.

health checks that python3 is 3.11 or newer and marks checklist 1.1. The app .venv is checked by verify_local_setup and website_green.

env/compat/cache fold validate_env, compat_check, and semantic_cache_status (those names stay on the lint toolset).

If the user already gave a Zeus URL or sample name, next call set_prereq with those values (not Helper localhost defaults), then start_project / next_step. Do not grep the Zeus engine tree for first green.

Inputs: detail. Returns: object

explain_scopeA
Read-onlyIdempotent

Summarize the live chat_request stamp on public :8080.

Entity types, display fields, text-search fields, foreign-key fields, and the verb for list (find), detail (get), and search. No prompt text, document bodies, or secrets. fetch_chat_request stays template only. When GET /v1/ai/chat_request.json has no ## MINI-SCHEMA heading, the summary is parsed from bootstrap.chat_request. missing_mini_schema remains when that message also has no heading. A failed stamp sets failure_class and does not invent entity types.

Inputs: no named parameters. Returns: object

inject_business_rulesB
Idempotent

Write named business rules into the current Zeus app.

Omit app_dir and sample to use the current directory when it is a Zeus app, otherwise the checklist sample (the beer app just created). ask_user means ask and wait, then call again. An explicit path that is not a Zeus app returns not_a_zeus_app and does not write. wire_required means the app builds ClientSettings itself. Pass settings.rules into that constructor. This tool writes config.json only.

Inputs: rules, remove, sample, app_dir, +1 more. Returns: object

load_process_loginA
Idempotent

Load Zeus login from a mode-600 env file into this process.

Write ZEUS_USERNAME and ZEUS_PASSWORD to a file outside the repo or gitignored, chmod 600, then pass that path. The password is not an argument. The same file may set ZEUS_AUTH_MODE (none, basic, or bearer), LLM_BASE_URL, LLM_MODEL, and LLM_API_KEY. set_prereq stores presence flags only. The result lists loaded names and never values. Then readiness_check.

Inputs: env_file (required). Returns: object

next_stepA
Read-onlyIdempotent

Return the single current checklist blocker + recommended Helper tools (coach).

Call only the recommended tool next. If the user named a URL/bucket and prereqs are unset, recommend set_prereq first. Prefer zeus-helper:// + readiness_check / smoke_test_zeus over hand-rolled curl.

Inputs: no named parameters. Returns: object

readiness_checkB
Idempotent

Live Zeus platform gates: healthz/readyz/version, auth, bootstrap, chat_request.

Never returns secret values. Emits failure_class + next_action on red paths.

Inputs: update_checklist. Returns: object

recommend_surfaceC
Read-onlyIdempotent

Name each website input. One box still returns one surface. Does not call Zeus.

A website (intent=nl_question) returns inputs: Direct list, chips, typeahead, paging, and detail, plus a One chat question box. url_count, scope_count, or report_wait_s of 20 seconds or more is a Job hint. The tool does not write jobs.host_url. Zero counts mean one URL and one scope.

Inputs: intent (required), qps, page, needs_llm, +6 more. Returns: object

sample_support_packA
Read-onlyIdempotent

Read-only paste for a beer, travel, or yelp-demo support request.

Writes nothing and calls no Zeus API. Returns one Markdown paste: sample kind, bound directory, creation log, prereqs, open checklist rows in phases 1–5, the last website_green class, local setup, recent tool names, the support-journal tail, and the last 8 wish sections. Session ids stay in support_pack_from_turn. sample=api and bare sample=yelp are refused.

Inputs: sample. Returns: object

scaffold_appA
Destructive

Write a ZeusRuntime middle-man.

app_kind=cli (default) or api (FastAPI POST /turn). coding_language=python only today. UI demos use use_sample / demo_travel_sample, not this tool. When no Zeus URL is stored, the MCP call asks before writing files. Do not pass a password.

Inputs: target_dir (required), force, app_kind, project_name, +1 more. Returns: object

set_prereqA
Idempotent

Store non-secret prereqs for readiness (does not store password/token values).

Put real secrets in environment variables (ZEUS_PASSWORD, ZEUS_BEARER_TOKEN, LLM_API_KEY). When the user named a Zeus URL or sample in chat, pass that zeus_url / bucket / scope here (not Helper localhost defaults). If the user did not name a URL, leave zeus_url empty and wait for the form. Do not copy the host ZEUS_URL. Persisted values override MCP host ZEUS_* env defaults so readiness/doctor hit the user's cluster (ZDM-3). Presence flags only for credentials and LLM key.

Inputs: mode, role, scope, bucket, +7 more. Returns: object

smoke_test_agentC

One ZeusRuntime run_turn (requires kotenai-zeus-client>=2.3.0 + LLM key).

If the client is missing and demo_travel_sample documents Docker install, returns guide-only docker compose next_action instead of only pip install.

Inputs: question, update_checklist. Returns: object

smoke_test_zeusB

Smoke Zeus without LLM: readiness + POST /v2/{bucket}/{scope}/describe.

Inputs: update_checklist. Returns: object

start_projectB
Destructive

Start or reset first-app coaching checklist (single-agent default).

sample:

  • travel (default) — UI path via demo_travel_sample / use_sample

  • beer — beer-sample catalog UI; search is run_turn + MINI-SCHEMA (use_sample sample=beer)

  • demo_yelp — yelp-demo UI; use_sample clones the LocalAI template https://github.com/koten-ai/demo_yelp (aliases yelp-demo, demo-yelp)

  • api — API-only FastAPI scaffold (scaffold_app app_kind=api)

  • yelp / multi — gated until single-agent smokes green unless force_multi. Not the yelp demo. Utterances yelp-demo / demo_yelp use sample=demo_yelp.

Multi-agent goals (goal=multi or sample=yelp) are gated until single-agent smokes are green, unless force_multi=true (ZDH-11).

When no Zeus URL is stored, the MCP call asks for the public :8080 URL before the checklist starts. Leave zeus_url empty when the user did not name one. Do not copy the host ZEUS_URL. Do not pass a password.

Inputs: goal, sample, force_multi. Returns: object

use_sampleA
Idempotent

UI sample: travel clone, beer catalog UI, live-stamp page, or yelp demo clone.

sample=travel — shallow-clone https://github.com/koten-ai/demo_travel_sample.git when the destination is missing. Optional version: a named tag that exists is cloned exactly; an omitted version or a missing tag uses the latest semver tag; main is used only when that repository has no semver tags. demo_travel_sample, demo_beer_sample, and demo_yelp are tagged 0.1.0. Pass use_sample(version=...) when the user names a version. An existing checkout stays in place. The destination is sample_dir, or parent_dir plus project_name. A blank parent is the directory next to this Helper checkout. Start with python -m travel_planner on port 5000 unless PORT is set. The create path does not rewrite Docker files. Set DEMO_TRAVEL_SAMPLE_DIR. A mode 600 .env keeps populated values and fills empty Zeus and LLM names. ZEUS_USERNAME defaults to demo_1. A rewrite of an existing .env sets env_change. settings_written names which of ZEUS_AUTH_MODE, ZEUS_USERNAME, LLM_BASE_URL, and LLM_MODEL changed. settings_kept gives the populated values that stayed. ZEUS_PASSWORD, ZEUS_BEARER_TOKEN, and LLM_API_KEY stay presence-only in secret_presence. Restart the app before run_turn when env_change is true. sample=beer — shallow-clone https://github.com/koten-ai/demo_beer_sample when missing. A named tag that exists is cloned exactly; an omitted version or a missing tag uses the latest semver tag; main is used only when that repository has no semver tags. The repository is tagged 0.1.0. Set DEMO_BEER_SAMPLE_DIR. Start with python main.py after a Python 3.11+ virtualenv (python3 -m venv only when python3 is 3.11 or newer) and pip install -r requirements.txt. use_sample writes mode 600 .env from .env.example, keeps populated values, and adds missing template keys. LLM_API_KEY, LLM_BASE_URL, and LLM_MODEL are resolved together. The clone keeps LLM_MODEL=grok-4.5-latest. Do not copy .env.example over a .env that already has values. A rewrite of an existing .env sets env_change. settings_written names which of ZEUS_AUTH_MODE, ZEUS_USERNAME, LLM_BASE_URL, and LLM_MODEL changed. settings_kept gives the populated values that stayed. ZEUS_PASSWORD, ZEUS_BEARER_TOKEN, and LLM_API_KEY stay presence-only in secret_presence. Restart the app before run_turn when env_change is true. Lists are Direct and need no LLM key. Pour is rt.agent.run_turn with chat_request omitted (catalog.load_for_turn merges MINI-SCHEMA) and max_rounds 4. Pour stays off until an LLM key is in the app .env. No pipeline body. Do not write a job for this one-scope page. Clone success is not website_green. When the checkout has both a Dockerfile and a compose file, serve_choice_required is true, serve_options lists Python and Docker, host_question is the selection, and run is empty until serve_with is python or docker. Follow host_question and next_action on that result. The helper does not run Docker. Pass serve_with on a later use_sample or website_green call. An already-serving checkout does not ask. sample=catalog — write demo_catalog_sample from explain_scope. A beer-sample bucket, or entity types that are exactly Beer and Brewery, still writes the beer UI. sample=demo_yelp — locate or clone the LocalAI template https://github.com/koten-ai/demo_yelp (aliases yelp-demo, demo-yelp, yelp_demo, yelpdemo). A named tag that exists is cloned exactly; an omitted version or a missing tag uses the latest semver tag; main is used only when that repository has no semver tags. The repository is tagged 0.1.0. Set DEMO_YELP_SAMPLE_DIR. When parent_dir is set, clone into that directory. Docker is the preferred elicitation option and is guide-only: DOCKER_BUILDKIT=1 docker compose up -d --build. UI http://localhost:3000. API http://localhost:5000. The helper does not run that command. python is one option for both host processes: pip install -e . && python -m local_guide on port 5000 and cd frontend && npm install && npm run dev on port 5173 (the SPA proxies /api to port 5000). Writes gitignored mode-600 config.json from this process. llm.api_key_env stays the name LLM_API_KEY. The first yelp-demo create, while yelp-demo-build.md is absent and the host shows a form, asks a Couchbase card after the Zeus connection card, then a server card, then the LLM card. The server field is docker or python. docker is the default and the first enum value. Both cards are yelp-only. A declined or cancelled card does not create the app. couchbase_query_url and couchbase_username are strings. COUCHBASE_PASSWORD stays in the app .env and is not collected on the form or as a tool argument. An accepted card writes the two strings into a mode-600 .env (created from .env.example when missing) and leaves an existing COUCHBASE_PASSWORD line unchanged. Beer, travel, the API scaffold, and bare sample=yelp do not ask the Couchbase card or the server field. When the card is not shown, ask_user adds text rows for COUCHBASE_QUERY_URL and COUCHBASE_USERNAME and tells the user to write COUCHBASE_PASSWORD in the app .env. Search POSTs /api/search and sends the live chat_request.json for yelp-demo/_default mode analytics as the session body. A 401 stays red. Search cards get latitude and longitude from biz:yelp: when the project step omits them, including a cached business page. The business page GETs /api/business/{id} when the id is not in the bundled catalog. Review text is the source document, not the rev: doc key. Also downloads the public business photo set into frontend/public/business-images//{1,2,3}.png (no biz: prefix, no API key). Do not write a replacement or copy demo_beer_sample. Bare sample=yelp stays the multi-agent handoff. project_name = directory name (defaults: demo_travel_sample / demo_beer_sample / demo_catalog_sample / demo_yelp). Extra travel-only phases stay on travel_golden_path (travel toolset). When no Zeus URL is stored, the MCP call asks before writing or cloning. Do not pass a password.

Inputs: sample, version, parent_dir, sample_dir, +3 more. Returns: object

website_greenA

Install, start, and check the catalog page.

Separate from smoke_test_zeus. Mints the scope session when auth is basic, then checks list cards and, when Pour is on, one search. A title-cased doc_key or src_keys entry is not a search card. A describe 200 is not this check. Does not call smoke_test_agent. No secrets in the result. serve_with is python or docker. When the checkout has both a Dockerfile and a compose file and serve_with is empty, this returns serve_choice_required and host_question and does not start Python. Follow host_question and next_action. Docker is not run.

Inputs: serve_with, target_dir. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 17 tools

    Disambiguation3/5

    The many 'is it green?' tools overlap heavily in spirit—readiness_check, smoke_test_zeus, smoke_test_agent, website_green, and doctor all verify some aspect of the setup—and set_prereq vs load_process_login both handle credentials, so an agent must lean on dense descriptions to choose correctly. The descriptions do carve out distinct roles (platform gates vs describe vs one LLM turn vs catalog page), which keeps this from being worse.

    Naming Consistency4/5

    Nearly every tool follows a snake_case verb_noun pattern (start_project, set_prereq, smoke_test_zeus, inject_business_rules, bind_contract). The lone outlier is the bare noun 'doctor', a minor deviation from an otherwise predictable convention.

    Tool Count3/5

    At 17 tools this sits just in the heavy end of the range for what is essentially a guided dev-helper workflow, and several near-duplicate verification tools inflate the count. Each broadly maps to a step, but consolidation of the check tools would tighten the surface.

    Completeness4/5

    The set covers the full first-app lifecycle: prereqs/login, readiness, sampling and scaffolding, business-rule injection, smoke tests, UI green check, error diagnosis, support bundling, and contract binding. Minor gaps remain (no teardown/reset of samples, no project-listing or log-streaming operation), but agents have workarounds.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Local-first Agent OS that wraps Claude Code, Codex CLI, and other coding agents in a replayable Seed → Ledger → Runtime contract, driven by an interview → seed → execute → evaluate → evolve workflow loop.
      34
      6,385
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI coding agents to conduct Socratic interviews, crystallize answers into immutable specifications, execute staged development, and run automated evaluation and evolutionary loops until convergence.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI coding agents to run a specification-first workflow through MCP tools: Socratic interview, immutable seed specification, execution, staged evaluation, and evolutionary loops. This helps turn vague ideas into verified, working codebases across multiple runtimes.
      MIT