MCP Tools Reference

Complete documentation for all 86 CKB MCP tools. For setup instructions, see MCP-Integration.

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 ✓

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 (single symbol)	v5.1 ✓
`analyzeChange`	Heavy	Change risk (git diff)	v7.5 ✓

See Impact-Analysis for comprehensive documentation on both tools.

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 with remediation	v8.0 ✓
`doctor`	Cheap	Diagnostics	v5.1 ✓
`reindex`	Cheap	Index refresh guidance	v8.0 ✓

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 ✓

Daemon Mode (v6.2.1)

Tool	Budget	Purpose	Status
`daemonStatus`	Cheap	Daemon health and stats	v6.2.1 ✓
`listSchedules`	Cheap	List scheduled tasks	v6.2.1 ✓
`runSchedule`	Cheap	Run a schedule immediately	v6.2.1 ✓
`listWebhooks`	Cheap	List configured webhooks	v6.2.1 ✓
`testWebhook`	Cheap	Send test webhook	v6.2.1 ✓
`webhookDeliveries`	Cheap	Get delivery history	v6.2.1 ✓

Tree-sitter Complexity (v6.2.2)

Tool	Budget	Purpose	Status
`getFileComplexity`	Cheap	Cyclomatic/cognitive complexity metrics	v6.2.2 ✓

Contract Analysis (v6.3)

Tool	Budget	Purpose	Status
`listContracts`	Cheap	List contracts in federation	v6.3 ✓
`analyzeContractImpact`	Heavy	Analyze impact of contract changes	v6.3 ✓
`getContractDependencies`	Heavy	Get contract deps for a repo	v6.3 ✓
`suppressContractEdge`	Cheap	Suppress false positive edge	v6.3 ✓
`verifyContractEdge`	Cheap	Verify an edge	v6.3 ✓
`getContractStats`	Cheap	Contract statistics	v6.3 ✓

Runtime Telemetry (v6.4)

Tool	Budget	Purpose	Status
`getTelemetryStatus`	Cheap	Coverage metrics and sync status	v6.4 ✓
`getObservedUsage`	Cheap	Usage data for a symbol	v6.4 ✓
`findDeadCodeCandidates`	Heavy	Find symbols with zero runtime calls	v6.4 ✓

Developer Intelligence (v6.5)

Tool	Budget	Purpose	Status
`explainOrigin`	Cheap	Why does this code exist? (origin, evolution, warnings)	v6.5 ✓
`analyzeCoupling`	Heavy	Find files/symbols that change together	v6.5 ✓
`exportForLLM`	Heavy	LLM-friendly codebase export	v6.5 ✓
`auditRisk`	Heavy	Multi-signal risk audit (8 factors)	v6.5 ✓

Doc-Symbol Linking (v7.3)

Tool	Budget	Purpose	Status
`indexDocs`	Heavy	Scan and index documentation for symbol references	v7.3 ✓
`getDocsForSymbol`	Cheap	Find docs referencing a symbol	v7.3 ✓
`getSymbolsInDoc`	Cheap	List symbols in a document	v7.3 ✓
`getDocsForModule`	Cheap	Find docs linked to a module via directive	v7.3 ✓
`checkDocStaleness`	Heavy	Check for stale symbol references	v7.3 ✓
`getDocCoverage`	Heavy	Documentation coverage statistics	v7.3 ✓

Remote Federation (v7.3)

Tool	Budget	Purpose	Status
`federationAddRemote`	Cheap	Add a remote CKB index server	v7.3 ✓
`federationRemoveRemote`	Cheap	Remove a remote server	v7.3 ✓
`federationListRemote`	Cheap	List remote servers in a federation	v7.3 ✓
`federationSyncRemote`	Heavy	Sync metadata from remote servers	v7.3 ✓
`federationStatusRemote`	Cheap	Get status of a remote server	v7.3 ✓
`federationSearchSymbolsHybrid`	Heavy	Search symbols across local + remote	v7.3 ✓
`federationListAllRepos`	Cheap	List repos from local and remote sources	v7.3 ✓

Multi-Repo Management (v7.3)

Tool	Budget	Purpose	Status
`listRepos`	Cheap	List registered repos with state and active status	v7.3 ✓
`switchRepo`	Cheap	Switch active repo context for MCP session	v7.3 ✓
`getActiveRepo`	Cheap	Get information about currently active repo	v7.3 ✓

Compound Operations (v8.0)

Tool	Budget	Purpose	Status
`explore`	Heavy	Comprehensive area exploration (file/dir/module)	v8.0 ✓
`understand`	Heavy	Symbol deep-dive with ambiguity handling	v8.0 ✓
`prepareChange`	Heavy	Pre-change impact + risk assessment	v8.0 ✓
`batchGet`	Cheap	Retrieve multiple symbols by ID (max 50)	v8.0 ✓
`batchSearch`	Cheap	Multiple symbol searches (max 10 queries)	v8.0 ✓

See #Compound Operations (v8.0) for detailed documentation. These tools reduce AI tool calls by 60-70%.

Core Tools (v5.1-v5.2)

traceUsage

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

Budget: Heavy

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

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

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

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, and (v6.5) annotations containing related ADRs and module metadata.

justifySymbol

{ "symbolId": "..." }

Verdicts: keep | investigate | remove-candidate

v6.5: Now considers related ADRs - if a module has an accepted/proposed ADR, symbols without callers return "investigate" instead of "remove-candidate" with reasoning like "No callers found, but related to ADR-001: Use Redis for caching".

getCallGraph

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

getModuleOverview

{ "path": "internal/query" }

v6.5: Now includes annotations (responsibility, capabilities, tags, boundaries) and relatedDecisions (ADRs affecting this module).

analyzeImpact

Analyze the impact of changing a symbol. Returns direct callers, transitive callers (v7.6+), risk scoring, and blast radius metrics.

Budget: Medium-High (depends on caller count)

{ "symbolId": "...", "depth": 2, "includeTelemetry": true, "telemetryPeriod": "90d" }

Parameters:

Parameter	Type	Default	Description
`symbolId`	string	required	The stable symbol ID to analyze
`depth`	number	2	Max transitive depth (1-4). Depth 1 = direct only
`includeTelemetry`	boolean	true	Include runtime telemetry data
`telemetryPeriod`	string	"90d"	Time period: "7d", "30d", "90d", or "all"

Response (v7.6+):

