Source: github.com/Nomannazir/codebase-brain-mcp · Install: PyPI · MIT licence
Claude Code asks why a function looks the way it does, what breaks if it changes, and whether its docs are current. Codebase Brain answers with commits, callers, tests and doc findings, all cited.
The problem
AI coding assistants write new code well, but struggle with code that already exists:
- They can't see the whole project. They read a few files and guess the rest, so they miss the function that matters or invent one that doesn't exist.
- You can't check their answers. Without file and line references, you either trust them or re-read the code yourself.
- They don't know why code is the way it is. The reasons live in git history and pull requests, which assistants never read, so they "clean up" code that exists for a reason.
- They don't know what a change will break, or whether the docs still match the code.
- Many tools send your code to someone else's server.
What I built
An MCP server that works with Claude Code, Claude Desktop, Cursor, VS Code Copilot, Windsurf, Gemini CLI and Codex CLI. Point it at a local folder or a public git URL and the assistant gets these tools:
ask_codebaseandsearch: answers with proof. Every result points to the exact file and lines.explain_history: every change made to a function, who made it, why (commit message and pull request) and what changed.impact_of_change: everything that uses a function, directly or indirectly, plus the tests that cover it.find_doc_drift: documentation that mentions functions, files or settings that no longer exist, or examples that would no longer work, each with a suggested fix.read_lines: opens the exact lines behind a citation, and refuses paths outside the repo.
How it works
- Code-aware chunking. Python is split with
ast; JavaScript, TypeScript, JSX and TSX with tree-sitter, by function, class, method, interface and type, with their doc comments. Each chunk knows its symbol and exact lines, so citations point at real code. - Hybrid retrieval. SQLite FTS5 (BM25, with camelCase and snake_case splitting) plus local embeddings, merged with reciprocal-rank fusion, so exact names and plain-English questions both work.
- Private and free. Embeddings run on your machine with fastembed (ONNX). No API keys, and code never leaves your computer.
- Incremental indexing. Only changed files are re-embedded; a no-change re-index of a 42-file repo takes about 2 seconds.
- History-aware. Follows a function's lines back through git and links the pull requests behind each change.
- Safe remote mode. It can run as a Streamable HTTP server with bearer-token auth (constant-time comparison), refuses to listen publicly without a strong token, only indexes public git URLs remotely, and limits repo size and git command time.
Stack
Python · MCP · RAG · tree-sitter · SQLite FTS5 · fastembed / ONNX · git · GitHub Actions CI
What this means for your project
If you want AI agents that work on your real systems (your codebase, your documents, your data) and give answers you can verify, this is the kind of tooling I build: retrieval that cites its sources, tools with clear limits, and security that's on by default.