ai-cli-mcp

AI CLI MCP Server

🇯🇵 日语版 README 请见此处

📦 软件包迁移通知：此软件包之前名为 @mkxultra/claude-code-mcp，现已更名为 ai-cli-mcp，以体现其对多种 AI CLI 工具的扩展支持。

一个 MCP（Model Context Protocol）服务，可在后台进程中运行 AI CLI 工具（Claude、Codex、Gemini、OpenCode、Grok 和 Pi），并自动处理权限。

你是否发现 Cursor 有时难以处理复杂的多步骤编辑或操作？此服务提供强大的统一 run 工具，可让多个 AI Agent 更有效地处理你的编码任务。

演示

概述

此 MCP 服务提供可供大模型使用的工具，以便与 AI CLI 工具交互。集成到 MCP 客户端后，它可让大模型：

• 绕过所有权限运行 Claude CLI（使用 --dangerously-skip-permissions）
• 绕过审批和沙盒运行 Codex CLI（使用 --dangerously-bypass-approvals-and-sandbox）
• 通过 Antigravity CLI 运行 Gemini 模型（agy --print、stream-json 和 --dangerously-skip-permissions）
• 以无头模式运行 Grok Build CLI，使用 streaming-messages-json，自动批准工具调用，并禁用自动更新
• 以非交互式 JSON 模式运行 OpenCode（使用 opencode run --format json --dir <workFolder> <prompt>）
• 以非交互式 JSON 模式运行 Pi，并启用工具审批，以便无人值守运行
• 支持多种 AI 模型：Claude（sonnet、sonnet[1m]、opus、opusplan、fable、haiku）、Codex（gpt-6-astra、gpt-6.1-sol、gpt-6-sol、gpt-6-luna、gpt-5.4、gpt-5.6-sol、gpt-5.6-terra、gpt-5.6-luna、gpt-5.5、gpt-5.4-mini、gpt-5.3-codex、gpt-5.3-codex-spark、gpt-5.2）、Gemini（gemini-3.8-flash-high/medium/low、gemini-3.7-flash-high/medium/low、gemini-3.6-flash-high/medium/low、gemini-3.1-pro-high/low）、Grok（grok、grok-4.6、grok-4.5）、OpenCode（opencode 以及 oc-<provider/model>）和 Pi（pi 以及 pi-<provider/model>）
• 通过 PID 跟踪管理后台进程
• 解析并返回来自两种工具的结构化输出

使用示例（高级并行处理）

你可以像这样指示主 Agent 并行执行多个任务：

使用 acm mcp run 为以下 3 项任务启动 Agent：

1. 使用 sonnet 重构 src/backend 代码
2. 使用 gpt-5.3-codex 为 src/frontend 创建单元测试
3. 使用 gemini-3.1-pro-high 更新 docs/ 中的文档

在它们运行期间，请更新 TODO 列表。完成后，使用 wait 工具等待所有任务完成，并汇总报告结果。

使用示例（上下文缓存与共享）

运行多个任务时，你可以使用会话 ID 重用大型代码库等大量上下文，以节省成本。

1. 首先，使用 opus 运行 acm mcp run，读取 src/ 中的所有文件并了解项目结构。
2. 使用 wait 工具等待任务完成，并从结果中获取 session_id。
3. 使用该 session_id，通过 acm mcp run 并行运行以下两项任务：
   • 使用 sonnet 为 src/utils 提出重构方案
   • 使用 gpt-5.3-codex 为 README.md 添加架构文档
4. 最后，再次使用 wait，汇总两项任务的结果。

优势

• 真正的异步多任务处理：Agent 在后台执行，并立即返回控制权。调用方 AI 可以继续执行下一个任务，或调用其他 Agent，而无需等待任务完成。
• CLI 中的 CLI（Agent 中的 Agent）：可从任何支持 MCP 的 IDE 或 CLI 直接调用 Claude Code 或 Codex 等强大的 CLI 工具。这能突破宿主环境的限制，执行范围更广、复杂度更高的系统操作和自动化任务。
• 不受模型和提供商限制：可自由选择并组合 Claude、Codex（GPT）、Gemini、OpenCode、Grok 和 Pi 中“最强”或“最具性价比”的模型，而不受特定生态系统限制。

前置条件

唯一的前置条件是：你想使用的 AI CLI 工具已在本地安装并正确配置。

• Claude Code：claude doctor 检查通过，并且已获准使用 --dangerously-skip-permissions 执行（你必须手动运行一次，以登录并接受条款）。
• Codex CLI（可选）：已安装并完成初始设置（登录等）。
• Antigravity CLI（可选，用于 Gemini 模型）：安装 agy 并登录一次；已使用 1.2.5 进行测试。请参阅下文的迁移说明。
• Grok Build CLI（可选）：在本地安装并验证 Grok（已使用 1.0.13 和 OAuth 进行测试）。发现程序会先检查 ~/.grok/bin/grok，然后检查 PATH；GROK_CLI_NAME 可通过命令名称或绝对路径覆盖这两者。
• OpenCode（可选）：已安装并配置。此集成使用 opencode run --format json，显式选择提供商和模型时，需遵循 ai-cli models 提供的 oc-<provider/model> 包装语法。
• Pi（可选）：在本地安装并验证 Pi（已使用 0.86.1 进行测试）。运行 pi --list-models 可查看你的账户可用的提供商/模型组合。PI_CLI_NAME 可覆盖二进制文件名称或路径。

