MCP Codebase Analyzer

A Model Context Protocol (MCP) server that lets an LLM explore a codebase structurally - outlines, signatures, dependencies, complexity, and change impact, instead of ingesting raw files into context.

The Problem

Feeding entire files or repositories into an LLM's context window wastes tokens and increases hallucination risk. Most of that content is irrelevant to any given question. If someone asks "what does read_file do," the model doesn't need the whole file — it needs the function's signature, docstring, and maybe its body, nothing else.

Related MCP server: RepoMap

The Approach

Instead of dumping raw text, this server parses code into an Abstract Syntax Tree using Tree-sitter and exposes that structure through a set of MCP tools. An LLM client (e.g. Claude Desktop) can query exactly what it needs, a directory outline, one function's source, an import graph, a complexity score and drill deeper only when the task requires it. The result is a smaller, more precise context footprint and fewer tokens spent on irrelevant code.

Tech Stack

• Python 3.13

• FastMCP - MCP server framework

• Tree-sitter (+ language grammars for Python and JavaScript) - structural parsing

• Git (via subprocess) - diff and change-impact analysis

• GitHub API - remote repository ingestion

• MCP Inspector - protocol-level testing and debugging

Tools

Design Principles

• On-demand over front-loaded. Every tool returns the minimum structure needed to answer the next question, not the whole file.

• Sandboxed by default. All file access is path-bounded to a configured project root, preventing traversal outside the allowed workspace.

• Composable. Higher-level tools (dead code detection, churn heatmaps) are built by combining outputs from lower-level tools (outline, search, git) rather than duplicating parsing logic.

• Language-extensible. Tree-sitter's grammar model means adding a new language is a matter of adding a grammar + query, not rewriting the architecture.

Status

Phase 1 of a three-phase project. Phase 2 is a self-hosted home server (reverse proxy, monitoring, CI/CD). Phase 3 merges the two: applying this same "structured query over raw dump" philosophy to infrastructure — an LLM querying and managing a live server the same way it queries a codebase here.

Running Locally

git clone <this-repo>
cd mcp-codebase-analyzer
python -m venv venv
venv\Scripts\activate      # Windows
pip install -r requirements.txt
fastmcp run server.py

Test with MCP Inspector:

npx @modelcontextprotocol/inspector fastmcp run server.py

Or connect it to Claude Desktop as an MCP server for real LLM tool-use testing.