Tool Presets

CKB exposes 92 tools via MCP, but most sessions only need a subset. Presets group tools by workflow, reducing token overhead by up to 77% while maintaining full functionality.

Why Presets Matter

"My MCP tools were consuming 66,000+ tokens before I even started a conversation." — Community feedback

Every MCP tool definition consumes context window tokens. With 92 tools, the full tools/list response costs ~11k tokens before you even ask a question. Presets solve this by exposing only relevant tools.

Quick Reference

# List all available presets
ckb mcp --list-presets

# Start with a specific preset
ckb mcp --preset=review

Output:

Available presets:

  PRESET        TOOLS         TOKENS  DESCRIPTION
  ------        -----         ------  -----------
  core             21     ~2k tokens  Quick navigation, search, impact analysis (default)
  review           27     ~3k tokens  Code review with ownership and PR summaries
  refactor         33     ~4k tokens  Refactoring analysis with coupling, cycles, dead code
  federation       34     ~4k tokens  Multi-repo queries and cross-repo visibility
  docs             27     ~3k tokens  Documentation-symbol linking and coverage
  ops              33     ~4k tokens  Diagnostics, daemon, webhooks, jobs
  full             92    ~11k tokens  Complete feature set (all tools)

Use: ckb mcp --preset=<name>

Preset Details

`core` (Default)

21 tools | ~2k tokens

The default preset enables the "Investigate & Assess Impact" workflow—sufficient for most coding sessions.

Category	Tools
Compound	`explore`, `understand`, `prepareChange`, `batchGet`, `batchSearch`
Discovery	`searchSymbols`, `getSymbol`
Understanding	`explainSymbol`, `explainFile`, `findReferences`, `getCallGraph`, `traceUsage`
Architecture	`getArchitecture`, `getModuleOverview`, `listKeyConcepts`
Impact	`analyzeImpact`, `getHotspots`
Refactoring	`planRefactor`
System	`getStatus`, `switchProject`, `expandToolset`

Best for: General development, debugging, understanding code, assessing change impact.

`review`

27 tools | ~3k tokens (core + 6 tools)

Code review workflow with ownership and PR analysis.

Added Tools	Purpose
`summarizeDiff`	Analyze git diffs with symbol-level context
`summarizePr`	Comprehensive PR analysis with risk assessment
`getOwnership`	CODEOWNERS + git-blame analysis
`getOwnershipDrift`	Detect ownership changes over time
`recentlyRelevant`	Find recently modified related code
`scanSecrets`	Secret detection for PR reviews

Best for: Pull request reviews, understanding who owns what, reviewing changes.

`refactor`

33 tools | ~4k tokens (core + 13 tools)

Comprehensive refactoring analysis with cycle detection, coupling, dead code, and proactive suggestions.

Added Tools	Purpose
`justifySymbol`	Explain why a symbol exists (trace to entrypoints)
`analyzeCoupling`	Detect co-change patterns from git history
`findDeadCodeCandidates`	Identify potentially unused code
`findDeadCode`	Static dead code detection (no telemetry needed)
`getAffectedTests`	Find tests affected by changes
`compareAPI`	Breaking change detection
`auditRisk`	Multi-factor risk scoring (8 weighted factors)
`explainOrigin`	Trace symbol history through renames
`scanSecrets`	Secret detection for security audits
`analyzeTestGaps`	Find high-risk code lacking test coverage
`findCycles`	Detect dependency cycles with break recommendations
`suggestRefactorings`	Proactive refactoring opportunity detection

Best for: Refactoring planning, identifying dead code, dependency cycle detection, tech debt triage.

`docs`

27 tools | ~3k tokens (core + 6 tools)

Documentation-symbol linking and coverage analysis.

Added Tools	Purpose
`indexDocs`	Index markdown documentation
`getDocsForSymbol`	Find documentation mentioning a symbol
`getSymbolsInDoc`	Find symbols referenced in a document
`getDocsForModule`	Get documentation for a module
`checkDocStaleness`	Detect outdated documentation
`getDocCoverage`	Documentation coverage metrics

Best for: Documentation maintenance, finding related docs, checking doc freshness.

`ops`

33 tools | ~4k tokens (core + 12 tools)

Operational tools for daemon management, jobs, and webhooks.

Added Tools	Purpose
`doctor`	Diagnose configuration issues
`reindex`	Index refresh guidance
`daemonStatus`	Check daemon health
`listJobs`, `getJobStatus`, `cancelJob`	Background job management
`listSchedules`, `runSchedule`	Scheduled task management
`listWebhooks`, `testWebhook`, `webhookDeliveries`	Webhook management
`getWideResultMetrics`	Tool response size analytics

Best for: CKB administration, debugging indexing issues, monitoring.

`federation`

34 tools | ~4k tokens (core + 13 tools)

Multi-repository queries and cross-repo visibility.

Added Tools	Purpose
`listFederations`	List configured federations
`federationStatus`	Federation health check
`federationRepos`	List repos in a federation
`federationSearchModules`	Search modules across repos
`federationSearchOwnership`	Find owners across repos
`federationGetHotspots`	Cross-repo hotspot analysis
`federationSync`	Sync federation data
`federationAddRemote`, `federationRemoveRemote`	Manage remote repos
`federationListRemote`, `federationSyncRemote`, `federationStatusRemote`	Remote repo operations
`federationSearchSymbolsHybrid`	Hybrid local+remote symbol search
`federationListAllRepos`	List all federated repos

Best for: Monorepos, microservices, cross-repository dependency analysis.

`full`

92 tools | ~11k tokens

All available tools. Use when you need capabilities not covered by other presets.

Best for: Power users, when you need everything, legacy compatibility.

Dynamic Expansion

The expandToolset meta-tool (included in all presets) allows the AI to request additional tools mid-session:

{
  "name": "expandToolset",
  "arguments": {
    "preset": "federation",
    "reason": "User asked about cross-repository dependencies"
  }
}

Guardrails:

Requires a reason (minimum 10 characters)
Rate-limited to one expansion per session
Emits tools/list_changed notification for compliant clients

This means you can start with core and let the AI expand when needed, rather than loading everything upfront.

MCP Configuration

Claude Code / Cursor / Windsurf

{
  "mcpServers": {
    "ckb": {
      "command": "npx",
      "args": ["@tastehub/ckb", "mcp", "--preset=review"]
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "ckb": {
      "command": "npx",
      "args": ["@tastehub/ckb", "mcp", "--preset=core", "--repo", "/path/to/repo"]
    }
  }
}

Token Efficiency Visibility

CKB shows token savings at startup:

CKB MCP Server v8.1.0
  Active tools: 21 / 92 (23%)
  Estimated context: ~2k tokens
  Preset: core

The getStatus tool also returns token efficiency metrics:

{
  "preset": {
    "active": "core",
    "exposed": 21,
    "total": 92,
    "expanded": false,
    "estimatedTokens": 2100,
    "fullPresetTokens": 11000,
    "tokenSavings": "77%"
  }
}

Choosing a Preset

If you're...	Use
Just exploring code	`core` (default)
Reviewing a PR	`review`
Planning a refactor	`refactor`
Updating documentation	`docs`
Debugging CKB itself	`ops`
Working across repos	`federation`
Not sure / need everything	`full`

When in doubt, start with core. The AI can expand if needed.