io.github.koten-ai/zeus-dev-helper
OfficialA stdio MCP onboarding coach that guides a coding agent and a human to a first successful Zeus Client app turn — it checks, scaffolds, and explains, but never runs data-plane Explore/Verify verbs.
Health & setup —
doctor(health/env/compat/cache),load_process_login(loads mode-600 credentials from a file),set_prereq(stores non-secret prereqs, presence flags only)Checklist coaching —
start_project(travel, beer, demo_yelp, or api path),next_step(returns the single current blocker and recommended tools)Live Zeus checks —
readiness_check(healthz/readyz/version, auth, bootstrap),smoke_test_zeus(read-only describe, no LLM),explain_scope(summarizes the livechat_requeststamp: entity types, fields, verbs)App creation —
scaffold_app(CLI or FastAPIPOST /turn, Python only),use_sample(clones demo_travel_sample / demo_beer_sample / demo_yelp or writes a catalog page, writes mode-600.env)Wiring & verification —
bind_contract(copies a stampedcontract.hashonly, never invents one),inject_business_rules(writesconfig.jsonrules),recommend_surface(intent → Client surface + do-not list),website_green(install/start/check the catalog page),smoke_test_agent(onerun_turn, needs LLM key)Debugging & support —
diagnose_error(symptom → failure class + one suggested file change),sample_support_pack(read-only redacted Markdown paste for gate failures)Reference material — always-on
zeus-helper://resources (checklist, glossary, verbs, hash-boundary/req-id policies, catalog modes) and prompts (first_green,smoke_question,support_pack)Guardrails — public Zeus API on
:8080only, no invented hashes, no secrets in results or support packs, semantic cache off, multi-agent/data-plane work is handoff-only
Clones public sample and template repositories (demo_travel_sample, demo_yelp, and the zeus_chat_request catalog templates) from GitHub when they are not already present locally, letting the coach path pull ready-made UI samples and catalog templates for the first-app walkthrough.
Provides a Yelp demo UI path: start_project(sample=demo_yelp) plus use_sample(sample=demo_yelp) clone the demo_yelp app when missing, point at the yelp-demo bucket / _default scope, and set DEMO_YELP_SAMPLE_DIR so a Yelp-style demo UI can be stood up and smoke-tested. Bare sample=yelp is reserved as the multi-agent handoff.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@io.github.koten-ai/zeus-dev-helper Walk me through a first Zeus Client app turn, from onboarding to smoke tests."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
|
Registry name |
|
Transport | stdio |
Python | 3.11+ |
MCP SDK |
|
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_hashNo 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-mcpRun
zeus-dev-helper-mcp
# or
python -m zeus_dev_helper_mcpPrefer 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:8080If 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-mcpFrom 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_mcpEquivalent 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 = trueThen 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; useuvx --from 'zeus-dev-helper-mcp[agent]' zeus-dev-helper-mcpNo module named 'zeus_client'— this Helper process has noagentextra. Installingkotenai-zeus-clientinto the app.venvleaves 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/pythonpath aboveNo 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_errorPrefer 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 publicdemo_travel_sample. The clone URL stayshttps://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;mainis used only when that repository has no semver tags.demo_travel_sample,demo_beer_sample, anddemo_yelpare tagged0.1.0. Passuse_sample(version=...)when the user names a version. The destination issample_dir, orparent_dirplusproject_name. A blank parent is the directory next to this Helper checkout. A foreign default directory moves to the next open sibling. An explicit foreignsample_dirreturnsforeign_sample_dirand writes nothing. A recorded checkout that answersGET /api/healthstays in place. The entrypoint stayspython -m travel_planneron port 5000 unlessPORTis set.use_samplewrites a mode 600.envfrom the non-secret Zeus and LLM names, keeps populated values, and fills empties. A rewrite of an existing.envsetsenv_change.settings_writtennames which ofZEUS_AUTH_MODE,ZEUS_USERNAME,LLM_BASE_URL, andLLM_MODELchanged.settings_keptgives the populated values that stayed.ZEUS_PASSWORD,ZEUS_BEARER_TOKEN, andLLM_API_KEYstay presence-only insecret_presence. Restart the app beforerun_turnwhenenv_changeis true.ZEUS_USERNAMEdefaults todemo_1. The create path does not rewrite the Dockerfile or compose file. Checklist 1.2 stays open until this process hasLLM_API_KEY,XAI_API_KEY, orOPENAI_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 recommendwebsite_green. Travel is one scope: smoke-green does not recommendhandoff_to_multiand does not writejobs.host_url.Beer catalog UI:
start_project(sample=beer)→use_sample(sample=beer)clones publicdemo_beer_samplewhen missing and setsDEMO_BEER_SAMPLE_DIR. A named tag that exists is cloned exactly; an omitted version or a missing tag uses the latest semver tag;mainis used only when that repository has no semver tags. The repository is tagged0.1.0. That checkout is the app. Start it with Python 3.11 or newer. Theuse_samplerun string usespython3 -m venvonly whenpython3is 3.11 or newer. Thenpip install -r requirements.txtandpython main.py(binds127.0.0.1:8090). When that checkout has both aDockerfileand a compose file,use_sampleasks 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 installskotenai-zeus-client>=2.5.3,<2.6from PyPI.use_samplewrites mode 600.envfrom.env.example, keeps populated values, and adds missing template keys. A rewrite of an existing.envsetsenv_change.settings_writtennames which ofZEUS_AUTH_MODE,ZEUS_USERNAME,LLM_BASE_URL, andLLM_MODELchanged.settings_keptgives the populated values that stayed.ZEUS_PASSWORD,ZEUS_BEARER_TOKEN, andLLM_API_KEYstay presence-only insecret_presence. Restart the app beforerun_turnwhenenv_changeis true. It resolvesLLM_API_KEY,LLM_BASE_URL, andLLM_MODELtogether, and copiesOPENAI_API_KEYorXAI_API_KEYonly when the base URL and model match that provider. The clone keepsLLM_MODEL=grok-4.5-latest.runandnext_actiondo not say to copy.env.exampleover that file.website_greendoes not run pip when the app.venvis older than 3.11. Lists are Direct and need no LLM key. Pour matches travel:rt.agent.run_turnwithchat_requestomitted socatalog.load_for_turnmerges the live SCOPE BRIEF and MINI-SCHEMA. A helper-written catalog page usesmax_rounds4. Pour stays off untilLLM_API_KEY,XAI_API_KEY, orOPENAI_API_KEYis in the app.env, including whenhas_llm_key=false. Leaveconfig.jsonllm.api_key_envas that variable name.verify_local_setupkeeps checklist 3.2 open until that file check passes. The BFF does not build a pipeline body. Do not clonedemo_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 templatedemo_yelpwhen missing (utterancesyelp-demo/demo_yelp) and setsDEMO_YELP_SAMPLE_DIR. A named tag that exists is cloned exactly; an omitted version or a missing tag uses the latest semver tag;mainis used only when that repository has no semver tags. The repository is tagged0.1.0. Whenparent_diris 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_guideon port 5000 andcd frontend && npm install && npm run devon port 5173. Do not write a replacement or copy the beer sample.use_samplealso downloads the public business photo set intofrontend/public/business-images/<id>/{1,2,3}.png(nobiz:prefix, no API key). Search POSTs/api/searchand sends the live chat request foryelp-demo/_defaultas 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 arev:doc key.set_prereqbucket isyelp-demo, scope_default. Do not clonedemo_travel_sample. Baresample=yelpstays 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)(FastAPIPOST /turnonkotenai-zeus-client). Other languages not scaffolded yet.Credentials from chat → process env / gitignored
.env;set_prereqpresence flags only.has_llm_key=truedoes not count as the key. Pass the user’s Zeus URL intoset_prereq(zeus_url=…). Do not paste the secret intollm.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 |
| Health. |
| Init checklist; |
| Current item plus recommended tools and resource links |
| Store non-secret prereqs (presence flags only; |
| Live gates: healthz / readyz / version, auth, bootstrap. Marks 1.2 done only when the URL is set and, on a |
| Live public |
| CLI or FastAPI ( |
| Travel UI clone, beer catalog clone ( |
| Copy a stamped |
| Intent → Client surface + do-not list |
| No LLM: readiness plus a read-only describe |
| Install, start, and check the catalog page (named list card, page ids, search when Pour is on). A title-cased |
| One Client |
| Map a symptom, hop name, and result keys to a failure class and one generated-file change |
| Read-only paste for a beer, travel, or yelp-demo gate failure. Writes nothing and calls no Zeus API. Session ids stay in |
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 |
| Public Zeus API base URL (port 8080). Remote host first; |
| Scope for bootstrap and auth probes |
| Default catalog mode ( |
| Auth mode ( |
| Basic auth (never logged) |
| Bearer auth (never logged) |
| Process key for checklist 1.2, |
| OpenAI-compatible endpoint and model. Offered defaults: Grok |
| Local directory of min catalog templates; auto-set when |
| Local sample directory for |
| Local |
| Optional CDN prefix for the yelp photo download (no trailing slash). Default is the public |
| Set to |
| Parallel downloads for that photo set. Default |
| Checklist, prereqs, local metrics, the write-once sample creation logs ( |
| Static toolsets: |
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 |
Verb explain / lint / draft ( | POSTing |
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:8080pytest -qMCP 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 toolsbind_contractCRead-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_errorBRead-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
doctorARead-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_scopeARead-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_rulesBIdempotent
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_loginAIdempotent
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_stepARead-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_checkBIdempotent
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_surfaceCRead-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_packARead-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_appADestructive
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_prereqAIdempotent
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_projectBDestructive
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_sampleAIdempotent
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
Scored across 17 tools
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.
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.
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.
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
Related MCP Connectors
Agent routing, safety preflight, execution receipts, best execution and verified outcomes.
Agents ask other agents for help: post requests, take work, rooms, signed receipts. Test USDC beta.
ERC-8004 agent identity, on-chain subscriptions, reputation, A2A tasks and chat over 53 tools.
Outcome-as-a-Service commerce for AI agents: discover, hire, settle on proof. Live on devnet.
Related MCP Servers
- AlicenseBqualityBmaintenanceLocal-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.346,385MIT
- FlicenseAqualityDmaintenanceDemonstrates agent-native platform onboarding with human-in-the-loop API key provisioning, plus live usage and rate-limit queries via Anthropic Admin APIs.3-
- AlicenseNot gradedqualityDmaintenanceEnables 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
- AlicenseNot gradedqualityDmaintenanceEnables 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