{
  "symbol": { "stableId": "...", "name": "Engine", "kind": "class" },
  "visibility": { "visibility": "public", "confidence": 0.9 },
  "riskScore": {
    "score": 0.72,
    "level": "high",
    "explanation": "High risk: 15 direct caller(s) across 4 module(s).",
    "factors": [
      { "name": "visibility", "value": 0.9, "weight": 0.3 },
      { "name": "direct-callers", "value": 0.8, "weight": 0.35 },
      { "name": "module-spread", "value": 0.6, "weight": 0.25 },
      { "name": "impact-kind", "value": 0.7, "weight": 0.1 }
    ]
  },
  "blastRadius": {
    "moduleCount": 4,
    "fileCount": 12,
    "uniqueCallerCount": 18,
    "riskLevel": "medium"
  },
  "directImpact": [
    { "stableId": "...", "name": "NewEngine", "kind": "direct-caller", "distance": 1, "confidence": 0.95 }
  ],
  "transitiveImpact": [
    { "stableId": "...", "name": "MCPServer#init", "kind": "transitive-caller", "distance": 2, "confidence": 0.85 },
    { "stableId": "...", "name": "main", "kind": "transitive-caller", "distance": 3, "confidence": 0.75 }
  ],
  "modulesAffected": [
    { "moduleId": "internal/query", "name": "query", "impactCount": 8 },
    { "moduleId": "internal/mcp", "name": "mcp", "impactCount": 5 }
  ],
  "observedUsage": { "hasTelemetry": true, "totalCalls": 1250, "trend": "stable" },
  "blendedConfidence": 0.89,
  "relatedDecisions": [ ... ],
  "docsToUpdate": [ ... ]
}

Key Fields:

blastRadius (v7.6): Summary of impact spread with risk classification
- riskLevel: "low" (<2 modules, <5 callers), "medium", "high" (>5 modules or >20 callers)
transitiveImpact (v7.6): Callers at depth 2+ when SCIP available and depth > 1
- Confidence decreases with depth: 0.85 (depth 2) → 0.75 (depth 3) → 0.65 (depth 4)
riskScore: 4-factor weighted score (visibility 30%, callers 35%, module spread 25%, impact kind 10%)
observedUsage: Runtime telemetry when available (requires telemetry integration)

v6.5: Added relatedDecisions showing ADRs that affect impacted modules. v7.3: Added docsToUpdate listing documentation that references this symbol. v7.6: Added blastRadius summary and real transitiveImpact via call graph analysis.

getStatus

Get system status including backend availability, cache statistics, index freshness, and actionable remediation.

{}

Response includes (v8.0+):

{
  "status": "healthy",
  "healthy": true,
  "overallHealth": "available",
  "backends": [
    {
      "id": "scip",
      "available": true,
      "healthy": true,
      "status": "available",
      "capabilities": ["symbol-search", "find-references", "goto-definition"],
      "details": "Symbols: 1234, Documents: 56"
    },
    {
      "id": "git",
      "available": true,
      "healthy": true,
      "status": "available",
      "capabilities": ["blame", "history", "churn"],
      "details": "Ready"
    },
    {
      "id": "lsp",
      "available": false,
      "healthy": false,
      "status": "unavailable",
      "reason": "No servers configured",
      "remediation": "Configure LSP server in .ckb/config.json or run 'ckb setup'"
    }
  ],
  "index": {
    "exists": true,
    "fresh": false,
    "commitsBehind": 5,
    "reason": "5 commit(s) behind HEAD"
  },
  "suggestions": [
    "Index is 5 commits behind. Run 'ckb index' to refresh"
  ],
  "lastRefresh": {
    "at": "2024-12-25T10:00:00Z",
    "trigger": "head-changed",
    "triggerInfo": "branch or commit changed",
    "durationMs": 1200
  },
  "cache": {
    "sizeBytes": 102400,
    "queriesCached": 156,
    "viewsCached": 42,
    "hitRate": 0.85
  },
  "preset": {
    "active": "core",
    "exposed": 14,
    "total": 81,
    "expanded": false,
    "estimatedTokens": 1529,
    "fullPresetTokens": 9040,
    "tokenSavingsPercent": 83
  }
}

v8.0 Enhancements:

The backends array now includes health tiers and remediation:

status — Health tier: available, degraded, or unavailable
reason — Why the backend is degraded or unavailable
remediation — Actionable fix for unavailable backends

The overallHealth field (v8.0) summarizes system state:

available — All backends healthy
degraded — Some backends unhealthy or unavailable
unavailable — All backends unavailable

The suggestions array (v8.0) provides actionable fixes:

Generated based on backend status and index freshness
Examples: "Run 'ckb index' to create SCIP index", "Initialize git with 'git init'"

Earlier Versions:

The index field (v7.5) provides staleness visibility:

fresh — Whether the index is up to date
commitsBehind — Number of commits since last index
reason — Staleness reason when not fresh

The lastRefresh field (v7.6) shows the most recent index refresh:

at — ISO 8601 timestamp of last refresh
trigger — What triggered the refresh: head-changed, index-changed, manual, scheduled, webhook, stale
triggerInfo — Human-readable description of the trigger
durationMs — How long the refresh took in milliseconds

The preset field (v7.5) provides token efficiency visibility (see Presets for details):

active — Current preset name
exposed — Number of tools exposed to the AI
total — Total available tools
expanded — Whether expandToolset was called this session
estimatedTokens — Estimated tokens for current preset's tools/list
fullPresetTokens — Estimated tokens if using all tools
tokenSavingsPercent — Percentage reduction vs full preset

reindex

New in v8.0

Get guidance on refreshing the SCIP index. Checks current index staleness and provides actionable instructions.

{
  "scope": "full"
}

Parameters:

scope — (optional) Reindex scope: full for complete reindex (default), incremental for changed files only

Response when index is fresh:

{
  "status": "skipped",
  "message": "Index is already fresh. No reindex needed."
}

Response when index is stale:

{
  "status": "action_required",
  "message": "Index is stale. Index is 5 commits behind HEAD. Reason: behind-head. Run 'ckb index' in your terminal to refresh the index."
}

For incremental scope:

{
  "status": "action_required",
  "message": "Index is stale. Run 'ckb index --incremental' for faster incremental update."
}

Note: This tool provides guidance rather than executing the reindex directly. Run the suggested command in your terminal to refresh the index.

doctor

{}

Architectural Memory Tools (v6.0)

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"],
  "alternatives": ["LSP-only approach", "Custom parser"],
  "status": "proposed"
}

Parameters:

Parameter	Required	Description
`title`	Yes	Short title for the decision
`context`	Yes	Background and forces driving the decision
`decision`	Yes	What was decided and why
`consequences`	No	List of consequences (positive and negative)
`affectedModules`	No	Module paths this decision applies to
`alternatives`	No	Other options that were considered
`status`	No	`proposed` (default), `accepted`, `deprecated`, `superseded`
`author`	No	Who made this decision

Output:

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

v6.5 Integration: Once recorded, decisions automatically appear in:

explainSymbol → annotations.relatedDecisions for symbols in affected modules
justifySymbol → Influences verdict (prevents "remove-candidate" for intentional code)
analyzeImpact → relatedDecisions when impacting modules with ADRs
getModuleOverview → relatedDecisions for the module

getDecisions

Query architectural decisions.

Budget: Cheap

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

Parameters:

