Codebase Intelligence

Give your AI assistant a deep understanding of your codebase — without burning your context window.

CI npm License: MIT

An MCP server that parses your entire codebase with tree-sitter, builds a semantic graph of symbols, references, and dependencies, and lets AI assistants query it in real time. 18 tools, 8 languages, zero infrastructure.

Works with Claude Code, Cursor, VS Code, and any MCP-compatible client.

---

Why?

AI coding assistants are limited by what fits in their context window. When they need to understand your codebase — find callers of a function, trace a dependency chain, or assess the impact of a change — they resort to grep and guesswork, burning thousands of tokens on raw file reads.

mcp-codebase-intelligence gives them structured understanding in ~200 tokens instead of 50,000.

	Without	With codebase-intelligence
Understand a PR	Read 1200 lines, open 23 files	semantic_diff → 8 risk flags in 3 seconds
Find payment logic	grep "payment" → 200 results	search_codebase "payment processing" → 3 exact matches with docstrings
Impact of a change	Manually trace callers for 30 min	analyze_change_impact → 12 dependents across 6 files, instantly
Onboard to new repo	Read code for 2 days	architecture_diagram + query_codebase → 10 minutes
AI context cost	Feed 50k tokens of raw files	Structured 200-token summaries

No Docker. No cloud. No API keys. No embeddings. Just npx.

---

Quick Start

One-liner (no clone needed)

# Add to Claude Code via npx — auto-detects your project from cwd
claude mcp add codebase-intelligence npx mcp-codebase-intelligence

Or with an explicit project path:

claude mcp add codebase-intelligence \
  npx mcp-codebase-intelligence \
  -e PROJECT_ROOT=/path/to/your/project

JSON config (Claude Code, Cursor, VS Code)

Add to your MCP config file:

