32a718dacd
Implements the `bd` reopen command across the entire MCP stack, enabling agents to reopen closed issues with optional reason tracking for audit trails. This addresses the need to handle regressions and incorrectly closed issues without manual `bd` CLI intervention. The reopen command is more explicit than `bd update --status open` and emits a dedicated Reopened event in the audit log, making it easier to track why issues were reopened during analysis. Changes: - `models.py`: Add ReopenIssueParams with issue_ids list and optional reason - `bd_client.py`: Implement reopen() method with JSON response parsing - `tools.py`: Add beads_reopen_issue() wrapper with Annotated types for MCP - `server.py`: Register 'reopen' MCP tool with description and parameters Testing (10 new): - `test_bd_client.py`: 4 unit tests (mocked subprocess) - `test_bd_client_integration.py`: 3 integration tests (real `bd` CLI) - `test_mcp_server_integration.py`: 3 MCP integration tests (FastMCP Client) - `test_tools.py`: 3 tools wrapper tests (mocked BdClient) Also updated `README.md`.
117 lines
2.5 KiB
Markdown
117 lines
2.5 KiB
Markdown
# beads-mcp
|
|
|
|
MCP server for [beads](https://github.com/steveyegge/beads) issue tracker and agentic memory system.
|
|
Enables AI agents to manage tasks using bd CLI through Model Context Protocol.
|
|
|
|
## Installing
|
|
|
|
Install from PyPI:
|
|
|
|
```bash
|
|
# Using uv (recommended)
|
|
uv tool install beads-mcp
|
|
|
|
# Or using pip
|
|
pip install beads-mcp
|
|
```
|
|
|
|
Add to your Claude Desktop config:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"beads": {
|
|
"command": "beads-mcp"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Development Installation
|
|
|
|
For development, clone the repository:
|
|
|
|
```bash
|
|
git clone https://github.com/steveyegge/beads
|
|
cd beads/integrations/beads-mcp
|
|
uv sync
|
|
```
|
|
|
|
Then use in Claude Desktop config:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"beads": {
|
|
"command": "uv",
|
|
"args": [
|
|
"--directory",
|
|
"/path/to/beads-mcp",
|
|
"run",
|
|
"beads-mcp"
|
|
]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**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_WORKING_DIR` - Working directory for bd commands (default: `$PWD` or 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 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
|
|
- `reopen` - Reopen a closed issue with optional reason
|
|
|
|
|
|
## Development
|
|
|
|
Run MCP inspector:
|
|
```bash
|
|
# inside beads-mcp dir
|
|
uv run fastmcp dev src/beads_mcp/server.py
|
|
```
|
|
|
|
Type checking:
|
|
```bash
|
|
uv run mypy src/beads_mcp
|
|
```
|
|
|
|
Linting and formatting:
|
|
```bash
|
|
uv run ruff check src/beads_mcp
|
|
uv run ruff format src/beads_mcp
|
|
```
|
|
|
|
## Testing
|
|
|
|
Run all tests:
|
|
```bash
|
|
uv run pytest
|
|
```
|
|
|
|
With coverage:
|
|
```bash
|
|
uv run pytest --cov=beads_mcp tests/
|
|
```
|
|
|
|
Test suite includes both mocked unit tests and integration tests with real `bd` CLI.
|