ai-cli-mcp

AI CLI MCP サーバー

🇯🇵 日本語のREADMEはこちら

📦 パッケージ移行のお知らせ: このパッケージは以前 @mkxultra/claude-code-mcp という名前でしたが、複数の AI CLI ツールへのサポート拡大を反映して ai-cli-mcp に改名されました。

AI CLI ツール（Claude、Codex、Gemini、OpenCode、Grok、Pi）を、権限処理を自動化したバックグラウンドプロセスで実行できるようにする MCP（Model Context Protocol）サーバーです。

Cursor が複雑な複数ステップの編集や操作に時々苦戦することに気づいたことはありませんか？ このサーバーは、強力で統合された run ツールによって、複数の AI エージェントがコーディングタスクをより効果的に処理できるようにします。

デモ

概要

この MCP サーバーは、LLM が AI CLI ツールとやり取りするために使用できるツールを提供します。MCP クライアントと統合すると、LLM は次のことができるようになります。

• すべての権限をバイパスして Claude CLI を実行する（--dangerously-skip-permissions を使用）
• 承認とサンドボックスをバイパスして Codex CLI を実行する（--dangerously-bypass-approvals-and-sandbox を使用）
• Antigravity CLI を通じて Gemini モデルを実行する（agy --print、stream-json、--dangerously-skip-permissions）
• streaming-messages-json、ツール承認の自動化、自動更新の無効化により、Grok Build CLI をヘッドレスで実行する
• 非対話型 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 追跡によるバックグラウンドプロセスの管理
• 両方のツールからの構造化された出力を解析して返す

使用例（高度な並列処理）

メインエージェントに対して、次のように複数のタスクを並列で実行するよう指示できます。

acm mcp run を使って、次の 3 つのタスクのエージェントを起動してください:

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 を使って、次の 2 つのタスクを acm mcp run で並列に実行します:
   • sonnet を使って src/utils のリファクタリング提案を作成する
   • gpt-5.3-codex を使って README.md にアーキテクチャドキュメントを追加する
4. 最後に、再度 wait して両方の結果を統合します。

メリット

• 真の非同期マルチタスキング: エージェントの実行はバックグラウンドで行われ、制御はすぐに戻ります。呼び出し元の AI は完了を待たずに次のタスクに進んだり、別のエージェントを呼び出したりできます。
• CLI 内の CLI (エージェント内のエージェント): 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 を選択します。古い Gemini CLI 名を対象としたカスタムエイリアスは ai-cli alias add で更新してください。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 の実行制限をデフォルトで 2 時間 (2h) に設定します。上書きするには、ai-cli または MCP サーバーの環境で ANTIGRAVITY_PRINT_TIMEOUT=1h (または別の正の期間) を設定してください。Antigravity の 0 は即時タイムアウトを意味します。ACM の wait(timeout: 0) は待機の期限を削除するだけで、この別個の実行制限は変更しません。

このパッケージを使用する主な方法は現在 2 つあります:

• ai-cli-mcp: MCP サーバーのエントリポイント
• ai-cli: バックグラウンド AI 実行のための人間向け CLI

npx を使用した MCP の使用

MCP サーバーを使用する推奨の方法は npx 経由です。

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 の使用

本番 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 を使用した Human 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 を使用できるようにするには、まず --dangerously-skip-permissions フラグを付けて Claude CLI を手動で一度実行し、ログインして利用規約に同意する必要があります。

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 を使用します。最新の Sol モデルには gpt-6.1-sol、以前の Sol モデルには gpt-6-sol、Luna には gpt-6-luna を選択してください。これら3つはすべて 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 イベントを報告します。Thinking デルタ、ツールの更新、および生のツール出力は除外されます。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 の effort 検証が行われます。モデルの可用性は 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 でも機能します。エイリアスは既存のユーザー設定を使用します。effort を指定しない場合、Grok が effort を決定します。プロバイダーキー 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 を使用し、さらにオプションの model、effort、--resume=<session_id> を指定します。添付された値は先頭のハイフンと改行を保持します。ai-cli のサーフェスでは、-- で始まる値には --prompt="--text" / --session-id="--id" を使用するか、プロンプトファイルを使用してください。これは既存の無人ツール承認ポリシーに従います。使用前に Grok で認証してください。doctor.grok はバイナリの検出のみを確認します。Grok 1.0.13 の models コマンドは、OAuth ヘッドレス実行が機能する場合でも未認証のバナーを表示することがあるため、そのバナーは認証テストとして使用されません。

