ruvector/crates/mcp-brain

mcp-brain

MCP (Model Context Protocol) server for the RuVector Shared Brain. Enables Claude Code sessions to share and discover learning across sessions via stdio JSON-RPC.

This is the client-side MCP server that runs locally alongside Claude Code. It communicates with the mcp-brain-server backend deployed on Cloud Run at π.ruv.io.

Architecture

┌──────────────┐     stdio      ┌──────────────┐     HTTPS     ┌─────────────────┐
│  Claude Code │ ◄────────────► │  mcp-brain   │ ────────────► │ mcp-brain-server│
│  (client)    │   JSON-RPC     │  (MCP server)│   REST API    │ (π.ruv.io)      │
└──────────────┘                └──────────────┘               └─────────────────┘

MCP Tools (20)

Core (10)

Tool	Description
brain_share	Share a learning with the collective (PII-stripped, embedded, witnessed)
brain_search	Semantic search with hybrid ranking (keyword + cosine + graph + AGI)
brain_get	Retrieve a memory with full provenance and witness chain
brain_vote	Upvote/downvote a memory (Bayesian quality update)
brain_transfer	Cross-domain transfer learning (Thompson Sampling)
brain_drift	Check knowledge drift (coefficient of variation, trend)
brain_partition	MinCut graph partitioning with coherence scores
brain_list	List recent memories by category/quality
brain_delete	Delete own contribution
brain_status	System health and diagnostics
brain_sync	Sync local MicroLoRA weights with federated consensus

Brainpedia (5)

Tool	Description
brain_page_create	Create a Draft page (requires reputation >= 0.5)
brain_page_get	Get page with delta log and evidence
brain_page_delta	Submit correction/extension/deprecation delta
brain_page_deltas	List page modification history
brain_page_evidence	Add verifiable evidence (test_pass, build_success, etc.)
brain_page_promote	Promote Draft to Canonical (quality + evidence gates)

WASM Executable Nodes (5)

Tool	Description
brain_node_list	List published WASM nodes
brain_node_publish	Publish a WASM node with conformance vectors
brain_node_get	Get node metadata
brain_node_wasm	Download WASM binary (base64)
brain_node_revoke	Revoke a node (publisher only)

Installation

As a Claude Code MCP Server

# Add to Claude Code's MCP configuration
claude mcp add brain -- cargo run --release --manifest-path /path/to/ruvector/crates/mcp-brain/Cargo.toml

# Or with a custom backend URL
claude mcp add brain -- env BRAIN_URL=https://your-backend.run.app cargo run --release --manifest-path /path/to/ruvector/crates/mcp-brain/Cargo.toml

Build from Source

cd crates/mcp-brain
cargo build --release

# Binary at: target/release/mcp-brain

Run Directly

# Uses default backend (ruvbrain Cloud Run)
cargo run --release

# With custom backend
BRAIN_URL=http://localhost:8080 BRAIN_API_KEY=test-key cargo run --release

Configuration

Env Var	Default	Description
BRAIN_URL	https://ruvbrain-875130704813.us-central1.run.app	Backend REST API URL
BRAIN_API_KEY	anonymous	API key for authentication
RUST_LOG	info	Log level (logs to stderr)

Usage Examples

Once connected as an MCP server, Claude Code can use the tools directly:

# Share knowledge
brain_share({
  "category": "pattern",
  "title": "Rust error handling with thiserror",
  "content": "Use thiserror for library errors, anyhow for applications...",
  "tags": ["rust", "error-handling"]
})

# Search
brain_search({ "query": "rust error handling patterns", "limit": 5 })

# Vote on quality
brain_vote({ "id": "uuid-here", "direction": "up" })

# Check system status
brain_status({})

# Cross-domain transfer
brain_transfer({ "source_domain": "rust", "target_domain": "go" })

Protocol

The server implements MCP over stdio using JSON-RPC 2.0:

• Transport: stdin/stdout (one JSON object per line)
• Methods: initialize, tools/list, tools/call, ping
• Logging: stderr only (stdout is reserved for JSON-RPC)

Example Session

→ {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}
← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"mcp-brain","version":"0.1.0"}}}

→ {"jsonrpc":"2.0","id":2,"method":"tools/list"}
← {"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"brain_share",...},...]}}

→ {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"brain_search","arguments":{"query":"rust patterns"}}}
← {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"[{\"title\":\"...\"}]"}]}}

Dependencies

Crate	Purpose
tokio	Async runtime (stdio + HTTP)
reqwest	HTTPS client to backend
serde / serde_json	JSON-RPC serialization
sha3	SHAKE-256 witness hashing
ruvector-sona	Local SONA learning engine
regex-lite	PII detection (client-side)
tracing	Structured logging

Deployment

With npx ruvector

The mcp-brain functionality is also available via the npm package:

npx ruvector brain search "rust patterns"
npx ruvector brain share --category pattern --title "My Pattern" --content "..."
npx ruvector brain status

As a Standalone Binary

# Build
cd crates/mcp-brain
cargo build --release

# Install system-wide
cp target/release/mcp-brain /usr/local/bin/

# Run as MCP server (Claude Code will connect via stdio)
mcp-brain

Docker (for CI/CD integration)

FROM rust:1.77-bookworm AS builder
WORKDIR /app
COPY . .
RUN cargo build --release -p mcp-brain

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
COPY --from=builder /app/target/release/mcp-brain /usr/local/bin/
CMD ["mcp-brain"]

Related

• mcp-brain-server — Cloud Run backend (axum REST API)
• npx ruvector — npm CLI with brain commands
• ADR-059 — Shared Brain architecture
• ADR-062 — Brainpedia
• ADR-063 — WASM nodes
• ADR-076 — AGI capability wiring
• ADR-077 — Midstream integration

License

MIT