nickytonline/beads-mcp

A TypeScript HTTP MCP server built from nickytonline/mcp-typescript-template. Agents share Beads tasks through eleven tools; Node executes the installed bd CLI without a shell.
Inspiration and intent
This project was inspired by a livestream with Trillium Smith, where they mentioned building a Beads MCP. Credit to Trillium for the inspiration—and to anyone who explored this idea before them. This project makes no claim to originating the idea of exposing Beads through MCP.
I wanted to build a general-purpose Beads MCP using my TypeScript MCP template: a starting point that anyone can use, adapt, and extend for their own agents and workflows. Beads itself was created by Steve Yegge.
Architecture
One server process, one replica, one process-wide FIFO queue for **all** Beads commands, including reads and compound operations. Embedded Dolt is a single-writer store. Do not run another MCP instance, CLI process, or backup job against it concurrently. The queue has a 100-operation admission limit; each CLI subprocess has a 30-second timeout and a 4 MiB output limit. A timeout or invalid output can leave a write's outcome uncertain: inspect the task before retrying.
Transport uses the template's stateless Streamable HTTP adapter at /mcp. GET /health checks process liveness; startup verifies the initialized store before listening. Health does not continuously query the database. Logs omit task inputs and subprocess stderr.
Tools
| Tool | Purpose |
| --- | --- |
| ready | List unblocked work, with optional priority/label filters |
| search | Search text and status/assignee/label filters, including closed tasks |
| get | Task details, dependencies, and comment bodies, plus state_revision, activity_revision and last_activity_at |
| create | Task, acceptance criteria, priority, labels, optional parent/prerequisites |
| update | Edit fields, status, or labels; optional expected_revision compare-and-swap |
| claim | Native atomic bd update --claim, attributed to an actor |
| release | Verify ownership, optionally append a reason, clear assignee, set open |
| add_note | Append a comment |
| link | Add/remove a relationship; for blocks, id depends on target |
| complete | Close with summary/evidence; respects Beads gates/dependencies |
| handoff | Append structured done/remaining/next context; optionally release |
Every request to /mcp requires a verified signed JWT. The authenticated actor is derived from the configured claim (normally email, falling back to sub) and is used for every write; optional actor fields remain only for client compatibility and are ignored for authenticated HTTP requests. Claims never expire: ownership lasts until release, handoff with release, or complete. update, release, handoff and complete accept an optional expected_revision (the state_revision from get) for compare-and-swap; without it, writes are last-writer-wins. Compound operations are serialized but are not atomic database transactions; notes may persist if a subsequent release fails. Handoff returns a warning in that case. Results use { data: }; genuine failures have isError: true and a body of { error, code, retryable, outcome_unknown }. See docs/GUARANTEES.md for exactly what is guaranteed, what is tested, and what is still unverified.
Agent skill discovery
The server bundles the canonical Beads engineering-backlog Agent Skill. It explains when persistent engineering context is useful, how agents should search, claim, note, hand off, and complete work, and where Beads stops: it is not a personal to-do list, memory store, scheduler, orchestrator, or replacement for GitHub Issues.
On protocol revision 2026-07-28 or later, server/discover advertises the stable io.modelcontextprotocol/skills extension. Clients that support the extension can call skills/list or skills/get for skill://beads-engineering-backlog/SKILL.md, then read the same bytes through resources/read. The listing includes a complete file manifest with SHA-256 digests and byte sizes, plus ttlMs and cacheScope freshness hints. This release does not advertise optional directory reads. Clients that do not support the extension can use the URI in the server instructions or install the standalone SKILL.md manually.