Skip to content

MCP Integration

Jump to bottom
Lisa edited this page Dec 18, 2025 · 43 revisions

CKB MCP Integration Guide (v6.0)

CKB exposes AI-native code navigation and architectural memory capabilities via the Model Context Protocol (MCP), enabling AI assistants like Claude Code to discover, understand, and navigate codebases with persistent knowledge.

v6.0 Theme: Architectural Memory — persistent understanding of module boundaries, ownership, and design decisions v5.2 Theme: Discovery, orientation, and flow comprehension Non-goal: Code mutation, refactoring, enforcement, or policy

Quick Setup

Claude Code CLI

# Add CKB to your project (creates .mcp.json)
claude mcp add --transport stdio ckb --scope project -- /path/to/ckb mcp

# Or add globally for all projects
claude mcp add --transport stdio ckb --scope user -- /path/to/ckb mcp

# Verify configuration
claude mcp list

Manual Configuration

Add to .mcp.json in project root:

{
  "mcpServers": {
    "ckb": {
      "type": "stdio",
      "command": "/path/to/ckb",
      "args": ["mcp"],
      "env": {}
    }
  }
}

Claude Desktop

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

{
  "mcpServers": {
    "ckb": {
      "command": "/path/to/ckb",
      "args": ["mcp"],
      "cwd": "/path/to/your/repo"
    }
  }
}

Platform Contracts

Backend Budget Classification

Tools are classified by performance budget.

Cheap Tools (P95 < 300ms)

searchSymbols · explainFile · listEntrypoints · explainPath · getSymbol · explainSymbol · getOwnership · getModuleResponsibilities · recordDecision · getDecisions · annotateModule

  • Max 1 hop traversal
  • Max 50 results
  • No callgraph expansion or deep git history

Heavy Tools (P95 < 2000ms)

traceUsage · getArchitecture · getHotspots · summarizeDiff · recentlyRelevant · listKeyConcepts · analyzeImpact · getCallGraph · findReferences · justifySymbol

  • Up to depth 5 traversal
  • Up to 1000 git commits
  • Must include limitations field

Heavy Tools (P95 < 30000ms)

refreshArchitecture

  • Synchronous rebuild of architectural model
  • Blocks until complete

Confidence Rules

Condition Max confidence
Full static analysis (SCIP/LSP) 1.0
Partial static analysis 0.89
Heuristics only 0.79
Key backend missing 0.69
Multiple backends missing 0.39

Time Window Defaults

Tool Default
getHotspots 30 days
summarizeDiff 30 days
recentlyRelevant 7 days

Tools Overview

Discovery & Search

Tool Budget Purpose Status
searchSymbols Cheap Search with filtering v5.1 ✓
getSymbol Cheap Get symbol details v5.1 ✓

Flow & Runtime

Tool Budget Purpose Status
traceUsage Heavy How is this reached? v5.2 ✓
listEntrypoints Cheap System entrypoints v5.2 ✓
getCallGraph Heavy Caller/callee graph v5.1 ✓

File Navigation

Tool Budget Purpose Status
explainFile Cheap File orientation v5.2 ✓
explainPath Cheap Path role explanation v5.2 ✓

Change Awareness

Tool Budget Purpose Status
summarizeDiff Heavy What changed? v5.2 ✓

System Orientation

Tool Budget Purpose Status
getArchitecture Heavy Architecture overview v5.2 ✓
getHotspots Heavy Volatile areas with trends v6.0 ✓
listKeyConcepts Heavy Domain concepts v5.2 ✓
recentlyRelevant Heavy What matters now? v5.2 ✓
getModuleOverview Heavy Module statistics v5.1 ✓
getModuleResponsibilities Cheap Module purpose & capabilities v6.0 ✓

Symbol Analysis

Tool Budget Purpose Status
explainSymbol Cheap AI-friendly explanation v5.1 ✓
justifySymbol Heavy Keep/remove verdict v5.1 ✓
findReferences Heavy Find all usages v5.1 ✓
analyzeImpact Heavy Change risk v5.1 ✓

Ownership (v6.0)

Tool Budget Purpose Status
getOwnership Cheap Who owns this code? v6.0 ✓

Architectural Decisions (v6.0)

Tool Budget Purpose Status
recordDecision Cheap Create an ADR v6.0 ✓
getDecisions Cheap Query ADRs v6.0 ✓
annotateModule Cheap Add module metadata v6.0 ✓
refreshArchitecture Heavy Rebuild architectural model v6.0 ✓