安装与使用

用于 Gemini 模型的 Antigravity CLI

Gemini 后端使用 Google 的 Antigravity CLI（agy，已使用 1.2.5 进行测试）。在 macOS/Linux 上：

curl -fsSL https://antigravity.google/cli/install.sh | bash
~/.local/bin/agy  # Sign in once interactively
agy models
ai-cli run --cwd /path/to/project --model gemini-ultra --prompt "Review this project"

在 Windows 上，请遵循官方 PowerShell 说明。发现程序会先在 macOS/Linux 上检查 ~/.local/bin/agy，或在 Windows 上检查 %LOCALAPPDATA%/agy/bin/agy.exe，然后检查 PATH。设置 ANTIGRAVITY_CLI_NAME 可覆盖此路径。

在 doctor、models 和进程结果中，后端键仍为 gemini。内置的 gemini-ultra 会选择 gemini-3.8-flash-high。使用 ai-cli alias add 更新指向旧 Gemini CLI 名称的自定义别名；agy models 会列出你的账户可用的名称。提供的 reasoning_effort 必须与模型后缀匹配（例如，gemini-3.8-flash-medium 对应 medium）。其他 Antigravity 模型系列不会通过此后端路由。

peek 会读取增量助手文本以及可选的工具启动/完成事件。get_result/ai-cli result 会返回最终响应，并将 Antigravity 的 conversation_id 暴露为 session_id；将其传递给下一次运行，即可通过 --conversation 继续会话。不支持解析旧版 Gemini CLI 输出或恢复会话。

此集成默认将 Antigravity 的运行时限设为两小时（2h）。在 ai-cli 或 MCP 服务的运行环境中设置 ANTIGRAVITY_PRINT_TIMEOUT=1h（或其他正时长）即可覆盖此值。Antigravity 中的 0 表示立即超时。ACM wait(timeout: 0) 只会移除等待时限，不会更改这一独立的运行时限。

现在有两种主要方式可以使用此软件包：

• ai-cli-mcp：MCP 服务入口
• ai-cli：面向用户的后台 AI 运行 CLI

使用 npx 的 MCP 用法

推荐通过 npx 使用 MCP 服务。

在 MCP 配置中使用 npx：

    "ai-cli-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "ai-cli-mcp@latest"
      ]
    },

使用 Claude CLI mcp add 命令：

claude mcp add ai-cli '{"name":"ai-cli","command":"npx","args":["-y","ai-cli-mcp@latest"]}'

全局安装后的用户 CLI 用法

如果你想直接在 Shell 中使用生产版 CLI，请全局安装此软件包：

npm install -g ai-cli-mcp

这会提供以下两个命令：

• ai-cli
• ai-cli-mcp

示例：

ai-cli doctor
ai-cli models
ai-cli run --cwd "$PWD" --model sonnet --prompt "summarize this repository"
ai-cli run --cwd "$PWD" --model opencode --prompt "summarize this repository with OpenCode defaults"
ai-cli run --cwd "$PWD" --model oc-openai/gpt-5.4 --session-id ses_123 --prompt "continue this session with an explicit OpenCode model"
ai-cli run --cwd "$PWD" --model pi-openai-codex/gpt-6-astra --reasoning-effort high --prompt "review this repository with Pi"
ai-cli ps
ai-cli result 12345
ai-cli result 12345 --verbose
ai-cli peek 12345 --time 10
ai-cli wait 12345 --timeout 300
ai-cli wait 12345 --timeout 0
ai-cli wait 12345 --verbose
ai-cli kill 12345
ai-cli cleanup
ai-cli-mcp

使用 npx 运行 CLI

由于已发布的软件包名称仍为 ai-cli-mcp，CLI 最简的 npx 命令形式为：

npx -y --package ai-cli-mcp@latest ai-cli run --cwd "$PWD" --model sonnet --prompt "hello"
npx -y --package ai-cli-mcp@latest ai-cli run --cwd "$PWD" --model oc-openai/gpt-5.4 --prompt "hello from OpenCode"

首次设置的重要事项

Forge CLI 支持已移除。models 和 doctor 不再包含 Forge，且 model: "forge" 会被拒绝。在用户配置中，移除指向 forge 的别名，或将其目标更改为受支持的模型。不再使用 FORGE_CLI_NAME。

对于 Claude CLI：

MCP 服务要使用 Claude，你必须先手动运行一次 Claude CLI，并添加 --dangerously-skip-permissions 标志，然后登录并接受条款。

npm install -g @anthropic-ai/claude-code
claude --dangerously-skip-permissions

