mcp-await

Condition watcher MCP server + CLI for AI CLI assistants (Claude Code, Codex, Cursor, etc.).

Instead of polling with sleep loops and curl --retry that waste API round-trips, call a wait tool once — it blocks until the condition is met and returns the result.

Installation

# 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

Quick Start

# 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

Tools

| Tool | Key Params | How it watches | |------|------------|----------------| | wait_for_port | host, port | TCP dial loop, 500ms interval | | wait_for_file | path, event (create/modify/delete) | inotify via notify crate, no polling | | wait_for_url | url, expected_status (default 200) | curl loop, 2s interval (requires curl) | | wait_for_pid | pid | /proc/{pid} check, 500ms interval | | wait_for_docker | container | docker wait (requires docker) | | wait_for_gh_run | run_id, repo (optional) | gh run watch (requires gh) | | wait_for_command | command, interval_seconds (default 5) | Re-run via sh -c until exit 0 | | cancel_watch | watch_id | Cancels a non-blocking watch |

All tools accept timeout_seconds (default: 300) and blocking (default: true).

CLI Usage

The binary doubles as a standalone CLI tool:

# 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

Exit Codes

| Code | Meaning | |------|---------| | 0 | Condition met (success) | | 1 | Timeout | | 2 | Error |

Output Format

All commands output JSON:

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

MCP Server Setup

Claude Code

Add to ~/.claude.json:

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

The binary runs as a stdio MCP server when invoked without a subcommand (or with mcp-await serve).

MCP Inspector

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

Blocking vs Non-Blocking Mode

Blocking (default)

The tool call holds until the condition is met, times out, or is cancelled. This is the simplest mode — the AI assistant waits for the result.

Non-Blocking

Set blocking: false to get an immediate response with a watch_id and resource URI. The server monitors in the background and pushes a notification when done.

Flow:

1. Call wait_for_port with blocking: false
2. Get back immediately:

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

3. Do other work while waiting
4. Receive notifications/resources/updated when the condition is met
5. Read watch://port-1 for the full result

Cancellation

Cancel any non-blocking watch with cancel_watch:

{"watch_id": "port-1"}

Resources

Non-blocking watches are exposed as MCP resources at watch://{watch_id}.

• list_resources — returns all active and completed watches
• read_resource("watch://port-1") — returns JSON with the watch status and result

Reinforcing Agent Usage

Agents sometimes fall back to shell workarounds instead of using mcp-await. Add a snippet to your project's agent instructions file to reinforce the behavior:

| Agent | Instructions file | |-------|-------------------| | 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.

Roadmap

• [ ] Agent-level instructions to enforce mcp-await usage across all agents (system prompts, tool metadata hints)
• [ ] Broader agent compatibility testing (Codex, Gemini CLI, Cursor, Windsurf)

Development

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

License

MIT