{
  "mcpServers": {
    "codebase-intelligence": {
      "command": "npx",
      "args": ["mcp-codebase-intelligence"],
      "env": {
        "PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

From source (for development)

git clone https://github.com/g-tiwari/mcp-codebase-intelligence.git
cd mcp-codebase-intelligence
npm install && npm run build

claude mcp add codebase-intelligence \
  node /path/to/mcp-codebase-intelligence/dist/index.js \
  -e PROJECT_ROOT=/path/to/your/project

That's it. The server indexes your codebase on startup and watches for changes.

---

Multi-Project Support

Work across multiple repos, monorepos, or a mix of both — from a single MCP server.

Auto-detection (zero config)

When no config is set, the server auto-detects your project:

1. Finds the git root from your current directory
2. Detects monorepo markers (pnpm, lerna, nx, npm/yarn workspaces, go.work, Cargo workspace)
3. Indexes accordingly

Multi-repo projects

Use PROJECT_ROOTS for projects spanning multiple repositories:

claude mcp add codebase-intelligence \
  npx mcp-codebase-intelligence \
  -e PROJECT_ROOTS="/code/shared-models,/code/api-gateway,/code/android-app"

Config file (power users)

Create .codegraph.json in your project root (or ~/.codegraph/config.json for user-level config):

{
  "projects": {
    "tv-backend": {
      "root": "/code/monorepo",
      "include": ["packages/api-gateway", "packages/shared-models"],
      "roots": ["/code/android-app", "/code/webos-app"]
    },
    "music-service": {
      "roots": ["/code/music-api", "/code/music-models"]
    }
  }
}

Then use list_projects and switch_project tools to navigate between projects.

---

18 Tools

Code Navigation

Tool	What it does
find_symbol	Search for functions, classes, interfaces, types by name. Fuzzy matching, kind/scope filters. Returns signatures and docstrings.
get_references	Find all callers/users of a symbol. Transitive: follow the chain N levels deep.
get_exports	Public API surface of any file — all exported symbols with signatures.
get_dependencies	Import graph for a file. Transitive: see the full dependency tree.
get_call_graph	Who calls this function? What does it call? Tree or mermaid diagram output.

Code Intelligence (LSP-powered)

Tool	What it does
goto_definition	Jump to the definition of any symbol at a given position (TS/JS).
get_type_info	Get the inferred type of any expression at a given position (TS/JS).
find_implementations	Find all implementations of an interface or abstract method (TS/JS).

Change Analysis

Tool	What it does
semantic_diff	Feed it a git_ref (e.g. HEAD~1). It identifies affected symbols, finds all downstream dependents, and flags breaking changes.
analyze_change_impact	Point it at specific lines in a file. It tells you which symbols are affected and who depends on them.

Architecture & Discovery

Tool	What it does
architecture_diagram	Auto-generate a mermaid diagram of module dependencies, grouped by directory.
query_codebase	Ask natural language questions: "find all API endpoints", "what does the orders module do?", "what depends on the database layer?"
search_codebase	Search symbols by their docstring/comment content. Find code by what it does, not what it's named.

Project Management

Tool	What it does
list_projects	Show all configured projects, their roots, and index stats.
switch_project	Change active project context. All tools operate against the selected project.
add_project	Add a new project at runtime. Indexes immediately and persists to config.

Admin

Tool	What it does
get_index_stats	How many files, symbols, references, and imports are indexed.
reindex	Trigger a full re-index after major changes.

---

8 Languages

Language	Extensions	Parser
TypeScript	.ts .tsx .mts .cts	tree-sitter + LSP
JavaScript	.js .jsx .mjs .cjs	tree-sitter + LSP
Python	.py .pyi	tree-sitter
Go	.go	tree-sitter
Rust	.rs	tree-sitter
Java	.java	tree-sitter
C	.c .h	tree-sitter
C++	.cpp .cc .cxx .hpp .hxx .hh	tree-sitter

All languages get symbol extraction, reference tracking, import/export analysis, call graphs, and docstring/comment extraction. TypeScript/JavaScript additionally get LSP-powered go-to-definition, type info, and find-implementations.

---

How It Works

Source Files ──> tree-sitter AST ──> Symbol Extraction ──> SQLite Graph
                                                              │
                                    File Watcher ─────────────┤ (incremental updates)
                                                              │
                                    MCP Tools ◄───────────────┘ (AI queries)
                                        │
                                    LSP Servers ──> Type Info (TS/JS)

1. Parse — tree-sitter builds ASTs for all supported files
2. Extract — language plugins walk the AST to find symbols, references, imports, inheritance, and docstrings
3. Store — everything goes into a SQLite database with WAL mode, prepared statements, batch transactions
4. Watch — chokidar monitors the filesystem; changed files are re-indexed incrementally
5. Query — MCP tools run recursive SQL queries against the graph (transitive references, dependency chains)
6. LSP — typescript-language-server provides type-aware intelligence for TS/JS

Performance

• Batch indexing with single-transaction writes
• Prepared statement cache -- 14 SQL statements prepared once at startup
• In-memory hash cache -- skip DB lookups for unchanged files
• Incremental updates -- only re-index files that actually changed

Tested on real-world projects: Zod, Express, gin, ripgrep, gson.

---

Testing

npm test

146 tests across 10 test suites covering all 8 language parsers, docstring extraction, grammar regression tests, the graph engine, and semantic diff.

---

Configuration

Environment Variables

Variable	Description	Default
PROJECT_ROOT	Path to a single codebase to index	git root of cwd()
PROJECT_ROOTS	Comma-separated paths for multi-repo projects	—
DB_PATH	Path to SQLite database file	~/.codegraph/graphs/<project>.db
LOG_LEVEL	Logging verbosity: debug, info, warn, error	info

Config Files

File	Scope	Purpose
.codegraph.json	Project (check into git)	Define project roots, monorepo scoping
~/.codegraph/config.json	User	Personal multi-project setup

---

License

MIT