dumbwaiter-mcp

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Dumbwaiter MCP: Wait-for-Change

Dumbwaiter MCP：等待变更

Goal: give Claude a single, stable way to “wait until X happens” on a code host (GitHub now; GitLab next). This skill teaches Claude when and how to use the Dumbwaiter MCP server’s tools.

Prerequisites

Server: this repo builds a stdio MCP server (
```
cargo build && target/debug/dumbwaiter-mcp
```
).
Auth:
```
export GITHUB_TOKEN=…
```
(repo read permissions are sufficient for commit statuses).
Persistence (optional):
```
DUMBWAITER_DB
```
to override
```
./state/dumbwaiter.sqlite
```
.
Await settings (optional):
```
DUMBWAITER_AWAIT_TTL_SECS
```
(default 900),
```
DUMBWAITER_ENGINE=1
```
to enable the background engine (legacy alias
```
DUMBWAITER_WATCHER=1
```
still works).

When to use this skill

You need to pause orchestration until PR checks turn green, a PR is merged, or checks fail.
You want durable waits with a
```
wait_id
```
, cancellable and recoverable after restarts.
You want progress updates visible to the host via MCP
```
notify_progress
```
.

Tools overview

```
wait.start
```
→ returns
```
{ wait_id }
```
for a condition on a selector

wait.status

→ returns current state:

pending|satisfied|failed|timeout|cancelled|unknown

```
wait.cancel
```
→ cancels a pending wait
```
wait.await
```
→ polls provider with exponential backoff; emits progress notifications; resolves to terminal state or timeout

Selectors and conditions (GitHub)

selector:

{ "owner": "ORG", "repo": "REPO", "pr": 123 }

Supported
```
condition
```
tokens:
- ```
checks_succeeded
```
  — combined status success
- ```
checks_failed
```
  — combined status failure/error
- ```
pr_merged
```
  — merged flag true
- ```
pr_approved
```
  — at least one approved review
- ```
changes_requested
```
  — an open review with changes requested
- ```
workflow_completed
```
  — at least one completed workflow run
- ```
comment_received
```
  — any new PR comment/review/reaction event (see streaming section below)

For

comment_received

, optional

filters

refine which events count. If omitted,

since

defaults to the wait's

created_at

timestamp so Dumbwaiter streams everything posted after the wait was created.

Happy-path flow

Start wait

name:
```
wait.start
```

arguments:

{ "provider": "github", "selector": {…}, "condition": "checks_succeeded" }

capture
```
wait_id
```

Await
- name:
```
wait.await
```
- arguments:
```
{ "wait_id": "…" }
```
- Observe progress notifications; handle final result
Query or cancel as needed
- ```
wait.status
```
  or
```
wait.cancel
```

Guidelines

Prefer
```
wait.await
```
when a host can display progress; otherwise poll with
```
wait.status
```
on an interval < backoff cap (default 30s).
Always report final state back to the orchestrator and link the
```
wait_id
```
in logs/notes.
On auth errors or rate limits, surface a clear, actionable message; do not retry aggressively (respect backoff).
On timeouts, return
```
timeout
```
with elapsed seconds; let the caller decide next steps.
Security: never echo tokens; require least scopes.

目标：为Claude提供一种单一、稳定的方式，在代码托管平台（目前支持GitHub，后续将支持GitLab）上“等待X事件发生”。本Skill将教会Claude何时以及如何使用Dumbwaiter MCP服务器的工具。

前置条件

服务器：本仓库可构建一个标准输入输出MCP服务器（
```
cargo build && target/debug/dumbwaiter-mcp
```
）。
认证：
```
export GITHUB_TOKEN=…
```
（仓库读取权限足以获取提交状态）。
持久化（可选）：通过
```
DUMBWAITER_DB
```
覆盖默认的
```
./state/dumbwaiter.sqlite
```
数据库路径。
等待设置（可选）：
```
DUMBWAITER_AWAIT_TTL_SECS
```
（默认900秒），设置
```
DUMBWAITER_ENGINE=1
```
以启用后台引擎（旧别名
```
DUMBWAITER_WATCHER=1
```
仍可使用）。

何时使用本Skill

你需要暂停编排流程，直到PR检查通过、PR被合并或检查失败。
你需要具备
```
wait_id
```
的可持久化等待任务，支持取消操作，且重启后可恢复。
你希望通过MCP
```
notify_progress
```
向宿主展示进度更新。

工具概述

```
wait.start
```
→ 返回对应选择器条件的
```
{ wait_id }
```

wait.status

→ 返回当前状态：

pending|satisfied|failed|timeout|cancelled|unknown

```
wait.cancel
```
→ 取消一个待处理的等待任务
```
wait.await
```
→ 以指数退避方式轮询供应商；发送进度通知；最终解析为终端状态或超时

选择器与条件（GitHub）

选择器：

{ "owner": "ORG", "repo": "REPO", "pr": 123 }

支持的
```
condition
```
标识：
- ```
checks_succeeded
```
  — 综合状态为成功
- ```
checks_failed
```
  — 综合状态为失败/错误
- ```
pr_merged
```
  — PR已合并
- ```
pr_approved
```
  — 至少有一个已批准的评审
- ```
changes_requested
```
  — 存在一个要求修改的未关闭评审
- ```
workflow_completed
```
  — 至少有一个工作流已完成
- ```
comment_received
```
  — 收到任何新的PR评论/评审/反应事件（见下方流处理章节）

对于

comment_received

条件，可通过可选的

filters

筛选符合条件的事件。若省略

since

，则默认使用等待任务创建时的

created_at

时间戳，Dumbwaiter将流式传输等待任务创建后发布的所有内容。

最佳实践流程

启动等待任务

名称：
```
wait.start
```

参数：

{ "provider": "github", "selector": {…}, "condition": "checks_succeeded" }

记录返回的
```
wait_id
```

等待结果
- 名称：
```
wait.await
```
- 参数：
```
{ "wait_id": "…" }
```
- 观察进度通知；处理最终结果
按需查询或取消
- 使用
```
wait.status
```
  查询状态或
```
wait.cancel
```
  取消任务

指南

若宿主支持展示进度，优先使用
```
wait.await
```
；否则，以小于退避上限（默认30秒）的时间间隔轮询
```
wait.status
```
。
务必将最终状态报告给编排器，并在日志/备注中关联对应的
```
wait_id
```
。
遇到认证错误或速率限制时，展示清晰、可执行的提示信息；不要频繁重试（遵循退避策略）。
超时后，返回
```
timeout
```
状态及已耗时秒数；由调用方决定后续操作。
安全：切勿回显令牌；使用最小权限原则。

Streaming GitHub comment events

流式处理GitHub评论事件

Set

condition

comment_received

plus optional filters:

json

{
  "provider": "github",
  "selector": { "owner": "acme", "repo": "widgets", "pr": 42 },
  "condition": "comment_received",
  "filters": {
    "since": "2025-01-01T00:00:00Z",
    "include_bots": true,
    "author_allowlist": ["alice"],
    "author_denylist": ["bot"]
  }
}

wait.await

emits

notify_progress

for every matching comment/review/reaction (body + URL + reaction counts + code context) before returning the terminal payload that mirrors the streamed events. Use this when an orchestrator needs to react to each individual discussion event.

Examples

“Wait for PR 42 in acme/widgets until checks pass.”

start →

{ provider: "github", selector: { owner: "acme", repo: "widgets", pr: 42 }, condition: "checks_succeeded" }

await →
```
{ wait_id }
```

“Stream every new comment on PR 42 since midnight UTC.”

start →

{ provider: "github", selector: { owner: "acme", repo: "widgets", pr: 42 }, condition: "comment_received", filters: { since: "2025-01-01T00:00:00Z", include_bots: true } }

await → receives per-comment progress events plus the final summary payload

Troubleshooting

```
unknown
```
status: the
```
wait_id
```
was not found (DB purge or wrong project).
No progress events: confirm host supports MCP notifications and server is connected.
Auth failures: ensure
```
GITHUB_TOKEN
```
is set and valid for the target repo.

将

condition

设置为

comment_received

并添加可选的

filters

：

json

{
  "provider": "github",
  "selector": { "owner": "acme", "repo": "widgets", "pr": 42 },
  "condition": "comment_received",
  "filters": {
    "since": "2025-01-01T00:00:00Z",
    "include_bots": true,
    "author_allowlist": ["alice"],
    "author_denylist": ["bot"]
  }
}

wait.await

会为每个匹配的评论/评审/反应事件发送

notify_progress

通知（包含内容体+URL+反应计数+代码上下文），之后返回与流式事件一致的终端负载。当编排器需要对每个单独的讨论事件做出反应时，可使用此功能。

示例

“等待acme/widgets仓库中PR 42的检查通过。”

启动任务 →

{ provider: "github", selector: { owner: "acme", repo: "widgets", pr: 42 }, condition: "checks_succeeded" }

等待结果 →
```
{ wait_id }
```

“流式传输PR 42自UTC午夜以来的所有新评论。”

启动任务 →

{ provider: "github", selector: { owner: "acme", repo: "widgets", pr: 42 }, condition: "comment_received", filters: { since: "2025-01-01T00:00:00Z", include_bots: true } }

等待结果 → 接收每条评论的进度事件及最终汇总负载

故障排除

```
unknown
```
状态：未找到对应的
```
wait_id
```
（数据库已清理或项目错误）。
无进度事件：确认宿主支持MCP通知且服务器已连接。
认证失败：确保已设置
```
GITHUB_TOKEN
```
且对目标仓库有效。