RepoLens MCP: Context Layer for Local Codebases over Model Context Protocol

RepoLens MCP is a powerful Model Context Protocol (MCP) server that transforms any local Git repository into a highly queryable, context-rich knowledge base. It enables AI assistants (like Claude and Cursor) to navigate, search, and understand your entire codebase with semantic precision.

Why RepoLens? (AST + Git > Naive RAG)

Traditional "Chat with your Code" or "Chat with PDF" systems use naive fixed-token splitting, breaking your codebase into arbitrary 500-token chunks. This destroys the context of large functions and classes.

RepoLens takes a fundamentally better approach:

• AST-Aware Chunking: Uses tree-sitter to parse code into logical boundaries (Functions, Classes, Methods) rather than arbitrary text chunks.
• Git Metadata Enrichment: Merges Git commit history directly into the code chunk before embedding. The vector index understands not just what the code does, but who wrote it, when, and why (via commit messages).
• Hybrid Context: By combining ChromaDB dense vector similarity with deterministic Git history and absolute line-range extraction, the LLM receives perfectly bounded, highly relevant context.

System Architecture

sequenceDiagram
    participant Client as MCP Client (Claude/Cursor)
    participant Server as RepoLens FastMCP Server
    participant Chunker as AST Chunker (Tree-sitter)
    participant Git as GitUtils
    participant DB as ChromaDB (SentenceTransformers)

    Note over Server,DB: Initialization Phase (Local RAG)
    Server->>Chunker: Scan Repository & Parse Files
    Chunker-->>Server: Yield logical CodeChunks (Classes/Functions)
    Server->>Git: Fetch commit provenance for file
    Git-->>Server: Return Git Metadata string
    Server->>DB: Embed enriched chunk (Code + Metadata)
    
    Note over Client,DB: Tool Call Phase
    Client->>Server: call_tool("search_codebase", query="auth logic")
    Server->>DB: Semantic Search (all-MiniLM-L6-v2)
    DB-->>Server: Top K Chunks
    Server-->>Client: Formatted results with scores & file boundaries

Setup & Installation

1. Environment Setup

Ensure you have Python 3.11+ installed. Clone this repository and run the automated setup script.

Windows (PowerShell):

.\setup.ps1

macOS / Linux:

./setup.sh

This will automatically create a virtual environment, install dependencies, run the test suite, and output the correct MCP configuration JSON for your system.

2. Client Integrations

RepoLens integrates seamlessly with standard MCP clients. Ensure you point the config to the generated virtual environment's Python executable.

Claude Desktop

Add the following to your claude_desktop_config.json:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "repolens": {
      "command": "/absolute/path/to/repolens-mcp/.venv/bin/python",
      "args": [
        "-m", "repolens-mcp"
      ],
      "env": {
        "REPO_PATH": "/absolute/path/to/target/repository",
        "CHROMA_PATH": "/absolute/path/to/repolens-mcp/chroma_db"
      }
    }
  }
}

(Note: On Windows, the python path will end in .venv\\Scripts\\python.exe and args can point directly to src\\server.py)

Cursor IDE

Add the following to .cursor/mcp.json in your target project:

{
  "mcpServers": {
    "repolens": {
      "command": "/absolute/path/to/repolens-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/repolens-mcp/src/server.py"],
      "env": {
        "REPO_PATH": "."
      }
    }
  }
}

3. Local Development & Inspector

To test the server locally with an interactive UI, use the FastMCP Inspector:

# Activate the virtual environment
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# Run the dev inspector
fastmcp dev inspector src/server.py

Tool Reference

Tool Name	Description	Parameters
search_codebase	Semantic vector search over the indexed repository. Finds code chunks most relevant to a natural language query.	query (str)<br>top_k (int, default: 5)
read_file_content	Safe line-range reader for any file in the repository. Prepends line numbers and prevents path-traversal.	file_path (str)<br>start_line (int, default: 1)<br>end_line (int, default: 200)
get_file_history	Retrieves the recent Git commit history (who, when, why) for a specific file.	file_path (str)

Benchmark Results (Phase 5)

RepoLens includes an automated evaluation framework to measure RAG retrieval performance against ground-truth developer queries.

Our baseline run on the RepoLens codebase itself (22 complex architectural & lookup queries) yields:

Metric	Result	Description
File Hit Rate	81.8%	At least one correct file was retrieved in the top 5 results
Recall@5 (files)	79.5%	Fraction of expected target files present in the top 5
Recall@5 (symbols)	47.0%	Fraction of exact expected functions/classes in the top 5
Search Latency	~18ms	Average latency per query for local ChromaDB lookup
LLM Correctness	2.09 / 5.0	Scored strictly using deterministic keyword-overlap fallback

(Run python eval/run_eval.py --repo . to regenerate these metrics)

Cloud Deployment (Render)

RepoLens is pre-configured to be deployed globally as an MCP Server over Server-Sent Events (SSE) using Render's free or low-cost Docker hosting.

Step-by-Step Deployment Guide

1. Push to GitHub: Ensure your project is pushed to a public or private GitHub repository.
2. Create a Render Account: Go to Render.com and sign in with GitHub.
3. Deploy via Blueprint (Easiest):
   • Go to your Render Dashboard and click New > Blueprint.
   • Connect your GitHub repository.
   • Render will automatically read the render.yaml file in the root of the repository.
   • Click Apply to provision the Web Service. (Note: The blueprint sets MCP_TRANSPORT=sse and binds the correct ports automatically).
4. Deploy Manually (Alternative):
   • Go to your Render Dashboard and click New > Web Service.
   • Connect your GitHub repository.
   • Choose Docker as the Runtime environment.
   • Under Advanced, add a new Environment Variable:
     • Key: MCP_TRANSPORT
     • Value: sse
   • Click Create Web Service.
5. Connect your Client:
   • Once deployed, Render will provide a public URL (e.g., https://repolens-mcp-xyz.onrender.com).
   • In your MCP Client (like Claude Desktop or Cursor), configure the SSE connection:
     • Go to the MCP settings and add a new Server.
     • Set the type to SSE (Server-Sent Events).
     • Enter your Render URL with the /sse endpoint (e.g., https://repolens-mcp-xyz.onrender.com/sse).

Because the Hugging Face embedding models are pre-downloaded in our customized Dockerfile, the server will bypass the heavy "cold start" latency and boot up incredibly fast!