Condition watcher for AI assistants — wait for ports, files, URLs, processes, and more
io.github.ricardo-hdrn/mcp-await — Condition watcher for AI assistants (MCP)
This MCP server (and CLI) provides a condition watcher for AI CLI assistants. Instead of repeatedly polling with sleep loops or retrying network requests, it exposes a wait tool that blocks until a specified condition becomes true, then returns.
🛠️ Key Features
Condition watcher for AI CLI assistants
Wait tool that blocks until conditions are met
Detects conditions related to ports, files, URLs, processes, and more
🚀 Use Cases
Waiting for an open port during startup before proceeding
Blocking until a required file appears or updates
Waiting for a target URL condition
Waiting for a process state as part of automation
⚡ Developer Benefits
Avoids wasted API round-trips caused by polling
Reduces reliance on sleep loops and curl --retry
⚠️ Limitations
The provided description does not specify configuration options, supported platforms, or any edge-case behavior beyond blocking until conditions are met
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.
demo
Installation
bash
# 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
bash
# 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).
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.
Receive notifications/resources/updated when the condition is met
Read watch://port-1 for the full result
Cancellation
Cancel any non-blocking watch with cancel_watch:
json
{"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
markdown
## 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)