Parameter	Required	Description
`id`	No	Get a specific ADR by ID (e.g., "ADR-001")
`moduleId`	No	Filter to ADRs affecting a specific module
`status`	No	Filter by status: `proposed`, `accepted`, `deprecated`, `superseded`
`search`	No	Full-text search in title and content
`limit`	No	Max results (default: 50)

Output:

{
  "decisions": [
    {
      "id": "ADR-001",
      "title": "Use Redis for caching",
      "status": "accepted",
      "affectedModules": ["internal/cache"],
      "filePath": "docs/decisions/adr-001-use-redis.md",
      "date": "2024-01-15",
      "author": "team-platform"
    }
  ],
  "totalCount": 1
}

annotateModule

Add or update module metadata. Annotations are used by other tools for context.

Budget: Cheap

{
  "moduleId": "internal/api",
  "responsibility": "HTTP API handlers and middleware",
  "capabilities": ["REST", "WebSocket", "Authentication"],
  "tags": ["core", "api"],
  "publicPaths": ["handler.go", "routes.go"],
  "internalPaths": ["helpers.go", "middleware.go"]
}

Parameters:

Parameter	Required	Description
`moduleId`	Yes	Module path (e.g., "internal/api")
`responsibility`	No	One-sentence description of the module's purpose
`capabilities`	No	List of capabilities this module provides
`tags`	No	Categorization tags (e.g., "core", "deprecated", "infrastructure")
`publicPaths`	No	Files that are part of the public API
`internalPaths`	No	Files that are internal implementation

Output:

status: "created" | "updated"
moduleId: The module that was annotated
responsibility: The set responsibility
capabilities: The set capabilities
tags: The set tags

v6.5 Integration: Once annotated, module metadata appears in:

explainSymbol → annotations.moduleAnnotations with responsibility, capabilities, tags
getModuleOverview → annotations field with full module metadata
getModuleResponsibilities → Declared annotations override inferred ones with higher confidence

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

Background Jobs & CI/CD Tools (v6.1)

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

Federation Tools (v6.2)

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

Daemon Mode Tools (v6.2.1)

The daemon provides an always-on service for continuous code intelligence. See Daemon-Mode for full documentation.

daemonStatus

Get daemon health and statistics.

Budget: Cheap

{}

Output:

running: Whether daemon is running
pid: Process ID (when running)
logFile: Path to log file
dbFile: Path to database file
pidFile: Path to PID file
daemonDir: Daemon storage directory
hint: Suggested CLI commands

listSchedules

List scheduled tasks with optional filtering.

Budget: Cheap

{ "taskType": "refresh", "enabled": true, "limit": 20 }

Parameters:

taskType: Filter by task type (refresh, federation_sync, cleanup, health_check)
enabled: Filter by enabled state
limit: Max results (default: 20)

Output:

schedules: Array of schedule objects with id, taskType, target, schedule, enabled, nextRun, lastRun
totalCount: Total number of schedules

runSchedule

Run a scheduled task immediately.

Budget: Cheap

{ "scheduleId": "schedule-abc123" }

Output:

success: Whether the trigger succeeded
scheduleId: The triggered schedule ID
message: Status message

listWebhooks

List configured webhooks.

Budget: Cheap

{}

Output:

webhooks: Array of webhook summaries with id, url, events, enabled, deliveriesTotal, deliveriesSuccessful
totalCount: Total number of webhooks

testWebhook

Send a test event to a webhook.

Budget: Cheap

{ "webhookId": "webhook-abc123" }

Output:

success: Whether the test was queued
webhookId: The tested webhook ID
message: Status message

webhookDeliveries

Get delivery history for a webhook.

Budget: Cheap

{ "webhookId": "webhook-abc123", "status": "failed", "limit": 20 }

Parameters:

webhookId: Webhook ID (required)
status: Filter by status (queued, pending, delivered, failed, dead)
limit: Max results (default: 20)

Output:

deliveries: Array of delivery objects with id, eventType, status, attempts, lastAttemptAt, lastError
totalCount: Total number of deliveries

Tree-sitter Complexity (v6.2.2)

getFileComplexity

Get code complexity metrics for a source file using tree-sitter parsing.

Budget: Cheap

{
  "filePath": "internal/query/engine.go",
  "includeFunctions": true,
  "limit": 20,
  "sortBy": "cyclomatic"
}

Parameters:

filePath: Path to the source file (required)
includeFunctions: Include per-function breakdown (default: true)
limit: Maximum functions to return (default: 20)
sortBy: Sort by "cyclomatic", "cognitive", or "lines" (default: "cyclomatic")

Output:

filePath: Analyzed file path
language: Detected language
aggregate:
- totalCyclomatic: Sum of all function cyclomatic complexity
- totalCognitive: Sum of all function cognitive complexity
- averageCyclomatic: Average per function
- averageCognitive: Average per function
- maxCyclomatic: Highest cyclomatic in file
- maxCognitive: Highest cognitive in file
- functionCount: Number of functions
- lineCount: Total lines
functions: Array of function metrics (sorted by sortBy)
- name: Function name
- line: Start line
- endLine: End line
- cyclomatic: Cyclomatic complexity
- cognitive: Cognitive complexity
- lines: Lines of code
- parameters: Parameter count

Supported Languages: Go, JavaScript, TypeScript, Python, Rust, Java, Kotlin

Complexity Types:

Cyclomatic — Decision points count (if, for, while, switch, &&, ||)
Cognitive — Nesting-weighted complexity for maintainability assessment

Integration: Complexity metrics feed into getHotspots risk scoring.

Contract Analysis Tools (v6.3)

Contract analysis enables cross-repo intelligence through explicit API boundaries. See Federation for full documentation.

listContracts

List API contracts (protobuf, OpenAPI) in a federation.

Budget: Cheap

{
  "federation": "platform",
  "repoId": "api",
  "contractType": "proto",
  "visibility": "public"
}

Parameters:

federation: Federation name (required)
repoId: Filter to contracts from this repo
contractType: Filter by type (proto, openapi)
visibility: Filter by visibility (public, internal, unknown)

Output:

contracts: Array of contracts with repoId, path, contractType, visibility, confidence
totalCount: Total number of contracts

analyzeContractImpact

Analyze the impact of changing an API contract.

Budget: Heavy

{
  "federation": "platform",
  "repoId": "api",
  "path": "proto/api/v1/user.proto",
  "includeHeuristic": false,
  "includeTransitive": true,
  "maxDepth": 3
}

Parameters:

federation: Federation name (required)
repoId: Repository containing the contract (required)
path: Path to the contract file (required)
includeHeuristic: Include tier 3 edges (default: false)
includeTransitive: Include transitive consumers (default: true)
maxDepth: Max depth for transitive analysis (default: 3)

Output:

