Zeus Dev Helper

Zeus Dev Helper MCP

コーディングエージェントと人間を、Zeus Client アプリで最初のターンを正常に完了するまでガイドする Stdio MCP サーバーです。

これはデータプレーン MCP ではありません。Explore／Verify の動詞を代行して実行したり、コントラクトハッシュを捏造したり、Hub の管理操作を行ったりすることはありません。最初のスモークテストがすべて成功した後のデータプレーンやマルチエージェントの作業は、引き継ぎのみとなります。

パッケージ	zeus-dev-helper-mcp
レジストリ名	io.github.koten-ai/zeus-dev-helper
トランスポート	stdio
Python	3.11+
MCP SDK	mcp（1.x では FastMCP ／ 2.x では MCPServer）

機能

サーバーは、初回アプリのチェックリストに沿って案内します。前提条件、Zeus 公開 API のライブな準備状況、カタログテンプレート、コントラクトのバインド（スタンプ付きハッシュのコピーのみ）、サーフェス／動詞のガイダンス、設定のリンティング、スモークテストが含まれます。カタログにはライブの Zeus スタンプを使用してください。fetch_chat_request は常にテンプレートのみです。

ツールで適用される主な制約：

• Zeus 公開 API のポート 8080 のみを使用します（アプリの経路で Hub の 9091 を使用することはありません）
• contract_hash を決して捏造しません
• ツールの結果、チェックリストの証跡、サポートパックにシークレットを含めません
• セマンティックキャッシュは無効のままにします

インストール

verify_local_setup と smoke_test_agent は、この Helper プロセス内で zeus_client をインポートします。その環境に agent エクストラをインストールしてください。アプリの .venv ではチェックを満たせません。

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

実行

zeus-dev-helper-mcp
# or
python -m zeus_dev_helper_mcp

ホスト側でソースをチェックアウトせずに済むよう、公開済みのコンソールスクリプト（uvx ／ pip install）を使用してください。

ホストへのインストール

ZEUS_URL をポート 8080 の Zeus 公開 API に設定します（Hub の :9091 は使用しないでください）。実際に使用するリモートホストを優先してください。http://localhost:8080 を使用するのは、MCP ホストと同じマシンで Zeus が動作している場合のみです。

# 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

ユーザーがチャット内で URL やサンプルを指定した場合は、その zeus_url ／バケット／スコープを指定して set_prereq を呼び出してください（古い localhost の既定値を使い続けないでください）。doctor は URL のルーティングについて、保存値と有効値を報告します（ZDM-3 を参照）。

Grok Build

grok mcp add では、-m などのフラグは -- の後に置かない限り、Grok 自身のフラグとして扱われます。uvx の引数は MCP サーバー ID の zeus-dev-helper ではなく、PyPI パッケージの zeus-dev-helper-mcp です。

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

ローカルのチェックアウトで pip install -e ".[dev,agent]" を実行した後、ホストが仮想環境を有効化せずに起動された場合でもサーバーを起動できるよう、command にこのツリーの仮想環境を指定します。

grok mcp add zeus-dev-helper \
  -e ZEUS_URL=http://192.168.0.219:8080 \
  -- "$(pwd)/.venv/bin/python" -m zeus_dev_helper_mcp

同等の設定：

