Zeus Dev Helper

Zeus 开发辅助 MCP

标准输入/输出 MCP 服务，可指导编码 Agent 和用户完成 Zeus Client 应用的首次成功调用。

这不是数据平面 MCP。它不会代替你运行 Explore/Verify 动词、编造合约哈希或执行 Hub 管理操作。首次绿色冒烟测试通过后，数据平面和多 Agent 工作仅通过交接完成。

软件包	zeus-dev-helper-mcp
注册表名称	io.github.koten-ai/zeus-dev-helper
传输方式	标准输入/输出
Python	3.11+
MCP SDK	mcp（1.x 中为 FastMCP / 2.x 中为 MCPServer）

功能

该服务会引导你完成首次应用检查清单：前置条件、Zeus 公共 API 的实时就绪状态、目录模板、合约绑定（仅复制带戳哈希）、界面/动词指导、配置检查和冒烟测试。目录数据优先使用实时 Zeus 戳记。fetch_chat_request 始终仅提供模板。

工具强制执行以下限制：

• 仅使用端口 8080 上的 Zeus 公共 API（应用路径绝不使用 Hub 9091）
• 绝不编造 contract_hash
• 工具结果、检查清单证据或支持包中不得包含机密信息
• 语义缓存保持关闭

安装

verify_local_setup 和 smoke_test_agent 会在此 Helper 进程中导入 zeus_client。请在该环境中安装 agent extra。应用的 .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 设为 Zeus 的公共 API，端口为 8080（绝不使用 Hub :9091）。建议使用你实际使用的远程主机。只有当 Zeus 与 MCP 主机运行在同一台机器上时，才使用 http://localhost:8080。

# 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 或示例，请调用 set_prereq 并传入对应的 zeus_url / bucket / scope（不要保留过时的 localhost 默认值）。doctor 会报告 URL 路由的已存储值与生效值（参见 ZDM-3）。

Grok Build

grok mcp add 会将 -m 等标志视为自身参数，除非这些参数位于 -- 之后。uvx 参数应为 PyPI 软件包 zeus-dev-helper-mcp，而不是 MCP 服务 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

在本地检出代码后，运行 pip install -e ".[dev,agent]"，然后将 command 指向此代码库的 venv，这样即使启动主机时没有激活 venv，主机也能启动服务：

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 extra。在应用的 .venv 中安装 kotenai-zeus-client 仍会导致检查不通过。在 Helper 环境中安装 extra 后，重启 MCP 服务。
• No module named 'zeus_dev_helper_mcp' / python: No such file or directory — 主机未继承 venv；请使用上方的 .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 对话线程。除非 localhost 已加入允许列表，否则请关闭网络代理，因为沙盒化命令仍需要本地 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"]

从已有网络连接的进程安装应用的 requirements.txt。此安装不会将 zeus_client 安装到 Helper 解释器中。Helper 环境添加 agent extra 后，重启 MCP 服务。

其他 stdio 宿主

将宿主的 MCP stdio 入口指向 uvx --from 'zeus-dev-helper-mcp[agent]' zeus-dev-helper-mcp（或者指向已安装 agent extra 的 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，而不是输出完整清单。两条首次成功路径（TravelPlan 并非唯一选择）：

