Skip to content

MCP Integration

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

MCP Integration Guide

CKB exposes code intelligence capabilities via the Model Context Protocol (MCP), enabling AI assistants like Claude Code to understand and navigate codebases.

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 ~/.claude.json (per-project) or .mcp.json (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"
    }
  }
}

Tools Overview

Tool Purpose Primary Use Case
searchSymbols Find symbols by name "Find all handlers in the codebase"
getSymbol Get symbol details "What does UserService do?"
findReferences Find all usages "Where is this function called?"
getArchitecture Module overview "How is this codebase structured?"
analyzeImpact Change risk analysis "What breaks if I change this?"
explainSymbol AI-friendly summary "Explain this symbol to me"
justifySymbol Keep/remove verdict "Is this code still needed?"
getCallGraph Caller/callee graph "What calls this function?"
getModuleOverview Module statistics "How active is this package?"
getStatus System health "Is CKB working?"
doctor Diagnostics "Why isn't CKB working?"

Core Navigation Tools

searchSymbols

Search for symbols by name with optional filtering.

Parameters:

Name Type Required Default Description
query string Yes - Search query (substring match, case-insensitive)
scope string No - Module ID to limit search scope
kinds string[] No - Symbol kinds: function, method, class, interface, variable, constant
limit number No 20 Maximum results

Use Cases:

Scenario Arguments
Find HTTP handlers { "query": "Handler", "kinds": ["function", "method"], "limit": 50 }
Find classes in module { "query": "", "scope": "internal/api", "kinds": ["class"] }
Quick symbol lookup { "query": "NewServer" }

Example Response:

{
  "symbols": [
    {
      "stableId": "scip-go gomod ckb ... `pkg/path`/Symbol().",
      "name": "NewServer",
      "kind": "function",
      "score": 100,
      "location": { "fileId": "internal/api/server.go", "startLine": 42 },
      "visibility": { "visibility": "public", "confidence": 0.9 }
    }
  ],
  "totalCount": 15,
  "truncated": true
}

getSymbol

Get detailed metadata for a specific symbol by its stable ID.

Parameters:

Name Type Required Default Description
symbolId string Yes - Stable symbol ID from search results
repoStateMode string No head head (committed only) or full (include uncommitted)

Use Cases:

Scenario Arguments
Get symbol details { "symbolId": "scip-go gomod ckb ..." }
Include uncommitted { "symbolId": "...", "repoStateMode": "full" }

Example Response:

{
  "symbol": {
    "stableId": "scip-go gomod ckb ...",
    "name": "SearchSymbols",
    "kind": "method",
    "signature": "func (e *Engine) SearchSymbols(ctx context.Context, opts SearchSymbolsOptions) (*SearchSymbolsResponse, error)",
    "containerName": "Engine",
    "documentation": "SearchSymbols finds symbols matching the query",
    "location": { "fileId": "internal/query/engine.go", "startLine": 156 },
    "moduleId": "internal/query",
    "visibility": { "visibility": "public", "confidence": 0.9 }
  }
}

findReferences

Find all references to a symbol across the codebase.

Parameters:

Name Type Required Default Description
symbolId string Yes - Stable symbol ID
scope string No - Module ID to limit search
includeTests boolean No false Include test file references
merge string No prefer-first Backend merge: prefer-first or union
limit number No 100 Maximum references

Use Cases:

Scenario Arguments
Find all callers { "symbolId": "..." }
Include test usages { "symbolId": "...", "includeTests": true }
Search in module { "symbolId": "...", "scope": "internal/mcp" }

Example Response:

{
  "references": [
    {
      "kind": "call",
      "location": { "fileId": "cmd/ckb/serve.go", "startLine": 45 },
      "context": "server := api.NewServer(engine, logger)",
      "isTest": false
    }
  ],
  "totalCount": 12,
  "truncated": false
}

getArchitecture

Get codebase architecture with module dependencies.

Parameters:

Name Type Required Default Description
depth number No 2 Dependency traversal depth
includeExternalDeps boolean No false Include external dependencies
refresh boolean No false Force cache refresh

Use Cases:

Scenario Arguments
Codebase overview {}
Deep analysis { "depth": 4, "includeExternalDeps": true }

Example Response:

{
  "modules": [
    {
      "moduleId": "internal/query",
      "name": "query",
      "path": "internal/query",
      "symbolCount": 245,
      "fileCount": 12
    }
  ],
  "dependencyGraph": [
    { "from": "internal/api", "to": "internal/query", "kind": "import", "strength": 15 }
  ]
}

analyzeImpact

Analyze the blast radius of changing a symbol.

Parameters:

Name Type Required Default Description
symbolId string Yes - Stable symbol ID to analyze
depth number No 2 Transitive impact depth

Use Cases:

Scenario Arguments
Before refactoring { "symbolId": "..." }
Deep impact analysis { "symbolId": "...", "depth": 4 }

Example Response:

{
  "directImpact": [
    {
      "stableId": "...",
      "name": "handleSearch",
      "kind": "function",
      "distance": 1,
      "moduleId": "internal/api"
    }
  ],
  "transitiveImpact": [
    { "name": "ServeHTTP", "distance": 2 }
  ],
  "riskScore": {
    "score": 0.65,
    "level": "medium",
    "explanation": "Changes affect 3 modules with 12 direct dependents",
    "factors": [
      { "name": "publicAPI", "value": 0.8 },
      { "name": "crossModule", "value": 0.6 }
    ]
  }
}

AI Navigation Tools

These tools are optimized for AI assistants to quickly understand code.

explainSymbol

Get an AI-friendly explanation of a symbol including usage patterns, history, and summary.

Parameters:

Name Type Required Description
symbolId string Yes Stable symbol ID to explain

