Skip to content

MCP Integration

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

CKB MCP Integration Guide (v6.2)

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.2 Theme: Federation — cross-repository queries and unified organizational visibility v6.1 Theme: Production-ready architectural memory with background jobs and CI/CD integration 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 · listFederations · federationStatus · federationRepos

  • 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 · federationSearchModules · federationSearchOwnership · federationGetHotspots · federationSearchDecisions · federationSync

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

Heavy Tools (P95 < 30000ms)

refreshArchitecture · summarizePr · getOwnershipDrift

  • refreshArchitecture: Supports async mode (v6.1) — returns jobId for polling
  • summarizePr: Analyze PR changes, suggest reviewers, assess risk
  • getOwnershipDrift: Compare CODEOWNERS vs actual git-blame ownership

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 ✓

Background Jobs (v6.1)

Tool Budget Purpose Status
getJobStatus Cheap Query job by ID v6.1 ✓
listJobs Cheap List jobs with filters v6.1 ✓
cancelJob Cheap Cancel queued/running job v6.1 ✓

CI/CD Integration (v6.1)

Tool Budget Purpose Status
summarizePr Heavy PR risk analysis & reviewers v6.1 ✓
getOwnershipDrift Heavy CODEOWNERS vs actual ownership v6.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()

CI/CD Integration (v6.1)

summarizePr() → getOwnershipDrift() → getHotspots()

Background Refresh (v6.1)

refreshArchitecture({ async: true }) → getJobStatus() → [poll until complete]

Cross-Repo Analysis (v6.2)

listFederations() → federationStatus() → federationSearchModules() → federationGetHotspots()

Organization-Wide Review (v6.2)

federationSearchOwnership() → federationSearchDecisions() → federationSync()

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
    }
  }]
}

v6.1 New Tools

getJobStatus

Query status and result of a background job.

Budget: Cheap

{ "jobId": "job-abc123" }

Output:

  • id: Job identifier
  • type: Job type (e.g., "refresh-architecture")
  • status: "queued" | "running" | "completed" | "failed" | "cancelled"
  • progress: 0-100 percentage
  • result: Job-specific result (when completed)
  • error: Error message (when failed)

listJobs

List jobs with optional filters.

Budget: Cheap

{ "status": "running", "type": "refresh-architecture", "limit": 20 }

Filters:

  • status: Filter by job status
  • type: Filter by job type
  • limit: Max results (default: 20)

cancelJob

Cancel a queued or running job.

Budget: Cheap

{ "jobId": "job-abc123" }

Output:

  • cancelled: true if job was cancelled
  • status: Final job status

refreshArchitecture (Enhanced in v6.1)

Now supports async mode for long-running operations.

Budget: Heavy (sync) / Cheap (async)

{ "scope": "all", "force": true, "async": true }

New async fields:

  • async: Set to true to run in background
  • Response includes jobId when async

Usage pattern:

1. refreshArchitecture({ async: true }) → { jobId: "..." }
2. getJobStatus({ jobId }) → { status: "running", progress: 50 }
3. getJobStatus({ jobId }) → { status: "completed", result: {...} }

summarizePr

Analyze a pull request for risk, affected modules, and suggested reviewers.

Budget: Heavy

{ "baseBranch": "main", "headBranch": "feature/my-feature" }
// or
{ "baseBranch": "main" }  // uses current branch as head

Output:

  • filesChanged: Number of files modified
  • linesAdded / linesRemoved: Change volume
  • modulesAffected: List of affected module IDs
  • hotspotsTouched: Hotspots in changed files
  • suggestedReviewers: Recommended reviewers from ownership data
  • riskAssessment: "low" | "medium" | "high"
  • riskFactors: Reasons for the risk level

Risk factors considered:

  • Hotspot files touched
  • Number of modules affected
  • Breaking API changes
  • Missing test coverage

getOwnershipDrift

Compare declared ownership (CODEOWNERS) vs actual ownership (git-blame).

Budget: Heavy

{ "scope": "internal/api", "threshold": 0.3, "limit": 20 }

Parameters:

  • scope: Module or path to analyze (optional, defaults to all)
  • threshold: Minimum drift score to include (0.0-1.0, default: 0.3)
  • limit: Max results (default: 20)

Output per drifted file:

  • path: File path
  • declaredOwner: Owner from CODEOWNERS
  • actualOwners: Top contributors from git-blame
  • driftScore: 0.0 (no drift) to 1.0 (complete drift)
  • recommendation: Suggested action

