Mcphero CLI

mcpheroctl

用于与进行交互的CLI工具 MCPHero 平台——通过向导管道创建、管理和部署MCP服务器。

专为人类使用和AI代理工作流程而设计，如下 代理优先CLI 原则：

• 结构化JSON输出到 stdout；人类可读的消息 stderr
• 有记录、有意义的退出代码
• --json 在每个命令上标记脚本/管道集成
• 名词-动词命令语法(mcpheroctl )

______________________________________________________________________

需求

• Python≥3.12
• 紫外线 或 家酿

______________________________________________________________________

安装

通过Homebrew（macOS/Linux）

brew install arterialist/mcpheroctl/mcpheroctl

通过uv工具（跨平台）

uv tool install mcpheroctl

______________________________________________________________________

认证

mcpheroctl使用 组织API令牌 储存于 ~/.config/mcpheroctl/config.json.

mcpheroctl auth login --token 

从获取您的令牌 MCPHero仪表板.

获取令牌

1. 登录到 MCPHero仪表板.
2. 首选 设置 → 组织 → 开发者.
3. 点击 创建API密钥.
4. 复制生成的令牌以供使用 mcpheroctl auth login.

大多数命令还接受可选 --customer-id / CUSTOMER_ID 论证；当使用 org API密钥，客户上下文是自动推断的——只有在跨多个客户使用管理员密钥时才需要传递客户ID。

身份验证命令

______________________________________________________________________

配置

配置存储在 ~/.config/mcpheroctl/config.json:

{
  "api_token": "your-token-here",
  "base_url": "https://api.mcphero.app/api"
}

在登录时覆盖API终结点：

mcpheroctl auth login --token TOKEN --base-url https://staging.mcphero.app/api

______________________________________________________________________

服务器命令

管理已部署的MCP服务器。

mcpheroctl server 

示例

# List servers for your org
mcpheroctl server list

# List for a specific customer (admin key)
mcpheroctl server list 550e8400-e29b-41d4-a716-446655440000

# Get details as JSON (for scripting)
mcpheroctl server get SERVER_ID --json

# Update
mcpheroctl server update SERVER_ID --name "My Weather API" --description "Provides weather data"

# Delete (non-interactive)
mcpheroctl server delete SERVER_ID --yes

# Get API key
mcpheroctl server api-key SERVER_ID --json

______________________________________________________________________

向导命令

向导管道将指导您完成端到端创建新MCP服务器的过程。每一步都对应一个后端操作——后台步骤应通过以下方式轮询 wizard state.

mcpheroctl wizard 

管道概述

  create-session
    → conversation (iterate until is_ready)
    → start
    → list-tools / refine-tools (iterate)
    → submit-tools
    → [suggest-env-vars]
    → list-env-vars / refine-env-vars (iterate)
    → submit-env-vars
    → set-auth
    → generate-code / regenerate-tool-code (iterate)
    → deploy

投票 wizard state SERVER_ID 在异步步骤之间，检查服务器何时准备好执行下一个命令。

______________________________________________________________________

步骤0a：创建会话

# Create a new session (returns server_id)
mcpheroctl wizard create-session

# With explicit customer (admin key)
mcpheroctl wizard create-session --customer-id CUSTOMER_UUID

# JSON output (returns { "server_id": "..." })
mcpheroctl wizard create-session --json

创建新的向导会话并返回 server_id.以前用过这个 conversation 开始收集需求。

______________________________________________________________________

步骤0b：对话

# Chat with the AI to describe your server
mcpheroctl wizard conversation SERVER_ID -m "I want a GitHub integration server"

# Continue refining requirements
mcpheroctl wizard conversation SERVER_ID -m "Add webhook support and remove the delete endpoint"

# JSON output (includes is_ready flag)
mcpheroctl wizard conversation SERVER_ID --message "looks good" --json

迭代地向AI描述您的MCP服务器。响应包括 is_ready 字段--何时 true，AI已经收集了足够的信息，您可以继续 wizard start 如果要求完整。

______________________________________________________________________

第一步：开始

# Transition to tool suggestion (after conversation is_ready)
mcpheroctl wizard start SERVER_ID

# Optionally override the description with a spec file
mcpheroctl wizard start SERVER_ID --spec spec.md

# With additional technical detail files
mcpheroctl wizard start SERVER_ID -d openapi.md -d schema.md

# JSON output
mcpheroctl wizard start SERVER_ID --json

将服务器从需求收集转换为工具建议。服务器必须已完成 conversation 步骤(is_ready=true).技术细节文件(-d)可以包含API模式、端点文档等。

