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 <noreply@anthropic.com>
This commit is contained in:
Eric Garcia
parent
8f0063683f
commit
36aeb2f889
4 changed files with 887 additions and 0 deletions
144
INSTALL.md
Normal file
144
INSTALL.md
Normal file
|
|
@ -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`
|
||||||
371
docs/mcp/README.md
Normal file
371
docs/mcp/README.md
Normal file
|
|
@ -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>/<rfc>/`.
|
||||||
|
|
||||||
|
### 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 <realm>' first.",
|
||||||
|
"next_steps": ["Join a realm with 'blue realm admin join <realm-name>'"]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 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.
|
||||||
310
docs/mcp/integration.md
Normal file
310
docs/mcp/integration.md
Normal file
|
|
@ -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 <realm-name>
|
||||||
|
```
|
||||||
|
|
||||||
|
### "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.
|
||||||
62
install.sh
Executable file
62
install.sh
Executable file
|
|
@ -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."
|
||||||
Loading…
Reference in a new issue