Mcp Await

mcp-await

AI コマンドラインアシスタント（Claude Code、Codex、Cursor など）向けの条件監視 MCP サーバーと CLI です。

API のラウンドトリップを無駄にする sleep ループや curl --retry でポーリングする代わりに、待機ツールを一度呼び出すだけで、条件が満たされるまで処理がブロックされ、結果が返されます。

インストール

# Prebuilt binary (Linux, macOS, Windows) — download from GitHub Releases
# https://github.com/ricardo-hdrn/mcp-await/releases/latest

# From crates.io
cargo install mcp-await

# From source
git clone https://github.com/ricardo-hdrn/mcp-await.git
cd mcp-await
cargo build --release

クイックスタート

# Wait for a service to be ready
mcp-await port localhost 8080 --timeout 30

# Wait for a file to appear
mcp-await file /tmp/deploy.lock --event create --timeout 60

# Wait for a command to succeed
mcp-await cmd "curl -sf http://localhost:8080/health" --interval 2 --timeout 30

ツール

ツール	主なパラメーター	監視方法
wait_for_port	host、port	TCP 接続のループ、500ms 間隔
wait_for_file	path、event（create/modify/delete）	notify クレート経由の inotify、ポーリングなし
wait_for_url	url、expected_status（デフォルトは 200）	curl ループ、2s 間隔（curl が必要）
wait_for_pid	pid	/proc/{pid} を確認、500ms 間隔
wait_for_docker	container	docker wait（docker が必要）
wait_for_gh_run	run_id、repo（任意）	gh run watch（gh が必要）
wait_for_command	command、interval_seconds（デフォルトは 5）	終了コードが 0 になるまで sh -c で再実行
cancel_watch	watch_id	ノンブロッキング監視をキャンセル

すべてのツールは timeout_seconds（デフォルト：300）と blocking（デフォルト：true）を受け付けます。

CLI の使用方法

バイナリはスタンドアロンの CLI ツールとしても使用できます。

# TCP port
mcp-await port localhost 5432 --timeout 30

# File events
mcp-await file /var/log/app.log --event modify --timeout 120
mcp-await file /tmp/flag --event create --timeout 60
mcp-await file /tmp/old.pid --event delete --timeout 30

# HTTP status
mcp-await url https://api.example.com/health --status 200 --timeout 120

# Process exit
mcp-await pid 12345 --timeout 300

# Docker container exit
mcp-await docker my-container --timeout 600

# GitHub Actions run
mcp-await gh-run 12345678 --repo owner/repo --timeout 1800

# Arbitrary shell command (exit 0 = success)
mcp-await cmd "test -f /tmp/ready" --interval 2 --timeout 30

終了コード

コード	意味
0	条件を満たしました（成功）
1	タイムアウト
2	エラー

出力形式

すべてのコマンドは JSON を出力します。

{
  "status": "success",
  "elapsed_seconds": 1.23,
  "detail": "localhost:8080 is accepting connections"
}

MCP サーバーのセットアップ

Claude Code

~/.claude.json に追加します。

{
  "mcpServers": {
    "await": {
      "command": "/path/to/mcp-await"
    }
  }
}

サブコマンドなしで（または mcp-await serve を指定して）実行すると、バイナリは stdio MCP サーバーとして動作します。

MCP Inspector

npx @modelcontextprotocol/inspector ./target/release/mcp-await

ブロッキングモードとノンブロッキングモード

ブロッキング（デフォルト）

条件が満たされるか、タイムアウトするか、キャンセルされるまで、ツール呼び出しは保留されます。最もシンプルなモードで、AI アシスタントは結果を待ちます。

ノンブロッキング

blocking: false を設定すると、watch_id とリソース URI がすぐに返されます。サーバーはバックグラウンドで監視し、完了すると通知を送信します。

フロー：

1. blocking: false を指定して wait_for_port を呼び出す
2. すぐに次の応答を受け取ります：

   {"watch_id": "port-1", "resource": "watch://port-1", "status": "watching"}
   

3. 待機中に別の作業を行う
4. 条件が満たされると notifications/resources/updated を受け取る
5. watch://port-1 を読み込み、結果全体を取得する

キャンセル

cancel_watch を使って、ノンブロッキング監視をキャンセルできます。

{"watch_id": "port-1"}

リソース

ノンブロッキング監視は、watch://{watch_id} の MCP リソースとして公開されます。

• list_resources — アクティブな監視と完了した監視をすべて返します
• read_resource("watch://port-1") — 監視のステータスと結果を含む JSON を返します

エージェントでの使用を徹底する

エージェントは、mcp-await を使用せず、シェルによる回避策を使うことがあります。動作を徹底するには、プロジェクトのエージェント指示ファイルにスニペットを追加してください。

エージェント	指示ファイル
Claude Code	CLAUDE.md
Codex	AGENTS.md
Gemini CLI	GEMINI.md
Cursor	.cursor/rules/
Windsurf	.windsurfrules

## Waiting for conditions

Use mcp-await tools instead of shell workarounds:
- `wait_for_port` instead of `while ! nc ...; do sleep 1; done`
- `wait_for_url` instead of `curl --retry`
- `wait_for_file` instead of polling loops
- `wait_for_command` instead of `while ! cmd; do sleep N; done`

Prefer `blocking: false` when there is independent work to do in parallel.

ロードマップ

• すべてのエージェントで mcp-await の使用を徹底するためのエージェントレベルの指示（システムプロンプト、ツールのメタデータヒント）
• より幅広いエージェント互換性テスト（Codex、Gemini CLI、Cursor、Windsurf）

開発

cargo build           # debug build
cargo build --release # release build
cargo test            # run tests
cargo clippy          # lint
cargo fmt             # format

ライセンス

MIT