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

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

Official
by Koten-ai-org

use_sample

Idempotent

Clones and prepares demo UI samples (travel, beer, catalog, or Yelp), resolving versions and environment settings so you can run or serve the sample locally.

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. 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.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "use_sample"
  }
}

Input Schema

NameRequiredDescriptionDefault
sampleNotravel
versionNo
parent_dirNo
sample_dirNo
serve_withNo
project_nameNo
clone_if_missingNo

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.7.13
    • addedInput schema / properties / version
      Added value: +{
      +  "default": "",
      +  "title": "Version",
      +  "type": "string"
      +}
  2. Changed1 schema field changedv0.7.10
    • addedInput schema / properties / serve_with
      Added value: +{
      +  "default": "",
      +  "title": "Serve With",
      +  "type": "string"
      +}
  3. First observedv0.7.3

TDQS

A4.2/5.0
Behavior5/5

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

The annotations already declare readOnly=false, openWorld=true, idempotent=true, and destructive=false, but the description adds extensive behavioral detail: clone-vs-existing behavior, tag fallback, env writes and rewrites, secret presence, service-choice gating, and the fact that Docker commands are not run. This is strong disclosure of side effects and prerequisites that annotations alone cannot convey.

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

Conciseness3/5

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

The description is front-loaded but extremely long and repetitive, with tag-selection mechanics and env/settings language repeated across travel and beer sections instead of being consolidated. It is also a single dense block with no headings or bullets, making the relevant branch hard to scan. The content is relevant, but the structure is poor.

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

Completeness5/5

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

For a complex multi-sample setup tool with an output schema, the description covers the critical branches: clone targets, version fallback, port and start commands, env handling, elicitation cards, Docker non-execution, and security constraints. The remaining omission of an explicit clone_if_missing definition is minor relative to the total complexity.

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

Parameters4/5

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

Schema coverage is 0%, so the description carries the full burden. It explains sample, version, parent_dir/sample_dir, project_name, and serve_with in detail, but clone_if_missing is only implied by 'when missing' and 'existing checkout stays in place' rather than explicitly named. That keeps it below a perfect score despite strong coverage.

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 and the sample-specific branches identify the resource as UI/demo sample projects (travel, beer, catalog, yelp) and the operations as cloning or writing them. It names some related flows such as travel_golden_path and website_green, but it lacks a single compact high-level verb and a clean sibling distinction.

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

Usage Guidelines4/5

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

It gives per-sample operating guidance and explicit exclusions: bare sample=yelp stays on the multi-agent handoff, extra travel phases stay on travel_golden_path, and the user must not be asked for a password. It still lacks a concise upfront 'use this when' statement or direct comparison with other project-creation tools, leaving the agent to extract guidance from the long branch notes.

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