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

Official

Overview Schema Source Related Servers Discussions Admin

use_sample

Idempotent

Clones the selected travel, beer, catalog, or Yelp demo when missing, then writes its environment configuration so the Zeus Client sample can run.

Instructions

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. 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; 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); set DEMO_YELP_SAMPLE_DIR. When parent_dir is set, clone into that directory. The checkout is the app: pip install -e . && python -m local_guide on http://127.0.0.1:5000, and cd frontend && npm install && npm run dev on http://localhost: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. 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.

Input Schema

Name	Required	Default
`sample`	No	travel
`parent_dir`	No
`sample_dir`	No
`serve_with`	No
`project_name`	No
`clone_if_missing`	No

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.7.10Oct 30, 2026
- addedInput schema / properties / serve_with
```
Added value: +{
+  "default": "",
+  "title": "Serve With",
+  "type": "string"
+}
```
First observedv0.7.3Sep 22, 2026

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With annotations only marking this as non-readonly, open-world, idempotent and non-destructive, the description carries substantial extra weight: it discloses clone targets, mode-600 .env writing that preserves populated values, presence-only secret handling, that intact populated values are kept, that Docker files are not rewritten, and that the helper does not run Docker. The disclosure is genuinely rich, though its density and lack of ordering make some effects hard to extract reliably.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

This is a single unstructured wall of roughly 600 words with no headings, bullets, or per-sample separation, and repeated boilerplate (env_change, settings_written, settings_kept, secret_presence, restart-before-run_turn) appears verbatim in both the travel and beer blocks. Precious little is front-loaded, so an agent must scan the whole block to find the section relevant to its sample value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a high-complexity tool spanning four distinct project setups, the description does cover setup commands, ports, env handling, and the serve-choice branching, which is substantial. But it redundantly re-specifies return fields (env_change, settings_written, next_action) despite an output schema existing, leaves 'live-stamp page' unexplained, and never says whether repeated invocation re-runs setup, so completeness is offset by gaps and redundancy.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must define all six parameters, and it largely does: it enumerates sample values including the yelp aliases, explains that destination is sample_dir or parent_dir plus project_name, gives project_name defaults per sample, defines serve_with as python or docker, and implies that cloning occurs only when the destination is missing (clone_if_missing). Only clone_if_missing and the parent_dir resolution are somewhat indirect.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening fragment names the resource and its four variants (travel, beer, catalog, demo_yelp), and each per-sample block states concrete actions: shallow-clone a repo, write a mode-600 .env, and give a start command. The core verb is buried in a sprawling block rather than front-loaded, and the first-line mention of a 'live-stamp page' is never explained in any section, leaving one advertised variant undocumented.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Scattered directives do provide routing: extra travel-only phases belong on travel_golden_path, bare sample=yelp stays the multi-agent handoff, and the agent must pass serve_with on a later call when serve_choice_required is true. However, there is no explicit statement of when to choose this tool over siblings like scaffold_app, start_project, or website_green, so the boundary is inferred rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server