* fix(export): populate export_hashes after successful export (GH#1278) Child issues created with --parent were missing from export_hashes table, which affects integrity tracking and future incremental export features. This fix ensures SetExportHash() is called for all exported issues: - Updated ExportResult to include IssueContentHashes map - Updated finalizeExport() to call SetExportHash() for each exported issue - Updated exportToJSONLDeferred() to collect content hashes during export - Updated performIncrementalExport() to collect content hashes for dirty issues - Updated exportToJSONLWithStore() to call SetExportHash() after export - Updated daemon's handleExport() to call SetExportHash() after export Added test TestExportPopulatesExportHashes to verify the fix works for both regular and hierarchical (child) issue IDs. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * docs: add GitHub Copilot integration guide Add comprehensive documentation for using beads with GitHub Copilot in VS Code via the MCP server. New files: - docs/COPILOT_INTEGRATION.md - Complete setup guide with prerequisites, MCP tools reference, example workflows, troubleshooting, and FAQ - website/docs/integrations/github-copilot.md - Shorter website version Updated files: - docs/INSTALLING.md - Added GitHub Copilot row to setup matrix and new "GitHub Copilot (VS Code)" section with quick setup steps - website/docs/getting-started/ide-setup.md - Added GitHub Copilot section - website/docs/integrations/mcp-server.md - Added VS Code / GitHub Copilot configuration examples for both .vscode/mcp.json and settings.json Key clarifications: - Beads is a system-wide CLI tool installed once, not cloned into projects - The .beads/ directory only contains the issue database - Added FAQ addressing "Do I need to clone beads?" explicitly Fixes #148 * docs: add cross-platform paths for user-level VS Code MCP config Add Linux and Windows paths alongside macOS for the VS Code user-level MCP configuration. Users can now find the correct path for their platform in a simple table format. Paths by platform: - macOS: ~/Library/Application Support/Code/User/mcp.json - Linux: ~/.config/Code/User/mcp.json - Windows: %APPDATA%\Code\User\mcp.json Fixes #148 --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
3 KiB
3 KiB
| id | title | sidebar_position |
|---|---|---|
| mcp-server | MCP Server | 2 |
MCP Server
Use beads in MCP-only environments.
When to Use MCP
Use MCP server when CLI is unavailable:
- Claude Desktop (no shell access)
- Sourcegraph Amp without shell
- Other MCP-only environments
Prefer CLI + hooks when shell is available - it's more context efficient.
Installation
Using uv (Recommended)
uv tool install beads-mcp
Using pip
pip install beads-mcp
Configuration
Claude Desktop (macOS)
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"beads": {
"command": "beads-mcp"
}
}
}
Claude Desktop (Windows)
Add to %APPDATA%\Claude\claude_desktop_config.json:
{
"mcpServers": {
"beads": {
"command": "beads-mcp"
}
}
}
Sourcegraph Amp
Add to MCP settings:
{
"beads": {
"command": "beads-mcp",
"args": []
}
}
VS Code / GitHub Copilot
Create .vscode/mcp.json in your project:
{
"servers": {
"beads": {
"command": "beads-mcp"
}
}
}
For all projects: Add to VS Code user-level MCP config:
| Platform | Path |
|---|---|
| macOS | ~/Library/Application Support/Code/User/mcp.json |
| Linux | ~/.config/Code/User/mcp.json |
| Windows | %APPDATA%\Code\User\mcp.json |
{
"servers": {
"beads": {
"command": "beads-mcp",
"args": []
}
}
}
Note: Requires VS Code 1.96+ with MCP support enabled.
See GitHub Copilot Integration for complete setup guide.
Available Tools
The MCP server exposes these tools:
| Tool | Description |
|---|---|
beads_create |
Create new issue |
beads_list |
List issues |
beads_show |
Show issue details |
beads_update |
Update issue |
beads_close |
Close issue |
beads_ready |
Show ready work |
beads_sync |
Sync to git |
beads_dep_add |
Add dependency |
beads_dep_tree |
Show dependency tree |
Usage
Once configured, use naturally:
Create an issue for fixing the login bug with priority 1
The MCP server translates to appropriate bd commands.
Trade-offs
| Aspect | CLI + Hooks | MCP Server |
|---|---|---|
| Context overhead | ~1-2k tokens | 10-50k tokens |
| Latency | Direct calls | MCP protocol |
| Setup | Hooks config | MCP config |
| Availability | Shell required | MCP environments |
Troubleshooting
Server won't start
Check if beads-mcp is in PATH:
which beads-mcp
If not found:
# Reinstall
pip uninstall beads-mcp
pip install beads-mcp
Tools not appearing
- Restart Claude Desktop
- Check MCP config JSON syntax
- Verify server path
Permission errors
# Check directory permissions
ls -la .beads/
# Initialize if needed
bd init --quiet
See Also
- Claude Code - CLI integration
- Installation - Full install guide