contract: Contract details (repoId, path, type, visibility)
directConsumers: Repos that directly use this contract
- repoId, tier, evidenceType, confidence, consumerPaths
transitiveConsumers: Repos reached through imports
- repoId, viaContract, depth
summary:
- directRepoCount: Number of direct consumers
- transitiveRepoCount: Number of transitive consumers
- riskLevel: "low" | "medium" | "high"
- riskFactors: Array of risk reasons
ownership:
- approvalRequired: Owners who should approve changes

Risk Levels:

Low: ≤2 direct consumers, internal visibility
Medium: 3-5 direct consumers
High: >5 direct consumers, public visibility, has services

getContractDependencies

Get contract dependencies for a repository.

Budget: Heavy

{
  "federation": "platform",
  "repoId": "api",
  "direction": "both",
  "includeHeuristic": false
}

Parameters:

federation: Federation name (required)
repoId: Repository to analyze (required)
direction: "dependencies", "consumers", or "both" (default: "both")
includeHeuristic: Include tier 3 edges (default: false)

Output:

dependencies: Contracts this repo depends on
- contract: Contract details
- tier: Evidence tier
- confidence: Confidence score
consumers: Repos consuming this repo's contracts
- contract: Contract details
- consumerRepo: Consumer details with tier and confidence

suppressContractEdge

Suppress a false positive contract dependency edge.

Budget: Cheap

{
  "federation": "platform",
  "edgeId": 123,
  "reason": "Not actually used - legacy import"
}

Parameters:

federation: Federation name (required)
edgeId: Edge ID to suppress (required)
reason: Reason for suppression

Output:

success: Whether suppression succeeded
edgeId: The suppressed edge ID

verifyContractEdge

Verify a contract edge, increasing confidence.

Budget: Cheap

{
  "federation": "platform",
  "edgeId": 123
}

Parameters:

federation: Federation name (required)
edgeId: Edge ID to verify (required)

Output:

success: Whether verification succeeded
edgeId: The verified edge ID

getContractStats

Get contract statistics for a federation.

Budget: Cheap

{
  "federation": "platform"
}

Parameters:

federation: Federation name (required)

Output:

totalContracts: Total number of contracts
publicContracts: Public contracts count
internalContracts: Internal contracts count
byType: Breakdown by contract type (proto, openapi)
totalEdges: Total dependency edges
declaredEdges: Tier 1 edge count
derivedEdges: Tier 2 edge count

Runtime Telemetry Tools (v6.4)

Telemetry tools enable confident answers to "is this code actually used?" by integrating runtime observability data.

getTelemetryStatus

Get telemetry coverage metrics and sync status.

Budget: Cheap

{}

Output:

enabled: Whether telemetry is enabled
lastSync: Last successful sync timestamp
coverage:
- attribute: % of events with file_path, namespace, line_number
- match: % of events matched to symbols (exact + strong)
- service: % of repos with telemetry data
- overall: Combined coverage score
- level: "high" (≥0.8), "medium" (≥0.6), "low" (≥0.4), "insufficient" (<0.4)
unmappedServices: Services that couldn't be mapped to repos
warnings: Coverage warnings and recommendations

getObservedUsage

Get runtime observed usage for a symbol.

Budget: Cheap

{
  "symbolId": "ckb:repo:sym:abc123",
  "period": "90d",
  "includeCallers": true
}

Parameters:

symbolId: Symbol to query (required)
period: Time period - "7d", "30d", "90d", or "all" (default: "90d")
includeCallers: Include caller service breakdown (default: false)

Output:

symbolId: Queried symbol
callCount: Total calls in period
errorCount: Errors in period
matchQuality: "exact" | "strong" | "weak"
matchConfidence: Confidence score (0.60-0.95)
trend: "increasing" | "stable" | "decreasing"
callers: Caller breakdown (if includeCallers: true)
- service: Calling service name
- callCount: Calls from this service
- lastSeen: Last call timestamp

Match Quality Levels:

Quality	Confidence	Criteria
Exact	0.95	file_path + function_name + line_number
Strong	0.85	file_path + function_name
Weak	0.60	namespace + function_name (no file)

findDeadCodeCandidates

Find symbols that may be dead code based on observed runtime telemetry.

Budget: Heavy

{
  "repoId": "my-repo",
  "minConfidence": 0.7,
  "limit": 100
}

Parameters:

repoId: Repository to analyze (optional, defaults to current repo)
minConfidence: Minimum confidence threshold 0-1 (default: 0.7)
limit: Max candidates to return (default: 100)

Output:

candidates: Array of dead code candidates
- symbolId: Symbol identifier
- name: Symbol name
- filePath: File location
- staticRefs: Static reference count
- observedCalls: Runtime call count (always 0 for candidates)
- matchQuality: How symbol was matched
- confidence: Confidence score (capped at 0.90)
- reasons: Factors affecting confidence
summary:
- totalAnalyzed: Symbols analyzed
- candidateCount: Dead code candidates found
- coverageLevel: Telemetry coverage level
- observationDays: Days of telemetry data
coverage: Coverage details
limitations: Analysis limitations

Confidence Factors:

Base: exact (0.90), strong (0.80)
Coverage adjustment: medium (-0.05), low (N/A - disabled)
High static refs: -0.05
Short observation: -0.10 (< 90 days)
Sampling detected: -0.15

Requirements:

Coverage level must be "medium" or higher
Only exact/strong matches are considered
Minimum observation period applies

Exclusions (configurable):

