ai-cli-mcp 2.3.3 → 2.5.0

package/.gemini/settings.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "acm-dev": {
+      "command": "npm",
+      "args": [
+        "run",
+        "dev"
+      ]
+    }
+  }
+}

package/.mcp.json

@@ -3,7 +3,8 @@
     "acm-dev": {
       "command": "npm",
       "args": [
-        "start"
+        "run",
+        "dev"
       ]
     }
   }

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+# [2.5.0](https://github.com/mkXultra/claude-code-mcp/compare/v2.4.0...v2.5.0) (2026-01-24)
+
+
+### Features
+
+* enhance output parsers for Codex and Claude with tool usage extraction ([b6410a1](https://github.com/mkXultra/claude-code-mcp/commit/b6410a104666eca592735acea093b877c0f03f64))
+* track command execution in Codex output and include .gemini config ([91f7f06](https://github.com/mkXultra/claude-code-mcp/commit/91f7f067a1d453fd8e3a5a95bb90f21b7df0af8a))
+* update Claude CLI args to stream-json and add verbose option to get_result ([b7f9abc](https://github.com/mkXultra/claude-code-mcp/commit/b7f9abc11c56ad0c8c95e90a614d1d869d8a3bfa))
+
+# [2.4.0](https://github.com/mkXultra/claude-code-mcp/compare/v2.3.3...v2.4.0) (2026-01-24)
+
+
+### Features
+
+* add model aliases and auto-reasoning for Codex ([16bbd7c](https://github.com/mkXultra/claude-code-mcp/commit/16bbd7cef934cbe2c652e7e48c8dd289f1a64eda))
+* add support for gemini-3-flash-preview ([b51a2d1](https://github.com/mkXultra/claude-code-mcp/commit/b51a2d1789455f3366dfc8f6397cf7ffc39f930d))
+
 ## [2.3.3](https://github.com/mkXultra/claude-code-mcp/compare/v2.3.2...v2.3.3) (2026-01-20)
 
 

package/CONTRIBUTING.md

@@ -0,0 +1,71 @@
+# Contributing
+
+## Development Setup
+
+```bash
+git clone https://github.com/mkXultra/claude-code-mcp.git
+cd claude-code-mcp
+npm install
+npm run build
+```
+
+## Testing
+
+```bash
+# Run all tests
+npm test
+
+# Unit tests only
+npm run test:unit
+
+# E2E tests (with mocks)
+npm run test:e2e
+
+# E2E tests locally (requires Claude CLI)
+npm run test:e2e:local
+
+# Watch mode
+npm run test:watch
+
+# Coverage
+npm run test:coverage
+```
+
+## Manual Testing with MCP Inspector
+
+```bash
+npm run build
+npx @modelcontextprotocol/inspector node dist/server.js
+```
+
+## Local Development with npm link
+
+```bash
+npm install
+npm run build
+npm link
+```
+
+Then use `ai-cli-mcp` command globally.
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `CLAUDE_CLI_NAME` | Claude CLI binary name or absolute path |
+| `CODEX_CLI_NAME` | Codex CLI binary name or absolute path |
+| `GEMINI_CLI_NAME` | Gemini CLI binary name or absolute path |
+| `MCP_CLAUDE_DEBUG` | Enable debug logging (`true`/`false`) |
+
+## Release Process
+
+See [docs/RELEASE_CHECKLIST.md](docs/RELEASE_CHECKLIST.md) for release instructions.
+
+Uses semantic-release with Conventional Commits:
+- `fix:` → patch release
+- `feat:` → minor release
+- `feat!:` or `BREAKING CHANGE:` → major release
+
+## License
+
+MIT

package/README.ja.md

@@ -0,0 +1,227 @@
+# AI CLI MCP Server
+
+[![npm package](https://img.shields.io/npm/v/ai-cli-mcp)](https://www.npmjs.com/package/ai-cli-mcp)
+[![View changelog](https://img.shields.io/badge/Explore%20Changelog-brightgreen)](/CHANGELOG.md)
+
+> **📦 パッケージ移行のお知らせ**: 本パッケージは旧名 `@mkxultra/claude-code-mcp` から `ai-cli-mcp` に名称変更されました。これは、複数のAI CLIツールのサポート拡大を反映したものです。
+
+AI CLIツール（Claude, Codex, Gemini）をバックグラウンドプロセスとして実行し、権限処理を自動化するMCP（Model Context Protocol）サーバーです。
+
+Cursorなどのエディタが、複雑な手順を伴う編集や操作に苦戦していることに気づいたことはありませんか？このサーバーは、強力な統合 `run` ツールを提供し、複数のAIエージェントを活用してコーディングタスクをより効果的に処理できるようにします。
+
+<img src="assets/screenshot.png" width="300" alt="Screenshot">
+
+## 概要
+
+このMCPサーバーは、LLMがAI CLIツールと対話するためのツールを提供します。MCPクライアントと統合することで、LLMは以下のことが可能になります：
+
+- すべての権限確認をスキップしてClaude CLIを実行（`--dangerously-skip-permissions` を使用）
+- 自動承認モードでCodex CLIを実行（`--full-auto` を使用）
+- 自動承認モードでGemini CLIを実行（`-y` を使用）
+- 複数のAIモデルのサポート：
+    - Claude (sonnet, opus, haiku)
+    - Codex (gpt-5.2-codex, gpt-5.1-codex-mini, gpt-5.1-codex-max, など)
+    - Gemini (gemini-2.5-pro, gemini-2.5-flash, gemini-3-pro-preview, gemini-3-flash-preview)
+- PID追跡によるバックグラウンドプロセスの管理
+- ツールからの構造化された出力の解析と返却
+
+### 使用例（高度な並行処理）
+
+メインのエージェントに以下のように指示することで、複数のタスクを並行して実行させることができます。
+
+> 以下の3つのタスクをacm mcp runでエージェントを起動して：
+> 1. `sonnet` で `src/backend` のコードをリファクタリング
+> 2. `gpt-5.2-codex` で `src/frontend` のユニットテストを作成
+> 3. `gemini-2.5-pro` で `docs/` のドキュメントを更新
+>
+> 実行中はあなたはTODOリストを更新する作業を行ってください。それが終わったら `wait` ツールを使ってすべての完了を待機し、結果をまとめて報告してください。
+
+### 使用例（コンテキストキャッシュの共有）
+
+一度読み込んだ重いコンテキスト（大規模なコードベースやドキュメント）をセッションIDを使って再利用することで、コストを抑えながら複数のタスクを実行できます。
+
+> 1. まず `acm mcp run` を使い、`opus` で `src/` 以下の全ファイルを読み込み、プロジェクトの構造を理解させてください。
+> 2. `wait` ツールでこの処理の完了を待ち、結果から `session_id` を取得してください。
+> 3. その `session_id` を使い、以下の2つのタスクを `acm mcp run` で並行して実行してください：
+>    - `sonnet` で `src/utils` のリファクタリング案を作成
+>    - `gpt-5.2-codex` で `README.md` にアーキテクチャの解説を追記
+> 4. 最後に再び `wait` して、両方の結果をまとめてください。
+
+## メリット
+
+- **真の非同期マルチタスク**: エージェントの実行はバックグラウンドで行われ、即座に制御が戻ります。呼び出し元のAIは実行完了を待つことなく、並行して次のタスクの実行や別のエージェントの呼び出しを行うことができます。
+- **CLI in CLI (Agent in Agent) の実現**: MCPをサポートするあらゆるIDEやCLIから、Claude CodeやCodexといった強力なCLIツールを直接呼び出せます。ホスト環境の制限を超えた、より広範で複雑なシステム操作や自動化が可能になります。
+- **モデル・プロバイダの制約からの解放**: 特定のエコシステムに縛られることなく、Claude、Codex (GPT)、Geminiの中から、タスクに最適な「最強のモデル」や「コスト効率の良いモデル」を自由に選択・組み合わせて利用できます。
+
+## 前提条件
+
+利用したいAI CLIツールがローカル環境にインストールされ、正しく設定されていることが唯一の前提条件です。
+
+- **Claude Code**: `claude doctor` が通り、`--dangerously-skip-permissions` での実行が承認済み（一度手動で実行してログイン・承認済み）であること。
+- **Codex CLI**（オプション）: インストール済みで、ログインなどの初期設定が完了していること。
+- **Gemini CLI**（オプション）: インストール済みで、ログインなどの初期設定が完了していること。
+
+## インストールと使い方
+
+推奨される使用方法は、`npx` を使用してインストールすることです。
+
+### MCP設定ファイルでnpxを使用する場合:
+
+```json
+    "ai-cli-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "ai-cli-mcp@latest"
+      ]
+    },
+```
+
+### Claude CLI mcp add コマンドを使用する場合:
+
+```bash
+claude mcp add ai-cli '{"name":"ai-cli","command":"npx","args":["-y","ai-cli-mcp@latest"]}'
+```
+
+## 重要な初回セットアップ
+
+### Claude CLIの場合:
+
+**MCPサーバーがClaudeを使用する前に、一度手動で `--dangerously-skip-permissions` フラグを付けてClaude CLIを実行し、ログインして利用規約に同意する必要があります。**
+
+```bash
+npm install -g @anthropic-ai/claude-code
+claude --dangerously-skip-permissions
+```
+
+プロンプトに従って同意してください。これが完了すると、MCPサーバーはこのフラグを使って非対話的に実行できるようになります。
+
+### Codex CLIの場合:
+
+**Codexの場合、ログインして必要な規約に同意していることを確認してください：**
+
+```bash
+codex login
+```
+
+### Gemini CLIの場合:
+
+**Geminiの場合、ログインして認証情報を設定していることを確認してください：**
+
+```bash
+gemini auth login
+```
+
+macOSでは、これらのツールを初めて実行する際にフォルダへのアクセス許可を求められる場合があります。最初の実行が失敗しても、2回目以降は動作するはずです。
+
+## MCPクライアントへの接続
+
+サーバーのセットアップ後、MCPクライアント（CursorやWindsurfなど）の設定ファイル（`mcp.json` や `mcp_config.json`）に設定を追加してください。
+
+ファイルが存在しない場合は作成し、`ai-cli-mcp` の設定を追加してください。
+
+## 提供されるツール
+
+このサーバーは以下のツールを公開しています：
+
+### `run`
+
+Claude CLI、Codex CLI、またはGemini CLIを使用してプロンプトを実行します。モデル名に基づいて適切なCLIが自動的に選択されます。
+
+**引数:**
+- `prompt` (string, 任意): AIエージェントに送信するプロンプト。`prompt` または `prompt_file` のいずれかが必須です。
+- `prompt_file` (string, 任意): プロンプトを含むファイルへのパス。`prompt` または `prompt_file` のいずれかが必須です。絶対パス、または `workFolder` からの相対パスが指定可能です。
+- `workFolder` (string, 必須): CLIを実行する作業ディレクトリ。絶対パスである必要があります。
+- **モデル (Models):**
+    - **Ultra エイリアス:** `claude-ultra`, `codex-ultra` (自動的に high-reasoning に設定), `gemini-ultra`
+    - Claude: `sonnet`, `opus`, `haiku`
+    - Codex: `gpt-5.2-codex`, `gpt-5.1-codex-mini`, `gpt-5.1-codex-max`, `gpt-5.2`, `gpt-5.1`, `gpt-5`
+    - Gemini: `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-3-pro-preview`, `gemini-3-flash-preview`
+- `reasoning_effort` (string, 任意): Codex専用。`model_reasoning_effort` を設定します（許容値: "low", "medium", "high"）。
+- `session_id` (string, 任意): 以前のセッションを再開するためのセッションID。対応モデル: haiku, sonnet, opus, gemini-2.5-pro, gemini-2.5-flash, gemini-3-pro-preview, gemini-3-flash-preview。
+
+### `wait`
+
+複数のAIエージェントプロセスの完了を待機し、結果をまとめて返します。指定されたすべてのPIDが終了するか、タイムアウトになるまでブロックします。
+
+**引数:**
+- `pids` (array of numbers, 必須): 待機するプロセスIDのリスト（`run` ツールから返されたもの）。
+- `timeout` (number, 任意): 最大待機時間（秒）。デフォルトは180秒（3分）です。
+
+### `list_processes`
+
+実行中および完了したすべてのAIエージェントプロセスを、ステータス、PID、基本情報とともにリストアップします。
+
+### `get_result`
+
+PIDを指定して、AIエージェントプロセスの現在の出力とステータスを取得します。
+
+**引数:**
+- `pid` (number, 必須): `run` ツールによって返されたプロセスID。
+
+### `kill_process`
+
+PIDを指定して、実行中のAIエージェントプロセスを終了します。
+
+**引数:**
+- `pid` (number, 必須): 終了させるプロセスID。
+
+## トラブルシューティング
+
+- **"Command not found" (claude-code-mcp):** グローバルにインストールした場合、npmのグローバルbinディレクトリがシステムのPATHに含まれているか確認してください。`npx` を使用している場合、`npx` 自体が機能しているか確認してください。
+- **"Command not found" (claude または ~/.claude/local/claude):** Claude CLIが正しくインストールされていることを確認してください。`claude/doctor` を実行するか、公式ドキュメントを確認してください。
+- **権限の問題:** 「重要な初回セットアップ」の手順を実行したか確認してください。
+- **サーバーからのJSONエラー:** `MCP_CLAUDE_DEBUG` が `true` の場合、エラーメッセージやログがMCPのJSON解析を妨げる可能性があります。通常動作時は `false` に設定してください。
+
+## 開発者向け: ローカルセットアップと貢献
+
+このサーバーを開発・貢献したい場合、またはクローンしたリポジトリから実行してテストしたい場合は、[Local Installation & Development Setup Guide](./docs/local_install.md) を参照してください。
+
+## テスト
+
+プロジェクトには包括的なテストスイートが含まれています：
+
+```bash
+# 全テストの実行
+npm test
+
+# ユニットテストのみ実行
+npm run test:unit
+
+# E2Eテストの実行（モック使用）
+npm run test:e2e
+```
+
+## 高度な設定（オプション）
+
+通常の利用では設定不要ですが、CLIツールのパスをカスタマイズしたい場合やデバッグが必要な場合に使用できる環境変数です。
+
+- `CLAUDE_CLI_NAME`: Claude CLIのバイナリ名または絶対パスを上書き（デフォルト: `claude`）
+- `CODEX_CLI_NAME`: Codex CLIのバイナリ名または絶対パスを上書き（デフォルト: `codex`）
+- `GEMINI_CLI_NAME`: Gemini CLIのバイナリ名または絶対パスを上書き（デフォルト: `gemini`）
+- `MCP_CLAUDE_DEBUG`: デバッグログを有効化（`true` に設定すると詳細な出力が表示されます）
+
+**CLI名の指定方法:**
+- コマンド名のみ: `CLAUDE_CLI_NAME=claude-custom`
+- 絶対パス: `CLAUDE_CLI_NAME=/path/to/custom/claude`
+※ 相対パスは使用できません。
+
+### カスタムCLIバイナリを使用する場合の設定例:
+
+```json
+    "ai-cli-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "ai-cli-mcp@latest"
+      ],
+      "env": {
+        "CLAUDE_CLI_NAME": "claude-custom",
+        "CODEX_CLI_NAME": "codex-custom"
+      }
+    },
+```
+
+## ライセンス
+
+MIT

package/README.md

@@ -3,6 +3,8 @@
 [![npm package](https://img.shields.io/npm/v/ai-cli-mcp)](https://www.npmjs.com/package/ai-cli-mcp)
 [![View changelog](https://img.shields.io/badge/Explore%20Changelog-brightgreen)](/CHANGELOG.md)
 
+[🇯🇵 日本語のREADMEはこちら](./README.ja.md)
+
 > **📦 Package Migration Notice**: This package was formerly `@mkxultra/claude-code-mcp` and has been renamed to `ai-cli-mcp` to reflect its expanded support for multiple AI CLI tools.
 
 An MCP (Model Context Protocol) server that allows running AI CLI tools (Claude, Codex, and Gemini) in background processes with automatic permission handling.
@@ -18,39 +20,45 @@ This MCP server provides tools that can be used by LLMs to interact with AI CLI
 - Run Claude CLI with all permissions bypassed (using `--dangerously-skip-permissions`)
 - Execute Codex CLI with automatic approval mode (using `--full-auto`)
 - Execute Gemini CLI with automatic approval mode (using `-y`)
-- Support multiple AI models: Claude (sonnet, opus, haiku), Codex (gpt-5.2-codex, gpt-5.1-codex-mini, gpt-5.1-codex-max, gpt-5.2, gpt-5.1, gpt-5.1-codex, gpt-5-codex, gpt-5-codex-mini, gpt-5), and Gemini (gemini-2.5-pro, gemini-2.5-flash, gemini-3-pro-preview)
+- Support multiple AI models: Claude (sonnet, opus, haiku), Codex (gpt-5.2-codex, gpt-5.1-codex-mini, gpt-5.1-codex-max, gpt-5.2, gpt-5.1, gpt-5.1-codex, gpt-5-codex, gpt-5-codex-mini, gpt-5), and Gemini (gemini-2.5-pro, gemini-2.5-flash, gemini-3-pro-preview, gemini-3-flash-preview)
 - Manage background processes with PID tracking
 - Parse and return structured outputs from both tools
 
-## Benefits
+### Usage Example (Advanced Parallel Processing)
 
-- Claude/Windsurf often have trouble editing files. Claude Code is better and faster at it.
-- Multiple commands can be queued instead of direct execution. This saves context space so more important stuff is retained longer, fewer compacts happen.
-- File ops, git, or other operations don't need costy models. Claude Code is pretty cost effective if you sign up for Antropic Max. You can use Gemini or o3 in Max mode and save costs with offloading tasks to cheaper models.
-- Claude has wider system access and can do things that Cursor/Windsurf can't do (or believe they can't), so whenever they are stuck just ask them "use claude code" and it will usually un-stuck them.
-- Agents in Agents rules.
+You can instruct your main agent to run multiple tasks in parallel like this:
 
-## Prerequisites
+> Launch agents for the following 3 tasks using acm mcp run:
+> 1. Refactor `src/backend` code using `sonnet`
+> 2. Create unit tests for `src/frontend` using `gpt-5.2-codex`
+> 3. Update docs in `docs/` using `gemini-2.5-pro`
+>
+> While they run, please update the TODO list. Once done, use the `wait` tool to wait for all completions and report the results together.
 
-- Node.js v20 or later (Use fnm or nvm to install)
-- Claude CLI installed locally (run it and call /doctor) and `--dangerously-skip-permissions` accepted
-- Codex CLI installed (optional, for Codex support)
-- Gemini CLI installed (optional, for Gemini support)
+### Usage Example (Context Caching & Sharing)
 
-## Configuration
+You can reuse heavy context (like large codebases) using session IDs to save costs while running multiple tasks.
 
-### Environment Variables
+> 1. First, use `acm mcp run` with `opus` to read all files in `src/` and understand the project structure.
+> 2. Use the `wait` tool to wait for completion and retrieve the `session_id` from the result.
+> 3. Using that `session_id`, run the following two tasks in parallel with `acm mcp run`:
+>    - Create refactoring proposals for `src/utils` using `sonnet`
+>    - Add architecture documentation to `README.md` using `gpt-5.2-codex`
+> 4. Finally, `wait` again to combine both results.
 
-- `CLAUDE_CLI_NAME`: Override the Claude CLI binary name or provide an absolute path (default: `claude`)
-- `CODEX_CLI_NAME`: Override the Codex CLI binary name or provide an absolute path (default: `codex`)
-- `GEMINI_CLI_NAME`: Override the Gemini CLI binary name or provide an absolute path (default: `gemini`)
-- `MCP_CLAUDE_DEBUG`: Enable debug logging (set to `true` for verbose output)
+## Benefits
 
-All CLI name variables support:
-- Simple name: `CLAUDE_CLI_NAME=claude-custom` or `CODEX_CLI_NAME=codex-v2`
-- Absolute path: `CLAUDE_CLI_NAME=/path/to/custom/claude`
+- **True Async Multitasking**: Agent execution happens in the background, returning control immediately. The calling AI can proceed with the next task or invoke another agent without waiting for completion.
+- **CLI in CLI (Agent in Agent)**: Directly invoke powerful CLI tools like Claude Code or Codex from any MCP-supported IDE or CLI. This enables broader, more complex system operations and automation beyond host environment limitations.
+- **Freedom from Model/Provider Constraints**: Freely select and combine the "strongest" or "most cost-effective" models from Claude, Codex (GPT), and Gemini without being tied to a specific ecosystem.
 
-Note: Relative paths are not allowed and will throw an error.
+## Prerequisites
+
+The only prerequisite is that the AI CLI tools you want to use are locally installed and correctly configured.
+
+- **Claude Code**: `claude doctor` passes, and execution with `--dangerously-skip-permissions` is approved (you must run it manually once to login and accept terms).
+- **Codex CLI** (Optional): Installed and initial setup (login etc.) completed.
+- **Gemini CLI** (Optional): Installed and initial setup (login etc.) completed.
 
 ## Installation & Usage
 
@@ -74,22 +82,6 @@ The recommended way to use this server is by installing it by using `npx`.
 claude mcp add ai-cli '{"name":"ai-cli","command":"npx","args":["-y","ai-cli-mcp@latest"]}'
 ```
 
-### With custom CLI binaries:
-
-```json
-    "ai-cli-mcp": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "ai-cli-mcp@latest"
-      ],
-      "env": {
-        "CLAUDE_CLI_NAME": "claude-custom",
-        "CODEX_CLI_NAME": "codex-custom"
-      }
-    },
-```
-
 ## Important First-Time Setup
 
 ### For Claude CLI:
@@ -123,29 +115,9 @@ macOS might ask for folder permissions the first time any of these tools run. If
 
 ## Connecting to Your MCP Client
 
-After setting up the server, you need to configure your MCP client (like Cursor or others that use `mcp.json` or `mcp_config.json`).
+After setting up the server, add the configuration to your MCP client's settings file (e.g., `mcp.json` for Cursor, `mcp_config.json` for Windsurf).
 
-### MCP Configuration File
-
-The configuration is typically done in a JSON file. The name and location can vary depending on your client.
-
-#### Cursor
-
-Cursor uses `mcp.json`.
-- **macOS:** `~/.cursor/mcp.json`
-- **Windows:** `%APPDATA%\\Cursor\\mcp.json`
-- **Linux:** `~/.config/cursor/mcp.json`
-
-#### Windsurf
-
-Windsurf users use `mcp_config.json`
-- **macOS:** `~/.codeium/windsurf/mcp_config.json`
-- **Windows:** `%APPDATA%\\Codeium\\windsurf\\mcp_config.json`
-- **Linux:** `~/.config/.codeium/windsurf/mcp_config.json`
-
-(Note: In some mixed setups, if Cursor is also installed, these clients might fall back to using Cursor's `~/.cursor/mcp.json` path. Prioritize the Codeium-specific paths if using the Codeium extension.)
-
-Create this file if it doesn't exist. Add or update the configuration for `ai-cli-mcp`:
+If the file doesn't exist, create it and add the `ai-cli-mcp` configuration.
 
 ## Tools Provided
 
@@ -159,12 +131,21 @@ Executes a prompt using Claude CLI, Codex CLI, or Gemini CLI. The appropriate CL
 - `prompt` (string, optional): The prompt to send to the AI agent. Either `prompt` or `prompt_file` is required.
 - `prompt_file` (string, optional): Path to a file containing the prompt. Either `prompt` or `prompt_file` is required. Can be absolute path or relative to `workFolder`.
 - `workFolder` (string, required): The working directory for the CLI execution. Must be an absolute path.
-- `model` (string, optional): The model to use:
-  - Claude models: "sonnet", "opus", "haiku"
-  - Codex models: "gpt-5.2-codex", "gpt-5.1-codex-mini", "gpt-5.1-codex-max", "gpt-5.2", "gpt-5.1", "gpt-5.1-codex", "gpt-5-codex", "gpt-5-codex-mini", "gpt-5"
-  - Gemini models: "gemini-2.5-pro", "gemini-2.5-flash", "gemini-3-pro-preview"
+**Models:**
+- **Ultra Aliases:** `claude-ultra`, `codex-ultra` (defaults to high-reasoning), `gemini-ultra`
+- Claude: `sonnet`, `opus`, `haiku`
+- Codex: `gpt-5.2-codex`, `gpt-5.1-codex-mini`, `gpt-5.1-codex-max`, `gpt-5.2`, `gpt-5.1`, `gpt-5`
+- Gemini: `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-3-pro-preview`, `gemini-3-flash-preview`
 - `reasoning_effort` (string, optional): Codex only. Sets `model_reasoning_effort` (allowed: "low", "medium", "high").
-- `session_id` (string, optional): Optional session ID to resume a previous session. Supported for: haiku, sonnet, opus, gemini-2.5-pro, gemini-2.5-flash, gemini-3-pro-preview.
+- `session_id` (string, optional): Optional session ID to resume a previous session. Supported for: haiku, sonnet, opus, gemini-2.5-pro, gemini-2.5-flash, gemini-3-pro-preview, gemini-3-flash-preview.
+
+### `wait`
+
+Waits for multiple AI agent processes to complete and returns their combined results. Blocks until all specified PIDs finish or a timeout occurs.
+
+**Arguments:**
+- `pids` (array of numbers, required): List of process IDs to wait for (returned by the `run` tool).
+- `timeout` (number, optional): Maximum wait time in seconds. Defaults to 180 (3 minutes).
 
 ### `list_processes`
 
@@ -184,43 +165,6 @@ Terminates a running AI agent process by PID.
 **Arguments:**
 - `pid` (number, required): The process ID to terminate.
 
-**Example with Claude:**
-```json
-{
-  "toolName": "run",
-  "arguments": {
-    "prompt": "Refactor the function foo in main.py to be async.",
-    "workFolder": "/Users/username/my_project",
-    "model": "sonnet"
-  }
-}
-```
-
-**Example with Codex:**
-```json
-{
-  "toolName": "run",
-  "arguments": {
-    "prompt": "Create a REST API with Express.js",
-    "workFolder": "/Users/username/my_project",
-    "model": "gpt-5.2-codex",
-    "reasoning_effort": "high"
-  }
-}
-```
-
-**Example with Gemini:**
-```json
-{
-  "toolName": "run",
-  "arguments": {
-    "prompt": "Generate unit tests for the Calculator class",
-    "workFolder": "/Users/username/my_project",
-    "model": "gemini-2.5-pro"
-  }
-}
-```
-
 ### Examples
 
 Here are some visual examples of the server in action:
@@ -348,7 +292,7 @@ This will open a web interface where you can:
 3. Test different AI models including:
    - Claude models: `sonnet`, `opus`, `haiku`
    - Codex models: `gpt-5.2-codex`, `gpt-5.1-codex-mini`, `gpt-5.1-codex-max`, `gpt-5.2`, `gpt-5.1`, `gpt-5.1-codex`, `gpt-5-codex`, `gpt-5-codex-mini`, `gpt-5`
-   - Gemini models: `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-3-pro-preview`
+   - Gemini models: `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-3-pro-preview`, `gemini-3-flash-preview`
 
 Example test: Select the `run` tool and provide:
 - `prompt`: "What is 2+2?"
@@ -371,6 +315,36 @@ Contributions are welcome! Please refer to the [Local Installation & Development
 
 Submit issues and pull requests to the [GitHub repository](https://github.com/mkXultra/claude-code-mcp).
 
+## Advanced Configuration (Optional)
+
+Normally not required, but useful for customizing CLI paths or debugging.
+
+- `CLAUDE_CLI_NAME`: Override the Claude CLI binary name or provide an absolute path (default: `claude`)
+- `CODEX_CLI_NAME`: Override the Codex CLI binary name or provide an absolute path (default: `codex`)
+- `GEMINI_CLI_NAME`: Override the Gemini CLI binary name or provide an absolute path (default: `gemini`)
+- `MCP_CLAUDE_DEBUG`: Enable debug logging (set to `true` for verbose output)
+
+**CLI Name Specification:**
+- Command name only: `CLAUDE_CLI_NAME=claude-custom`
+- Absolute path: `CLAUDE_CLI_NAME=/path/to/custom/claude`
+*Relative paths are not supported.*
+
+### Example with custom CLI binaries:
+
+```json
+    "ai-cli-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "ai-cli-mcp@latest"
+      ],
+      "env": {
+        "CLAUDE_CLI_NAME": "claude-custom",
+        "CODEX_CLI_NAME": "codex-custom"
+      }
+    },
+```
+
 ## License
 
 MIT