Use cases:

  • Audit CODEOWNERS accuracy
  • Find stale ownership assignments
  • Identify knowledge silos

v6.2 Federation Tools

Federation enables cross-repository queries and unified visibility. See Federation for full documentation.

listFederations

List all available federations.

Budget: Cheap

{}

Output:

  • federations: Array of federation names
  • count: Total number of federations

federationStatus

Get detailed status of a federation including repos, compatibility, and sync state.

Budget: Cheap

{ "federation": "platform" }

Output:

  • name: Federation name
  • description: Federation description
  • createdAt: Creation timestamp
  • repoCount: Number of repos
  • repos: Array of repo configs
  • compatibility: Compatible vs incompatible repo counts

federationRepos

List repositories in a federation with paths, tags, and optional compatibility status.

Budget: Cheap

{ "federation": "platform", "includeCompatibility": true }

Output:

  • repos: Array of repo configs with UUID, ID, path, tags
  • count: Total repos
  • compatibility: Optional schema compatibility checks

federationSearchModules

Search for modules across all repositories in a federation.

Budget: Heavy

{
  "federation": "platform",
  "query": "authentication",
  "repos": ["api", "auth"],
  "tags": ["security"],
  "limit": 20
}

Parameters:

  • federation: Federation name (required)
  • query: FTS search query
  • repos: Optional repo ID filter
  • tags: Optional tag filter
  • limit: Max results (default: 50)

Output:

  • modules: Array of module results with repoId, moduleId, name, responsibility, owner
  • total: Result count
  • staleness: Federation-wide staleness info

federationSearchOwnership

Search for ownership patterns across all repositories.

Budget: Heavy

{
  "federation": "platform",
  "path": "**/api/**",
  "repos": ["api", "web"],
  "limit": 50
}

Parameters:

  • federation: Federation name (required)
  • path: Glob pattern to match
  • repos: Optional repo ID filter
  • limit: Max results (default: 50)

Output:

  • matches: Array of ownership matches with pattern, owners, scope, source, confidence
  • total: Result count
  • staleness: Federation-wide staleness info

federationGetHotspots

Get merged hotspots across all repositories in the federation.

Budget: Heavy

{
  "federation": "platform",
  "repos": ["api"],
  "top": 20,
  "minScore": 0.3
}

Parameters:

  • federation: Federation name (required)
  • repos: Optional repo ID filter
  • top: Number of top hotspots (default: 20)
  • minScore: Minimum score threshold (default: 0.3)

Output:

  • hotspots: Array of hotspots with repoId, targetId, score, churn, complexity, coupling
  • total: Result count
  • staleness: Federation-wide staleness info

federationSearchDecisions

Search for architectural decisions (ADRs) across all repositories.

Budget: Heavy

{
  "federation": "platform",
  "query": "database",
  "status": ["accepted"],
  "repos": ["api"],
  "module": "persistence",
  "limit": 50
}

Parameters:

  • federation: Federation name (required)
  • query: FTS search query
  • status: Status filter (proposed, accepted, deprecated, superseded)
  • repos: Optional repo ID filter
  • module: Filter by affected module
  • limit: Max results (default: 50)

Output:

  • decisions: Array of decisions with repoId, decisionId, title, status, affectedModules
  • total: Result count
  • staleness: Federation-wide staleness info

federationSync

Sync federation index from repository data.

Budget: Heavy

{
  "federation": "platform",
  "force": true,
  "dryRun": false,
  "repos": ["api"]
}

Parameters:

  • federation: Federation name (required)
  • force: Force sync even if data is fresh
  • dryRun: Preview what would be synced
  • repos: Optional specific repos to sync (default: all)

Output:

  • results: Per-repo sync results with modulesSynced, ownershipSynced, hotspotsSynced, decisionsSynced
  • summary: Overall success/failed/skipped counts

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

v6.1 ✓ (Complete - Production Ready)

All v6.1 tools are implemented:

Background Jobs: getJobStatus, listJobs, cancelJob

Async Operations: refreshArchitecture now supports async: true mode

CI/CD Integration: summarizePr, getOwnershipDrift

v6.2 ✓ (Complete - Federation)

All v6.2 tools are implemented:

Federation Management: listFederations, federationStatus, federationRepos, federationSync

Cross-Repo Queries: federationSearchModules, federationSearchOwnership, federationGetHotspots, federationSearchDecisions

Total: 38 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