Example Response:

{
  "symbolId": "...",
  "name": "SearchSymbols",
  "kind": "method",
  "summary": "Core search function that finds symbols by name across the codebase",
  "signature": "func (e *Engine) SearchSymbols(...) (*SearchSymbolsResponse, error)",
  "documentation": "SearchSymbols finds symbols matching the query...",
  "usageStats": {
    "referenceCount": 8,
    "callerCount": 5,
    "testCoverage": true
  },
  "history": {
    "lastModified": "2025-12-15",
    "recentCommits": 3,
    "authors": ["alice", "bob"]
  },
  "relatedSymbols": [
    { "name": "SearchSymbolsOptions", "kind": "struct", "relationship": "parameter" }
  ]
}

justifySymbol

Get a keep/investigate/remove verdict for dead code detection.

Parameters:

Name Type Required Description
symbolId string Yes Stable symbol ID to analyze

Verdicts:

  • keep - Symbol is actively used, well-tested
  • investigate - Low usage, may need review
  • remove - Appears to be dead code

Example Response:

{
  "symbolId": "...",
  "name": "OldHandler",
  "verdict": "investigate",
  "confidence": 0.75,
  "reasoning": [
    "Only 2 references found",
    "No test coverage",
    "Not modified in 6 months"
  ],
  "usageEvidence": {
    "referenceCount": 2,
    "callerModules": ["internal/api"],
    "isExported": true,
    "hasTests": false
  },
  "recommendation": "Review usage in internal/api - may be dead code"
}

getCallGraph

Get a lightweight call graph showing callers and callees.

Parameters:

Name Type Required Default Description
symbolId string Yes - Root symbol for the graph
direction string No both callers, callees, or both
depth number No 1 Traversal depth (1-4)

Use Cases:

Scenario Arguments
What calls this? { "symbolId": "...", "direction": "callers" }
What does this call? { "symbolId": "...", "direction": "callees" }
Full graph depth 2 { "symbolId": "...", "direction": "both", "depth": 2 }

Example Response:

{
  "root": {
    "symbolId": "...",
    "name": "SearchSymbols",
    "kind": "method"
  },
  "callers": [
    {
      "symbolId": "...",
      "name": "handleSearch",
      "kind": "function",
      "depth": 1
    }
  ],
  "callees": [
    {
      "symbolId": "...",
      "name": "searchSCIP",
      "kind": "method",
      "depth": 1
    }
  ]
}

getModuleOverview

Get a high-level overview of a module including statistics and activity.

Parameters:

Name Type Required Description
path string No Path to module directory
name string No Friendly name for the module

Example Response:

{
  "moduleId": "internal/query",
  "name": "query",
  "path": "internal/query",
  "stats": {
    "fileCount": 12,
    "symbolCount": 245,
    "linesOfCode": 3500,
    "publicSymbols": 45,
    "privateSymbols": 200
  },
  "activity": {
    "lastModified": "2025-12-16",
    "commitsLast30Days": 15,
    "activeContributors": 3
  },
  "topSymbols": [
    { "name": "Engine", "kind": "struct", "referenceCount": 89 }
  ],
  "dependencies": ["internal/backends", "internal/storage"],
  "dependents": ["internal/api", "internal/mcp"]
}

System Tools

getStatus

Get CKB system status.

Parameters: None

Example Response:

{
  "status": "healthy",
  "healthy": true,
  "backends": [
    {
      "id": "scip",
      "available": true,
      "healthy": true,
      "capabilities": ["symbol-search", "find-references"],
      "details": { "symbolCount": 2915 }
    }
  ],
  "cache": {
    "queriesCached": 45,
    "hitRate": 0.85
  },
  "repoState": {
    "dirty": true,
    "headCommit": "abc123"
  }
}

doctor

Run diagnostic checks and get suggested fixes.

Parameters: None

Example Response:

{
  "healthy": false,
  "checks": [
    {
      "name": "SCIP Index",
      "status": "warning",
      "message": "SCIP index is stale",
      "fixes": ["scip-go --repository-root=."]
    }
  ]
}

Recommended Workflows

Understanding a New Codebase

1. getStatus()           → Verify CKB is healthy
2. getArchitecture()     → See module structure
3. getModuleOverview()   → Understand key modules
4. searchSymbols()       → Find entry points

Before Making Changes

1. searchSymbols("TargetFunction")  → Find the symbol
2. getSymbol(symbolId)              → Get full details
3. findReferences(symbolId)         → Find all usages
4. analyzeImpact(symbolId)          → Assess risk
5. getCallGraph(symbolId)           → Understand call flow

Dead Code Detection

1. searchSymbols(query, kinds=["function"])  → Find candidates
2. justifySymbol(symbolId)                    → Get verdict
3. explainSymbol(symbolId)                    → Understand context

Troubleshooting

Server won't start

# Check CKB is installed
which ckb

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

No tools available

# Verify CKB is initialized
ls -la .ckb/

# Initialize if needed
ckb init

Stale results

# Regenerate SCIP index
scip-go --repository-root=.

# Check diagnostics
ckb doctor

Error Codes

Code Description Fix
SYMBOL_NOT_FOUND Invalid symbol ID Use searchSymbols() first
BACKEND_UNAVAILABLE Backend not running Check getStatus()
INDEX_STALE SCIP needs refresh Run scip-go
QUERY_TIMEOUT Query too slow Add scope/limit

Performance Tips

  1. Use limit - Don't fetch more than needed
  2. Use scope - Limit to relevant modules
  3. Start with getStatus() - Skip if backends unhealthy
  4. Cache symbol IDs - Reuse across queries
  5. Prefer prefer-first - Faster than union

Clone this wiki locally