dumbwaiter-mcp

Dumbwaiter MCP：等待状态变化

目标：为 Claude 提供一种统一且稳定的方式，在代码托管平台上“等待 X 发生”（目前支持 GitHub；接下来支持 GitLab）。此技能会教 Claude 何时以及如何使用 Dumbwaiter MCP 服务的工具。

前置条件

• 服务端：此仓库会构建一个 stdio 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 仍可用）。

何时使用此技能

• 你需要暂停编排，直到 PR 检查全部通过、PR 合并或检查失败。
• 你需要可持久化的等待，可通过 wait_id 取消，并可在重启后恢复。
• 你希望通过 MCP notify_progress 向宿主显示进度更新。

工具概览

• wait.start → 针对某个选择器的条件返回 { wait_id }
• wait.status → 返回当前状态：pending|satisfied|failed|timeout|cancelled|unknown
• wait.cancel → 取消正在等待的任务
• wait.await → 通过指数退避轮询服务提供方；发送进度通知；直至达到终态或超时

选择器与条件（GitHub）

• selector：{ "owner": "ORG", "repo": "REPO", "pr": 123 }
• 支持的 condition 标记：
  • checks_succeeded — 综合状态成功
  • checks_failed — 综合状态失败／错误
  • pr_merged — 合并标记为 true
  • pr_approved — 至少有一条已批准的审查
  • changes_requested — 有一条未关闭的审查要求修改
  • workflow_completed — 至少有一次工作流运行已完成
  • comment_received — 收到任何新的 PR 评论／审查／反应事件（见下方的流式处理部分）

对于 comment_received，可选的 filters 可进一步筛选符合条件的事件。如果省略，since 默认为等待的 created_at 时间戳，因此 Dumbwaiter 会流式处理等待创建后发布的所有内容。

正常流程

1. 开始等待
   • 名称：wait.start
   • 参数：{ "provider": "github", "selector": {…}, "condition": "checks_succeeded" }
   • 记录 wait_id
2. 等待
   • 名称：wait.await
   • 参数：{ "wait_id": "…" }
   • 观察进度通知；处理最终结果
3. 按需查询或取消
   • wait.status 或 wait.cancel

指南

• 如果宿主可以显示进度，优先使用 wait.await；否则以小于退避上限的间隔（默认 30s）轮询 wait.status。
• 始终将最终状态报告给编排器，并在日志／备注中附上 wait_id 链接。
• 遇到身份验证错误或速率限制时，给出明确且可执行的提示；不要激进地重试（遵守退避策略）。
• 超时时，返回 timeout 和已耗秒数；由调用方决定后续步骤。
• 安全：绝不回显令牌；遵循最小权限原则。

流式 GitHub 评论事件

将 condition 设为 comment_received，并可选添加筛选条件：

{
  "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，直到检查通过。”
  • start → { provider: "github", selector: { owner: "acme", repo: "widgets", pr: 42 }, condition: "checks_succeeded" }
  • await → { wait_id }
• “流式获取自 UTC 午夜以来 PR 42 上的每条新评论。”
  • start → { provider: "github", selector: { owner: "acme", repo: "widgets", pr: 42 }, condition: "comment_received", filters: { since: "2025-01-01T00:00:00Z", include_bots: true } }
  • await → 接收每条评论的进度事件以及最终摘要载荷

故障排查

• 状态为 unknown：未找到 wait_id（数据库已清理或项目错误）。
• 没有进度事件：确认宿主支持 MCP 通知且服务已连接。
• 身份验证失败：确保已设置 GITHUB_TOKEN，且该令牌对目标仓库有效。