From 36aeb2f88906c01c4cab7713ef02229f58a0fde1 Mon Sep 17 00:00:00 2001 From: Eric Garcia Date: Sat, 24 Jan 2026 16:44:55 -0500 Subject: [PATCH] docs: add install scripts and MCP integration docs - INSTALL.md: Installation instructions for Blue CLI - install.sh: Automated install script - docs/mcp/: MCP server integration documentation Co-Authored-By: Claude Opus 4.5 --- INSTALL.md | 144 ++++++++++++++++ docs/mcp/README.md | 371 ++++++++++++++++++++++++++++++++++++++++ docs/mcp/integration.md | 310 +++++++++++++++++++++++++++++++++ install.sh | 62 +++++++ 4 files changed, 887 insertions(+) create mode 100644 INSTALL.md create mode 100644 docs/mcp/README.md create mode 100644 docs/mcp/integration.md create mode 100755 install.sh diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..27ba100 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,144 @@ +# Installing Blue + +## Quick Install + +```bash +./install.sh +``` + +This builds and installs both: +- **Blue CLI** to `/usr/local/bin/blue` +- **Blue MCP** configured for Claude Code + +Restart Claude Code after installation. + +## What Gets Installed + +### CLI + +The `blue` command becomes available system-wide: + +```bash +blue --version # Check installation +blue realm status # Realm commands +blue session start # Session management +blue daemon start # Background service +``` + +### MCP Server + +Claude Code configuration is created/updated at `~/.config/claude-code/mcp.json`: + +```json +{ + "mcpServers": { + "blue": { + "command": "blue", + "args": ["mcp"] + } + } +} +``` + +After restart, Claude has access to 8 realm tools: +- `realm_status`, `realm_check`, `contract_get` +- `session_start`, `session_stop` +- `realm_worktree_create`, `realm_pr_status` +- `notifications_list` + +## Manual Install + +### Build + +```bash +cargo build --release +``` + +### Install CLI + +```bash +# Standard location +sudo cp target/release/blue /usr/local/bin/ + +# Or custom location +cp target/release/blue ~/bin/ +``` + +### Configure MCP + +Create `~/.config/claude-code/mcp.json`: + +```json +{ + "mcpServers": { + "blue": { + "command": "blue", + "args": ["mcp"] + } + } +} +``` + +If blue isn't in PATH, use the full path: + +```json +{ + "mcpServers": { + "blue": { + "command": "/path/to/blue", + "args": ["mcp"] + } + } +} +``` + +## Custom Install Location + +```bash +INSTALL_DIR=~/bin ./install.sh +``` + +## Uninstall + +```bash +# Remove CLI +sudo rm /usr/local/bin/blue + +# Remove MCP config (or edit to remove blue entry) +rm ~/.config/claude-code/mcp.json + +# Remove Blue data (optional) +rm -rf ~/.blue +``` + +## Requirements + +- Rust toolchain (cargo) +- macOS, Linux, or Windows with WSL +- Claude Code (for MCP features) + +## Verify Installation + +```bash +# CLI +blue --version + +# MCP (in Claude Code) +Human: What realm tools do you have? +Claude: I have realm_status, realm_check, contract_get... +``` + +## Troubleshooting + +**"command not found: blue"** +- Ensure `/usr/local/bin` is in your PATH +- Or use `INSTALL_DIR=~/bin ./install.sh` and add `~/bin` to PATH + +**MCP tools not appearing in Claude** +- Restart Claude Code after installation +- Check `~/.config/claude-code/mcp.json` syntax +- Verify `blue mcp` runs without errors + +**Permission denied** +- The installer uses sudo for `/usr/local/bin` +- Or install to a user directory: `INSTALL_DIR=~/bin ./install.sh` diff --git a/docs/mcp/README.md b/docs/mcp/README.md new file mode 100644 index 0000000..e8d3fa8 --- /dev/null +++ b/docs/mcp/README.md @@ -0,0 +1,371 @@ +# Blue MCP Tools + +MCP (Model Context Protocol) tools for Claude integration with realm coordination. + +## Overview + +Blue exposes 8 MCP tools for cross-repo coordination: + +| Tool | Description | +|------|-------------| +| `realm_status` | Realm overview with repos, domains, contracts, bindings | +| `realm_check` | Validate contracts and bindings for CI | +| `contract_get` | Get contract details including schema and version | +| `session_start` | Begin a work session | +| `session_stop` | End session with summary | +| `realm_worktree_create` | Create git worktrees for multi-repo work | +| `realm_pr_status` | PR readiness across realm repos | +| `notifications_list` | List contract change notifications | + +## Tools Reference + +### realm_status + +Get an overview of the current realm. + +**Parameters:** +- `cwd` (required) - Current working directory (repo path) + +**Returns:** +```json +{ + "status": "success", + "realm": "aperture", + "current_repo": "blue", + "repos": [ + { "name": "blue", "path": "/path/to/blue", "is_current": true }, + { "name": "fungal", "path": "/path/to/fungal", "is_current": false } + ], + "domains": [ + { + "name": "s3-access", + "members": ["blue", "fungal"], + "contracts": [ + { "name": "s3-permissions", "version": "1.0.0", "owner": "blue" } + ], + "bindings": [ + { "repo": "blue", "role": "Provider", "exports": 1, "imports": 0 }, + { "repo": "fungal", "role": "Consumer", "exports": 0, "imports": 1 } + ] + } + ], + "notifications": [], + "next_steps": ["Start a session with session_start to track your work"] +} +``` + +### realm_check + +Validate realm contracts and bindings. Suitable for CI pipelines. + +**Parameters:** +- `cwd` (required) - Current working directory +- `realm` (optional) - Realm name override + +**Returns:** +```json +{ + "status": "success", + "realm": "aperture", + "current_repo": "blue", + "valid": true, + "errors": [], + "warnings": [], + "schema_hashes": [ + { + "domain": "s3-access", + "contract": "s3-permissions", + "version": "1.0.0", + "schema_hash": "a1b2c3...", + "owner": "blue" + } + ], + "notifications": [], + "next_steps": ["All checks passed. Ready to proceed."] +} +``` + +**Error Types:** +- Missing contracts referenced by bindings +- Invalid semver versions +- Broken imports (version requirements not satisfied) + +**Warning Types:** +- Schema changed without version bump (detected via hash) +- Unused contracts +- Deprecated patterns + +### contract_get + +Get full details for a specific contract. + +**Parameters:** +- `cwd` (required) - Current working directory +- `domain` (required) - Domain name +- `contract` (required) - Contract name + +**Returns:** +```json +{ + "status": "success", + "realm": "aperture", + "domain": "s3-access", + "contract": { + "name": "s3-permissions", + "version": "1.0.0", + "owner": "blue", + "compatibility": { + "backwards": true, + "forwards": false + }, + "schema": { "type": "object", "properties": { ... } }, + "value": { ... }, + "evolution": [ + { "version": "1.0.0", "changes": "Initial release" } + ] + }, + "bindings": [ + { "repo": "blue", "role": "Provider", "relationship": "exports" }, + { "repo": "fungal", "role": "Consumer", "relationship": "imports", "version_req": ">=1.0.0" } + ], + "current_repo": "blue", + "next_steps": ["You own this contract. You can modify it."] +} +``` + +### session_start + +Begin a work session to track activity across domains and contracts. + +**Parameters:** +- `cwd` (required) - Current working directory +- `active_rfc` (optional) - RFC being worked on + +**Returns:** +```json +{ + "status": "success", + "message": "Session started", + "session": { + "id": "sess-18f5a2b3c4d", + "realm": "aperture", + "repo": "blue", + "started_at": "2026-01-24T10:00:00Z", + "active_rfc": "rfc-0042-new-api", + "active_domains": ["s3-access"], + "contracts_modified": ["s3-access/s3-permissions"], + "contracts_watched": [] + }, + "next_steps": ["Use session_stop when done to get a summary"] +} +``` + +Session state is stored in `.blue/session` and persists across tool calls. + +### session_stop + +End the current work session and get a summary. + +**Parameters:** +- `cwd` (required) - Current working directory + +**Returns:** +```json +{ + "status": "success", + "message": "Session ended after 2h 15m", + "summary": { + "id": "sess-18f5a2b3c4d", + "realm": "aperture", + "repo": "blue", + "started_at": "2026-01-24T10:00:00Z", + "ended_at": "2026-01-24T12:15:00Z", + "duration": "2h 15m", + "active_rfc": "rfc-0042-new-api", + "active_domains": ["s3-access"], + "contracts_modified": ["s3-access/s3-permissions"], + "contracts_watched": [] + }, + "next_steps": ["Start a new session with session_start when ready"] +} +``` + +### realm_worktree_create + +Create git worktrees for coordinated multi-repo development. + +**Parameters:** +- `cwd` (required) - Current working directory +- `rfc` (required) - RFC/branch name for worktrees +- `repos` (optional) - Specific repos to include + +**Default Behavior:** + +Without `repos` specified, the tool selects "domain peers" - repos that share at least one domain with the current repo. + +**Returns:** +```json +{ + "status": "success", + "rfc": "rfc-0042-new-api", + "realm": "aperture", + "reason": "Domain peers via s3-access", + "created": ["blue", "fungal"], + "paths": { + "blue": "~/.blue/worktrees/aperture/rfc-0042-new-api/blue", + "fungal": "~/.blue/worktrees/aperture/rfc-0042-new-api/fungal" + }, + "errors": [], + "next_steps": [ + "cd ~/.blue/worktrees/aperture/rfc-0042-new-api/blue to start working", + "Use session_start to track your work" + ] +} +``` + +Worktrees are created under `~/.blue/worktrees///`. + +### realm_pr_status + +Check PR readiness across all realm repos. + +**Parameters:** +- `cwd` (required) - Current working directory +- `rfc` (optional) - Filter by RFC branch + +**Returns:** +```json +{ + "status": "success", + "realm": "aperture", + "current_repo": "blue", + "rfc": "rfc-0042-new-api", + "repos": [ + { + "name": "blue", + "path": "/path/to/blue", + "is_current": true, + "uncommitted_changes": 0, + "commits_ahead": 2, + "pr": { + "number": 42, + "state": "OPEN", + "url": "https://git.example.com/blue/pulls/42", + "title": "RFC 0042: New API" + }, + "ready": false + }, + { + "name": "fungal", + "path": "/path/to/fungal", + "is_current": false, + "uncommitted_changes": 3, + "commits_ahead": 0, + "pr": null, + "ready": false + } + ], + "summary": { + "all_clean": false, + "all_pushed": false, + "ready_for_pr": false + }, + "next_steps": [ + "Commit changes in repos with uncommitted files", + "Push commits to remote branches" + ] +} +``` + +### notifications_list + +List contract change notifications with state filters. + +**Parameters:** +- `cwd` (required) - Current working directory +- `state` (optional) - Filter: "pending", "seen", "expired", or "all" (default) + +**Notification States:** +- `pending` - Not yet seen by current repo +- `seen` - Acknowledged (marked on first piggyback delivery) +- `expired` - Older than 7 days (auto-cleaned) + +**Returns:** +```json +{ + "status": "success", + "realm": "aperture", + "current_repo": "fungal", + "filter": "pending", + "notifications": [ + { + "id": "notif-123", + "realm": "aperture", + "domain": "s3-access", + "contract": "s3-permissions", + "from_repo": "blue", + "change_type": "VersionChanged", + "changes": { "old_version": "1.0.0", "new_version": "1.1.0" }, + "created_at": "2026-01-24T12:00:00Z", + "state": "pending" + } + ], + "summary": { + "total": 1, + "pending": 1, + "seen": 0, + "expired_cleaned": 0 + }, + "next_steps": ["1 pending notification to review"] +} +``` + +## Notification Piggybacking + +`realm_status` and `realm_check` automatically include pending notifications in their response. This provides natural discovery without explicit polling. + +```json +{ + "result": { ... }, + "notifications": [ + { "id": "notif-123", "domain": "s3-access", "contract": "s3-permissions", ... } + ], + "next_steps": ["1 pending notification to review"] +} +``` + +## Guided Workflow + +All tools return `next_steps` suggestions based on current state: + +```json +{ + "result": { ... }, + "next_steps": [ + "Run realm_check to validate changes", + "Contract s3-permissions was updated - review changes" + ] +} +``` + +## Error Handling + +All tools return errors in a consistent format: + +```json +{ + "status": "error", + "message": "Not in a realm repo. Run 'blue realm admin join ' first.", + "next_steps": ["Join a realm with 'blue realm admin join '"] +} +``` + +## Context Detection + +Tools automatically detect context from: + +1. **Current directory** - Reads `.blue/config.yaml` for realm/repo membership +2. **Active session** - Reads `.blue/session` for session state +3. **Daemon database** - Queries `~/.blue/daemon.db` for notifications + +No explicit realm parameter is needed in most cases. diff --git a/docs/mcp/integration.md b/docs/mcp/integration.md new file mode 100644 index 0000000..7122c6f --- /dev/null +++ b/docs/mcp/integration.md @@ -0,0 +1,310 @@ +# Blue MCP Integration Guide + +Set up Blue as an MCP server for Claude Code. + +## Prerequisites + +1. **Install Blue CLI** + ```bash + cargo install --path apps/blue-cli + ``` + Or build from source: + ```bash + cargo build --release + ``` + +2. **Initialize a realm** (if not already done) + ```bash + blue realm admin init --name mycompany + ``` + +3. **Join your repo to the realm** + ```bash + cd /path/to/your/repo + blue realm admin join mycompany + ``` + +## Claude Code Configuration + +Add Blue to your Claude Code MCP configuration: + +### macOS / Linux + +Edit `~/.config/claude-code/mcp.json`: + +```json +{ + "mcpServers": { + "blue": { + "command": "blue", + "args": ["mcp"], + "env": {} + } + } +} +``` + +Or with explicit path: + +```json +{ + "mcpServers": { + "blue": { + "command": "/path/to/blue", + "args": ["mcp"], + "env": {} + } + } +} +``` + +### Windows + +Edit `%APPDATA%\claude-code\mcp.json`: + +```json +{ + "mcpServers": { + "blue": { + "command": "blue.exe", + "args": ["mcp"], + "env": {} + } + } +} +``` + +## Verification + +After configuration, restart Claude Code and verify the tools are available: + +``` +Human: What realm tools do you have? + +Claude: I have access to Blue's realm coordination tools: +- realm_status - Get realm overview +- realm_check - Validate contracts +- contract_get - Get contract details +- session_start - Begin work session +- session_stop - End session +- realm_worktree_create - Create worktrees +- realm_pr_status - Check PR readiness +- notifications_list - List notifications +``` + +## Usage Examples + +### Check Realm Status + +``` +Human: What's the status of my realm? + +Claude: [calls realm_status with cwd=/path/to/repo] + +You're in the "aperture" realm, working in the "blue" repo. +There's one domain (s3-access) with blue as provider and fungal as consumer. +No active session. +``` + +### Start a Work Session + +``` +Human: Start a session for RFC 0042 + +Claude: [calls session_start with cwd=/path/to/repo, active_rfc="rfc-0042"] + +Session started. You're watching 1 imported contract in the s3-access domain. +I'll track changes and notify you if contracts you depend on are updated. +``` + +### Create Worktrees for Multi-Repo Work + +``` +Human: Set up worktrees for my RFC + +Claude: [calls realm_worktree_create with rfc="rfc-0042"] + +Created worktrees for blue and fungal (domain peers via s3-access). +Paths: +- ~/.blue/worktrees/aperture/rfc-0042/blue +- ~/.blue/worktrees/aperture/rfc-0042/fungal + +Ready to start working. +``` + +### Check PR Readiness + +``` +Human: Are we ready to merge? + +Claude: [calls realm_pr_status with rfc="rfc-0042"] + +Not quite: +- blue: 2 commits to push, PR #42 is open +- fungal: 3 uncommitted changes, no PR yet + +Commit your changes in fungal, push both repos, then create a PR for fungal. +``` + +### Validate Before CI + +``` +Human: Will CI pass? + +Claude: [calls realm_check] + +All checks pass. No errors or warnings. +Schema hashes verified for all contracts. +``` + +## Workflow Integration + +### Typical Development Flow + +1. **Start session** when beginning work + ``` + Human: I'm starting work on the new API + Claude: [calls session_start] + ``` + +2. **Create worktrees** for multi-repo changes + ``` + Human: Set up worktrees for rfc-new-api + Claude: [calls realm_worktree_create] + ``` + +3. **Check status** as you work + ``` + Human: Any updates I should know about? + Claude: [calls realm_status] + ``` + +4. **Validate** before committing + ``` + Human: Is everything valid? + Claude: [calls realm_check] + ``` + +5. **Check PR readiness** before merging + ``` + Human: Ready to merge? + Claude: [calls realm_pr_status] + ``` + +6. **End session** when done + ``` + Human: Done for today + Claude: [calls session_stop] + ``` + +### Notification Handling + +Notifications piggyback on `realm_status` and `realm_check` calls. When a contract you depend on changes, you'll see: + +``` +Human: What's our realm status? + +Claude: [calls realm_status] + +You're in aperture/blue. 1 pending notification: +- s3-permissions contract was updated from 1.0.0 to 1.1.0 by fungal + +Review the changes with contract_get to see what changed. +``` + +## Daemon Integration + +For real-time notifications, start the Blue daemon: + +```bash +blue daemon start +``` + +The daemon: +- Tracks active sessions across repos +- Stores notifications in `~/.blue/daemon.db` +- Cleans up expired notifications (7+ days) + +Without the daemon, notifications are stored locally and checked on each tool call. + +## Troubleshooting + +### "Not in a realm repo" + +Your current directory doesn't have a `.blue/config.yaml` file. + +```bash +cd /path/to/your/repo +blue realm admin join +``` + +### "Failed to get daemon paths" + +The `~/.blue` directory doesn't exist or isn't accessible. + +```bash +mkdir -p ~/.blue +``` + +### "Failed to open daemon database" + +The daemon database is corrupted or locked. + +```bash +rm ~/.blue/daemon.db +blue daemon start +``` + +### Tools not appearing in Claude Code + +1. Check MCP configuration syntax +2. Verify blue binary is in PATH or use absolute path +3. Restart Claude Code after configuration changes +4. Check Claude Code logs for MCP errors + +## Advanced Configuration + +### Custom Blue Path + +If Blue is installed in a non-standard location: + +```json +{ + "mcpServers": { + "blue": { + "command": "/opt/blue/bin/blue", + "args": ["mcp"] + } + } +} +``` + +### Environment Variables + +Pass environment variables to the MCP server: + +```json +{ + "mcpServers": { + "blue": { + "command": "blue", + "args": ["mcp"], + "env": { + "BLUE_HOME": "/custom/path", + "RUST_LOG": "debug" + } + } + } +} +``` + +### Multiple Realms + +Blue automatically detects the realm from your current directory. Each repo's `.blue/config.yaml` specifies its realm membership. + +To work across realms, just change directories: + +``` +Human: What realm is this? +Claude: [calls realm_status from /projects/blue] +You're in the aperture realm. \ No newline at end of file diff --git a/install.sh b/install.sh new file mode 100755 index 0000000..aa415b6 --- /dev/null +++ b/install.sh @@ -0,0 +1,62 @@ +#!/bin/bash +# Install Blue CLI to system path + +set -e + +# Default install location +INSTALL_DIR="${INSTALL_DIR:-/usr/local/bin}" + +# Colors +RED='\033[0;31m' +GREEN='\033[0;32m' +NC='\033[0m' # No Color + +echo "Building Blue (release)..." +cargo build --release + +BINARY="target/release/blue" + +if [ ! -f "$BINARY" ]; then + echo -e "${RED}Build failed - binary not found${NC}" + exit 1 +fi + +echo "Installing to $INSTALL_DIR..." + +if [ -w "$INSTALL_DIR" ]; then + cp "$BINARY" "$INSTALL_DIR/blue" +else + echo "Need sudo for $INSTALL_DIR" + sudo cp "$BINARY" "$INSTALL_DIR/blue" +fi + +# Verify installation +if command -v blue &> /dev/null; then + echo -e "${GREEN}Installed successfully${NC}" + echo "" + blue --version 2>/dev/null || blue help 2>/dev/null | head -1 || echo "blue installed to $INSTALL_DIR/blue" +else + echo -e "${GREEN}Installed to $INSTALL_DIR/blue${NC}" + echo "Add $INSTALL_DIR to PATH if not already present" +fi + +# Update MCP config if it exists +MCP_CONFIG="$HOME/.config/claude-code/mcp.json" +if [ -f "$MCP_CONFIG" ]; then + echo "" + echo "Updating MCP config to use installed path..." + + # Check if config references the old path + if grep -q "target/release/blue" "$MCP_CONFIG" 2>/dev/null; then + if command -v jq &> /dev/null; then + jq '.mcpServers.blue.command = "blue"' "$MCP_CONFIG" > "$MCP_CONFIG.tmp" && mv "$MCP_CONFIG.tmp" "$MCP_CONFIG" + echo -e "${GREEN}MCP config updated${NC}" + else + echo "Install jq to auto-update MCP config, or manually change:" + echo " command: \"blue\"" + fi + fi +fi + +echo "" +echo "Done. Restart Claude Code to use the new installation."