按照提示接受条款。完成后，MCP 服务便可以在非交互模式下使用该标志。

对于 Codex CLI：

对于 Codex，请确保你已登录并接受任何必要的条款：

codex login

对于 Antigravity CLI（Gemini）：

先以交互方式启动一次 Antigravity 以登录：

agy

macOS 可能会在这些工具首次运行时请求文件夹权限。如果首次运行失败，后续运行应该可以正常工作。

CLI 命令

ai-cli 目前支持：

• run
• ps
• result
• peek
• wait
• kill
• cleanup
• doctor
• models
• alias list / alias add / alias rm
• mcp

示例流程：

ai-cli doctor
ai-cli models
ai-cli run --cwd "$PWD" --model gpt-5.4 --prompt "use the default Codex model"
ai-cli run --cwd "$PWD" --model codex-ultra --prompt "fix failing tests"
ai-cli run --cwd "$PWD" --model opencode --session-id ses_existing --prompt "continue this OpenCode session"
ai-cli run --cwd "$PWD" --model oc-openai/gpt-5.4 --prompt "run with an explicit OpenCode backend model"
ai-cli run --cwd "$PWD" --model pi --prompt "run with Pi's configured default model"
ai-cli run --cwd "$PWD" --model pi-openai-codex/gpt-6-astra --reasoning-effort xhigh --prompt "run Pi with an explicit model"
ai-cli ps
ai-cli peek 12345 --time 10
ai-cli peek 12345 12346 --time 10
ai-cli wait 12345
ai-cli wait 12345 --verbose
ai-cli result 12345
ai-cli result 12345 --verbose
ai-cli cleanup

run 将 --cwd 作为主要工作目录标志，并且为保持兼容性，也接受旧别名 --workFolder / --work-folder。

OpenCode 模型选择支持以下两种形式：

• opencode 表示 CLI 中配置的默认模型
• oc-<provider/model> 表示明确指定的 OpenCode 提供商/模型，例如 oc-openai/gpt-5.4

ai-cli models 会运行 opencode models，并在 opencode 数组中返回 opencode 以及发现的名称，例如 oc-openai/gpt-6-astra。每个名称都可以直接传递给 run。发现状态和错误可在 dynamicModelBackends.opencode.discovery 中查看。

Codex 模型选择使用 gpt-5.4 作为默认公布的模型。选择 gpt-6.1-sol 可使用最新的 Sol 模型，选择 gpt-6-sol 可使用上一代 Sol 模型，选择 gpt-6-luna 可使用 Luna。这三个模型均接受 low、medium、high、xhigh 和 max 推理强度；两个 Sol 模型还可通过 Codex CLI 使用 ultra。省略推理强度时将使用 CLI 默认值。例如：ai-cli run --cwd "$PWD" --model gpt-6.1-sol --reasoning-effort ultra --prompt "Review this project"。

doctor 仅检查二进制文件是否可用以及路径解析情况。其 JSON 输出包含一个 checks 区块，其中登录状态和条款接受情况均标记为未检查。

Pi CLI

在启动 ai-cli 或 MCP 服务之前，请先安装 Pi 并登录一次。此集成已通过 Pi 0.86.1 验证。

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
pi                    # use /login if authentication is not configured
pi --list-models

使用 pi 让 Pi 选择其配置的默认模型。使用 pi-<provider/model> 指定模型，例如 pi-openai-codex/gpt-6-astra。ai-cli models 会运行 pi --list-models，并在其 pi 数组中包含这些名称（名称位于 pi 之后）。dynamicModelBackends.pi.discovery 会报告发现状态；reasoningEfforts.pi 列出 off、minimal、low、medium、high、xhigh 和 max。省略 reasoning_effort 时，由 Pi 决定。

ai-cli run --cwd "$PWD" --model pi --prompt "Explain this project"
ai-cli run --cwd "$PWD" --model pi-openai-codex/gpt-6-astra --reasoning-effort xhigh --prompt "Review this change"
ai-cli alias add pi-coding pi-openai-codex/gpt-5.6-terra --effort high
ai-cli run --cwd "$PWD" --model pi-coding --session-id <session_id> --prompt "Continue"

运行时会执行 pi --mode json --approve，可选传入 --model、--thinking 和 --session，然后跟上 -p -- <prompt>。--approve 标志允许 Pi 加载项目资源并执行其配置的工具，无需交互确认。现有的 workFolder 和进程隔离规则仍然适用。

peek 会累积 Pi 的 text_delta 事件，并可选择报告标准化后的 tool_execution_start / tool_execution_end 事件。思考增量、工具更新和原始工具输出均不包含在内。get_result 和 wait 会返回最终文本、提供商、模型、用量、停止原因和 Pi 会话 ID。将该 ID 传入下一次运行，即可通过 --session 恢复同一会话。详细结果包含完整的工具历史记录；精简结果则不包含。运行失败时会保留诊断性 stderr；取消操作使用与 Grok 和 Antigravity 相同的进程树终止机制。

Grok Build CLI

