MikeRecognex/mcp-codebase-index

A structural codebase indexer with an MCP server for AI-assisted development. Zero runtime dependencies — uses Python's ast module for Python analysis and regex-based parsing for TypeScript/JS, Go, Rust, and C#. Requires Python 3.11+.
What It Does
Indexes codebases by parsing source files into structural metadata -- functions, classes, imports, dependency graphs, and cross-file call chains -- then exposes 18 query tools via the Model Context Protocol, enabling Claude Code and other MCP clients to navigate codebases efficiently without reading entire files.
**Automatic incremental re-indexing:** In git repositories, the index stays up to date automatically. Before every query, the server checks git diff and git status (~1-2ms). If files changed, only those files are re-parsed and the dependency graph is rebuilt. No need to manually call reindex after edits, branch switches, or pulls.
**Persistent disk cache:** The index is saved to a pickle cache file (.codebase-index-cache.pkl) after every build. On subsequent server starts, the cache is loaded and validated against the current git HEAD — if the ref matches, startup is instant. If a small number of files changed (≤20), the cached index is loaded and incrementally updated instead of rebuilt from scratch. This eliminates the cold-start penalty when restarting Claude Code sessions, restarting the MCP server, or resuming work after context compaction.
Language Support
| Language | Method | Extracts |
|----------|--------|----------|
| Python (.py) | AST parsing | Functions, classes, methods, imports, dependency graph |
| TypeScript/JS (.ts, .tsx, .js, .jsx) | Regex-based | Functions, arrow functions, classes, interfaces, type aliases, imports |
| Go (.go) | Regex-based | Functions, methods (receiver-based), structs, interfaces, type aliases, imports, doc comments |
| Rust (.rs) | Regex-based | Functions (pub/async/const/unsafe), structs, enums, traits, impl blocks, use statements, attributes, doc comments, macro_rules |
| C# (.cs) | Regex-based | Classes, interfaces, structs, enums, records, methods, constructors, using directives, [Attributes], /// XML doc comments |
| Markdown/Text (.md, .txt, .rst) | Heading detection | Sections (# headings, underlines, numbered, ALL-CAPS) |
| Other | Generic | Line counts only |
Installation
The [mcp] extra includes the MCP server dependency. Omit it if you only need the programmatic API.
For development (from a local clone):
MCP Server
Running
PROJECT_ROOT specifies which directory to index. Defaults to the current working directory.
Persistent Cache
In git repositories, the server automatically caches the index to .codebase-index-cache.pkl in the project root. On startup:
1. **Cache hit (exact match):** If the cached git ref matches the current HEAD, the index loads instantly from disk — no parsing, no file walking.
2. **Cache hit (small changeset):** If ≤20 files changed since the cached ref, the cached index is loaded and incrementally updated on the first query.
3. **Cache miss:** If the changeset is large or no cache exists, a full rebuild runs and saves a new cache.
Add .codebase-index-cache.pkl to your .gitignore — it's a local-only build artifact.
Configuring with OpenClaw
Install the package on the machine where OpenClaw is running:
Add the MCP server to your OpenClaw agent config (openclaw.json):
Restart OpenClaw and verify the connection:
All 18 tools will be available to your agent.
**Performance note:** The server automatically detects file changes via git diff before every query (~1-2ms) and incrementally re-indexes only what changed. However, OpenClaw's default MCP integration via mcporter spawns a fresh server process per tool call, which discards the in-memory index and forces a full rebuild each time (~1-2s for small projects, longer for large ones). With persistent caching, these cold starts are now significantly faster — the server loads from the disk cache instead of re-parsing the entire codebase. For persistent connections (avoiding even the cache load overhead), use the openclaw-mcp-adapter plugin, which connects once at startup and keeps the server running: