Dumbwaiter MCP: Wait-for-Change

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): DUMBWAITERAWAITTTLSECS (default 900), DUMBWAITERWATCHER=1 to enable background polling.

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:

- checkssucceeded — combined status success - checksfailed — combined status failure/error - prmerged — merged flag true - prapproved — at least one approved review - changesrequested — an open review with changes requested - workflowcompleted — at least one completed workflow run - comment_received — any new PR comment/review/reaction event (see streaming section below)

For commentreceived, optional filters refine which events count. If omitted, since defaults to the wait's createdat timestamp so Dumbwaiter streams everything posted after the wait was created.

Happy-path flow

1. Start wait

- name: wait.start - arguments: { "provider": "github", "selector": {…}, "condition": "checkssucceeded" } - capture waitid

1. Await

- name: wait.await - arguments: { "wait_id": "…" } - Observe progress notifications; handle final result

1. 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.

Streaming GitHub comment events

Set condition to comment_received plus optional filters:

{
  "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: "checkssucceeded" } - await → { waitid }

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

- start → { provider: "github", selector: { owner: "acme", repo: "widgets", pr: 42 }, condition: "commentreceived", filters: { since: "2025-01-01T00:00:00Z", includebots: 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.