Prepare for public launch: comprehensive examples, docs, and tooling
This commit adds everything needed for a successful public launch: **New Documentation** - SECURITY.md: Security policy and best practices - CLAUDE.md: Complete agent instructions for contributing to beads - Enhanced README with pain points, FAQ, troubleshooting sections - Added Taskwarrior to comparison table with detailed explanation **Installation** - install.sh: One-liner installation script with platform detection - Auto-detects OS/arch, tries go install, falls back to building from source - Updated README with prominent installation instructions **Examples** (2,268+ lines of working code) - examples/python-agent/: Full Python implementation of agent workflow - examples/bash-agent/: Shell script agent with colorized output - examples/git-hooks/: Pre-commit, post-merge, post-checkout hooks with installer - examples/claude-desktop-mcp/: Documentation for future MCP server integration - examples/README.md: Overview of all examples **Dogfooding** - Initialized bd in beads project itself (.beads/beads.db) - Created issues for roadmap (MCP server, migrations, demos, 1.0 milestone) - Exported to .beads/issues.jsonl for git versioning **Visual Assets** - Added screenshot showing agent using beads to README intro - Placed in .github/images/ following GitHub conventions This addresses all launch readiness items: ✅ Security policy ✅ Working agent examples (Python, Bash) ✅ Git hooks for automation ✅ FAQ addressing skeptics ✅ Troubleshooting common issues ✅ Easy installation ✅ Dogfooding our own tool ✅ Pain points that create urgency Ready to ship! 🚀 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Steve Yegge
208
examples/claude-desktop-mcp/README.md
Normal file
208
examples/claude-desktop-mcp/README.md
Normal file
@@ -0,0 +1,208 @@
|
||||
# Claude Desktop MCP Server for Beads
|
||||
|
||||
> **Note**: This is a reference implementation showing how to integrate bd with Claude Desktop via MCP (Model Context Protocol).
|
||||
|
||||
## What This Provides
|
||||
|
||||
An MCP server that exposes bd functionality to Claude Desktop, allowing Claude to:
|
||||
- Query ready work
|
||||
- Create and update issues
|
||||
- Manage dependencies
|
||||
- Track discovered work
|
||||
|
||||
## Implementation Status
|
||||
|
||||
This is a **documentation stub** showing the intended integration pattern. Full implementation coming soon!
|
||||
|
||||
## Planned Features
|
||||
|
||||
```typescript
|
||||
// MCP server will expose these tools to Claude:
|
||||
|
||||
// Find ready work
|
||||
{
|
||||
"name": "beads_ready_work",
|
||||
"description": "Find issues with no blocking dependencies",
|
||||
"parameters": {
|
||||
"limit": "number",
|
||||
"priority": "number (0-4)",
|
||||
"assignee": "string"
|
||||
}
|
||||
}
|
||||
|
||||
// Create issue
|
||||
{
|
||||
"name": "beads_create_issue",
|
||||
"description": "Create a new issue",
|
||||
"parameters": {
|
||||
"title": "string",
|
||||
"description": "string",
|
||||
"priority": "number (0-4)",
|
||||
"type": "bug|feature|task|epic|chore"
|
||||
}
|
||||
}
|
||||
|
||||
// Update issue
|
||||
{
|
||||
"name": "beads_update_issue",
|
||||
"description": "Update issue status or fields",
|
||||
"parameters": {
|
||||
"id": "string",
|
||||
"status": "open|in_progress|blocked|closed",
|
||||
"priority": "number",
|
||||
"assignee": "string"
|
||||
}
|
||||
}
|
||||
|
||||
// Add dependency
|
||||
{
|
||||
"name": "beads_add_dependency",
|
||||
"description": "Link issues with dependencies",
|
||||
"parameters": {
|
||||
"from": "string (issue ID)",
|
||||
"to": "string (issue ID)",
|
||||
"type": "blocks|related|parent-child|discovered-from"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## How It Would Work
|
||||
|
||||
1. Install the MCP server for Claude Desktop
|
||||
2. Claude gains access to bd commands
|
||||
3. During coding sessions, Claude can:
|
||||
- Check for ready work: "What should I work on next?"
|
||||
- Create issues: "I found a bug, let me track it"
|
||||
- Link discoveries: "This is related to the issue we're working on"
|
||||
- Update status: "Marking bd-5 as completed"
|
||||
|
||||
## Example Conversation
|
||||
|
||||
```
|
||||
User: What's ready to work on?
|
||||
|
||||
Claude: Let me check the ready work queue...
|
||||
[Calls beads_ready_work()]
|
||||
|
||||
I found 3 ready issues:
|
||||
1. bd-12: Fix authentication bug (priority 0, bug)
|
||||
2. bd-15: Add dark mode toggle (priority 1, feature)
|
||||
3. bd-18: Update documentation (priority 2, task)
|
||||
|
||||
Which would you like to work on?
|
||||
|
||||
User: Let's do bd-12
|
||||
|
||||
Claude: Great! I'll mark bd-12 as in progress.
|
||||
[Calls beads_update_issue("bd-12", status="in_progress")]
|
||||
|
||||
Let me investigate the authentication code...
|
||||
[Works on the issue]
|
||||
|
||||
I found the bug in auth.js:45 - there's a race condition. While fixing this, I noticed we're also missing rate limiting. Should I track that as a separate issue?
|
||||
|
||||
User: Yes please
|
||||
|
||||
Claude: [Calls beads_create_issue("Add rate limiting to auth endpoints", type="task", priority=1)]
|
||||
Created bd-23: Add rate limiting to auth endpoints
|
||||
|
||||
[Calls beads_add_dependency("bd-23", "bd-12", type="discovered-from")]
|
||||
Linked bd-23 as discovered from bd-12
|
||||
|
||||
Now I'll complete the auth bug fix...
|
||||
```
|
||||
|
||||
## Implementation Guide
|
||||
|
||||
To implement this MCP server:
|
||||
|
||||
1. Create a Node.js/TypeScript project
|
||||
2. Use the MCP SDK: `npm install @anthropic/mcp-sdk`
|
||||
3. Implement tool handlers that call `bd` commands via child_process
|
||||
4. Register with Claude Desktop's config
|
||||
|
||||
Example skeleton:
|
||||
|
||||
```typescript
|
||||
import { Server } from "@anthropic/mcp-sdk";
|
||||
import { exec } from "child_process";
|
||||
import { promisify } from "util";
|
||||
|
||||
const execAsync = promisify(exec);
|
||||
|
||||
const server = new Server({
|
||||
name: "beads",
|
||||
version: "1.0.0"
|
||||
});
|
||||
|
||||
// Register ready work tool
|
||||
server.tool("beads_ready_work", async (params) => {
|
||||
const { stdout } = await execAsync(
|
||||
`bd ready --json --limit ${params.limit || 10}`
|
||||
);
|
||||
return JSON.parse(stdout);
|
||||
});
|
||||
|
||||
// Register create issue tool
|
||||
server.tool("beads_create_issue", async (params) => {
|
||||
const { stdout } = await execAsync(
|
||||
`bd create "${params.title}" -d "${params.description}" -p ${params.priority} -t ${params.type} --json`
|
||||
);
|
||||
return JSON.parse(stdout);
|
||||
});
|
||||
|
||||
// ... more tools ...
|
||||
|
||||
server.start();
|
||||
```
|
||||
|
||||
## Installation (Future)
|
||||
|
||||
```bash
|
||||
# Install the MCP server
|
||||
npm install -g beads-mcp-server
|
||||
|
||||
# Configure Claude Desktop
|
||||
# Add to ~/Library/Application Support/Claude/claude_desktop_config.json
|
||||
{
|
||||
"mcpServers": {
|
||||
"beads": {
|
||||
"command": "beads-mcp-server",
|
||||
"args": []
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
# Restart Claude Desktop
|
||||
```
|
||||
|
||||
## Alternative: Direct bd Usage
|
||||
|
||||
Until the MCP server is available, you can instruct Claude to use bd directly:
|
||||
|
||||
```markdown
|
||||
# In your CLAUDE.md or project instructions:
|
||||
|
||||
We use Beads (bd) for issue tracking. Available commands:
|
||||
|
||||
- `bd ready --json` - Find ready work
|
||||
- `bd create "title" -p 1 -t bug --json` - Create issue
|
||||
- `bd update bd-1 --status in_progress --json` - Update status
|
||||
- `bd dep add bd-2 bd-1 --type discovered-from` - Link issues
|
||||
- `bd close bd-1 --reason "Done" --json` - Complete work
|
||||
|
||||
All commands support --json for parsing. Please use bd to track work during our sessions.
|
||||
```
|
||||
|
||||
## Contributing
|
||||
|
||||
Interested in building this MCP server? We welcome contributions!
|
||||
|
||||
See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.
|
||||
|
||||
## See Also
|
||||
|
||||
- [MCP Documentation](https://docs.anthropic.com/claude/docs/model-context-protocol)
|
||||
- [MCP SDK](https://github.com/anthropics/mcp-sdk)
|
||||
- [Claude Desktop](https://claude.ai/desktop)
|
||||
- [../python-agent/](../python-agent/) - Python implementation pattern
|
||||
Reference in New Issue
Block a user