Test files (**/test/**)
Migrations (**/migrations/**)
Functions matching patterns (*Migration*, Test*, *Scheduled*)

Enhanced analyzeImpact (v6.4)

The analyzeImpact tool now accepts an optional includeTelemetry parameter.

Additional Parameters:

includeTelemetry: Include observed callers in analysis (default: true)
telemetryPeriod: Time period for telemetry data - "7d", "30d", "90d", or "all" (default: "90d")

Additional Output (when telemetry enabled and coverage is medium+):

observedImpact:
- observedCallers: Services that call this symbol
  - service: Service name
  - repoId: Mapped repository
  - callCount: Call volume
  - lastSeen: Last call timestamp
- comparison:
  - staticOnly: Consumers found only via static analysis
  - observedOnly: Callers found only via telemetry
  - both: Present in both static and observed
- coverageContext: Coverage level and warnings

Enhanced getHotspots (v6.4)

The getHotspots tool now includes observed usage data when telemetry is enabled.

Additional Output:

hotspots[].observedUsage (when telemetry enabled):
- callCount90d: Calls in last 90 days
- trend: "increasing" | "stable" | "decreasing"
- matchQuality: "exact" | "strong" | "weak" | "unmatched"

The hotspot scoring formula now includes a usage weight (0.20) when telemetry data is available.

Developer Intelligence Tools (v6.5)

Developer Intelligence tools help understand why code exists, not just what it does. They combine git history, co-change patterns, and multi-signal risk analysis.

explainOrigin

Explain why code exists with full context: who wrote it, when, why, and what might be concerning.

Budget: Cheap

{
  "symbol": "internal/query/engine.go:42",
  "includeUsage": true,
  "includeCoChange": true,
  "historyLimit": 10
}

Parameters:

symbol: File path, file:line, or symbol name (required)
includeUsage: Include usage analysis (default: true)
includeCoChange: Include co-change data (default: true)
historyLimit: Max history entries (default: 10)

Output:

origin:
- commitSha: Introducing commit
- author: Original author
- date: Creation date
- commitMessage: Why it was added
- prNumber / issueNumber: Linked references
evolution:
- totalCommits: Times modified
- contributors: Unique contributors
- lastModified: Most recent change
- timeline: Significant changes
usage:
- staticRefs: Reference count
- observedCalls: Runtime calls (if telemetry enabled)
- importance: "low" | "medium" | "high" | "critical"
coChanges:
- Array of files that frequently change together
- file, correlation, coCommits
warnings:
- type: "temporary_code" | "bus_factor" | "high_coupling" | "stale" | "complex"
- message: Human-readable description
- severity: "info" | "warning" | "critical"
references:
- issues: Linked GitHub issues
- prs: Linked pull requests
- jiraTickets: Linked JIRA tickets

Warning Types:

Type	Trigger
`temporary_code`	Contains TODO, FIXME, HACK, XXX
`bus_factor`	Only 1 contributor
`high_coupling`	≥5 files with correlation >0.7
`stale`	Not touched in 12+ months
`complex`	Cyclomatic complexity >20

analyzeCoupling

Find files and symbols that historically change together (temporal coupling).

Budget: Heavy

{
  "target": "internal/query/engine.go",
  "minCorrelation": 0.3,
  "windowDays": 365,
  "limit": 20
}

Parameters:

target: File or symbol to analyze (required)
minCorrelation: Minimum correlation threshold (default: 0.3)
windowDays: Time window in days (default: 365)
limit: Max results (default: 20)

Output:

target: Analyzed file/symbol
coupledFiles: Array of coupled files
- file: File path
- correlation: Correlation score (0-1)
- coCommits: Number of commits together
- lastCoChange: Last time they changed together
- authors: Shared authors
summary:
- totalFiles: Files above threshold
- strongCoupling: Files with correlation >0.7
- moderateCoupling: Files with 0.5-0.7
- weakCoupling: Files with 0.3-0.5
insights:
- Recommendations based on coupling patterns
- Example: "Consider extracting shared logic from X and Y"

Use Cases:

Find hidden dependencies
Identify refactoring targets
Understand implicit contracts
Plan code reviews (suggest reviewing coupled files)

exportForLLM

Export codebase structure in LLM-friendly format with importance ranking.

Budget: Heavy

{
  "includeUsage": true,
  "includeOwnership": true,
  "includeContracts": true,
  "includeComplexity": true,
  "minComplexity": 10,
  "minCalls": 100,
  "maxSymbols": 500
}

Parameters:

includeUsage: Include call counts (default: true)
includeOwnership: Include owners (default: true)
includeContracts: Include contract info (default: true)
includeComplexity: Include complexity metrics (default: true)
minComplexity: Skip symbols below this complexity (default: 0)
minCalls: Skip symbols below this call count (default: 0)
maxSymbols: Maximum symbols to include (default: unlimited)

Output:

text: Formatted text output for LLM consumption
metadata:
- repo: Repository name
- generated: Generation timestamp
- symbolCount: Total symbols exported
- fileCount: Total files
- moduleCount: Total modules

Text Format:

# Codebase: my-project
# Generated: 2025-12-18T10:00:00Z
# Symbols: 150 | Files: 45 | Modules: 8

## internal/api/ (owner: @api-team)

  ! handler.go
      $ Server                  c=5  calls=10k/day ★★★
      # HandleRequest()         c=12 calls=8k/day  ★★★
      # ValidateInput()         c=8  calls=8k/day  ★★

  ! middleware.go
      # AuthMiddleware()        c=15 calls=10k/day ★★★  contract:auth.proto

---
Legend:
  !  = file
  $  = class/struct
  #  = function/method
  c  = complexity (cyclomatic)
  ★  = importance (usage × complexity)
  contract: = exposes or consumes a contract

Importance Ranking:

Level	Stars	Criteria
Critical	★★★	High usage + high complexity
High	★★	High usage OR high complexity
Medium	★	Moderate usage and complexity
Low	(none)	Low usage and complexity

auditRisk

Find risky code based on multiple weighted signals.

Budget: Heavy

{
  "minScore": 40,
  "limit": 50,
  "factor": "complexity",
  "quickWins": false
}

Parameters:

minScore: Minimum risk score to include (default: 40)
limit: Max results (default: 50)
factor: Focus on specific factor (optional)
quickWins: Return only high-impact, low-effort targets (default: false)

Output:

risks: Array of risky items
- target: File or symbol path
- score: Risk score (0-100)
- factors: Individual factor scores
  - complexity: 0-100 (weight: 20%)
  - testCoverage: 0-100 inverted (weight: 20%)
  - busFactor: 0-100 (weight: 15%)
  - securitySensitive: 0-100 (weight: 15%)
  - staleness: 0-100 (weight: 10%)
  - errorRate: 0-100 (weight: 10%)
  - coupling: 0-100 (weight: 5%)
  - churn: 0-100 (weight: 5%)
- topFactors: Top 3 contributing factors
- suggestions: Remediation suggestions
summary:
- totalAnalyzed: Files/symbols analyzed
- highRisk: Count with score ≥70
- mediumRisk: Count with score 40-70
- factorDistribution: Breakdown by dominant factor
quickWins: (when quickWins: true)
- Items with high risk but low effort to fix
- Ranked by impact/effort ratio

Risk Factor Weights:

Factor	Weight	Description
Complexity	20%	Cyclomatic/cognitive complexity
Test Coverage	20%	Lack of test coverage
Bus Factor	15%	Single-author code
Security	15%	Handles auth, crypto, PII
Staleness	10%	Not touched in 6+ months
Error Rate	10%	Runtime error frequency
Coupling	5%	High co-change coupling
Churn	5%	Frequent modifications

Quick Wins Criteria:

High risk score (≥60)
Low complexity (easy to fix)
High usage (high impact)
Clear owner (someone to assign)

Doc-Symbol Linking Tools (v7.3)

Doc-symbol linking bridges documentation and code by automatically detecting symbol references in markdown files.

indexDocs

Scan and index documentation for symbol references.

Budget: Heavy

{
  "force": false
}

Parameters:

force: Re-index all docs even if unchanged (default: false)

Output:

indexed: Number of documents indexed
references: Total symbol references found
resolved: References successfully resolved to symbols
duration: Indexing duration

getDocsForSymbol

Find documentation that references a symbol.

Budget: Cheap

{
  "symbol": "Engine.Start",
  "limit": 10
}

Parameters:

symbol: Symbol name or ID to search for (required)
limit: Max results (default: 10)

Output:

docs: Array of documents referencing the symbol
- path: Document path
- line: Line number of reference
- context: Surrounding text
- detection: How it was detected (backtick, directive, fence)
- confidence: Resolution confidence

getSymbolsInDoc

List all symbol references found in a documentation file.

Budget: Cheap

{
  "path": "README.md"
}

Parameters:

path: Path to the documentation file (required)

Output:

symbols: Array of symbol references
- rawText: Original text in document
- line: Line number
- symbolId: Resolved symbol ID (if resolved)
- status: "exact" | "suffix" | "ambiguous" | "missing"
- confidence: Resolution confidence
- detection: Detection method

getDocsForModule

Find documents linked to a module via  directives.

Budget: Cheap

{
  "moduleId": "internal/query"
}

Parameters:

moduleId: Module ID (directory path) to find docs for (required)

Output:

docs: Array of documents linked to the module
- path: Document path
- line: Line number of directive

checkDocStaleness

Check documentation for stale symbol references.

Budget: Heavy

{
  "path": "README.md"
}

Or check all documents:

{
  "all": true
}

Parameters:

path: Path to check (optional)
all: Check all indexed documentation (default: false)

Output:

reports: Array of staleness reports
- docPath: Document path
- stale: Array of stale references
  - rawText: Original text in document
  - line: Line number
  - reason: "missing_symbol" | "ambiguous_symbol" | "index_incomplete" | "symbol_renamed"
  - message: Human-readable description
  - suggestions: Alternative symbol names (for ambiguous)
  - newSymbolId: New symbol ID (for renamed symbols)
totalStale: Total stale references count

Staleness Reasons:

Reason	Description
`missing_symbol`	Symbol no longer exists in codebase
`ambiguous_symbol`	Reference matches multiple symbols
`index_incomplete`	Language not indexed at current tier
`symbol_renamed`	Symbol was renamed (alias chain detected)

getDocCoverage

Get documentation coverage statistics.

Budget: Heavy

{
  "exportedOnly": false,
  "topN": 10
}

Parameters:

exportedOnly: Only count exported/public symbols (default: false)
topN: Number of top undocumented symbols to return (default: 10)

Output:

coverage:
- totalSymbols: Total symbols in codebase
- documentedSymbols: Symbols with at least one doc reference
- percentage: Coverage percentage (0-100)
topUndocumented: Most important undocumented symbols
- symbolId: Symbol identifier
- name: Symbol name
- kind: Symbol kind (function, class, etc.)
- centrality: Importance score based on references
byModule: Coverage breakdown by module

CI Integration:

# Fail if coverage drops below threshold
ckb docs coverage --fail-under=80

Exit codes:

0: Coverage meets threshold
1: Coverage below threshold

Remote Federation Tools (v7.3)

Remote federation enables querying remote CKB index servers alongside local repositories. This transforms federation from local-only aggregation to a distributed code intelligence network.

federationAddRemote

Add a remote CKB index server to a federation.

Budget: Cheap

{
  "federation": "platform",
  "name": "prod",
  "url": "https://ckb.company.com",
  "token": "${CKB_PROD_TOKEN}",
  "cacheTtl": "1h",
  "timeout": "30s"
}

Parameters:

federation: Federation name (required)
name: Unique server name (required)
url: Server URL - https:// or http:// (required)
token: Auth token - supports ${VAR} expansion (optional)
cacheTtl: Cache TTL duration (default: "1h")
timeout: Request timeout (default: "30s")

Output:

name: Server name
url: Server URL
cacheTtl: Cache TTL
timeout: Request timeout
enabled: Whether server is enabled
message: Success message

federationRemoveRemote

Remove a remote server from a federation.

Budget: Cheap

{
  "federation": "platform",
  "name": "staging"
}

Parameters:

federation: Federation name (required)
name: Server name to remove (required)

Output:

name: Removed server name
message: Success message

federationListRemote

List remote servers in a federation.

Budget: Cheap

{
  "federation": "platform"
}

Parameters:

federation: Federation name (required)

Output:

servers: Array of server configs
- name: Server name
- url: Server URL
- cacheTtl: Cache TTL
- timeout: Request timeout
- enabled: Whether server is enabled
- addedAt: When server was added
- lastSyncedAt: Last successful sync
- lastError: Last error message
count: Total server count

federationSyncRemote

Sync metadata from remote server(s).

Budget: Heavy

{
  "federation": "platform",
  "name": "prod"
}

Or sync all servers:

{
  "federation": "platform"
}

Parameters:

federation: Federation name (required)
name: Specific server to sync (optional - syncs all if omitted)

Output (specific server):

server: Server name
repoCount: Number of repos synced
message: Success message

Output (all servers):

total: Total servers
success: Successful syncs
failed: Failed syncs
errors: Array of error details
message: Summary message

federationStatusRemote

Get status of a remote server including connectivity check.

Budget: Cheap

{
  "federation": "platform",
  "name": "prod"
}

Parameters:

federation: Federation name (required)
name: Server name (required)

Output:

name: Server name
url: Server URL
enabled: Whether server is enabled
online: Whether server is reachable
latency: Response latency
pingError: Error message if offline
lastSyncedAt: Last successful sync
lastError: Last error message
cachedRepoCount: Number of cached repos

federationSearchSymbolsHybrid

Search symbols across local federation repositories AND remote servers.

Budget: Heavy

{
  "federation": "platform",
  "query": "Handler",
  "limit": 100,
  "language": "go",
  "kind": "function",
  "servers": ["prod", "staging"]
}

Parameters:

federation: Federation name (required)
query: Search query (required)
limit: Max results (default: 100)
language: Filter by language (optional)
kind: Filter by symbol kind (optional)
servers: Specific remote servers to query (optional - queries all if omitted)

Output:

results: Array of symbol results
- symbol: Symbol details
- source: "local" or remote server name
- repoId: Repository ID
- serverUrl: Server URL (empty for local)
sources: Which servers responded
- name: Source name
- latency: Response time
- resultCount: Results from this source
errors: Which servers failed
- source: Server name
- message: Error message
totalResults: Total result count
truncated: Whether results were truncated

Source Attribution:

Results include source attribution showing where each result came from:

"local" - From local federation repositories
Server name (e.g., "prod") - From remote server

federationListAllRepos

List repositories from both local federation and remote servers.

Budget: Cheap

{
  "federation": "platform"
}

Parameters:

federation: Federation name (required)

Output:

local: Local repository info
- repos: Array of local repos
- count: Local repo count
remote: Remote repository info
- servers: Array of server details
  - name: Server name
  - repos: Array of remote repos
  - count: Repo count for this server
- totalCount: Total remote repos
totalCount: Grand total (local + remote)

Remote Federation Workflows

Add and sync a remote server:

federationAddRemote({ federation: "platform", name: "prod", url: "..." })
  → federationSyncRemote({ federation: "platform", name: "prod" })
  → federationSearchSymbolsHybrid({ federation: "platform", query: "..." })

Monitor remote server health:

federationListRemote({ federation: "platform" })
  → federationStatusRemote({ federation: "platform", name: "prod" })

Cross-organization code search:

federationSearchSymbolsHybrid({ federation: "org", query: "Auth", servers: ["team-a", "team-b"] })

Multi-Repo Management Tools (v7.3)

Multi-repo management enables quick context switching between multiple repositories in MCP sessions. Unlike federation (which queries across repos), this feature lets you focus on one repo at a time with easy switching.

listRepos

List all registered repositories with their state and active status.

Budget: Cheap

{}

Output:

repos: Array of registered repositories
- name: Repository alias
- path: Absolute filesystem path
- state: Current state (valid, uninitialized, missing)
- active: Whether this is the currently active repo
- default: Whether this is the default repo
- loaded: Whether engine is currently loaded in memory
- addedAt: When repo was registered
- lastUsedAt: When repo was last accessed
count: Total number of registered repos
activeRepo: Name of currently active repo (if any)

States:

valid: Path exists and .ckb/ is initialized
uninitialized: Path exists but .ckb/ is missing
missing: Path no longer exists

switchRepo

Switch to a different repository by name.

Budget: Cheap

{
  "name": "myproject"
}

Parameters:

name: Name of the registered repository to switch to (required)

Output:

success: Whether switch succeeded
name: Repository name
path: Repository path
state: Repository state
activeRepo: Current active repo name

Errors:

Repo not found in registry
Path does not exist (missing state)
Repo not initialized (uninitialized state) — returns actionable fix

Engine Lifecycle:

Max 5 engines in memory at once
LRU eviction when switching to a 6th repo
Active repo is never evicted
Each engine loads its own .ckb/config.json

getActiveRepo

Get information about the currently active repository.

Budget: Cheap

{}

Output (active repo):

name: Repository name
path: Repository path
state: Current state

Output (no active repo):

name: null
state: "none"
error: Actionable message

Legacy mode (single-repo):

mode: "legacy"
path: Repository path
state: "valid"

Multi-Repo Workflows

Setup and switch:

# CLI: Register repos
ckb repo add frontend /path/to/frontend
ckb repo add backend /path/to/backend
ckb repo default frontend

# MCP: Switch context
listRepos()
  → switchRepo({ name: "backend" })
  → searchSymbols({ query: "Auth" })

Start MCP with specific repo:

ckb mcp --repo backend

Scripting:

# Get current repo name
REPO=$(ckb repo which | cut -f1)

# Check all repos are valid
ckb repo check --json | jq '.missing'

Compound Operations (v8.0)

Compound tools aggregate multiple granular queries to reduce AI tool calls by 60-70%. Instead of calling explainFile → searchSymbols → getCallGraph → getHotspots separately, use explore for a single comprehensive response.

Design principle: Compound tools coexist with granular tools. Use compound tools for common exploration workflows; use granular tools for specific, targeted queries.

explore

Comprehensive area exploration for files, directories, or modules.

Budget: Heavy

Replaces: explainFile → searchSymbols → getCallGraph → getHotspots

{
  "target": "internal/query",
  "depth": "standard",
  "focus": "structure"
}

Parameters:

target: File, directory, or module path to explore (required)
depth: Exploration thoroughness (optional)
- shallow — Quick overview (5 symbols, no hotspots)
- standard — Balanced exploration (default, 10 symbols)
- deep — Comprehensive (20 symbols, full hotspots)
focus: Aspect to emphasize (optional)
- structure — Symbols and types (default)
- dependencies — Imports and exports
- changes — Hotspots and history

Output:

{
  "overview": {
    "targetType": "directory",
    "path": "/abs/path/internal/query",
    "name": "query",
    "fileCount": 24,
    "symbolCount": 156,
    "lineCount": 4521,
    "language": "go",
    "role": "core",
    "responsibility": "Query engine and backend orchestration"
  },
  "keySymbols": [
    {
      "stableId": "ckb:repo:sym:abc123",
      "name": "Engine",
      "kind": "struct",
      "visibility": "public",
      "importance": 0.95,
      "reason": "Main entry point, high reference count"
    }
  ],
  "dependencies": {
    "imports": [{ "name": "internal/storage", "internal": true }],
    "exports": [{ "name": "Engine", "kind": "struct" }]
  },
  "recentChanges": [
    { "commitHash": "abc123", "message": "Add compound tools", "author": "dev", "filesChanged": 3 }
  ],
  "hotspots": [
    { "file": "engine.go", "score": 0.85, "reason": "high-churn" }
  ],
  "health": {
    "scipAvailable": true,
    "gitAvailable": true,
    "overallStatus": "healthy"
  },
  "suggestions": ["Explore Engine struct for main functionality"]
}

Use cases:

Initial codebase orientation
Understanding unfamiliar modules
Finding entry points for investigation

understand

Comprehensive symbol deep-dive with intelligent ambiguity handling.

Budget: Heavy

Replaces: searchSymbols → getSymbol → explainSymbol → findReferences → getCallGraph

{
  "query": "Engine",
  "includeReferences": true,
  "includeCallGraph": true,
  "maxReferences": 50
}

Parameters:

query: Symbol name or stable ID (required)
includeReferences: Include reference information grouped by file (default: true)
includeCallGraph: Include callers and callees (default: true)
maxReferences: Maximum references to include (default: 50)

Output (single match):

{
  "symbol": {
    "stableId": "ckb:repo:sym:abc123",
    "name": "Engine",
    "kind": "struct",
    "filePath": "internal/query/engine.go",
    "line": 42
  },
  "explanation": "Engine is the central query coordinator that routes requests to SCIP, LSP, and Git backends...",
  "references": {
    "totalCount": 47,
    "byFile": [
      { "file": "internal/mcp/server.go", "lines": [12, 45, 78], "count": 3 }
    ],
    "truncated": false
  },
  "callers": [
    { "symbolId": "...", "name": "MCPServer.toolGetStatus", "file": "tool_impls.go", "line": 20 }
  ],
  "callees": [
    { "symbolId": "...", "name": "GetRepoState", "kind": "method" }
  ],
  "relatedTests": [
    { "file": "engine_test.go", "name": "TestEngine_SearchSymbols" }
  ]
}

Output (multiple matches — ambiguity):

{
  "ambiguity": {
    "matchCount": 3,
    "matches": [
      { "stableId": "...", "name": "Engine", "kind": "struct", "file": "query/engine.go" },
      { "stableId": "...", "name": "Engine", "kind": "struct", "file": "federation/engine.go" },
      { "stableId": "...", "name": "Engine", "kind": "interface", "file": "backends/engine.go" }
    ],
    "suggestion": "Use a symbol ID or more specific query"
  },
  "symbol": null
}

Use cases:

Deep-diving into specific code
Understanding symbol relationships
Finding all usages before refactoring

prepareChange

Pre-change impact analysis for safe refactoring.

Budget: Heavy

Replaces: analyzeImpact + getAffectedTests + analyzeCoupling + risk assessment

{
  "target": "ckb:repo:sym:abc123",
  "changeType": "modify"
}

Parameters:

target: Symbol ID or file path to analyze (required)
changeType: Type of change being planned (optional)
- modify — Changing implementation (default)
- rename — Renaming symbol or file
- delete — Removing symbol or file
- extract — Extracting to new location

Output:

{
  "target": {
    "symbolId": "ckb:repo:sym:abc123",
    "name": "ProcessPayment",
    "kind": "function",
    "path": "internal/payments/processor.go",
    "visibility": "public"
  },
  "directDependents": [
    { "symbolId": "...", "name": "CheckoutHandler", "file": "api/checkout.go", "line": 45 }
  ],
  "transitiveImpact": {
    "depth2Count": 12,
    "depth3Count": 35,
    "moduleSpread": 4,
    "riskLevel": "medium"
  },
  "relatedTests": [
    { "file": "processor_test.go", "name": "TestProcessPayment", "direct": true },
    { "file": "checkout_test.go", "name": "TestCheckoutFlow", "direct": false }
  ],
  "coChangeFiles": [
    { "file": "internal/payments/refund.go", "correlation": 0.85, "coCommits": 12 }
  ],
  "riskAssessment": {
    "overallRisk": "medium",
    "factors": [
      { "factor": "moduleSpread", "score": 0.6, "reason": "Affects 4 modules" },
      { "factor": "testCoverage", "score": 0.8, "reason": "Good test coverage" }
    ],
    "recommendation": "Review checkout handler integration carefully",
    "suggestedReviewers": ["@payments-team"]
  }
}

Risk levels:

Level	Criteria
Low	≤2 modules AND ≤5 direct callers
Medium	3-5 modules OR 6-20 callers
High	>5 modules OR >20 callers OR poor test coverage

Use cases:

Planning refactoring safely
Assessing risk before deleting code
Finding related tests to run

batchGet

Retrieve multiple symbols by ID in a single call.

Budget: Cheap

{
  "symbolIds": [
    "ckb:repo:sym:abc123",
    "ckb:repo:sym:def456",
    "ckb:repo:sym:ghi789"
  ]
}

Parameters:

symbolIds: Array of symbol IDs to retrieve (required, max 50)

Output:

{
  "results": {
    "ckb:repo:sym:abc123": {
      "stableId": "ckb:repo:sym:abc123",
      "name": "Engine",
      "kind": "struct",
      "filePath": "internal/query/engine.go"
    },
    "ckb:repo:sym:def456": {
      "stableId": "ckb:repo:sym:def456",
      "name": "SearchSymbols",
      "kind": "method"
    }
  },
  "errors": {
    "ckb:repo:sym:ghi789": "symbol not found"
  }
}

Use cases:

Fetching details for symbols from a previous search
Batch lookups after findReferences
Reducing round trips for known symbol IDs

batchSearch

Perform multiple symbol searches in a single call.

Budget: Cheap

{
  "queries": [
    { "query": "Handler", "kind": "function", "limit": 5 },
    { "query": "Service", "kind": "struct", "scope": "internal/api" },
    { "query": "Config", "limit": 10 }
  ]
}

Parameters:

queries: Array of search queries (required, max 10)
- query: Search query string (required)
- kind: Symbol kind filter (optional)
- scope: Module scope filter (optional)
- limit: Max results per query (default: 10)

Output:

{
  "results": [
    {
      "query": "Handler",
      "symbols": [
        { "stableId": "...", "name": "HTTPHandler", "kind": "function" }
      ],
      "totalCount": 12,
      "truncated": true
    },
    {
      "query": "Service",
      "symbols": [
        { "stableId": "...", "name": "UserService", "kind": "struct" }
      ],
      "totalCount": 3,
      "truncated": false
    },
    {
      "query": "Config",
      "symbols": [],
      "totalCount": 0,
      "error": "no matches found"
    }
  ]
}

Use cases:

Searching for multiple related concepts at once
Finding all handlers, services, and configs together
Reducing search iterations during exploration

When to Use Compound vs Granular Tools

Scenario	Use	Reason
Initial exploration	`explore`	Get comprehensive overview in one call
Deep-dive into symbol	`understand`	Aggregates 5+ granular calls
Before refactoring	`prepareChange`	Risk + tests + impact in one call
Specific reference lookup	`findReferences`	Targeted query is faster
Single symbol details	`getSymbol`	No overhead from aggregation
CI pipeline integration	Granular tools	More control over caching

MCP-Integration — Setup guides for all platforms
Presets — Tool presets for token optimization
API-Reference — HTTP API documentation
Prompt-Cookbook — Example prompts and workflows
Federation — Cross-repo federation setup
Daemon-Mode — Daemon configuration
Telemetry — Runtime telemetry setup

MCP Tools Reference

Tools Overview

Discovery & Search

Flow & Runtime

File Navigation

Change Awareness

System Orientation

Symbol Analysis

Ownership (v6.0)

Architectural Decisions (v6.0)

System

Background Jobs (v6.1)

CI/CD Integration (v6.1)

Daemon Mode (v6.2.1)

Tree-sitter Complexity (v6.2.2)

Contract Analysis (v6.3)

Runtime Telemetry (v6.4)

Developer Intelligence (v6.5)

Doc-Symbol Linking (v7.3)

Remote Federation (v7.3)

Multi-Repo Management (v7.3)

Compound Operations (v8.0)

Core Tools (v5.1-v5.2)

traceUsage

listEntrypoints

explainFile

explainPath

summarizeDiff

getArchitecture

getHotspots

listKeyConcepts

recentlyRelevant

searchSymbols

getSymbol

findReferences

explainSymbol

justifySymbol

getCallGraph

getModuleOverview

analyzeImpact

getStatus

reindex

doctor

Architectural Memory Tools (v6.0)

getOwnership

getModuleResponsibilities

recordDecision

getDecisions

annotateModule

refreshArchitecture

Enhanced getHotspots (v6.0)

Background Jobs & CI/CD Tools (v6.1)

getJobStatus

listJobs

cancelJob

refreshArchitecture (Enhanced in v6.1)

summarizePr

getOwnershipDrift

Federation Tools (v6.2)

listFederations

federationStatus

federationRepos

federationSearchModules

federationSearchOwnership

federationGetHotspots

federationSearchDecisions

federationSync

Daemon Mode Tools (v6.2.1)

daemonStatus

listSchedules

runSchedule

listWebhooks

testWebhook

webhookDeliveries

Tree-sitter Complexity (v6.2.2)

getFileComplexity

Contract Analysis Tools (v6.3)

listContracts

analyzeContractImpact

getContractDependencies