有关身份验证和 CLI 设置，请参阅 Grok 无头模式指南。

如果没有名为 grok 的用户别名，MCP 和 ai-cli 都会将 grok 和原生 grok-* 名称路由到 Grok。grok 会省略 --model，使用 Grok CLI 配置；显式指定名称则会选择对应模型。models 包含 grok: ["grok", "grok-4.6", "grok-4.5"] 和 reasoningEfforts.grok 中接受的级别。其他原生名称会被转发，并进行常见的 low/medium/high 工作量验证；模型是否可用由 Grok 决定。

ai-cli run --cwd "$PWD" --model grok --prompt "Explain this project"
ai-cli run --cwd "$PWD" --model grok-4.6 --reasoning-effort xhigh --prompt "Review this change"
ai-cli alias add grok-coding grok-4.6 --effort high
ai-cli run --cwd "$PWD" --model grok-coding --session-id <session_id> --prompt "Continue"

已存在的名为 grok 的用户别名仍具有优先权，包括指向 OpenCode 的别名。它仍会显示在 models 和 alias list 中，且不会影响无关的运行或 MCP 工具发现。显式指定 grok-4.6 / grok-4.5 始终会选择原生后端。若要使用 CLI 配置的提供方默认值，请重命名该别名，或显式执行 ai-cli alias rm grok 将其删除；升级绝不会修改你的配置。

同一别名以及 model、reasoning_effort 和 session_id 字段也适用于 MCP run。别名使用现有的用户配置。未提供工作量时，由 Grok 决定工作量。提供方键 grok 接受 low/medium/high；要使用 xhigh，请显式选择 grok-4.6。grok-4.5 接受 low/medium/high。两者都不接受 max 或 ultra。

命令使用 grok --single=<prompt> --cwd <workFolder> --output-format streaming-messages-json --always-approve --no-auto-update，并可选指定模型、工作量和 --resume=<session_id>。附加的值会保留开头的连字符和换行符。在 ai-cli 界面中，对于以 -- 开头的值，请使用 --prompt="--text" / --session-id="--id"，或使用提示词文件。这遵循现有的无人值守工具审批策略。使用前请先通过 Grok 进行身份验证；doctor.grok 只检查二进制文件的发现情况。即使 OAuth 无头模式执行正常，Grok 1.0.13 的 models 命令仍可能显示未经身份验证的横幅，因此不会将该横幅用作身份验证测试。

peek 会在调用期间观察完整的助手消息，以及可选的规范化工具启动/完成事件。不包含思考内容、令牌增量和原始工具输出。get_result 和 wait 会返回最终答案和会话 ID，或在运行期间返回可用的助手文本。如果存在，则会保留 Grok 模型/用量/成本元数据，以及终止状态 is_error、subtype、errors 和 stop_reason。失败时也会保留诊断信息 stderr，包括已有部分答案的情况。详细结果包含详细工具信息。kill/kill_process 会终止受跟踪的进程及其工具子进程；POSIX 取消操作使用 ps 和信号，Windows 使用 taskkill /t /f。如果 ps 不可用，仍会向受跟踪的 PID 及其所属进程组发送信号，验证进程是否退出，并在需要时升级为 SIGKILL；kill 响应和失败时的 stderr 会警告其他进程组中的子进程可能仍会存活。MCP 主机在收到 SIGINT/SIGTERM/SIGHUP 或 stdin/传输关闭时，会停止受跟踪的工作。进程组信号只会针对为受跟踪工作创建的进程组，绝不会针对 MCP 主机进程组。

在 MCP 取消期间，Grok 根进程可能会报告 failed/143，而其工具子进程仍在停止。并发的 kill_process 调用和主机关闭操作会等待同一进程树终止；cleanup_processes 会保留条目，直到该操作完成。如果第一次信号发送前就失败，则会返回错误；之后若自然完成，会保留其实际状态和退出代码。

用户模型别名

将模型及其默认推理工作量保存为一个名称，以便在不同项目中使用。CLI 和 MCP 共用相同的用户配置。

通过 CLI 管理和使用别名

内置别名 sol 和 luna 分别指向 gpt-6.1-sol 和 gpt-6-luna。它们不会设置推理强度：省略 --reasoning-effort 可使用 Codex CLI 默认值，也可以为单次运行指定该参数。例如，ai-cli run --cwd "$PWD" --model sol --prompt "Review this project"。同名的用户别名会覆盖这些默认值；通过 ai-cli alias rm sol 移除用户覆盖后，将恢复内置目标。

ai-cli alias add codex-coding gpt-5.6-terra --effort xhigh
ai-cli alias add claude-review opus --effort max
ai-cli alias list
ai-cli run --cwd "$PWD" --model codex-coding --prompt "fix failing tests"

这里，codex-coding 使用 xhigh 推理强度运行 gpt-5.6-terra。使用 --reasoning-effort low 可为单次运行覆盖推理强度。

