b40de9bc41
- 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
115 lines
3.4 KiB
Markdown
115 lines
3.4 KiB
Markdown
# Context Management for Multi-Repo Support
|
|
|
|
## Problem
|
|
|
|
MCP servers don't receive working directory context from AI clients (Claude Code/Amp), causing database routing issues:
|
|
|
|
1. MCP server process starts with its own CWD
|
|
2. `bd` uses tree-walking to discover databases based on CWD
|
|
3. Without correct CWD, `bd` discovers wrong database or falls back to `~/.beads`
|
|
4. Result: Issues get misrouted across repositories
|
|
|
|
## Current Implementation (Partial Solution)
|
|
|
|
We've added two new MCP tools to allow explicit context management:
|
|
|
|
### Tools
|
|
|
|
#### `set_context`
|
|
Sets the workspace root directory for all bd operations.
|
|
|
|
**Parameters:**
|
|
- `workspace_root` (string): Absolute path to workspace/project root directory
|
|
|
|
**Returns:**
|
|
Confirmation message with resolved paths (workspace root and database)
|
|
|
|
**Behavior:**
|
|
1. Resolves to git repo root if inside a git repository
|
|
2. Walks up directory tree to find `.beads/*.db`
|
|
3. Sets `BEADS_WORKING_DIR`, `BEADS_DB`, and `BEADS_CONTEXT_SET` environment variables
|
|
|
|
#### `where_am_i`
|
|
Shows current workspace context and database path for debugging.
|
|
|
|
**Returns:**
|
|
Current context information including workspace root, database path, and actor
|
|
|
|
### Write Operation Protection
|
|
|
|
All write operations (`create`, `update`, `close`, `reopen`, `dep`, `init`) are decorated with `@require_context`.
|
|
|
|
**Enforcement:** Only enforced when `BEADS_REQUIRE_CONTEXT=1` environment variable is set.
|
|
This allows backward compatibility while adding safety for multi-repo setups.
|
|
|
|
## Limitations
|
|
|
|
**Environment Variable Persistence:** FastMCP's architecture doesn't guarantee environment variables persist between tool calls. This means:
|
|
|
|
- `set_context` sets env vars for that tool call
|
|
- Subsequent tool calls may not see those env vars
|
|
- Context needs to be re-established for each session
|
|
|
|
## Recommended Usage
|
|
|
|
### For Single Repository (Current Default)
|
|
No changes needed. The MCP server works as before with auto-discovery.
|
|
|
|
### For Multiple Repositories (Future)
|
|
|
|
**Option 1: Explicit Database Path (Current Workaround)**
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"beads-repo1": {
|
|
"command": "uvx",
|
|
"args": ["beads-mcp"],
|
|
"env": {
|
|
"BEADS_DB": "/path/to/repo1/.beads/prefix.db"
|
|
}
|
|
},
|
|
"beads-repo2": {
|
|
"command": "uvx",
|
|
"args": ["beads-mcp"],
|
|
"env": {
|
|
"BEADS_DB": "/path/to/repo2/.beads/prefix.db"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Option 2: Client-Side Context Management (Future)**
|
|
AI clients would need to:
|
|
1. Call `set_context` at session start with workspace root
|
|
2. MCP protocol would need to support persistent session state
|
|
|
|
**Option 3: Daemon with RPC (Future - Path 1.5 from bd-105)**
|
|
- Add `cwd` parameter to daemon RPC protocol
|
|
- Daemon performs tree-walking per request
|
|
- MCP server passes workspace_root via RPC
|
|
- Benefits: Centralized routing, supports multiple contexts per daemon
|
|
|
|
**Option 4: Advanced Routing Daemon (Future - Path 2 from bd-105)**
|
|
For >50 repos:
|
|
- Dedicated routing daemon with repo→DB mappings
|
|
- MCP becomes thin shim
|
|
- Enables shared connection pooling, cross-repo queries
|
|
|
|
## Testing
|
|
|
|
The context management tools are tested in:
|
|
- `tests/test_mcp_server_integration.py`: MCP tool tests
|
|
- Manual testing: See `/tmp/test-repo-{1,2}` example
|
|
|
|
Run tests:
|
|
```bash
|
|
uv run pytest tests/test_mcp_server_integration.py -v
|
|
```
|
|
|
|
## Future Work
|
|
|
|
See [bd-105](https://github.com/steveyegge/beads/issues/105) for full architectural analysis and roadmap.
|
|
|
|
Priority: P0/P1 - Active data corruption risk in multi-repo setups.
|