codedb-mcp-fast-code-intelligence

codedb-mcp Fast Code Intelligence

Skill by ara.so — MCP Skills collection.

Overview

codedb-mcp (also called codebase-mcp) is a Rust-based MCP server that turns any local repository into a persistent code intelligence service. It maintains a tree-sitter indexed database under .codedb-mcp/ with symbols, references, dependencies, graph metadata, lexical indexes, and vector embeddings for fast semantic search.

Key capabilities:

• Millisecond-latency warm queries — 20,000x faster than rg on indexed searches
• Answer-oriented context tools — codedb_context and codedb_explore return ranked relevant code without dumping entire files
• Dependency-aware module discovery — Automatic grouping of related files based on dependency graphs
• LSP-like features — Symbol definitions, callers, outlines, and reference navigation
• Code Module Atlas — Visual 3D browser showing file relationships and module boundaries
• DeepWiki — Auto-generated repository documentation with cited sources
• Local-first — All data stored in project .codedb-mcp/ directory, no cloud dependencies

Performance benchmarks (u3dclient Unity C# project):

• Index 18,852 files in 13.8s cold, 0.741s warm cache-hit
• Symbol lookup: 0.088-0.351ms
• Text search: 0.103-0.442ms warm (vs 77-5,007ms for rg)
• Callers lookup: 8-17ms avg
• Token savings: 43% reduction vs shell-based code lookup (254k tokens saved across 3 feature analysis sessions)

Installation

Prerequisites

• Rust toolchain (for building from source)
• Node.js (for skills and atlas viewer)
• Git repository to index

Build from Source

git clone https://github.com/killop/codedb-mcp.git
cd codedb-mcp
cargo build --release

The binary will be at target/release/codedb-mcp (or codedb-mcp.exe on Windows).

Project Setup

1. Create configuration file in your target repository:

cd /path/to/your/project
mkdir -p .codedb-mcp

2. Create .codedb-mcp/codedb-mcp.toml:

# Basic configuration
[project]
name = "myproject"
root = "."

# Include/exclude patterns
[scan]
include = ["src/**/*.rs", "lib/**/*.rs"]
exclude = ["target/**", "node_modules/**", ".git/**"]

# Language-specific settings
[languages]
rust = { enabled = true }
typescript = { enabled = true }
python = { enabled = true }

# Vector search (optional, lazy-loaded on first use)
[vector]
model = "minishlab/potion-code-16M"  # Model2Vec model from HuggingFace

Unity C# example config:

[project]
name = "u3dclient"
root = "."

[scan]
include = ["Assets/**/*.cs", "Packages/**/*.cs"]
exclude = [
    "Library/**",
    "Temp/**",
    "obj/**",
    "Build/**",
    "Logs/**"
]

[languages]
csharp = { enabled = true }

3. Build initial index:

/path/to/codedb-mcp --project-root . index

MCP Server Configuration

Add to your MCP settings file (e.g., Claude Desktop config):

{
  "mcpServers": {
    "codedb-myproject": {
      "command": "/path/to/codedb-mcp",
      "args": ["--project-root", "/path/to/your/project", "serve"],
      "env": {
        "RUST_LOG": "info"
      }
    }
  }
}

Windows PowerShell example:

{
  "mcpServers": {
    "codedb-u3dclient": {
      "command": "D:\\tools\\codedb-mcp\\target\\release\\codedb-mcp.exe",
      "args": ["--project-root", "D:\\projects\\u3dclient", "serve"]
    }
  }
}

Core MCP Tools

Index Management

codedb_index

Build or rebuild the code database.

// Trigger full rebuild
await use_mcp_tool("codedb-myproject", "codedb_index", {
  force_rebuild: true
});

// Incremental update (default)
await use_mcp_tool("codedb-myproject", "codedb_index", {});

When to use:

• After cloning a repository
• When adding new files
• After significant code changes
• When index appears stale

codedb_status

Check index health and statistics.

const status = await use_mcp_tool("codedb-myproject", "codedb_status", {});
// Returns: file counts, chunk counts, graph stats, cache state

codedb_version

Get server version info.

const version = await use_mcp_tool("codedb-myproject", "codedb_version", {});

Symbol Navigation

codedb_symbol

Find symbol definitions across the codebase.

// Find class/function/variable definition
const defs = await use_mcp_tool("codedb-myproject", "codedb_symbol", {
  symbol: "PoolManager"
});
// Returns: [{path, line, column, context}]

// Find multiple symbols
const defs = await use_mcp_tool("codedb-myproject", "codedb_symbol", {
  symbol: "UserService|AuthController"
});

Use cases:

• Jump to definition
• Find class/interface declarations
• Locate function implementations

codedb_outline

Get symbol outline for a single file.

const outline = await use_mcp_tool("codedb-myproject", "codedb_outline", {
  path: "src/services/user_service.rs"
});
// Returns: hierarchical list of classes, functions, fields with line numbers

Performance: 0.088-0.351ms per file (after first load)

codedb_callers

Find all call sites for a symbol definition.

const callers = await use_mcp_tool("codedb-myproject", "codedb_callers", {
  path: "src/pool.rs",
  line: 42,  // definition line
  symbol: "PoolManager"
});
// Returns: [{caller_path, caller_line, context}]

Performance: 8-17ms avg

Use cases:

• Find all usages before refactoring
• Understand impact of API changes
• Trace call chains

Search Tools

codedb_text_search

Fast full-text and regex search using trigram indexing.

// Exact string search
const results = await use_mcp_tool("codedb-myproject", "codedb_text_search", {
  query: "NetworkListenerManager",
  case_sensitive: false
});

// Regex search
const results = await use_mcp_tool("codedb-myproject", "codedb_text_search", {
  query: "class\\s+(\\w+)Manager",
  is_regex: true
});

// Scoped search
const results = await use_mcp_tool("codedb-myproject", "codedb_text_search", {
  query: "PoolManager",
  scope: ["src/**/*.rs"]
});

Performance: 0.103-0.442ms warm (vs 77-5,007ms for rg on same queries)

Parameters:

• query: search string or regex pattern
• is_regex: treat query as regex (default: false)
• case_sensitive: case-sensitive matching (default: false)
• scope: file path patterns to limit search
• limit: max results (default: 100)

codedb_search

Unified semantic + symbol + text search.

// Symbol-aware search
const results = await use_mcp_tool("codedb-myproject", "codedb_search", {
  query: "PoolManager",
  mode: "symbol"
});

// Natural language semantic search (uses vector embeddings)
const results = await use_mcp_tool("codedb-myproject", "codedb_search", {
  query: "alliance rally join logic",
  mode: "semantic",
  limit: 20
});

// Combined search
const results = await use_mcp_tool("codedb-myproject", "codedb_search", {
  query: "user authentication",
  mode: "fusion"  // symbol + word-trigram + vector
});

Modes:

• symbol: exact symbol matching
• text: trigram full-text search
• semantic: vector similarity search
• fusion: weighted combination of all methods

Performance:

• Symbol-aware: 22ms
• Semantic: 36ms (after vector model load)

codedb_word

Exact identifier inverted index lookup.

const results = await use_mcp_tool("codedb-myproject", "codedb_word", {
  word: "initialize",
  limit: 50
});
// Returns: all files containing exact identifier "initialize"

Performance: ~100ms including lazy word sidecar access

Answer-Oriented Context Tools

codedb_context

Get ranked relevant code context WITHOUT dumping full files. Returns summaries, symbols, and snippets optimized for answering questions.

// Architecture question
const context = await use_mcp_tool("codedb-myproject", "codedb_context", {
  query: "how does the pool management system work?",
  max_tokens: 2000  // output budget
});

// Feature investigation
const context = await use_mcp_tool("codedb-myproject", "codedb_context", {
  query: "alliance rally and join logic",
  focus_paths: ["src/alliance/**"],
  max_tokens: 3000
});

Performance: 6.5-30ms depending on query complexity

Output: ~1.5-2.0k tokens of ranked context (vs potentially 100k+ from naive file dumps)

When to use:

• Answering "how does X work?" questions
• Feature area exploration
• Architecture understanding
• Before making changes to unfamiliar code

Parameters:

• query: natural language question or keyword
• max_tokens: output budget (default: 2000)
• focus_paths: limit to specific directories
• include_deps: include dependency information

codedb_explore

Budgeted source-context excerpts with token limit.

const excerpts = await use_mcp_tool("codedb-myproject", "codedb_explore", {
  query: "PoolManager initialization",
  max_chars: 10000  // character budget
});

// Returns: ranked code excerpts staying within max_chars limit
// Output: ~2.5-3.0k tokens

Performance: 7-29ms

Difference from codedb_context:

• codedb_context: returns summaries + symbols + minimal snippets
• codedb_explore: returns larger source excerpts with explicit char budget

Dependency Analysis

codedb_deps

Analyze file dependencies (imports, includes, references).

// Direct dependencies (what this file imports)
const deps = await use_mcp_tool("codedb-myproject", "codedb_deps", {
  path: "src/services/user.rs",
  direction: "depends_on"
});

// Reverse dependencies (what imports this file)
const rdeps = await use_mcp_tool("codedb-myproject", "codedb_deps", {
  path: "src/models/user.rs",
  direction: "imported_by"
});

// Transitive dependencies (full closure)
const transitive = await use_mcp_tool("codedb-myproject", "codedb_deps", {
  path: "src/core/engine.rs",
  direction: "depends_on",
  transitive: true,
  max_depth: 3
});

Performance:

• Direct: 0.096ms
• Reverse (first sidecar): 170ms, then sub-ms
• Transitive: depends on depth

Directions:

• depends_on: outgoing dependencies
• imported_by: incoming dependents

File Operations

codedb_read

Read indexed file or line range.

// Read entire file
const content = await use_mcp_tool("codedb-myproject", "codedb_read", {
  path: "src/main.rs"
});

// Read line range
const snippet = await use_mcp_tool("codedb-myproject", "codedb_read", {
  path: "src/services/auth.rs",
  start_line: 42,
  end_line: 67
});

Performance: 0.562ms avg

When to use:

• After using codedb_context to identify relevant files
• Reading specific functions identified by codedb_symbol
• NOT as first step for exploration (use codedb_context instead)

codedb_tree

Get indexed file tree with metadata.

const tree = await use_mcp_tool("codedb-myproject", "codedb_tree", {
  path_pattern: "src/**/*.rs"
});
// Returns: [{path, language, lines, symbol_count}]

Performance: 8.782ms

codedb_hot

Get recently modified indexed files.

const recent = await use_mcp_tool("codedb-myproject", "codedb_hot", {
  limit: 20
});
// Returns: files sorted by modification time

Performance: 2.116ms

Advanced Features

codedb_bundle

Execute multiple queries in a single MCP call (reduces round-trips).

const bundle = await use_mcp_tool("codedb-myproject", "codedb_bundle", {
  calls: [
    {tool: "codedb_symbol", args: {symbol: "UserService"}},
    {tool: "codedb_deps", args: {path: "src/user.rs", direction: "depends_on"}},
    {tool: "codedb_outline", args: {path: "src/user.rs"}}
  ]
});
// Returns: array of results matching call order

When to use:

• Gathering related information in one shot
• Reducing MCP overhead
• Building complex queries

Module Discovery & Atlas

Generate dependency-aware module groupings:

const modules = await use_mcp_tool("codedb-myproject", "codedb_modules", {
  min_size: 3,  // minimum files per module
  max_size: 50  // split large modules
});
// Returns: module groups based on dependency graph + label propagation

Build visual atlas (requires Node.js):

cd codedb-mcp/skills/code-module-atlas
node scripts/build-module-atlas.mjs myproject
cd assets/viewer
npm install
npm run dev -- --port 5174

Opens interactive 3D viewer showing:

• Star nodes for each source file
• Module boundaries and labels
• Dependency edges
• File details on selection

Configuration Patterns

Language-Specific Indexing

[languages]
rust = { enabled = true }
typescript = { enabled = true, extensions = [".ts", ".tsx"] }
python = { enabled = true, extensions = [".py"] }
csharp = { enabled = true, extensions = [".cs"] }
cpp = { enabled = true, extensions = [".cpp", ".hpp", ".cc", ".h"] }

Performance Tuning

[performance]
# Parallel indexing threads
threads = 8

# Memory limits
max_memory_mb = 2048

# Cache generations (for rolling updates)
cache_version = 23

Vector Search Configuration

[vector]
# Model2Vec model from HuggingFace
model = "minishlab/potion-code-16M"

# Cache location (optional, defaults to HuggingFace cache)
cache_dir = "/path/to/model/cache"

# Lazy loading (default: true)
lazy_load = true

Vector embeddings are built lazily on first semantic search, not during initial indexing.

Monorepo Configuration

For large monorepos, create separate configs per sub-project:

project-root/
  .codedb-mcp/codedb-mcp.toml          # Root project
  backend/.codedb-mcp/codedb-mcp.toml  # Backend service
  frontend/.codedb-mcp/codedb-mcp.toml # Frontend app

Each can run as separate MCP server instances.

Common Workflows

Workflow 1: Understanding a New Feature Area

// Step 1: Get high-level context without file dumps
const context = await use_mcp_tool("codedb-project", "codedb_context", {
  query: "how does user authentication work?",
  max_tokens: 2500
});

// Step 2: Find specific entry points
const entry = await use_mcp_tool("codedb-project", "codedb_symbol", {
  symbol: "AuthController|authenticate"
});

// Step 3: Check dependencies
const deps = await use_mcp_tool("codedb-project", "codedb_deps", {
  path: entry[0].path,
  direction: "depends_on"
});

// Step 4: Read focused files
const code = await use_mcp_tool("codedb-project", "codedb_read", {
  path: entry[0].path
});

Workflow 2: Impact Analysis for Refactoring

// Step 1: Find the symbol definition
const defs = await use_mcp_tool("codedb-project", "codedb_symbol", {
  symbol: "legacy_payment_process"
});

// Step 2: Find all callers
const callers = await use_mcp_tool("codedb-project", "codedb_callers", {
  path: defs[0].path,
  line: defs[0].line,
  symbol: "legacy_payment_process"
});

// Step 3: Check reverse dependencies
const dependents = await use_mcp_tool("codedb-project", "codedb_deps", {
  path: defs[0].path,
  direction: "imported_by"
});

// Step 4: Bundle outline reads for all affected files
const outlines = await use_mcp_tool("codedb-project", "codedb_bundle", {
  calls: callers.map(c => ({
    tool: "codedb_outline",
    args: {path: c.caller_path}
  }))
});

Workflow 3: Exploring Code Architecture

// Step 1: Semantic search for business domain
const modules = await use_mcp_tool("codedb-project", "codedb_search", {
  query: "payment processing workflow",
  mode: "semantic",
  limit: 30
});

// Step 2: Get focused context
const context = await use_mcp_tool("codedb-project", "codedb_context", {
  query: "payment processing workflow",
  focus_paths: ["src/payments/**"],
  max_tokens: 4000
});

// Step 3: Analyze module structure
const deps_analysis = await use_mcp_tool("codedb-project", "codedb_modules", {
  min_size: 5
});

Workflow 4: Incremental Index Updates

# Daily development routine
git pull
/path/to/codedb-mcp --project-root . index  # Incremental: 0.5-1.5s

# After major branch merge
/path/to/codedb-mcp --project-root . index --force-rebuild  # Full: 10-15s

Incremental performance (1,000 files changed):

• Add: 1.508s
• Modify: 1.544s
• Delete: 0.504s

Token Optimization

Codex Token Observer

Monitor and optimize MCP tool token usage:

cd codedb-mcp/skills/codedb-mcp
node scripts/codex-observe.mjs --project myproject --since 24h --top 12

Reports:

• Model token counts per session
• Tool output token estimates
• High-output call patterns
• Missed codedb_bundle opportunities
• Non-codedb source lookups that could use codedb tools

Example findings (Unity C# project):

• 43% token reduction vs shell-based lookup
• 38% faster execution
• 254k tokens saved across 3 feature analysis sessions

Best Practices for Token Efficiency

DO:

• Start with codedb_context for exploration (1.5-2k tokens)
• Use codedb_explore with explicit max_chars budgets
• Bundle related queries with codedb_bundle
• Use codedb_symbol + codedb_callers instead of grepping
• Scope searches with focus_paths or file patterns

DON'T:

• Call codedb_read on many files without first using codedb_context
• Use unbounded codedb_text_search on large codebases
• Repeatedly call codedb_outline in loops (use codedb_bundle instead)
• Dump full file contents when you only need specific symbols

Token Benchmark Comparison

Approach	World Map Logic	Hero Attributes	Alliance Rally	Total
codedb-mcp enabled	92,639 tokens	114,436 tokens	128,865 tokens	335,940 tokens
Shell-based lookup	231,810 tokens	173,576 tokens	185,448 tokens	590,834 tokens
Savings	60.0%	34.1%	30.5%	43.1%

Troubleshooting

Index Not Building

Symptoms: codedb_index fails or hangs

Solutions:

1. Check file permissions on .codedb-mcp/ directory
2. Verify include/exclude patterns in config:

   /path/to/codedb-mcp --project-root . status
   

3. Check for corrupted cache:

   rm -rf .codedb-mcp/*.bin
   /path/to/codedb-mcp --project-root . index --force-rebuild
   

4. Enable debug logging:

   RUST_LOG=debug /path/to/codedb-mcp --project-root . index
   

Slow Search Performance

Symptoms: codedb_text_search or codedb_search taking seconds

Causes:

• First query triggers lazy sidecar load (expected: 15-30ms)
• Regex search on very large files
• Vector model not cached

Solutions:

1. Warm up lazy sidecars:

   // First call loads word index (~100ms)
   await use_mcp_tool("codedb-project", "codedb_word", {word: "test"});
   
   // First semantic search loads embeddings (~1-2s)
   await use_mcp_tool("codedb-project", "codedb_search", {
     query: "warmup",
     mode: "semantic"
   });
   

2. Scope searches to reduce candidate files:

   await use_mcp_tool("codedb-project", "codedb_text_search", {
     query: "pattern",
     scope: ["src/core/**"]
   });
   

3. Use max_tokens or limit parameters to cap output

Vector Search Not Working

Symptoms: Semantic search returns no results or errors

Solutions:

1. Ensure Model2Vec model is downloaded:

   # Check HuggingFace cache
   ls ~/.cache/huggingface/hub/models--minishlab--potion-code-16M/
   

2. Configure explicit cache location if needed:

   [vector]
   model = "minishlab/potion-code-16M"
   cache_dir = "/alternative/cache/path"
   

3. Trigger embedding build manually:

   const results = await use_mcp_tool("codedb-project", "codedb_search", {
     query: "any query",
     mode: "semantic"
   });
   // First call builds embeddings (1-2s), subsequent calls are fast
   

Stale Results

Symptoms: Search/symbol results don't reflect recent changes

Solutions:

1. Check index freshness:

   const status = await use_mcp_tool("codedb-project", "codedb_status", {});
   // Check "last_indexed" timestamp
   

2. Run incremental update:

   /path/to/codedb-mcp --project-root . index
   

3. If incremental fails, force rebuild:

   /path/to/codedb-mcp --project-root . index --force-rebuild
   

High Memory Usage

Symptoms: codedb-mcp process using excessive RAM

Solutions:

1. Adjust thread count in config:

   [performance]
   threads = 4  # reduce from default 8
   

2. Limit scope of indexed files:

   [scan]
   exclude = ["vendor/**", "third_party/**", "*.generated.*"]
   

3. Disable vector search if not needed:

   [vector]
   enabled = false
   

MCP Server Won't Start

Symptoms: Agent can't connect to codedb MCP server

Solutions:

1. Test server manually:

   /path/to/codedb-mcp --project-root /path/to/project serve
   # Should start and wait for stdio MCP protocol
   

2. Check MCP config syntax:

   {
     "mcpServers": {
       "codedb-project": {
         "command": "/absolute/path/to/codedb-mcp",
         "args": ["--project-root", "/absolute/path/to/project", "serve"]
       }
     }
   }
   

3. Verify project has index:

   ls /path/to/project/.codedb-mcp/
   # Should contain *.bin files and codedb-mcp.toml
   

4. Check server logs in agent output

DeepWiki Documentation Generation

Generate repository documentation automatically:

cd codedb-mcp/skills/deepwiki

# Generate full documentation
node scripts/generate-deepwiki.mjs myproject

# Output: myproject-deepwiki/
#   index.md                  # Overview
#   modules/                  # Module-focused pages
#   architecture/             # Architecture diagrams
#   flows/                    # Feature flows

DeepWiki uses:

• MCP evidence from codedb_modules, codedb_deps, codedb_context
• Agent reasoning to write business-focused explanations
• Cited source files with line numbers
• Dependency-aware structure

Configure generation:

// In agent context
const wiki = await generate_deepwiki({
  project: "myproject",
  focus_areas: ["payment processing", "user management"],
  max_modules: 20,
  include_risks: true
});

Integration Examples

With Claude Code

// In Claude Desktop MCP config
{
  "mcpServers": {
    "codedb-backend": {
      "command": "/usr/local/bin/codedb-mcp",
      "args": ["--project-root", "/home/user/projects/backend", "serve"]
    }
  }
}

Then in Claude:

• "Search for authentication logic in the backend"
• "Show me what depends on UserService"
• "Find all callers of validate_token"

With Cursor

Add to Cursor MCP settings, then use in composer:

@codedb-project how does the payment processing workflow handle refunds?

The skill will use codedb_context to gather relevant code without dumping files.

With Codex

# Enable codedb-mcp skill and MCP server
codex config add-mcp codedb-project /path/to/codedb-mcp --project-root /path/to/project

# Use in conversation
codex chat "analyze the alliance rally join flow in u3dclient"

Codex will automatically use codedb_context, codedb_search, codedb_deps tools to answer efficiently.

Performance Optimization

Index Optimization

# Optimize for large codebases
[performance]
threads = 16                    # Use more CPU for faster indexing
max_memory_mb = 4096           # Allow more memory for large graphs

[scan]
exclude = [
  "node_modules/**",
  "vendor/**",
  "*.generated.*",
  "*.pb.*",                    # Generated protobuf
  "dist/**",
  "build/**"
]

# Skip large non-source files
max_file_size_kb = 1024

Query Optimization

// Prefer narrow scopes
const results = await use_mcp_tool("codedb-project", "codedb_context", {
  query: "payment logic",
  focus_paths: ["src/payments/**", "src/billing/**"],
  max_tokens: 2000
});

// Bundle related queries
const data = await use_mcp_tool("codedb-project", "codedb_bundle", {
  calls: [
    {tool: "codedb_symbol", args: {symbol: "PaymentProcessor"}},
    {tool: "codedb_context", args: {query: "payment flow", max_tokens: 1500}},
    {tool: "codedb_deps", args: {path: "src/payments/processor.rs"}}
  ]
});

Cache Management

# Check cache size
du -sh /path/to/project/.codedb-mcp/

# Clean old generations (keep only current)
/path/to/codedb-mcp --project-root . cleanup

# Full rebuild if cache corrupted
rm -rf /path/to/project/.codedb-mcp/*.bin
/path/to/codedb-mcp --project-root . index --force-rebuild

Advanced Rust API (for tool development)

If building custom tools that integrate with codedb:

use codedb_mcp::{CodeDb, IndexConfig, SearchMode};