______________________________________________________________________

第二步：工具

# View generated tool suggestions
mcpheroctl wizard list-tools SERVER_ID

# Refine all tools with feedback
mcpheroctl wizard refine-tools SERVER_ID --feedback "Add a search tool and remove the delete tool"

# Refine specific tools only
mcpheroctl wizard refine-tools SERVER_ID -f "Simplify parameters" --tool-id UUID1 --tool-id UUID2

# Submit selected tools to finalize (moves to env vars step)
mcpheroctl wizard submit-tools SERVER_ID --tool-id UUID1 --tool-id UUID2

______________________________________________________________________

步骤3：环境变量

# Trigger LLM suggestion of required env vars
mcpheroctl wizard suggest-env-vars SERVER_ID

# View suggestions
mcpheroctl wizard list-env-vars SERVER_ID

# Refine with feedback
mcpheroctl wizard refine-env-vars SERVER_ID --feedback "Combine DB vars into DATABASE_URL"

# Submit values for each variable (UUID=VALUE format)
mcpheroctl wizard submit-env-vars SERVER_ID \
  --var "API_KEY_UUID=sk-abc123" \
  --var "BASE_URL_UUID=https://api.example.com"

______________________________________________________________________

步骤4：身份验证

# Generate bearer token for the server
mcpheroctl wizard set-auth SERVER_ID --json

______________________________________________________________________

步骤5：代码生成

# Generate code for all tools (async — poll wizard state)
mcpheroctl wizard generate-code SERVER_ID

# Regenerate a single tool (synchronous — returns immediately)
mcpheroctl wizard regenerate-tool-code SERVER_ID TOOL_ID --json

______________________________________________________________________

步骤6：部署

mcpheroctl wizard deploy SERVER_ID

# JSON response contains the live server endpoint URL
mcpheroctl wizard deploy SERVER_ID --json

______________________________________________________________________

州民意调查

轮询状态以等待后台操作完成：

mcpheroctl wizard state SERVER_ID --json

有用状态： pending, generating_tools, tools_ready, generating_code, code_ready, deploying, deployed, error.

______________________________________________________________________

脚本和代理使用

所有命令支持 --json 用于结构化输出。与…结合 jq 或任何JSON工具：

# Create a session and get the server ID
SERVER_ID=$(mcpheroctl wizard create-session --json | jq -r '.server_id')

# Chat until the AI is ready and the requirements are complete
while true; do
  RESP=$(mcpheroctl wizard conversation "$SERVER_ID" -m "I want a weather API server" --json)
  echo "$RESP" | jq -r '.content'
  IS_READY=$(echo "$RESP" | jq -r '.is_ready')
  [ "$IS_READY" = "true" ] && break
done

# Transition to tool suggestion
mcpheroctl wizard start "$SERVER_ID" --json

# List tool IDs
TOOL_IDS=$(mcpheroctl wizard list-tools "$SERVER_ID" --json | jq -r '.[].id')

# Submit all suggested tools
mcpheroctl wizard submit-tools "$SERVER_ID" \
  $(echo "$TOOL_IDS" | xargs -I{} echo "--tool-id {}")

# Poll until state is ready
while true; do
  STATE=$(mcpheroctl wizard state "$SERVER_ID" --json | jq -r '.status')
  echo "State: $STATE"
  [ "$STATE" = "tools_ready" ] && break
  sleep 3
done

______________________________________________________________________

退出代码

______________________________________________________________________

错误输出

当 --json 传递后，错误将以结构化JSON形式发送到 stdout:

{
  "error": "not_found",
  "message": "Server not found",
  "status_code": 404
}

没有 --json，错误将打印到 stderr 带着一个 ✖ 前缀。

______________________________________________________________________

项目结构

src/mcpheroctl/
├── cli.py               # Main entrypoint — registers auth/server/wizard
├── commands/
│   ├── auth.py          # login, status, logout
│   ├── server.py        # list, get, update, delete, api-key
│   └── wizard.py        # Full wizard pipeline + conversation stub
└── core/
    ├── config.py        # Config storage (~/.config/mcpheroctl/config.json)
    ├── output.py        # JSON/stderr output helpers, exit codes
    └── client.py        # httpx HTTP client with tenacity retries

______________________________________________________________________

发展

# Install in editable mode
uv sync

# Run CLI directly
uv run mcpheroctl --help

# Format / lint
uv run ruff format .
uv run ruff check .

# Type check
uv run basedpyright

______________________________________________________________________

依赖项

______________________________________________________________________

许可证

Apache 2.0——请参阅 许可证.