alias list 会输出 JSON，其中包含 configPath 和一个 aliases 数组，列出当前生效的内置别名和用户别名。每个条目包含 name、resolvesTo、agent，以及可选的 defaultReasoningEffort，与 ai-cli models 中的别名一致。列出别名不会创建或修改配置文件。使用 ai-cli models 还可查看支持的模型目录。

alias add <name> <model> [--effort <level>] 会在需要时创建配置文件及其父目录，包括显式指定的 AI_CLI_CONFIG_PATH。重复使用名称会替换其定义；省略 --effort 会清除别名之前设置的推理强度。也接受 --reasoning-effort 和 --reasoning_effort。无效定义不会更改文件。

# Update the default effort
ai-cli alias add codex-coding gpt-5.6-terra --effort high
# Clear the alias effort and use the target CLI's default
ai-cli alias add codex-coding gpt-5.6-terra
# Remove the user alias
ai-cli alias rm codex-coding

alias rm <name> 只会移除用户定义。移除 codex-ultra 之类的覆盖后，将恢复内置默认值。移除未知名称，或移除没有用户覆盖的内置别名，都会返回错误。命令成功后会输出包含配置路径和所做更改的 JSON。使用 ai-cli alias --help 查看用法。

# Override a built-in alias
ai-cli alias add codex-ultra gpt-5.6-terra --effort xhigh
# Restore its built-in gpt-6-astra / ultra definition
ai-cli alias rm codex-ultra

通过 MCP 使用别名

按上述方式注册 codex-coding 后，将其名称传递给 MCP run 工具：

{
  "workFolder": "/absolute/path/to/project",
  "model": "codex-coding",
  "prompt": "fix failing tests"
}

添加 "reasoning_effort": "low" 可覆盖该请求的推理强度。ai-cli models 和 MCP models 工具会将当前生效的别名作为 aliases 条目公开，其中包含 name、resolvesTo、agent，以及可选的 defaultReasoningEffort 字段。

每次 run、models 和 MCP 工具列表请求都会读取配置。只要 CLI 和 MCP 使用相同的配置路径，配置更改就会应用于后续请求，无需重启 MCP 服务。

配置文件和规则

以上命令会编辑 ~/.config/ai-cli/config.json。你也可以直接编辑该文件；例如，以下文件定义了第一个示例中的两个别名：

{
  "model_aliases": {
    "codex-coding": {
      "model": "gpt-5.6-terra",
      "reasoning_effort": "xhigh"
    },
    "claude-review": {
      "model": "opus",
      "reasoning_effort": "max"
    }
  }
}

• model 为必填项；reasoning_effort 为可选项。后端根据目标模型选择，与别名名称无关。
• 努力程度的优先级依次为：显式运行参数 → 别名默认值 → 目标 CLI 默认值。目标模型必须支持该努力程度；Antigravity 的努力程度必须与模型后缀相匹配；OpenCode 别名必须省略该项。
• 用户条目可以覆盖内置别名，例如 codex-ultra。每个条目都会替换整个定义；若省略 reasoning_effort，则使用目标 CLI 的默认值，而不是继承内置努力程度。
• 目标必须是原生模型名称，例如 gpt-5.6-terra、opus 或 oc-openai/gpt-5.4；不支持别名链式引用。别名名称区分大小写，必须以 ASCII 字母开头，且只能包含 ASCII 字母、数字、_ 或 -。已列出的原生模型名称、codex 和 oc- 前缀均为保留项，但为保持兼容性，名为 grok 的用户别名仍具有优先权。
• 默认配置文件缺失时会保留内置行为。格式错误的文件以及无效的模型/努力程度组合会报错，并显示配置路径。显式指定的文件若不存在也会报错，但 alias add 可以创建该文件。

若 XDG_CONFIG_HOME 为绝对路径，默认位置会改为 $XDG_CONFIG_HOME/ai-cli/config.json。AI_CLI_CONFIG_PATH 会完全覆盖该位置；相对路径从 CLI/MCP 进程的工作目录解析。若要使用 MCP 专属路径，请在服务的 env 设置中配置 AI_CLI_CONFIG_PATH。不会查找项目级配置。该文件使用不带注释的 JSON，目前仅支持 model_aliases。

CLI 状态存储

后台 CLI 运行记录存储在：

~/.local/state/ai-cli/cwds/<normalized-cwd>/<pid>/

每个 PID 目录包含：

• meta.json
• stdout.log
• stderr.log
• 分离运行时的 exit-status.json

使用 ai-cli cleanup 删除已完成和失败的运行记录。正在运行的进程会保留。

退出状态跟踪

分离运行的 ai-cli 会通过 exit-status.json 为所有受支持的后端持久化自然退出状态。非零退出会记录为 failed，并显示记录的 exitCode；零退出会记录为 completed，且 exitCode: 0。ai-cli kill 会将 SIGTERM 终止记录为失败退出；若受跟踪的进程消失且没有退出元数据，则会将其视为 failed，而不会假定其成功。

连接到 MCP 客户端

设置好服务后，将配置添加到 MCP 客户端的设置文件中（例如 Cursor 的 mcp.json、Windsurf 的 mcp_config.json）。

