Files

Steve Yegge 584608a14e feat: add llms.txt standard support for AI agent discoverability (#784 )

Cherry-picked website/, scripts/generate-llms-full.sh, and deploy-docs.yml
from joyshmitz's PR. Fixed workflow to trigger on main branch instead of
docs/docusaurus-site.

Features:
- Docusaurus documentation site with llms.txt support
- Environment-variable driven config (defaults to steveyegge org)
- Automated llms-full.txt generation from docs
- GitHub Pages deployment workflow

Co-authored-by: joyshmitz <joyshmitz@users.noreply.github.com>

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Executed-By: beads/crew/dave
Rig: beads
Role: crew

2025-12-30 18:27:50 -08:00

2.4 KiB

Raw Blame History

id, title, sidebar_position

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": []
  }
}

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

2.4 KiB Raw Blame History