[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

その後、MCP サーバーを更新するか、grok mcp doctor zeus-dev-helper を実行します。

よくある失敗：

• unexpected argument '-m' — Python コマンドの前に -- がありません
• uvx zeus-dev-helper ／ No solution found — パッケージ名が間違っています。uvx --from 'zeus-dev-helper-mcp[agent]' zeus-dev-helper-mcp を使用してください
• No module named 'zeus_client' — この Helper プロセスに agent エクストラがありません。アプリの .venv に kotenai-zeus-client をインストールしても、チェックは失敗したままです。Helper の環境にエクストラをインストールした後、MCP サーバーを再起動してください。
• No module named 'zeus_dev_helper_mcp' ／ python: No such file or directory — ホストが仮想環境を引き継いでいません。上記の .venv/bin/python のパスを使用してください
• No module named 'mcp.server.fastmcp' — mcp 2.x で FastMCP の名前が変更されました。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

プロジェクト内の .cursor/mcp.json を追加（またはマージ）するか、Cursor のグローバル MCP 設定を使用します。

{
  "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

:workspace を継承する権限プロファイルでは、ネットワークは有効になりません。sandbox_approval が false の場合、Codex はネットワークを有効にするかどうか確認しません。そのため、Pip は [Errno -2] Name or service not known を報告します。これは、閉じたネットワークによる EAI_NONAME です。サンドボックスの外では応答するパッケージホストが、サンドボックスの内側では DNS エラーのように見えることがあります。

:workspace を継承し、ネットワークを有効にするトップレベルのプロファイルを設定してください。sandbox_mode または [sandbox_workspace_write] も設定しないでください。変更後、新しい Codex スレッドを開始してください。サンドボックス化されたコマンドでもローカルの Zeus が必要なため、localhost が許可リストに登録されていない限り、ネットワークプロキシはオフのままにしてください。

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"]

ネットワークに接続できるプロセスから、アプリの requirements.txt をインストールしてください。このインストールでは、Helper のインタープリターに zeus_client は追加されません。Helper 環境に agent エクストラを追加した後、MCP サーバーを再起動してください。

その他の stdio ホスト

ホストの MCP stdio エントリーを、同じ環境変数を指定して uvx --from 'zeus-dev-helper-mcp[agent]' zeus-dev-helper-mcp（または agent エクストラを含む venv から実行する python -m zeus_dev_helper_mcp）に設定してください。サンプルの IP を Zeus ホストのものに置き換えてください。

初日向けコーチングの手順

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

チェックリスト全体を出力するのではなく、next_step を優先してください。最初に成功させる方法は 2 通りあります（TravelPlan だけが方法ではありません）。

• 旅行 + LLM（UI のデフォルト）： start_project(sample=travel) → use_sample は、存在しない場合に公開 demo_travel_sample をクローンし（ディレクトリには任意で project_name を指定できます）、DEMO_TRAVEL_SAMPLE_DIR を設定します。このプロセスに LLM_API_KEY、XAI_API_KEY、または OPENAI_API_KEY が設定されるまで、チェックリスト 1.2 は未完了のままです。smoke_test_agent はこの変数を読み取ります。スタンドアロンのクローンでは、SDK 内のフェンス付きパイプラインを run_turn で復元できるよう、kotenai-zeus-client>=2.4.0,<2.5 に固定します。
• ビールカタログ UI： start_project(sample=beer) → use_sample(sample=beer) は、存在しない場合に公開 demo_beer_sample をクローンし、DEMO_BEER_SAMPLE_DIR を設定します。このチェックアウトがアプリです。Python 3.11 以降で起動してください。use_sample の実行文字列では、python3 が 3.11 以降の場合にのみ python3 -m venv を使用します。次に pip install -r requirements.txt と python main.py を実行します（127.0.0.1:8090 にバインドします）。このチェックアウトに Dockerfile と compose ファイルの両方がある場合、use_sample は、どちらかのコマンドを開始する前に、Python と Docker のどちらを使うかユーザーに選択するようエージェントに促します。website_green(serve_with=python|docker) は選択内容を記録します。このヘルパーは Docker を実行しません。この requirements ファイルは PyPI から kotenai-zeus-client>=2.5.3,<2.6 をインストールします。use_sample は .env.example からモード 600 の .env を書き込み、設定済みの値を保持し、テンプレートにある不足キーを追加します。LLM_API_KEY、LLM_BASE_URL、LLM_MODEL をまとめて解決し、ベース URL とモデルがそのプロバイダーに一致する場合に限り、OPENAI_API_KEY または XAI_API_KEY をコピーします。クローンでは LLM_MODEL=grok-4.5-latest が維持されます。run と next_action は、そのファイルに .env.example をコピーするよう指示しません。アプリの .venv が 3.11 より古い場合、website_green は pip を実行しません。検索では旅行と同様、ライブの SCOPE BRIEF と MINI-SCHEMA を catalog.load_for_turn がマージできるよう、chat_request を省略して rt.agent.run_turn を呼び出します。has_llm_key=false の場合でもキーは必須です。アプリの .env に設定してください。config.json の llm.api_key_env は、その変数名のままにしてください。ファイルチェックに合格するまで、verify_local_setup はチェックリスト 3.2 を未完了のままにします。BFF はパイプライン本文を構築しません。demo_travel_sample はクローンしないでください。
• Yelp デモ UI： start_project(sample=demo_yelp) → use_sample(sample=demo_yelp) は、存在しない場合に LocalAI テンプレート demo_yelp をクローンし（発話は yelp-demo / demo_yelp）、DEMO_YELP_SAMPLE_DIR を設定します。parent_dir が設定されている場合、クローンはそのディレクトリ内に作成されます。このチェックアウトがアプリです。これを実行し、置き換え版を作成したり、ビールサンプルをコピーしたりしないでください。use_sample は、公開ビジネス写真セットも frontend/public/business-images/<id>/{1,2,3}.png にダウンロードします（biz: プレフィックスも API キーも不要です）。検索では /api/search に POST し、yelp-demo / _default のライブチャットリクエストをセッション本文として送信します。検索カードはハイブリッド形式の {node, score} ヒットと、ネストされたパイプライン行を展開します。ビジネスページは、ID がバンドルされたカタログにない場合、/api/business/{id} に GET します。レビュー本文はソースドキュメントであり、rev: ドキュメントキーではありません。set_prereq のバケットは yelp-demo、スコープは _default です。demo_travel_sample はクローンしないでください。sample=yelp のみの場合は、従来どおりマルチエージェントへの引き継ぎになります。
• API のみ： ユーザーが API／REST アプリを求めている場合 → start_project(sample=api) → scaffold_app(app_kind=api, coding_language=python)（kotenai-zeus-client を使用した FastAPI の POST /turn）。他の言語はまだスキャフォールディングされていません。
• チャットから取得した認証情報 → プロセス環境変数／gitignore 対象の .env。set_prereq は存在フラグのみを扱います。has_llm_key=true でもキーが設定されていることにはなりません。ユーザーの Zeus URL を set_prereq(zeus_url=…) に渡してください。シークレットを llm.api_key_env に貼り付けないでください。
• 任意の既存リポジトリへの統合は対象外です。

用語集、動詞、ポリシー、カタログモードについては、zeus-helper:// リソースを確認してください。ホストは first_green、smoke_question、support_pack のプロンプトを選択できます。

デフォルトツール（core）

実行時の tools/list が呼び出し仕様です。デフォルトで利用できるのは core ツールセットです（ZEUS_DEV_HELPER_TOOLSETS=core）。

ツール	用途
doctor	ヘルスチェック。detail=health|env|compat|cache|all（env／compat／cache では lint ツールセットのチェックも行います）
start_project	初期化チェックリスト。sample=travel（UI のデフォルト）、sample=beer（カタログ UI、run_turn）、sample=demo_yelp（demo_yelp をクローン）、または sample=api
next_step	現在の項目と、推奨ツールおよびリソースへのリンク
set_prereq	シークレット以外の前提条件を保存します（存在フラグのみ。has_llm_key はキーそのものではありません）
readiness_check	実行時ゲート：healthz／readyz／version、認証、ブートストラップ。URL が設定され、run_turn の経路ではプロセスに LLM キーがある場合に限り、1.2 を完了としてマークします
explain_scope	公開されている :8080 の chat_request.json を実行時に要約します：エンティティ型、表示フィールド、テキスト検索フィールド、FK フィールド、一覧／詳細／検索の動詞。本文に ## MINI-SCHEMA 見出しがない場合は、bootstrap.chat_request を解析します。スタンプの取得に失敗すると、エンティティ型は空になります。fetch_chat_request はテンプレートのみです
scaffold_app	CLI または FastAPI（app_kind=cli|api）の ZeusRuntime アプリを作成します。Python のみ
use_sample	Travel UI のクローン、beer カタログのクローン（demo_beer_sample、python main.py、run_turn、chat_request は省略）、explain_scope の sample=catalog、または Yelp デモのクローン（sample=demo_yelp。DEMO_YELP_SAMPLE_DIR を設定し、API キーなしで公開写真を frontend/public/business-images/<id>/ にダウンロードします。ライブ検索とビジネスページを利用でき、レビュー文はソースドキュメントから取得します）
bind_contract	スタンプ付きの contract.hash のみをコピーします。パスが指定されていない場合、ソースはライブのブートストラップ chat_request です。ディレクトリへのポインターはカタログではありません。空の値／ローカルでの計算は拒否します
recommend_surface	インテント → クライアントのサーフェスと禁止事項リスト
smoke_test_zeus	LLM を使わず、準備状況の確認と読み取り専用の describe を実行します
website_green	カタログページをインストール、起動し、チェックします（名前付きリストカード、ページ ID、Pour が有効な場合は検索）。タイトルケースの doc_key は検索カードではありません。describe の 200 応答はこのチェックに該当しません
smoke_test_agent	クライアントで run_turn を 1 回実行します。このプロセスで [agent] エクストラと、LLM_API_KEY、XAI_API_KEY、OPENAI_API_KEY のいずれかが必要です
diagnose_error	症状、ホップ名、結果キーを、失敗クラスと生成ファイルの変更 1 件に対応付けます
sample_support_pack	beer、travel、または Yelp デモのゲート失敗時に貼り付ける、読み取り専用の情報を出力します。何も書き込まず、Zeus API も呼び出しません。セッション ID は support_pack_from_turn にのみ保持されます

オプトインのツールセット（静的、カンマ区切り）：catalog、lint、travel、support、handoff。all を指定するとすべてのセットが有効になります。when／args／side-effects の全マップは docs/TOOLS.md を参照してください。

リソース（常に有効）：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。

環境

シークレットはプロセス環境に保持されます。set_prereq が保存するのは、存在を示すフラグのみです。ツールの結果では、シークレットの値が伏せられます。

変数	用途
ZEUS_URL	公開 Zeus API のベース URL（ポート 8080）。まずリモートホストを指定し、Zeus がローカルで動作している場合に限り localhost を指定します
ZEUS_BUCKET / ZEUS_SCOPE / ZEUS_COLLECTION	ブートストラップおよび認証プローブのスコープ
ZEUS_MODE	デフォルトのカタログモード（analytics）
ZEUS_AUTH_MODE	認証モード（none、basic、bearer）
ZEUS_USERNAME / ZEUS_PASSWORD	Basic 認証（ログには記録されません）
ZEUS_BEARER_TOKEN	Bearer 認証（ログには記録されません）
LLM_API_KEY / XAI_API_KEY / OPENAI_API_KEY	チェックリスト 1.2、validate_env、smoke_test_agent で使うプロセスキー。Pour / uvicorn には、アプリの .env に同じ名前が必要です。config.json の llm.api_key_env には引き続きその名前を指定します。保存済みの has_llm_key フラグは該当しません
LLM_BASE_URL / LLM_MODEL	OpenAI 互換のエンドポイントとモデル。提示されるデフォルト値は、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、またはユーザーが入力したベース URL です。load_process_login は、パーミッション 600 のファイルから両方の名前を読み込みます
ZEUS_CHAT_REQUEST_DIR	min カタログテンプレートのローカルディレクトリ。list_catalog_modes / fetch_chat_request が公開の zeus_chat_request を見つけるか、クローンしたときに自動設定されます
DEMO_TRAVEL_SAMPLE_DIR	use_sample / travel_golden_path 用のローカルサンプルディレクトリ
DEMO_YELP_SAMPLE_DIR	use_sample(sample=demo_yelp) 用のローカル demo_yelp ディレクトリ
BUSINESS_IMAGES_BASE_URL	yelp 写真のダウンロードに使う任意の CDN プレフィックス（末尾にスラッシュを付けません）。デフォルトは公開の koten-yelp-demo-photos Space です。API キーは不要です
ZEUS_DEV_HELPER_SKIP_YELP_IMAGES	1 に設定すると、use_sample(sample=demo_yelp) 中の yelp 写真のダウンロードをスキップします
YELP_IMAGE_FETCH_WORKERS	その写真セットの並列ダウンロード数。デフォルトは 8 です
ZEUS_DEV_HELPER_STATE_DIR	チェックリスト、前提条件、ローカルメトリクス、書き換え不可のサンプル作成ログ（beer-sample-build.md、travel-sample-build.md、yelp-demo-build.md）、およびサポート記録（beer-sample-support.md、travel-sample-support.md、yelp-demo-support.md）。デフォルトは ~/.config/zeus_dev_helper です
ZEUS_DEV_HELPER_TOOLSETS	静的なツールセット：core（デフォルト）、さらに catalog,lint,travel,support,handoff または all

対象範囲

この MCP	この MCP の対象外
最初の成功までを支援するオンボーディングコーチ	データプレーンの Explore/Verify ツール
準備状況とスモークテストを含むカタログテンプレート	contract_hash の考案やローカルでの計算
Verb の説明 / lint / 下書き（posted=false）	find / search / get / pipeline の POST
調査用のURL テンプレート	Hub のスクレイピングや Hub の管理操作
Multi / データプレーンへの引き継ぎ	マルチエージェントのジョブ実行環境
ローカルのチェックリストとメトリクス	証跡やサポートパックへのシークレットの格納

開発用インストール

ローカルのチェックアウトから実行します：

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,agent]"
export ZEUS_URL=http://localhost:8080

pytest -q

MCP Registry

公式レジストリ名：io.github.koten-ai/zeus-dev-helper。レジストリがホストするのはメタデータのみです。インストールする成果物は PyPI パッケージ zeus-dev-helper-mcp です。

ライセンス

BSD-3-Clause — LICENSE を参照してください。