Commit Graph

9 Commits

Author SHA1 Message Date
Aarya Reddy
e58d60b802 feat(mcp): add output control parameters for token efficiency (#667)
Add granular control over MCP tool response sizes to minimize context
window usage while maintaining full functionality when needed.

## Output Control Parameters

### Read Operations (ready, list, show, blocked)
- `brief`: Return BriefIssue {id, title, status, priority} (~97% smaller)
- `fields`: Custom field projection with validation - invalid fields raise ValueError
- `max_description_length`: Truncate descriptions to N chars with "..."
- `brief_deps`: Full issue but dependencies as BriefDep (~48% smaller)

### Write Operations (create, update, close, reopen)
- `brief`: Return OperationResult {id, action, message} (~97% smaller)
- Default is brief=True for minimal confirmations

## Token Savings

| Operation | Before | After (brief) | Reduction |
|-----------|--------|---------------|-----------|
| ready(limit=10) | ~20KB | ~600B | 97% |
| list(limit=20) | ~40KB | ~800B | 98% |
| show() | ~2KB | ~60B | 97% |
| show() with 5 deps | ~4.5KB | ~2.3KB | 48% |
| blocked() | ~10KB | ~240B | 98% |
| create() response | ~2KB | ~50B | 97% |

## New Models

- BriefIssue: Ultra-minimal issue (4 fields, ~60B)
- BriefDep: Compact dependency (5 fields, ~70B)
- OperationResult: Write confirmation (3 fields, ~50B)
- OperationAction: Literal["created", "updated", "closed", "reopened"]

## Best Practices

- Unified `brief` parameter naming across all operations
- `brief=True` always means "give me less data"
- Field validation with clear error messages listing valid fields
- All parameters optional with backwards-compatible defaults
- Progressive disclosure: scan cheap, detail on demand

---

## Filtering Parameters (aligns MCP with CLI)

Add missing filter parameters to `list` and `ready` tools that were
documented in MCP instructions but not implemented.

### ReadyWorkParams - New Fields
- `labels: list[str]` - AND filter: must have ALL specified labels
- `labels_any: list[str]` - OR filter: must have at least one
- `unassigned: bool` - Filter to only unassigned issues
- `sort_policy: str` - Sort by: hybrid (default), priority, oldest

### ListIssuesParams - New Fields
- `labels: list[str]` - AND filter: must have ALL specified labels
- `labels_any: list[str]` - OR filter: must have at least one
- `query: str` - Search in title (case-insensitive substring)
- `unassigned: bool` - Filter to only unassigned issues

### CLI Flag Mappings

| MCP Parameter | ready CLI Flag | list CLI Flag |
|---------------|----------------|---------------|
| labels | --label (repeated) | --label (repeated) |
| labels_any | --label-any (repeated) | --label-any (repeated) |
| query | N/A | --title |
| unassigned | --unassigned | --no-assignee |
| sort_policy | --sort | N/A |

---

## Documentation & Testing

### get_tool_info() Updates
- Added `brief`, `brief_deps`, `fields`, `max_description_length` to show tool
- Added `brief` parameter docs for create, update, close, reopen
- Added `brief`, `brief_deps` parameter docs for blocked

### Test Coverage (16 new tests)
- `test_create_brief_default` / `test_create_brief_false`
- `test_update_brief_default` / `test_update_brief_false`
- `test_close_brief_default` / `test_close_brief_false`
- `test_reopen_brief_default`
- `test_show_brief` / `test_show_fields_projection` / `test_show_fields_invalid`
- `test_show_max_description_length` / `test_show_brief_deps`
- `test_list_brief` / `test_ready_brief` / `test_blocked_brief`

---

## Backward Compatibility

All new parameters are optional with sensible defaults:
- `brief`: False for reads, True for writes
- `fields`, `max_description_length`: None (no filtering/truncation)
- `labels`, `labels_any`, `query`: None (no filtering)
- `unassigned`: False (include all)
- `sort_policy`: None (use default hybrid sort)

Existing MCP tool calls continue to work unchanged.
2025-12-20 21:33:38 -08:00
Steve Yegge
e1d40733c6 feat(mcp): Consolidate context tools into unified 'context' tool
Merge set_context, where_am_i, and init into a single 'context' tool
with action parameter (set, show, init).

- set: Set the workspace root directory (default when workspace_root provided)
- show: Show current workspace context (default when no args)
- init: Initialize beads in the current workspace directory

This reduces tool count from 3 to 1 while maintaining all functionality.

Closes beads-eub

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-20 01:57:56 -08:00
Steve Yegge
ed4630092e fix(beads-mcp): resolve all mypy type checking errors
- Add mypy override in pyproject.toml to relax strict typing for test files
- Update test fixtures to use _connection_pool instead of deprecated _client
- Fix datetime type mismatches in test fixtures (use datetime objects, not strings)
- Add type annotations to inner functions in test_multi_project_switching.py
- Fix union type handling in test assertions with isinstance checks

Reduces mypy errors from 216 to 0. All 168 tests still pass.

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

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-26 21:54:23 -08:00
Steve Yegge
d97df21a65 Fix MCP server integration tests - add env variable propagation
- Fix BdCliClient._run_command() to pass BEADS_DIR/BEADS_DB env vars to subprocess
- Update temp_db fixture to create .beads in workspace and return .beads dir path
- Update mcp_client fixture to use beads_dir and enable BEADS_NO_DAEMON mode
- Simplify test_init_tool to work with connection pool architecture

Result: All 19 integration tests now pass (was 19 failing)
Amp-Thread-ID: https://ampcode.com/threads/T-c1da2a55-f086-4284-9c85-0dfa4c479cf9
Co-authored-by: Amp <amp@ampcode.com>
2025-11-07 19:27:22 -08:00
Steve Yegge
0e8936bf61 Fix test failures: update to new AddDependencyParams field names
- Update tests to use issue_id/depends_on_id instead of from_id/to_id
- Fix test_client_lazy_initialization to mock create_bd_client instead of BdClient
- Add workspace setup for lazy initialization test
- Fixes 2 test failures (now 123 passing, down from 121)

Amp-Thread-ID: https://ampcode.com/threads/T-71b3ce65-87cb-451a-a30d-162d76d92f9c
Co-authored-by: Amp <amp@ampcode.com>
2025-11-07 19:07:49 -08:00
Steve Yegge
4f1d1a2cca Fix MCP dep tool parameter names to match CLI (issue_id/depends_on_id)
- Changed from confusing from_id/to_id to clear issue_id/depends_on_id
- Matches CLI convention: bd dep add [issue-id] [depends-on-id]
- Updated all tests and implementations
- Fixes GH #113 where Claude Code was creating dependencies backwards

Closes bd-58

Amp-Thread-ID: https://ampcode.com/threads/T-f01aca11-a10f-4908-9ce6-7e1734f2068f
Co-authored-by: Amp <amp@ampcode.com>
2025-10-23 13:07:44 -07:00
Steve Yegge
b40de9bc41 Implement daemon RPC with per-request context routing (bd-115)
- Added per-request storage routing in daemon server
  - Server now supports Cwd field in requests for database discovery
  - Tree-walking to find .beads/*.db from any working directory
  - Storage caching for performance across requests

- Created Python daemon client (bd_daemon_client.py)
  - RPC over Unix socket communication
  - Implements full BdClientBase interface
  - Auto-discovery of daemon socket from working directory

- Refactored bd_client.py with abstract interface
  - BdClientBase abstract class for common interface
  - BdCliClient for CLI-based operations (renamed from BdClient)
  - create_bd_client() factory with daemon/CLI fallback
  - Backwards-compatible BdClient alias

Next: Update MCP server to use daemon client when available
2025-10-17 16:28:29 -07:00
Baishampayan Ghose
32a718dacd feat(mcp): Add reopen command support for closed issues
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`.
2025-10-16 12:01:04 -07:00
Baishampayan Ghose
1b1380e6c3 feat: Add Beads MCP Server [bd-5]
Implements MCP server for beads issue tracker, exposing all bd CLI functionality to MCP clients like Claude Desktop.

Features:
- Complete bd command coverage (init, create, list, ready, show, update, close, dep, blocked, stats)
- Type-safe Pydantic models with validation
- Comprehensive test suite (unit + integration tests)
- Production-ready Python package structure
- Environment variable configuration support
- Quickstart resource (beads://quickstart)

Ready for PyPI publication after real-world testing.

Co-authored-by: ghoseb <baishampayan.ghose@gmail.com>
2025-10-14 11:13:52 -07:00