System

Tool Budget Purpose Status
getStatus Cheap System health v5.1 ✓
doctor Cheap Diagnostics v5.1 ✓

v5.2 New Tools

traceUsage

Show how something is reached (causal paths, not neighbors).

Budget: Heavy

{ "symbolId": "...", "maxPaths": 10, "pathTypes": ["api", "cli"] }

Path types: api | cli | job | event | test | unknown

Differs from getCallGraph: Returns ranked paths from entrypoints, not local neighborhood.

listEntrypoints

List system entrypoints.

Budget: Cheap

{ "types": ["api", "cli"], "limit": 30 }

Entrypoint types: api | cli | job | event

Detection basis: naming | framework-config | static-call

explainFile

File-level orientation.

Budget: Cheap

{ "filePath": "internal/query/engine.go" }

Output: File role, top symbols (max 15), imports/exports, local hotspots.

explainPath

Why does this path exist?

Budget: Cheap

{ "filePath": "internal/legacy/handler.go", "contextHint": "from traceUsage" }

Role classifications: core | glue | legacy | test-only | config | unknown

summarizeDiff

What changed, what might break?

Budget: Heavy

{ "prId": "123" }
// or
{ "commitRange": { "base": "main", "head": "feature" } }
// or
{ "commit": "abc123" }
// or
{ "timeWindow": { "start": "2025-12-01", "end": "2025-12-17" } }

Output: Files touched, risk signals, suggested tests.

Not allowed: Code suggestions, refactor plans.

getArchitecture

Conservative architectural overview.

Budget: Heavy

{ "depth": 2, "includeExternalDeps": false }

Hard caps: 15–20 modules, 50 edges max.

getHotspots

Highlight volatile areas.

Budget: Heavy

{ "timeWindow": { "days": 30 }, "scope": "internal/query", "limit": 20 }

Ranking signals: churn, coupling, recency

listKeyConcepts

Main domain concepts in the codebase.

Budget: Heavy

{ "limit": 12 }

Output per concept:

  • label: "Auth", "Billing", etc.
  • evidence: Top 3–5 modules/symbols
  • basis: naming | cluster | entrypoints

recentlyRelevant

What should I care about now?

Budget: Heavy

{ "timeWindow": { "days": 7 }, "moduleFilter": "internal/api" }

Ranking signals: churn, fanIn, hasOpenChanges

v5.1 Implemented Tools

searchSymbols

{ "query": "Handler", "kinds": ["function"], "scope": "internal/api", "limit": 50 }

getSymbol

{ "symbolId": "...", "repoStateMode": "head" }

findReferences

{ "symbolId": "...", "scope": "internal/mcp", "includeTests": true, "limit": 100 }

explainSymbol

{ "symbolId": "..." }

Output: Name, kind, signature, usage stats, git history, related symbols.

justifySymbol

{ "symbolId": "..." }

Verdicts: keep | investigate | remove

getCallGraph

{ "symbolId": "...", "direction": "both", "depth": 2 }

getModuleOverview

{ "path": "internal/query" }

analyzeImpact

{ "symbolId": "...", "depth": 3 }

getStatus

{}

doctor

{}

Navigation Presets

Preset Focus
onboarding Broad, concept-first
bug-investigation Trace-focused, recent changes
refactor-safety Coupling and hotspots
review Diff-centric, risk signals

Recommended Workflows

New Codebase

getStatus() → listKeyConcepts() → getArchitecture() → listEntrypoints() → searchSymbols()

Bug Investigation

searchSymbols() → traceUsage() → getCallGraph() → recentlyRelevant()

Before Changes

searchSymbols() → explainSymbol() → findReferences() → analyzeImpact() → getHotspots()

Code Review

summarizeDiff() → getHotspots() → getOwnership() → traceUsage()

Dead Code

searchSymbols() → justifySymbol() → explainFile()

Understanding Module Ownership (v6.0)

getArchitecture() → getOwnership() → getModuleResponsibilities()

Recording Design Decisions (v6.0)

getDecisions() → recordDecision() → annotateModule()

Risk Assessment (v6.0)

getHotspots() → getOwnership() → summarizeDiff()

Error Codes

Code Fix
SYMBOL_NOT_FOUND Use searchSymbols() first
BACKEND_UNAVAILABLE Check getStatus()
INDEX_STALE Run scip-go
QUERY_TIMEOUT Add scope/limit
BUDGET_EXCEEDED Use cheaper tool

