#WIP (Multiple known issues)

Codebase Intelligence MCP Server

An stdio MCP server that indexes a Python codebase into a local SQLite graph. It offers hybrid code search, fast file context, lazy explanations, dependency traces, and version-aware symbol history.

It is a local, single-user tool—not a language server, hosted service, background crawler, or full type-inference engine.

Status

Phases 1–9 are implemented: schema and parser, graph traversal, search, lazy LLM summaries, versioning, seven MCP tools, CLI indexing, tests, and documentation.

Prerequisites

Python 3.11+
uv
Git (for commit-aware version tracking)
Ollama for indexing/search and local summaries
Node.js for MCP Inspector

Pull the configured local models:

ollama pull qwen3-embedding:0.6b
ollama pull qwen2.5-coder:7b

Setup and first index

cd "d:\Projects\MCP Project\codebase-intelligence-mcp"
uv sync
copy .env.example .env
# Set REPO_PATH in .env, if desired.
uv run codebase-intel index "d:\path\to\python-repo"

To change embedding models safely:

uv run codebase-intel reindex-embeddings "d:\path\to\python-repo"

Start the MCP server after setting REPO_PATH and ensuring Ollama is running:

uv run python src/server.py

MCP tools

Tool	Example	Purpose
`search_codebase`	`{"query":"parse Python files", "top_k":5}`	Hybrid vector + BM25 retrieval with centrality reranking.
`get_file_context`	`{"file_path":"src/parser/ast_parser.py"}`	Instant template summary, imports, and signatures.
`explain_function`	`{"symbol_name":"parse_file"}`	Cached behavioural summary plus live callers/callees.
`trace_dependencies`	`{"symbol_name":"parse_file", "depth":2}`	Breadth-first caller/callee traversal.
`detect_changes`	`{"since_version":"last"}`	Git-backed changed-file parsing and version diffs.
`get_version_history`	`{"symbol_name":"parse_file"}`	Added/removed/renamed/modified history, including rename lineage.
`get_codebase_health`	`{}`	Index counts, lazy-summary coverage, tombstones, and renames.

Configuration

See .env.example. Key settings are OLLAMA_HOST, SUMMARY_MODEL, EMBEDDING_MODEL, USE_REMOTE_SUMMARIES, GEMINI_API_KEY, DATABASE_PATH, and REPO_PATH.

Known limitations

Call-graph heuristic: dynamic dispatch is not resolved. Only unambiguous same-file names become call edges.
Rename heuristic: renames require an exact matching content hash; an edit plus rename appears as removed and added.
Concurrency: SQLite WAL plus a 5-second busy timeout is suitable for local use, not heavy simultaneous multi-process writes.
sqlite-vec scaling: brute-force vector search is comfortable to roughly 50K–100K symbols; it has no ANN index.

Testing

uv run pytest tests/ -v
npx @modelcontextprotocol/inspector uv run python src/server.py

The repository also contains phase exit scripts under scripts/. The CLI and server require local Ollama models; the automated unit tests mock provider calls.

Future work

Background crawler and cross-process coordination
LSP-assisted call resolution and refactor-aware renames
PageRank or impact-scoped centrality recomputation
Token-budget-aware response packing and staleness detection
More languages and ANN vector indexing