bbb-mcp-server

bbb-mcp-server

BrainBrainBrains — persistent memory + context layer for AI-assisted dev teams, exposed via the Model Context Protocol (MCP).

Store decisions, conventions, constraints, and architecture notes. Query them with full-text search. Assemble smart context for any task. Snapshot and rehydrate sessions across tools.

Quick Start

npx bbb-mcp-server --project my-project

Setup

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "bbb": {
      "command": "npx",
      "args": ["-y", "bbb-mcp-server", "--project", "my-project"]
    }
  }
}

Claude Code

claude mcp add bbb -- npx -y bbb-mcp-server --project my-project

Codex

Add to ~/.codex/config.toml:

[mcp_servers.bbb]
command = "npx"
args = ["-y", "bbb-mcp-server", "--project", "my-project"]

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "bbb": {
      "command": "npx",
      "args": ["-y", "bbb-mcp-server", "--project", "my-project"]
    }
  }
}

Tools (50)

Phase 1 — Core (17)

Memory (5)

Tool	Description
memory_store	Store a memory (decision, convention, constraint, etc.)
memory_query	Full-text search with BM25 ranking
memory_list	Paginated listing with filters
memory_update	Version-aware update (supersedes old)
memory_delete	Delete by ID

Artifacts (3)

Tool	Description
artifact_store	Store/update ADRs, PRDs, API contracts, etc.
artifact_get	Fetch by ID or search by type/title
artifact_list	Paginated listing with filters

Tasks (3)

Tool	Description
task_create	Create task with dependencies
task_update	Update status, linked artifacts
task_get_dag	Dependency graph view

Context (2)

Tool	Description
context_assemble	Smart context assembly with token budgeting
search_memories	Direct FTS5 search

Project (2)

Tool	Description
project_init	Initialize a new project
ingest_codebase	Auto-index repository files

Session (2)

Tool	Description
session_snapshot	Capture full session state
session_rehydrate	Restore snapshot + generate tool config

Phase 2 — Agent Workflows (20)

Swarm Sessions (4)

Tool	Description
swarm_session_start	Start a new swarm session in the hydrate phase
swarm_session_transition	Transition session to the next lifecycle phase
swarm_session_status	Get current status and allowed transitions
swarm_session_complete	Mark a swarm session as complete

Permissions & Approvals (5)

Tool	Description
permission_set	Set allow/deny/approval_required rules per tool and role
permission_list	List permission rules with filters
approval_request	Request approval to execute a tool
approval_respond	Approve or reject a pending request
approval_list	List pending/resolved execution requests

Audit (3)

Tool	Description
audit_query	Query audit events with filters
audit_verify	Verify audit trail integrity (SHA-256 chain)
audit_export	Export audit trail as JSON

Task Runner (4)

Tool	Description
task_decompose	Create a task DAG from a structured plan
task_execute	Mark a task as executed with results
task_batch	Batch create or update multiple tasks
task_rollback	Roll back a failed task to pending

Sandbox (4)

Tool	Description
sandbox_create	Create an E2B sandbox
sandbox_exec	Execute a command in a sandbox
sandbox_status	Get sandbox status
sandbox_destroy	Destroy a sandbox

Phase 3 — Multi-Model Orchestration (13)

Roles (4)

Tool	Description
role_register	Register an agent role with mission, model, and budget
role_list	List all registered roles
role_get	Get full role details by ID or name
role_update	Update a role's configuration

Models (2)

Tool	Description
model_register	Register an AI model with provider, capabilities, and pricing
model_list	List registered models with filters

Dispatch (1)

Tool	Description
task_dispatch	Route a task to the best model based on capabilities and strategy

Agent Comms (2)

Tool	Description
agent_message_send	Send a message between agent roles
agent_message_inbox	Get pending messages for a role

Conflicts (2)

Tool	Description
conflict_list	List detected conflicts between agent outputs
conflict_resolve	Resolve a conflict using a resolution strategy

Observability (2)

Tool	Description
cost_report	Get aggregated cost report by period, role, or model
metrics_dashboard	Get metrics dashboard with cost, latency, throughput, and error rates

How It Works

• SQLite + FTS5 — One .db file per project at ~/.bbb/data/. Full-text search with BM25 ranking. WAL mode for performance.
• Context Assembly — Extracts keywords from your task, searches memories + codebase, scores by relevance (BM25 + recency + tag overlap), and assembles a token-budgeted context block.
• Session Portability — Snapshot your entire project state and rehydrate it in any tool (Claude Code, Cursor, Claude Desktop, VS Code, Codex).
• Agent Workflows — Swarm session lifecycle, tool permissions with approval gates, SHA-256 audit chain, task decomposition/execution/rollback, and E2B sandbox integration.
• Multi-Model Orchestration — Role-based routing across Claude, GPT, and Gemini with cost-optimized/quality-optimized/balanced strategies, inter-agent messaging, conflict detection, and cost tracking.

License

MIT