74b460b298
This PR fixes three bugs that prevented the MCP plugin from working:
1. **Fixed parameter name mismatch in tools.py**
- Changed `workspace_root=workspace_root` to `working_dir=workspace_root`
- The `create_bd_client()` function expects `working_dir` parameter,
but tools.py was passing `workspace_root`
- This caused "got an unexpected keyword argument 'workspace_root'" error
2. **Added version check guard for daemon client**
- Added `hasattr(_client, '_check_version')` check before calling
- BdDaemonClient doesn't have `_check_version()` method, only BdCliClient does
- This caused "'BdDaemonClient' object has no attribute '_check_version'" error
3. **Implemented proper daemon socket detection for fallback**
- Added synchronous socket file existence check before creating daemon client
- Walks up directory tree looking for `.beads/bd.sock` file
- Only creates daemon client if socket exists, otherwise falls back to CLI
- Previously, daemon client was created but failed on first method call
- This enables the documented "prefer_daemon with automatic CLI fallback" behavior
**Testing:**
- Verified MCP tools work correctly with single-repo setup
- Confirmed automatic fallback to CLI when daemon isn't running
- Tested on macOS with bd v0.9.9
**Related Issues:**
- Addresses symptoms similar to #65 (Windows BEADS_WORKING_DIR issue)
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
Install from PyPI:
# Using uv (recommended)
uv tool install beads-mcp
# Or using pip
pip install beads-mcp
Add to your Claude Desktop config:
{
"mcpServers": {
"beads": {
"command": "beads-mcp"
}
}
}
Development Installation
For development, clone the repository:
git clone https://github.com/steveyegge/beads
cd beads/integrations/beads-mcp
uv sync
Then use in Claude Desktop config:
{
"mcpServers": {
"beads": {
"command": "uv",
"args": [
"--directory",
"/path/to/beads-mcp",
"run",
"beads-mcp"
]
}
}
}
Environment Variables (all optional):
BEADS_USE_DAEMON- Use daemon RPC instead of CLI (default:1, set to0to disable)BEADS_PATH- Path to bd executable (default:~/.local/bin/bd)BEADS_DB- Path to beads database file (default: auto-discover from cwd)BEADS_WORKING_DIR- Working directory for bd commands (default:$PWDor current directory)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 directorycreate- 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 onshow- Show detailed issue info including dependenciesupdate- Update issue (status, priority, design, notes, etc)close- Close completed issuedep- Add dependency (blocks, related, parent-child, discovered-from)blocked- Get blocked issuesstats- Get project statisticsreopen- Reopen a closed issue with optional reason
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.
Multi-Repo Integration Test
Test daemon RPC with multiple repositories:
# Start the daemon first
cd /path/to/beads
./bd daemon start
# Run multi-repo test
cd integrations/beads-mcp
uv run python test_multi_repo.py
This test verifies that the daemon can handle operations across multiple repositories simultaneously using per-request context routing.