如果文件不存在，请创建该文件并添加 ai-cli-mcp 配置。

提供的工具

此服务提供以下工具：

run

使用 Claude CLI、Codex CLI、Antigravity CLI（Gemini）、OpenCode、Grok 或 Pi 执行提示词。系统会根据模型名称自动选择相应的 CLI。

参数：

• prompt（字符串，可选）：要发送给 AI Agent 的提示词。必须提供 prompt 或 prompt_file。
• prompt_file（字符串，可选）：包含提示词的文件路径。必须提供 prompt 或 prompt_file。可以是绝对路径，也可以是相对于 workFolder 的路径。
• workFolder（字符串，必填）：CLI 执行时使用的工作目录。必须是绝对路径。 模型：
• Ultra 别名（内置默认值；用户配置可覆盖）： claude-ultra（opus，默认使用最大推理力度且不会选择 Fable）、codex-ultra（gpt-6-astra，默认使用 ultra 推理力度）、gemini-ultra
• Claude：sonnet、sonnet[1m]、opus、opusplan、fable、haiku
  • fable 会明确选择 Claude Code 的最新 Fable 模型。Fable 可能需要单独计费的使用额度，且内置的 claude-ultra 默认值不会选择它。
• Codex：gpt-6-astra、gpt-6.1-sol、gpt-6-sol、gpt-6-luna、gpt-5.4、gpt-5.6-sol、gpt-5.6-terra、gpt-5.6-luna、gpt-5.5、gpt-5.4-mini、gpt-5.3-codex、gpt-5.3-codex-spark、gpt-5.2
• Gemini：gemini-3.8-flash-high、gemini-3.8-flash-medium、gemini-3.8-flash-low、Gemini 3.7/3.6 Flash 变体、gemini-3.1-pro-high、gemini-3.1-pro-low
• Grok：grok 表示其配置的默认模型，grok-4.6、grok-4.5 以及其他原生 grok-* 名称
• OpenCode：opencode 表示配置的默认后端模型，也可使用 oc-openai/gpt-5.4 等显式包装器
• Pi：pi 表示配置的默认模型，也可使用 pi-openai-codex/gpt-6-astra 等显式包装器
• reasoning_effort（字符串，可选）：用于控制 Claude、Codex、Grok 和 Pi 的推理力度。Pi 会将 off|minimal|low|medium|high|xhigh|max 映射为 --thinking。Grok 使用 --reasoning-effort：grok-4.6 支持 low/medium/high/xhigh；grok-4.5、配置的 grok 默认模型以及其他原生 Grok 名称支持 low/medium/high。省略推理力度时使用 CLI 默认值；Grok 不接受 max/ultra。Claude 使用 --effort（允许值："low"、"medium"、"high"、"xhigh"、"max"）。Codex 使用 model_reasoning_effort（基础级别："low"、"medium"、"high"、"xhigh"；GPT-6.1 Sol、GPT-6 Astra/Sol 和 GPT-5.6 Sol/Terra 还支持 "max" 和 "ultra"，而 GPT-6 Luna 和 GPT-5.6 Luna 支持 "max"）。Antigravity 接受 --effort low|medium|high；如果模型名称中带有后缀，则该值必须与后缀一致。OpenCode 不支持 reasoning_effort。
• session_id（字符串，可选）：用于恢复先前会话的可选会话 ID。Claude、Codex、Gemini、OpenCode、Grok 和 Pi 均支持此参数。Grok 通过 --resume 恢复；OpenCode 和 Pi 通过 --session 原位恢复，也可以与显式模型选择结合使用。

wait

等待多个 AI Agent 进程完成，并返回它们的合并结果。此工具会阻塞，直到所有指定的 PID 都已结束或发生超时。

将 timeout 设为 0，即可等待所有指定进程完成，不受 ai-cli 截止时间限制。例如，使用 { "pids": [12345], "timeout": 0 } 调用 MCP wait，或使用 ai-cli wait 12345 --timeout 0。MCP 客户端或传输超时仍会独立生效。等待超时设为有限值时会返回错误，但进程仍会继续运行。

默认情况下，每个返回的结果项都使用与 get_result(verbose: false) 相同的紧凑结构：操作字段（如 pid、agent、status、exitCode、model）、解析后的输出（如 agentOutput），以及可用时顶层的 session_id。将 verbose: true 设为 true，即可包含完整元数据，如 startTime、workFolder、prompt，以及详细的解析后输出，如 agentOutput.tools。

参数：

• pids（数字数组，必需）：要等待的进程 ID 列表（由 run 工具返回）。
• timeout（数字，可选）：非负的最长等待时间，单位为秒。默认为 180（3 分钟）；设为 0 可禁用等待超时。
• verbose（布尔值，可选）：若为 true，每个结果项都使用完整结果结构。默认为 false。

peek

