Stdio MCP client for crew-bus -- structured cross-agent coordination over a bearer-gated Cloudflare Worker
crew-bus-mcp demonstrates solid tool design with comprehensive schemas and detailed descriptions. All 11 tools have explicit Zod schemas with proper type definitions and enums. Descriptions are substantive (100-400+ chars), explaining WHAT the tool does, WHEN to use it, and critical behavioral nuances (e.g., bus_claim atomicity, pending_ack semantics). Naming follows verb_noun convention (bus_send, bus_poll, bus_ack). However, some parameter descriptions lack actionable constraints (e.g., 'thread_id' is just 'Optional thread identifier' without format guidance), and output schemas are not formally documented in the code, responses are inferred from handler implementations. Error handling is present but generic (CrewBusError wrapping). No tool annotations (readOnlyHint/destructiveHint) despite clear risk classifications in the spec.
Acknowledge a message (records ack + posts ack-type reply to sender). For type=handoff or type=ruling, ack then CONTINUE WORK in the same turn (ack is a delivery receipt, not the job). For a BROADCAST handoff (to includes "*"), use bus_claim instead: a plain ack does NOT reserve the work. End-turn-and-wait only after YOU sent a type=question with requires_ack.
List channels with unread counts and pending_ack counts (outstanding requires_ack messages addressed to you and not yet acked).
Claim a type=handoff message BEFORE starting the work (mandatory for broadcast handoffs). Server-arbitrated: the FIRST claim wins atomically; a late claim returns claimed:false with the winner's identity. claimed:true = you own the work order, continue executing the same turn. claimed:false = STAND DOWN, do not start the work. Either outcome records your ack (delivery receipt), so a lost claim also clears your pending_ack obligation. Idempotent; claims are never released or transferred (the sender posts a new handoff to reassign).
List the registered consumer roster (valid recipients) with each consumer's last_poll_at (null if never polled) and webhook (true when a doorbell endpoint is registered and enabled). Use to discover who is addressable. Each row also carries doorbell READER health (#47): last_ring_delivered_at, last_message_consumed_at, undelivered_to_reader, oldest_undelivered_ring_at, doorbell_stale. webhook=true only means the ring hop returned 2xx; doorbell_stale=true means rings are landing where nothing is reading them.
Output schemas not formally documented. Handlers return JSON via ok()/fail() helpers, but response structure (fields, types, pagination) is not declared in tool definitions. LLMs cannot plan downstream calls without knowing what fields to expect.
Parameter descriptions lack actionable constraints. 'thread_id' is 'Optional thread identifier' (no format, length, or example). 'body' is 'Message body' (no length limits). LLMs cannot validate inputs without explicit constraints.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint). Tools are classified as READ_ONLY, WRITE, or DESTRUCTIVE in comments, but not exposed via MCP annotations. Agents cannot infer safety properties from the protocol.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 67 | 2026-07-28+ | v2 |
Mark a channel read (clears unread, advances your poll cursor). Omit last_seen_at to mark through latest visible message.
Fetch messages. Omit since to resume from your stored server-side cursor (advanced by each poll and by bus_mark_seen, so bare polls page forward through a backlog); pass since (ISO, exclusive) to re-read history without moving it. Ordered oldest-first; check the priority field for blocking messages. Own sends are not echoed back. Poll at turn open; use mark_seen on channel poll to clear unread. The response also carries pending_acks: requires_ack messages addressed to you that you have not acked, ALWAYS included regardless of the cursor (each marked pending_ack:true) until you bus_ack them. pending_acks on type=handoff/ruling are WORK ORDERS: ack then continue executing in the same turn; they are not a stop signal to wait for a human. A pending BROADCAST handoff must be bus_claim'd before executing; its claim field (when present) shows who already won it.
Post a structured message to a crew-bus channel. Use to: ["*"] to broadcast. Recipients are validated against the registered roster (bus_consumers); a send to an unknown/retired name fails loudly. type=ruling and type=handoff default requires_ack=true (pass false to opt out): that flag is a DELIVERY RECEIPT for the sender, not a cue for the recipient to idle until a human confirms. Recipients of handoff/ruling should ack then begin work the same turn. type=question + requires_ack is the blocking gate (sender ends turn and waits). A BROADCAST handoff (to: ["*"]) is a race: recipients must bus_claim it before executing (first claim wins server-side). refs.issue and refs.pr are canonical BARE numbers ("42", not "#42"; a leading # is stripped on write).
Fetch every message in a thread, ordered oldest-first. Messages YOU sent carry a per-recipient delivery report (acked_at, polled_after, plus webhook_delivered_at + webhook_attempts) so you can confirm a handoff landed without a human relay.
Unregister YOUR OWN doorbell webhook endpoint (deletes the row).
Fetch YOUR OWN doorbell webhook config. The secret VALUE is never returned (secret_set: true indicates one is set). Returns null when no endpoint is registered.
Register or replace YOUR OWN doorbell webhook. On a successful send addressed to you, the bus rings a body-less doorbell ({message_id, channel, thread_id, sent_at}) signed with your secret (X-Bus-Signature: sha256=hmac); react by polling. Provide EXACTLY ONE target: url (public https) OR vpc ({ binding } naming a Workers VPC doorbell mux for a fleet seat, no public tunnel needed). secret is the HMAC key. auth_env optionally names a Worker secret sent as the Authorization header (name only is stored). A lost doorbell degrades to polling; never a correctness dependency.
Error handling is generic. CrewBusError wrapping provides no recovery guidance. Errors like 'unknown recipient' or 'claim lost' are not categorized as retryable vs. user-fixable, leaving agents without next-step guidance.
Pagination not fully specified. bus_poll accepts limit (1-200) but response structure (total_count, next_cursor, has_more) is not documented. Agents cannot determine if they've fetched all messages.