peek は呼び出し中のアシスタントメッセージ全体を監視し、さらにオプションで正規化されたツールの開始/完了イベントも監視します。Thinking、トークンデルタ、生のツール出力は除外されます。get_result と wait は最終的な回答とセッション ID、または実行中は利用可能なアシスタントのテキストを返します。存在する場合、Grok の model/usage/cost メタデータと終端の 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 はその操作が完了するまでエントリを保持します。最初のシグナルが、シグナルが配信される前に失敗した場合、そのエラーが返され、その後の自然な完了は実際のステータスと終了コードを保持します。

ユーザーモデルエイリアス

モデルとそのデフォルトの reasoning effort を、プロジェクトをまたいで使用できる名前で保存します。CLI と MCP は同じユーザー設定を共有します。

コマンドラインからエイリアスを管理および使用する

組み込みエイリアス sol と luna は gpt-6.1-sol と gpt-6-luna を選択します。これらは reasoning effort を設定しません。Codex CLI のデフォルトを使用するには --reasoning-effort を省略するか、実行時に指定してください。たとえば、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 reasoning で gpt-5.6-terra を実行します。単一の実行で effort を上書きするには --reasoning-effort low を使用します。

alias list は、configPath と、有効な組み込みエイリアスおよびユーザーエイリアスを含む aliases 配列を持つ JSON を出力します。各エントリには name、resolvesTo、agent、およびオプションの defaultReasoningEffort があり、ai-cli models のエイリアスと一致します。リスト表示は設定ファイルを作成または変更しません。サポートされているモデルカタログも含めるには ai-cli models を使用します。

alias add <name> <model> [--effort <level>] は、必要に応じて設定ファイルとその親ディレクトリを作成します。これには、明示的に選択された AI_CLI_CONFIG_PATH も含まれます。名前を再利用するとその定義が置き換えられます。--effort を省略すると、以前のエイリアスの 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"
}

そのリクエストの effort を上書きするには "reasoning_effort": "low" を追加します。ai-cli models と MCP の models ツールは、有効なエイリアスを name、resolvesTo、agent、およびオプションの defaultReasoningEffort フィールドを持つ aliases エントリとして公開します。

設定は 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 は任意です。バックエンドはエイリアス名に関係なく、対象モデルから選択されます。
• Effort の優先順位は、実行時の明示的な引数 → エイリアスのデフォルト → 対象 CLI のデフォルトです。Effort は対象モデルでサポートされている必要があります。Antigravity の Effort はモデルのサフィックスと一致する必要があり、OpenCode のエイリアスでは省略する必要があります。
• ユーザーエントリは codex-ultra などの組み込みエイリアスを上書きできます。各エントリは定義全体を置き換えます。reasoning_effort を省略すると、組み込みの Effort を継承するのではなく、対象 CLI のデフォルトが使用されます。
• ターゲットは gpt-5.6-terra、opus、oc-openai/gpt-5.4 などのネイティブモデル名である必要があります。エイリアスのチェーンはサポートされていません。エイリアス名は大文字と小文字を区別し、ASCII 文字で始まり、ASCII 文字、数字、_、- のみを含みます。列挙されたネイティブモデル名、codex、および oc- プレフィックスは予約されていますが、互換性のために grok という名前のユーザーエイリアスは優先されます。
• デフォルトの設定ファイルが存在しない場合は、組み込みの動作が維持されます。不正な形式のファイルや無効なモデル/Effort の組み合わせは、設定パスを含むエラーを発生させます。明示的に設定されたファイルが存在しない場合もエラーになりますが、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 を通じて永続化します。ゼロ以外の終了は、記録された exitCode とともに failed として通知されます。ゼロの終了は、exitCode: 0 とともに completed として通知されます。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 (string, 任意): AI エージェントに送信するプロンプト。prompt または prompt_file のいずれかが必須です。
• prompt_file (string, 任意): プロンプトを含むファイルへのパス。prompt または prompt_file のいずれかが必須です。絶対パスまたは workFolder からの相対パスを指定できます。
• workFolder (string, 必須): 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 (string, 任意): 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 のデフォルトが使用されます。max/ultra は Grok では拒否されます。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 (string, 任意): 以前のセッションを再開するためのオプションのセッション ID。Claude、Codex、Gemini、OpenCode、Grok、Pi でサポートされています。Grok は --resume で再開し、OpenCode と Pi は --session でその場で再開し、明示的なモデル選択と組み合わせることもできます。

