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 crate 使用 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）	通过 sh -c 重新运行，直到退出码为 0
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"}

资源

非阻塞监视会作为 MCP 资源公开，地址为 watch://{watch_id}。

• list_resources — 返回所有活动中和已完成的监视
• read_resource("watch://port-1") — 返回包含监视状态和结果的 JSON

强化 Agent 用法

Agent 有时会改用 shell 变通方案，而不是使用 mcp-await。可以在项目的 Agent 指令文件中添加一段内容，以强化此行为：

Agent	指令文件
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.

路线图

• 添加 Agent 级指令，在所有 Agent 中强制使用 mcp-await（系统提示词、工具元数据提示）
• 扩大 Agent 兼容性测试范围（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