使用说明
mcp等待
状态监视器MCP服务器+CLI用于AI CLI助手（Claude Code、Codex、Cursor等）。
而不是投票 sleep 循环和 curl --retry 浪费API round-tips，调用一次等待工具-它会阻塞，直到满足条件并返回结果。
安装
# 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 （创建/修改/删除） |
通过 notify 板条箱，无投票 |
wait_for_url |
url, expected_status （默认值200） |
curl 循环，2秒间隔（需要 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.json:
{
"mcpServers": {
"await": {
"command": "/path/to/mcp-await"
}
}
}
当不使用子命令（或使用 mcp-await serve).
MCP检查员
npx @modelcontextprotocol/inspector ./target/release/mcp-await
阻塞与非阻塞模式
阻止（默认）
工具调用将一直保持，直到满足条件、超时或取消。这是最简单的模式——AI助手等待结果。
非阻塞
集 blocking: false 立即得到回应 watch_id 服务器在后台进行监控，并在完成时推送通知。
流量：
- 呼叫
wait_for_port随着blocking: false - 立即返回：
{"watch_id": "port-1", "resource": "watch://port-1", "status": "watching"} - 等待时做其他工作
- 接收
notifications/resources/updated当条件满足时 - 阅读
watch://port-1为了获得完整的结果
取消
取消任何非阻塞手表 cancel_watch:
{"watch_id": "port-1"}
资源
非阻塞手表作为MCP资源暴露在 watch://{watch_id}.
list_resources--返回所有活动和已完成的手表read_resource("watch://port-1")--返回带有监视状态和结果的JSON
增强剂的使用
代理有时会退回到shell解决方法，而不是使用mcp-wait。在项目的代理说明文件中添加一个代码段以强化行为：
| 代理 | 指令文件 |
|---|---|
| 克劳德代码 | CLAUDE.md |
| 食品法典委员会 | AGENTS.md |
| Gemini CLI | GEMINI.md |
| 光标 | .cursor/rules/ |
| 风帆冲浪 | .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等待的代理级指令（系统提示、工具元数据提示）
- []更广泛的代理兼容性测试（Codex、Gemini CLI、Cursor、Windsurf）
发展
cargo build # debug build
cargo build --release # release build
cargo test # run tests
cargo clippy # lint
cargo fmt # format
