io.github.ricardo-hdrn/mcp-await
Condition watcher for AI assistants — wait for ports, files, URLs, processes, and more
Open source Open in the app JSON README (API)
About
Condition watcher for AI assistants — wait for ports, files, URLs, processes, and more
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- ricardo-hdrn
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.3
- Stars
- 2
- Forks
- 1
- Open pull requests
- 2
- Last push
- 2026-03-23T12:30:18Z
- Repository state
- ativo
- Language
- Rust
- License
- MIT
- Added
- 2026-08-29 04:01:18
- Updated
- 2026-08-29 04:01:18
- Origin id
io.github.ricardo-hdrn/mcp-await
README
# mcp-await
[](https://crates.io/crates/mcp-await)
[](https://github.com/ricardo-hdrn/mcp-await/actions/workflows/ci.yml)
[](LICENSE)
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
```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).
## CLI Usage
The binary doubles as a standalone CLI tool:
```bash
# 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:
```json
{
"status": "success",
"elapsed_seconds": 1.23,
"detail": "localhost:8080 is accepting connections"
}
```
## MCP Server Setup
### Claude Code
Add to `~/.claude.json`:
```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
```bash
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:
```json
{"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`:
```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)
- [ ] Broader agent compatibility testing (Codex, Gemini CLI, Cursor, Windsurf)
## Development
```bash
cargo build # debug build
cargo build --release # release build
cargo test # run tests
cargo clippy # lint
cargo fmt # format
```
## License
[MIT](LICENSE)