Files

Steve Yegge a4d816d1f4 fix: Remove unsupported engines field and add runtime version checking

Fixes Claude Code marketplace plugin installation failure (bd-183).

Problem: The plugin.json manifest included an engines field (borrowed from npm)
to specify minimum bd CLI version requirements. However, Claude Code's plugin
manifest schema doesn't recognize this field, causing validation errors when
installing via /plugin marketplace add.

Solution:
1. Remove the engines field from plugin.json
2. Add runtime version checking in the MCP server startup
3. Update documentation to reflect automatic version checking

Changes:
- .claude-plugin/plugin.json: Remove unsupported engines field
- integrations/beads-mcp/src/beads_mcp/bd_client.py:
  - Add BdVersionError exception class
  - Add _check_version() method to validate bd CLI >= 0.9.0
  - Use bd version command (not bd --version)
- integrations/beads-mcp/src/beads_mcp/tools.py:
  - Make _get_client() async to support version checking
  - Update all tool functions to await _get_client()
  - Add version check on first MCP server use
- .claude-plugin/commands/bd-version.md: Update to mention automatic checking
- PLUGIN.md: Document automatic version validation at startup

Benefits:
- Plugin installs successfully via Claude Code marketplace
- Clear error messages if bd CLI version is too old
- Version check happens once per MCP server lifetime (not per command)
- Users get actionable update instructions in error messages

Closes bd-183

2025-10-14 15:54:50 -07:00

src/beads_mcp

fix: Remove unsupported engines field and add runtime version checking

2025-10-14 15:54:50 -07:00

tests

feat: Add Beads MCP Server [bd-5]

2025-10-14 11:13:52 -07:00

.gitignore

feat: Add Beads MCP Server [bd-5]

2025-10-14 11:13:52 -07:00

.python-version

feat: Add Beads MCP Server [bd-5]

2025-10-14 11:13:52 -07:00

pyproject.toml

fix: Sync all component versions to 0.9.2

2025-10-14 13:42:37 -07:00

README.md

feat: Add Beads MCP Server [bd-5]

2025-10-14 11:13:52 -07:00

uv.lock

chore: Update uv.lock after testing MCP server

2025-10-14 14:34:04 -07:00

README.md

beads-mcp

MCP server for beads issue tracker and agentic memory system. Enables AI agents to manage tasks using bd CLI through Model Context Protocol.

Installing

git clone https://github.com/steveyegge/beads
cd beads/integrations/beads-mcp
uv sync

Add to your Claude Desktop config:

{
  "mcpServers": {
    "beads": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/beads-mcp",
        "run",
        "beads-mcp"
      ],
      "env": {
        "BEADS_PATH": "/home/user/.local/bin/bd",
      }
    }
  }
}

Environment Variables (all optional):

BEADS_PATH - Path to bd executable (default: ~/.local/bin/bd)
BEADS_DB - Path to beads database file (default: auto-discover from cwd)
BEADS_ACTOR - Actor name for audit trail (default: $USER)
BEADS_NO_AUTO_FLUSH - Disable automatic JSONL sync (default: false)
BEADS_NO_AUTO_IMPORT - Disable automatic JSONL import (default: false)

Features

Resource:

beads://quickstart - Quickstart guide for using beads

Tools:

init - Initialize bd in current directory
create - Create new issue (bug, feature, task, epic, chore)
list - List issues with filters (status, priority, type, assignee)
ready - Find tasks with no blockers ready to work on
show - Show detailed issue info including dependencies
update - Update issue (status, priority, design, notes, etc)
close - Close completed issue
dep - Add dependency (blocks, related, parent-child, discovered-from)
blocked - Get blocked issues
stats - Get project statistics

Development

Run MCP inspector:

# inside beads-mcp dir
uv run fastmcp dev src/beads_mcp/server.py

Type checking:

uv run mypy src/beads_mcp

Linting and formatting:

uv run ruff check src/beads_mcp
uv run ruff format src/beads_mcp

Testing

Run all tests:

uv run pytest

With coverage:

uv run pytest --cov=beads_mcp tests/

Test suite includes both mocked unit tests and integration tests with real bd CLI.