为正在运行的子 Agent 启动一次短暂的观察窗口，并返回该次调用期间观察到的结构化事件。默认仅包含自然语言消息事件；传入 include_tool_calls 或 --include-tool-calls 还可包含规范化的工具调用事件。它不是历史记录 API，不提供无间隙的流式传输，也不会追踪 shell 标准输出／标准错误的末尾内容。不同的 peek 调用可能会遗漏调用间发出的事件；v1 有意不包含 --follow。

CLI v1：

ai-cli peek 123 --time 10
ai-cli peek 123 456 --time 10
ai-cli peek 123 --time 10 --include-tool-calls

参数：

• pids（数字数组，必填）：由 run 返回的 1～32 个进程 ID。服务端会对重复的 PID 去重，并保留首次出现的顺序。未知或未受管理的 PID 会按进程返回 not_found，不会导致整个调用失败。
• peek_time_sec（数字，可选）：正整数，表示观察时长，单位为秒。默认值为 10，上限为 60。0、负数和小数均无效。
• include_tool_calls（布尔值，可选）：设为 true 时，每个进程的 events 数组除消息事件外还会包含规范化的 tool_call 事件。默认值为 false。

观察与筛选：

• peek_started_at 和 events[].ts 是 ai-cli-mcp 服务端的 UTC RFC3339 时间戳。peek_started_at 表示验证并注册监听器后观察窗口开始的时间；events[].ts 表示 ai-cli-mcp 观察并接受事件的时间。
• 观察窗口会在 peek_time_sec 到期或所有目标进程进入终止状态时结束，以先发生者为准。
• 窗口开始前发出的事件不会返回。允许对同一 PID 并发调用 peek；每次调用都有独立的观察窗口，因此可能返回重叠的事件。
• 消息事件包括：Codex 的 agent_message 文本、Claude 和 Grok 的完整助手文本内容、part.type 为 "text" 的 OpenCode type: "text" 事件、Antigravity 的 step_update 事件，以及 Pi 的 text_delta 事件。
• 包含工具调用时，tool_call 事件会对 Codex 命令／MCP 调用、Claude／Grok 工具使用及结果、Antigravity 工具步骤、OpenCode 工具使用，以及 Pi 工具执行开始／结束事件进行规范化。工具摘要是根据工具名称和输入元数据生成的单行字符串，且长度有限。不包含原始工具和命令输出。
• 默认拒绝未知事件格式。对于不支持提取事件的受管理 Agent，会返回其实际进程状态，并将 events 设为 []、truncated 设为 false、error 设为 null。
• 每个 PID 最多保留观察窗口内最先观察到的 50 个事件。如果之后的事件被丢弃，truncated 为 true。
• status 的值为 running、completed、failed 或 not_found，表示观察窗口关闭时的状态。
• agent 的值为 claude、codex、gemini、opencode、grok、pi、未来受追踪的字符串值；如果进程未找到或无法确定 Agent，则为 null。

响应示例：

{
  "peek_started_at": "2026-04-11T12:34:56.789Z",
  "observed_duration_sec": 10.01,
  "processes": [
    {
      "pid": 123,
      "agent": "codex",
      "status": "running",
      "events": [
        { "kind": "message", "ts": "2026-04-11T12:34:59.120Z", "text": "I'm checking the implementation." },
        { "kind": "tool_call", "ts": "2026-04-11T12:35:00.000Z", "phase": "started", "id": "item_0", "tool": "command_execution", "summary": "/bin/sh -c 'echo hi'" }
      ],
      "truncated": false,
      "error": null
    },
    {
      "pid": 999,
      "agent": null,
      "status": "not_found",
      "events": [],
      "truncated": false,
      "error": "process not found"
    }
  ]
}

list_processes

列出所有正在运行和已完成的 AI Agent 进程，以及它们的状态、PID 和基本信息。

doctor

检查受支持的 AI CLI 二进制文件是否可用，以及从 MCP 客户端解析路径的情况。与 ai-cli doctor 类似，它会返回 checks 块，但不会验证登录状态或条款是否已接受。

models

列出受支持的模型名称和别名，包括通过运行 pi --list-models 和 opencode models 发现的模型。此工具返回与 ai-cli models 相同的结构化负载。pi 和 opencode 数组保留其默认键，并追加可直接用于 run 的名称。

这两个发现命令会并发运行，超时时间为 5 秒，每个 CLI 的输出上限为 1 MiB。可使用 PI_CLI_NAME 和 OPENCODE_CLI_NAME 覆盖默认值。发现过程使用调用进程的工作目录和 CLI 配置；列出的模型不保证已通过身份验证或可访问。

每个 dynamicModelBackends.<backend>.discovery 都包含 status（success 或 error）、checkedAt、cached，以及失败时的 error。CLI 缺失、超时或解析错误时，该后端的默认键以及所有其他模型列表和别名仍可用。成功但列表为空时，status 为 "success"，且不会添加其他名称。

MCP 服务会将发现结果（包括失败结果）缓存 60 秒，并共享并发查询结果。每次单独调用 ai-cli models 都会获取最新结果。可执行文件选择、工作目录或环境发生变化时会绕过缓存；CLI 配置文件的变更会在缓存过期后生效。每次请求都会读取用户别名。列出 MCP 工具和启动运行不会触发发现。