What CKB Does NOT Do

  • ❌ Code mutation/refactoring
  • ❌ Test generation
  • ❌ Fix suggestions
  • ❌ Policy enforcement
  • ❌ Lint judgments

Navigation and comprehension only.

v6.0 Architectural Memory Tools

getOwnership

Query ownership for a path, module, or symbol.

Budget: Cheap

{ "path": "internal/api/handler.go" }
// or
{ "moduleId": "internal/api" }
// or
{ "symbolId": "...", "includeHistory": true }

Output:

  • owners: List of owners with scope (maintainer/reviewer/contributor)
  • source: "codeowners" | "git-blame" | "declared"
  • suggestedReviewers: Recommended PR reviewers
  • history: Ownership changes over time (if includeHistory: true)

Sources: CODEOWNERS file (confidence: 1.0), git blame (confidence: 0.79)

getModuleResponsibilities

Query what a module is responsible for.

Budget: Cheap

{ "moduleId": "internal/query", "includeSymbols": true }

Output per module:

  • summary: One-sentence description
  • capabilities: What the module provides
  • keySymbols: Important exports (if includeSymbols: true)
  • confidence: How certain we are
  • source: "declared" | "inferred" | "llm-generated"

recordDecision

Create an Architectural Decision Record (ADR).

Budget: Cheap

{
  "title": "Use SCIP for code indexing",
  "context": "We need fast, accurate symbol resolution...",
  "decision": "We will use SCIP indexes generated by scip-go...",
  "consequences": ["Requires index regeneration on code changes", "..."],
  "affectedModules": ["internal/backends/scip"],
  "status": "proposed"
}

Output:

  • id: Assigned ADR ID (e.g., "ADR-001")
  • path: File path to the ADR markdown file
  • status: "created" | "updated"

getDecisions

Query architectural decisions.

Budget: Cheap

{ "moduleId": "internal/query", "status": ["accepted"], "search": "caching" }

Filters:

  • moduleId: ADRs affecting a specific module
  • status: Filter by status (proposed/accepted/deprecated/superseded)
  • search: Full-text search in title and content

annotateModule

Add or update module metadata.

Budget: Cheap

{
  "moduleId": "internal/api",
  "responsibility": "HTTP API handlers and middleware",
  "owner": "@api-team",
  "tags": ["core", "api"]
}

Output:

  • status: "created" | "updated"
  • changes: List of fields that changed

refreshArchitecture

Rebuild the architectural model from sources.

Budget: Heavy (up to 30s)

{ "scope": "all", "force": true, "dryRun": false }

Scope options:

  • all: Refresh everything
  • modules: Only module detection
  • ownership: Only CODEOWNERS + git-blame
  • hotspots: Only hotspot snapshots
  • responsibilities: Only responsibility extraction

Output:

  • status: "completed" | "skipped"
  • changes: Count of updates per category
  • duration: Time taken

Enhanced getHotspots (v6.0)

Now includes historical trends and module-level aggregation.

New fields in response:

{
  "hotspots": [{
    "targetId": "internal/query/engine.go",
    "score": 0.85,
    "trend": {
      "direction": "increasing",
      "velocity": 0.02,
      "projection30d": 0.91
    },
    "metrics": {
      "churnCommits30d": 12,
      "churnAuthors30d": 3,
      "complexityCyclomatic": 25
    }
  }]
}

Implementation Status

v5.1 ✓

searchSymbols, getSymbol, findReferences, explainSymbol, justifySymbol, getCallGraph, getModuleOverview, analyzeImpact, getStatus, doctor

v5.2 ✓ (Complete)

All v5.2 tools are now implemented:

Phase 1: explainFile, traceUsage, listEntrypoints

Phase 2: summarizeDiff

Phase 3: getHotspots, getArchitecture

Phase 4: explainPath, listKeyConcepts, recentlyRelevant

v6.0 ✓ (Complete - Architectural Memory)

All v6.0 tools are implemented:

Phase 1: getArchitecture (enhanced), refreshArchitecture

Phase 2: getOwnership

Phase 3: getHotspots (enhanced with trends), getModuleResponsibilities

Phase 4: recordDecision, getDecisions, annotateModule

Total: 25 MCP tools available

Troubleshooting

Server won't start

which ckb
echo '{"jsonrpc":"2.0","id":1,"method":"initialize"}' | ckb mcp

No tools available

ls -la .ckb/
ckb init

Stale results

scip-go --repository-root=.
ckb doctor

Clone this wiki locally