dumbwaiter-mcp

Original：🇺🇸 English

Translated

Provider-agnostic wait-for-change skill that uses the Dumbwaiter MCP server to wait on PR events (GitHub first) via wait.start/status/cancel/await, with progress notifications and durable state.

2installs

Sourcelambdamechanic/skills

Added on2026-03-14

NPX Install

npx skill4agent add lambdamechanic/skills dumbwaiter-mcp

SKILL.md Content

View Translation Comparison →

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):
```
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.

Streaming GitHub comment events

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.

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):
```
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.

Streaming GitHub comment events

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

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.

dumbwaiter-mcp

NPX Install

Tags

SKILL.md Content

Dumbwaiter MCP: Wait-for-Change

Streaming GitHub comment events

dumbwaiter-mcp

NPX Install

Tags

SKILL.md Content

Dumbwaiter MCP: Wait-for-Change

Streaming GitHub comment events