* 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>
186 lines
3 KiB
Markdown
186 lines
3 KiB
Markdown
---
|
|
id: mcp-server
|
|
title: MCP Server
|
|
sidebar_position: 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)
|
|
|
|
```bash
|
|
uv tool install beads-mcp
|
|
```
|
|
|
|
### Using pip
|
|
|
|
```bash
|
|
pip install beads-mcp
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### Claude Desktop (macOS)
|
|
|
|
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"beads": {
|
|
"command": "beads-mcp"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Claude Desktop (Windows)
|
|
|
|
Add to `%APPDATA%\Claude\claude_desktop_config.json`:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"beads": {
|
|
"command": "beads-mcp"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Sourcegraph Amp
|
|
|
|
Add to MCP settings:
|
|
|
|
```json
|
|
{
|
|
"beads": {
|
|
"command": "beads-mcp",
|
|
"args": []
|
|
}
|
|
}
|
|
```
|
|
|
|
### VS Code / GitHub Copilot
|
|
|
|
Create `.vscode/mcp.json` in your project:
|
|
|
|
```json
|
|
{
|
|
"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` |
|
|
|
|
```json
|
|
{
|
|
"servers": {
|
|
"beads": {
|
|
"command": "beads-mcp",
|
|
"args": []
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Note:** Requires VS Code 1.96+ with MCP support enabled.
|
|
|
|
See [GitHub Copilot Integration](/integrations/github-copilot) 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:
|
|
|
|
```bash
|
|
which beads-mcp
|
|
```
|
|
|
|
If not found:
|
|
|
|
```bash
|
|
# Reinstall
|
|
pip uninstall beads-mcp
|
|
pip install beads-mcp
|
|
```
|
|
|
|
### Tools not appearing
|
|
|
|
1. Restart Claude Desktop
|
|
2. Check MCP config JSON syntax
|
|
3. Verify server path
|
|
|
|
### Permission errors
|
|
|
|
```bash
|
|
# Check directory permissions
|
|
ls -la .beads/
|
|
|
|
# Initialize if needed
|
|
bd init --quiet
|
|
```
|
|
|
|
## See Also
|
|
|
|
- [Claude Code](/integrations/claude-code) - CLI integration
|
|
- [Installation](/getting-started/installation) - Full install guide
|