Files

Steve Yegge 3b5b4842ff fix: Replace sys.exit() with exception in config validation

Fixes MCP server hanging when bd executable is not found at default path.

Problem:
- Config validation used sys.exit(1) on failure
- sys.exit() hangs in async MCP server context (doesn't properly terminate)
- Default bd path was hardcoded to ~/.local/bin/bd

Solution:
1. Use shutil.which() to find bd in PATH before falling back to default
2. Raise ConfigError instead of calling sys.exit()
3. MCP server now properly fails with error message instead of hanging

This fixes the multi-minute hang when trying to use MCP tools if bd is
installed in a non-default location (e.g., /usr/local/bin/bd).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-10-14 16:10:52 -07:00

src/beads_mcp

fix: Replace sys.exit() with exception in config validation

2025-10-14 16:10:52 -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.