aliases 数组包含内置默认别名与用户模型别名合并后的结果。每个条目包含 name、resolvesTo、agent，以及可选的 defaultReasoningEffort。

get_result

根据 PID 获取 AI Agent 进程的当前输出和状态。

默认情况下，此工具返回精简的结果结构：pid、agent、status、exitCode、model 等操作字段、agentOutput 等已解析输出，以及可用时的顶层 session_id。结果会省略 startTime、workFolder 和 prompt 等元数据字段。设置 verbose: true 可返回完整的结果结构，包括这些元数据字段和 agentOutput.tools 等详细的已解析输出。如果已解析输出不可用或不完整，则保留原始 stdout/stderr 回退内容。

参数：

• pid（数字，必填）：run 工具返回的进程 ID。
• verbose（布尔值，可选）：若为 true，则返回完整的结果结构。默认为 false。

kill_process

根据 PID 终止正在运行的 AI Agent 进程。

参数：

• pid（数字，必填）：要终止的进程 ID。

故障排除

• “Command not found”（claude-code-mcp）： 如果是全局安装，请确保 npm 全局 bin 目录位于系统的 PATH 中。如果使用 npx，请确保 npx 本身可以正常运行。
• “Command not found”（ai-cli）： 如果是全局安装，请确保 npm 全局目录位于 PATH 中。如果使用 npx，请使用 npx -y --package ai-cli-mcp@latest ai-cli ...。
• “Command not found”（claude 或 ~/.claude/local/claude）： 请确保 Claude CLI 已正确安装。运行 claude/doctor 或查阅其文档。
• 权限问题： 请确保已执行“首次设置须知”步骤。
• 服务器返回 JSON 错误： 如果 MCP_CLAUDE_DEBUG 为 true，错误消息或日志可能会干扰 MCP 的 JSON 解析。将其设为 false 以正常运行。
• ESM/导入错误： 请确保使用 Node.js v20 或更高版本。

贡献

有关开发环境设置、测试和贡献指南，请参阅开发指南。

测试

# Deterministic unit, parser, contract, and mocked e2e tests
npm test

# Published npm package contents smoke test
npm run test:package

# Deterministic PR/release gate used by GitHub Actions.
# This does not enable real external CLI runs by itself.
npm run test:release

# Release-time live E2E against real installed AI CLIs
ACM_LIVE_E2E=1 ACM_LIVE_E2E_AGENTS=claude,codex npm run test:live

# Release-time live E2E for both ai-cli and MCP server surfaces
ACM_LIVE_E2E=1 ACM_LIVE_E2E_SURFACE=all ACM_LIVE_E2E_AGENTS=claude,codex npm run test:live

实时 E2E 测试为可选项，因为它依赖已安装并通过身份验证的外部 CLI、网络访问、提供商可用性和成本预算。ACM_LIVE_E2E_SURFACE 默认为 cli；使用 mcp 或 all 可将 MCP 服务界面纳入测试。

高级配置（可选）

通常不需要，但可用于自定义 CLI 路径或进行调试。

• CLAUDE_CLI_NAME：覆盖 Claude CLI 二进制文件名称，或提供绝对路径（默认值：claude）
• CODEX_CLI_NAME：覆盖 Codex CLI 二进制文件名称，或提供绝对路径（默认值：codex）
• ANTIGRAVITY_CLI_NAME：覆盖 Antigravity 二进制文件名称或绝对路径（默认值：agy）。已弃用的 GEMINI_CLI_NAME 优先级较低，也必须指向 Antigravity 二进制文件。
• ANTIGRAVITY_PRINT_TIMEOUT：使用正时长（例如 1h）覆盖 Antigravity 的运行时限（集成默认值：2h；0 不代表不限时）。
• GROK_CLI_NAME：覆盖 Grok CLI 二进制文件名称或绝对路径（默认查找顺序：~/.grok/bin/grok，然后是 PATH 中的 grok）
• OPENCODE_CLI_NAME：覆盖 OpenCode CLI 二进制文件名称，或提供绝对路径（默认值：opencode）
• PI_CLI_NAME：覆盖 Pi CLI 二进制文件名称，或提供绝对路径（默认值：pi）
• MCP_CLAUDE_DEBUG：启用调试日志（设为 true 可输出详细信息）

CLI 名称规范：

• 仅命令名称：CLAUDE_CLI_NAME=claude-custom
• 绝对路径：CLAUDE_CLI_NAME=/path/to/custom/claude 不支持相对路径。

使用自定义 CLI 二进制文件的示例：

    "ai-cli-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "ai-cli-mcp@latest"
      ],
      "env": {
        "CLAUDE_CLI_NAME": "claude-custom",
        "CODEX_CLI_NAME": "codex-custom",
        "OPENCODE_CLI_NAME": "opencode-custom",
        "PI_CLI_NAME": "pi-custom"
      }
    },

许可证

MIT