Replace Backlog.md integration with MCP server; add beads CLI (#18) - #26
Merged
Merged
Conversation
szachovy
force-pushed
the
feature/issue-18-backlog-mcp-and-beads
branch
from
April 24, 2026 09:36
a76544b to
5da14b1
Compare
Register `@radleta/backlog-md-mcp` as a `backlog-md` MCP server for Claude, Codex, and Opencode. Agents now talk to Backlog.md via typed MCP tools (`task_create`, `task_list`, `task_edit`, `board_show`, `overview`, etc.) instead of the CLI. Install `@beads/bd` globally so the `bd` graph issue tracker / agentic memory CLI is available to all three agents. Per upstream guidance, shell-capable agents use the CLI directly rather than an MCP wrapper (lower token cost and latency). CI fixes folded in: - Claude reads managed MCP servers from /etc/claude-code/managed-mcp.json, NOT from `mcpServers` inside managed-settings.json (that key is silently ignored). New .devcontainer/config/claude/managed-mcp.json holds the `backlog-md` entry and is moved to /etc/claude-code/ in the Dockerfile alongside managed-settings.json. - Opencode now reads its managed config under bash as well as zsh. Added OPENCODE_CONFIG=/etc/opencode/managed_config.json to the container-wide ENV block; previously this was only exported inside .zshrc, so non-interactive bash invocations (including the capability-check probe) didn't see the managed config. This side-effect-fixes the pre-existing `opencode mcp context7` failure on master. - capability-check.sh reads expected Claude MCPs from managed-mcp.json. No `beads` MCP server is added to managed configs. Rationale: the beads MCP server (`beads-mcp`) only exists as a PyPI package, and per the beads-mcp README itself — "for environments with shell access (Claude Code, Cursor, Windsurf), the CLI + hooks approach is recommended over MCP." Changes: - Dockerfile: new AGENT_PLATFORM_BACKLOG_MD_MCP_VERSION and AGENT_PLATFORM_BEADS_VERSION build args; npm-install both packages alongside the existing backlog.md CLI. Add OPENCODE_CONFIG env. Move and chmod managed-mcp.json. - devcontainer.json: thread the two new build args through. - Codex/Opencode managed configs gain the `backlog-md` MCP entry (inline; Claude uses the separate managed-mcp.json file). - `instructions` skill adds the `backlog-md` MCP row and a new `bd` CLI row. - docs/architecture.md tree updated; README env-var table updated; CHANGELOG Unreleased entries updated. Closes #18
szachovy
force-pushed
the
feature/issue-18-backlog-mcp-and-beads
branch
from
April 24, 2026 13:07
5da14b1 to
092ecc6
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
@radleta/backlog-md-mcpas abacklog-mdMCP server for Claude, Codex, and Opencode. Agents now talk to Backlog.md via typed MCP tools (task_create,task_list,task_edit,board_show,overview, etc.) instead of reading a ~625-line embedded CLI guide.@beads/bdglobally so thebdgraph issue tracker / agentic memory CLI is available to all three agents.<!-- BACKLOG.MD GUIDELINES -->block fromCLAUDE.md, CodexAGENTS.md, and OpencodeAGENTS.md(~1880 lines of always-loaded context removed across the three files).Scope notes
beadsMCP server is added to managed configs. Rationale: the beads MCP server (beads-mcp) only exists as a PyPI package, and per the beads-mcp README itself — "for environments with shell access (Claude Code, Cursor, Windsurf), the CLI + hooks approach is recommended over MCP. It uses ~1-2k tokens vs 10-50k for MCP schemas, resulting in lower compute cost and latency." Since all three target agents are shell-capable, thebdCLI is the right interface. AC 'beads MCP is installed and usable' is interpreted pragmatically: beads is installed (via@beads/bd) and usable from every agent.backlog.mdCLI install is retained alongside the new MCP — both version pins kept for reproducibility.AGENT_PLATFORM_BACKLOG_MD_MCP_VERSION,AGENT_PLATFORM_BEADS_VERSION(defaultlatest, follows existing pattern).Acceptance criteria
mcpServers/mcp_servers/mcpin all three managed configs; CIcapability-check.shwill verify via<agent> mcp list.grep -rn 'BACKLOG.MD GUIDELINES' .devcontainer/config/returns no matches.beadsis installed and usable from each supported agent —bdon PATH via@beads/bd; upstream-recommended CLI interface rather than MCP wrapper (see scope note above).README.mdenv-var table,CHANGELOG.mdUnreleased Added/Changed/Removed entries.instructionsskill is updated — new MCP row forbacklog-mdand new CLI row forbd.Test plan
backlog-mcp --helpstarts without error;bd --versionresolves.capability-check.shreportsPASS: claude mcp backlog-md available(and the same for codex/opencode).task_list) — confirm the MCP responds.bd initinside the container to confirm the beads CLI works; create and list a task.Closes #18