beads/website/docs/integrations/mcp-server.md
Scott Nixon 18f47fe8b6
docs: add GitHub Copilot integration guide with cross-platform MCP paths (#1348)
* 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>
2026-01-27 11:25:14 -08:00

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