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 (Architectural Memory)

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