codedb-mcp-fast-code-intelligence

# codedb-mcp Fast Code Intelligence > Skill by [ara.so](https://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 ```bash 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: ```bash cd /path/to/your/project mkdir -p .codedb-mcp ``` 2. **Create `.codedb-mcp/codedb-mcp.toml`**: ```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:** ```toml [project] name = "u3dclient" root = "." [scan] include = ["Assets/**/*.cs", "Packages/**/*.cs"] exclude = [ "Library/**", "Temp/**", "obj/**", "Build/**", "Logs/**" ] [languages] csharp = { enabled = true } ``` 3. **Build initial index**: ```bash /path/to/codedb-mcp --project-root . index ``` ### MCP Server Configuration Add to your MCP settings file (e.g., Claude Desktop config): ```json { "mcpServers": { "codedb-myproject": { "command": "/path/to/codedb-mcp", "args": ["--project-root", "/path/to/your/project", "serve"], "env": { "RUST_LOG": "info" } } } } ``` **Windows PowerShell example:** ```json { "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. ```typescript // 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. ```typescript 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. ```typescript const version = await use_mcp_tool("codedb-myproject", "codedb_version", {}); ``` ### Symbol Navigation #### `codedb_symbol` Find symbol definitions across the codebase. ```typescript // 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. ```typescript 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. ```typescript 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. ```typescript // 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. ```typescript // 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. ```typescript 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. ```typescript // 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. ```typescript 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). ```typescript // 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