• Travel + 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 会读取该变量。独立克隆的版本固定为 kotenai-zeus-client>=2.4.0,<2.5，以便 run_turn 能在 SDK 内恢复围栏代码块中的 pipeline。
• 啤酒目录 UI：start_project(sample=beer) → use_sample(sample=beer)，如果公共仓库 demo_beer_sample 不存在，则克隆该仓库并设置 DEMO_BEER_SAMPLE_DIR。该工作区就是应用。使用 Python 3.11 或更高版本启动。只有当 python3 为 3.11 或更高版本时，use_sample 的运行字符串才会使用 python3 -m venv。然后运行 pip install -r requirements.txt 和 python main.py（绑定到 127.0.0.1:8090）。如果该工作区同时包含 Dockerfile 和 compose 文件，use_sample 会要求 Agent 在任一命令启动前让用户选择 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 中的 Python 版本低于 3.11，website_green 不会运行 pip。搜索与 Travel 相同：调用 rt.agent.run_turn 时省略 chat_request，以便 catalog.load_for_turn 合并实时 SCOPE BRIEF 和 MINI-SCHEMA。即使 has_llm_key=false，也仍然需要密钥。将其放入应用的 .env。让 config.json 中的 llm.api_key_env 保持为该变量名。只有该文件检查通过后，verify_local_setup 才会关闭检查清单 3.2。BFF 不会构建 pipeline 请求体。不要克隆 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 密钥）。搜索会 POST 到 /api/search，并将 yelp-demo / _default 的实时聊天请求作为会话请求体发送。搜索卡片会解包混合格式的 {node, score} 命中结果以及嵌套的 pipeline 行。若商家 ID 不在内置目录中，商家页面会 GET /api/business/{id}。评论文本是源文档，而不是 rev: 文档键。set_prereq 的 bucket 为 yelp-demo，scope 为 _default。不要克隆 demo_travel_sample。单独使用 sample=yelp 仍会触发多 Agent 交接。
• **仅 API：**用户要求构建 API/REST 应用 → start_project(sample=api) → scaffold_app(app_kind=api, coding_language=python)（在 kotenai-zeus-client 上使用 FastAPI 的 POST /turn）。暂不支持其他语言的脚手架。
• 从聊天中获取的凭据 → 进程环境 / 被 git 忽略的 .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 / 版本、身份验证、引导初始化。仅当 URL 已设置，且在 run_turn 路径上进程具有 LLM 密钥时，才将 1.2 标记为完成
explain_scope	实时公开 :8080 chat_request.json 摘要：实体类型、显示字段、文本搜索字段、外键字段，以及列表/详情/搜索动词。当该主体没有 ## MINI-SCHEMA 标题时，解析 bootstrap.chat_request。标记失败时，实体类型为空。fetch_chat_request 仍仅为模板
scaffold_app	CLI 或 FastAPI（app_kind=cli|api）ZeusRuntime 应用；仅支持 python
use_sample	Travel UI 克隆、啤酒目录克隆（demo_beer_sample、python main.py、run_turn，省略 chat_request）、来自 explain_scope 的 sample=catalog，或 Yelp 演示克隆（sample=demo_yelp，设置 DEMO_YELP_SAMPLE_DIR；将公开照片下载到 frontend/public/business-images/<id>/，无需 API 密钥；提供实时搜索和商家页面，评论文本来自源文档）
bind_contract	仅复制已标记的 contract.hash。未提供路径时，来源为实时引导初始化 chat_request。目录指针不是目录。拒绝空值 / 本地计算
recommend_surface	意图 → 客户端界面 + 禁用项列表
smoke_test_zeus	无 LLM：就绪检查加只读描述
website_green	安装、启动并检查目录页面（命名列表卡片、页面 ID，以及 Pour 启用时的搜索）。标题大小写格式的 doc_key 不是搜索卡片。描述返回 200 不代表通过此检查
smoke_test_agent	一次客户端 run_turn。此进程需要 [agent] 扩展，以及 LLM_API_KEY、XAI_API_KEY 或 OPENAI_API_KEY
diagnose_error	将症状、跳转名称和结果键映射到故障类别及一项生成文件修改
sample_support_pack	只读粘贴内容，用于啤酒、旅行或 Yelp 演示门槛失败。不会写入任何内容，也不会调用 Zeus API。会话 ID 保留在 support_pack_from_turn 中

可选工具集（静态、逗号分隔）：catalog、lint、travel、support、handoff。all 启用所有工具集。完整的启用时机/参数/副作用映射：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 的进程密钥。应用的 .env 需要使用相同名称，供 Pour / uvicorn 使用。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
解释 / lint / 起草动词（posted=false）	POST find / search / get / pipeline
Detective URL 模板	抓取 Hub 或修改 Hub 管理设置
Multi / 数据平面交接	多 Agent 作业运行时
本地清单和指标	在证据或支持包中携带机密信息

开发安装

从本地检出目录：

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

pytest -q

MCP 注册表

官方注册表名称：io.github.koten-ai/zeus-dev-helper。注册表仅托管元数据；安装包是 PyPI 软件包 zeus-dev-helper-mcp。

许可证

BSD-3-Clause — 请参阅 LICENSE。