blue/docs/mcp

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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.

{
  "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:

{
  "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:

{
  "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.