wait

複数の AI エージェントプロセスの完了を待機し、それらの結合された結果を返します。指定されたすべての 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 を設定すると、startTime、workFolder、prompt などの完全なメタデータや、agentOutput.tools などの詳細な解析済み出力が含まれます。

引数:

• pids (数値の配列、必須): 待機するプロセス ID のリスト(run ツールによって返されます)。
• timeout (数値、オプション): 秒単位の非負の最大待機時間。デフォルトは 180(3 分)です。0 は待機タイムアウトを無効にします。
• verbose (ブール値、オプション): true の場合、各結果項目は完全な結果形式を使用します。デフォルトは false です。

peek

実行中の子エージェントに対するワンショットの短時間観測ウィンドウを開始し、その呼び出し中に観測された構造化イベントを返します。デフォルトでは自然言語のメッセージイベントのみが含まれます。include_tool_calls または --include-tool-calls を指定すると、正規化されたツール呼び出しイベントも含まれます。これは履歴 API ではなく、ギャップのないストリーミングでもなく、シェルの stdout/stderr の追尾でもありません。別々の peek 呼び出しでは、呼び出しの間に発生したイベントを取りこぼす可能性があります。--follow は意図的に v1 には含まれていません。

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 や管理対象外の 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 のアシスタントテキストコンテンツ全体、OpenCode の type: "text" イベントで part.type が "text" であるもの、Antigravity の step_update イベント、および Pi の text_delta イベントから認識されます。
• ツール呼び出しが含まれる場合、tool_call イベントは Codex のコマンド/MCP 呼び出し、Claude/Grok のツール使用/結果、Antigravity のツールステップ、OpenCode のツール使用、および Pi のツール実行開始/終了イベントに対して正規化されます。ツールの要約は、ツール名と入力メタデータのみから導出された 1 行に収まる文字列です。生のツールおよびコマンド出力は除外されます。
• 不明なイベント形状はデフォルトで拒否されます。サポートされている抽出を持たない管理対象エージェントは、実際のプロセスステータスと events: []、truncated: false、および error: null を返します。
• 各 PID はウィンドウ内で観測された最初の 50 件のイベントを保持します。それ以降のイベントが破棄された場合、truncated は true になります。
• status は running、completed、failed、または not_found のいずれかであり、観測ウィンドウが閉じた時点の状態を反映します。
• agent は claude、codex、gemini、opencode、grok、pi、将来追跡される文字列値、またはプロセスが見つからないかエージェントを判別できない場合は 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 エージェントプロセスを、そのステータス、PID、および基本情報とともに一覧表示します。

doctor

MCP クライアントから、サポートされている AI CLI バイナリの可用性とパス解決を確認します。ai-cli doctor と同様に、checks ブロックを返し、ログイン状態や利用規約への同意は検証しません。

models

サポートされているモデル名とエイリアスの一覧を表示します。これには pi --list-models および opencode models の実行によって検出されたモデルも含まれます。これは ai-cli models と同じ構造化ペイロードを返します。pi と opencode の配列はデフォルトのキーを保持し、run で使用できる名前を追加します。

2 つの検出コマンドは、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 エージェントプロセスの現在の出力とステータスを取得します。

デフォルトでは、コンパクトな結果形式を返します。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 エージェントプロセスを終了します。

引数:

• pid（数値、必須）: 終了するプロセス ID。

トラブルシューティング

• 「Command not found」（claude-code-mcp）: グローバルにインストールした場合は、npm のグローバル bin ディレクトリがシステムの PATH に含まれていることを確認してください。npx を使用している場合は、npx 自体が動作していることを確認してください。
• 「Command not found」（ai-cli）: グローバルにインストールした場合は、npm のグローバル bin ディレクトリが PATH に含まれていることを確認してください。npx を使用している場合は、npx -y --package ai-cli-mcp@latest ai-cli ... を使用してください。
• 「Command not found」（claude または ~/.claude/local/claude）: Claude CLI が正しくインストールされていることを確認してください。claude/doctor を実行するか、そのドキュメントを確認してください。
• 権限の問題: 「Important First-Time Setup」の手順を実行したことを確認してください。
• サーバーからの 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 サーバーのサーフェスを含めるには mcp または all を使用してください。

高度な設定（任意）

通常は不要ですが、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: Antigravity の実行制限を 1h のような正の期間で上書きします（統合のデフォルト: 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