Local Code Index

A high-performance, fully local, open-source Model Context Protocol (MCP) server built to index massive codebases into an easily searchable format for AI models.

This tool is explicitly optimized for TypeScript, JavaScript, and Java, utilizing official Tree-sitter AST parsing to capture complete code structures (classes, methods, decorators, annotations, and Javadoc comments) instead of blind text fragments. It runs entirely on your machine via Ollama and LanceDB, requiring zero API keys and protecting your intellectual property.

---

🛠️ Features

• AST-Aware Structural Chunking: Groups methods, classes, and relevant context (like @Get() decorators in NestJS or Javadoc strings in Spring Boot) into unified semantic records.
• Scalable Multi-Repo Architecture: Automatically provisions isolated database tables per repository. Scale up to 100+ codebases incrementally without performance or query degradation.
• Cross-Repository Search: Allows AI models to scan one repository or run a global matrix query across all indexed projects simultaneously.
• Production-Grade File Filtering: Automatically skips node_modules, build outputs, binaries, lockfiles, and environment secrets (.env).
• Sub-Second Latency: Automatically compiles localized IVF-PQ vector indexes on larger repositories to keep query speeds under a second.

---

🏗️ Architecture Design

┌────────────────────────────────────────────────────────┐
│             Your Massive Codebase (TS, JS, Java)       │
└───────────────────────────┬────────────────────────────┘
                            │ (Tree-sitter AST Parsing)
                            ▼
┌────────────────────────────────────────────────────────┐
│     Semantic Chunks (Functions, Classes, Decorators)   │
└───────────────────────────┬────────────────────────────┘
                            │ (Local Ollama nomic-embed-text)
                            ▼
┌────────────────────────────────────────────────────────┐
│    Isolated LanceDB Tables (repo_A, repo_B, etc.)     │
└───────────────────────────┬────────────────────────────┘
                            │
                  ┌─────────┴─────────┐
                  ▼                   ▼
      [ search_codebase ]       [ search_all_codebases ]
                  ▲                   ▲
                  └─────────┬─────────┘
                            │ (Model Context Protocol)
                            ▼
┌────────────────────────────────────────────────────────┐
│     Your AI Workspace Environment (Cursor / Cline)     │
└────────────────────────────────────────────────────────┘

---

📦 Project Structure

Ensure your local project directory matches this setup:

local-code-index/
├── pyproject.toml             # Pin-point environment and tool configurations
├── src/
│   └── local_code_index/
│       ├── __init__.py
│       ├── cli.py             # Cross-platform CLI (uv run local-code-index ...)
│       ├── parser_utils.py    # Official Tree-sitter AST parsing layer
│       └── server.py          # FastMCP server tool and LanceDB engine
└── README.md                  # Project documentation

---

🚀 Quick Start & Installation

1. Start Your Local Embedding Model

Make sure Ollama is installed and active on your machine, then download the code-optimized embedding vector weights:

ollama pull nomic-embed-text

2. Install the Project Package

Navigate to your project directory and run the compilation step using uv (or standard pip):

cd local-code-index
uv pip install -e .

3. Register the VS Code / Editor Extension

To connect this local tool to your AI chat interface, register it inside your favorite editor extension configurations. The MCP server advertises itself as Multi-Repo Indexer (set via FastMCP("Multi-Repo Indexer") in server.py); we recommend using the same name for the config key so the display is consistent across panels.

For Cursor (Cursor Settings -> Features -> MCP)

• Name: Multi-Repo Indexer
• Type: command
• Command: uv --directory "/absolute/path/to/local-code-index" run python -m local_code_index.server

For Cline (cline_mcp_settings.json)

Add this configuration snippet inside your mcpServers settings payload:

{
  "mcpServers": {
    "Multi-Repo Indexer": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/local-code-index",
        "run",
        "python",
        "-m",
        "local_code_index.server"
      ],
      "disabled": false
    }
  }
}

---

💻 Managing the Index from the Integrated Terminal

Indexing and maintenance are driven by a single built-in CLI command (local-code-index) that ships with the package — no ~/.bashrc or ~/.zshrc editing required, and it works the same on Windows PowerShell, macOS and Linux.

A shorter alias lci is also installed and points at the exact same CLI, so the two invocations below are interchangeable:

uv run local-code-index idx .   # full name
uv run lci idx .                # short alias

The CLI entry point is registered automatically via [project.scripts] in pyproject.toml during the uv pip install -e . step from the Quick Start. Run it through uv so the project's virtualenv is used:

uv run lci --help

Available Commands

Command	Description	Example
idx [path]	Index a repository folder (defaults to current directory)	uv run local-code-index idx .
rm [path]	Remove a repository from the index	uv run local-code-index rm ~/dev/my-api
list	List all currently indexed repositories	uv run local-code-index list
find <query>	Semantic search across all indexed codebases	uv run local-code-index find "JwtAuthGuard validation logic"
search [path] <query>	Semantic search within one indexed repository	uv run local-code-index search . "webhook signature"

Each command accepts --help for full flag details (token budgets, limit-per-repo, file filters, etc.), for example:

uv run local-code-index find --help
# Usage: local-code-index find [-h] [--limit-per-repo N] [--token-budget N] [-v] query ...

Concise vs. Verbose Output (-v / --verbose)

By default, find and search print a concise response — one line per hit showing [repo] file (line) type distance | Preview: <first 80 chars> — so you can quickly locate where something lives without scrolling through full source blocks.

Pass -v (or --verbose) to switch to the verbose response, which prints the complete source block for each hit (the original behavior):

# concise (default): one scannable line per match
uv run local-code-index find "JwtAuthGuard validation logic"

# verbose: include the full code block for every match
uv run local-code-index find -v "JwtAuthGuard validation logic"
uv run local-code-index search . "webhook signature" --verbose

Tip: If you prefer even shorter invocations, you can either (a) use the built-in lci alias (uv run lci idx .), (b) drop uv run entirely and call lci ... directly after activating the project virtualenv, or (c) create an alias of your own (alias idx="uv --directory /path/to/local-code-index run lci"). The CLI itself needs no special shell setup.

---

🔥 Practical Examples & Usage

Workflow 1: From the Integrated Terminal

Simply step into any repository folder on your system and index it with a single command — no shell profile edits needed:

cd ~/dev/projects/my-nest-api
uv run local-code-index idx .
# Output: Success: Codebase 'my-nest-api' indexed completely (420 nodes with basic vector direct lookup).

If you want to run a quick query across everything you've saved:

uv run local-code-index find "JwtAuthGuard validation logic"

---

Workflow 2: Conversational Prompts via AI Agents (Cursor / Cline)

Once the server status bar is green inside your editor panel, the underlying LLM gains access to your protocol tools natively. You can now use fluid language to ask complex architectural questions.

💡 Example 1: Isolating Features in a Specific Repo

User: "Check my payment-service repo. Do we have a specific method handling webhook signatures?"

AI Interaction: The model implicitly runs search_codebase against your project, targeting keyword vectors. It receives the whole relevant function block and returns a complete synthesis of your webhook logic.

💡 Example 2: Cross-Repository Code Archeology

User: "I need to implement a data-stream handler in this repo. Scan all our indexed codebases to see if we've written a reuseable utility class for this elsewhere so I can copy its pattern."

AI Interaction: The model triggers search_all_codebases to search across your microservices. It highlights a match found under a shared-java-utils directory, complete with its accompanying Javadocs.

💡 Example 3: Auditing Active Deployments

User: "List our indexed repositories and tell me which ones are running on our old database schema patterns."

AI Interaction: The model runs list_indexed_repositories to find all your project paths and walks through them to identify outdated code conventions.

---

🔒 Security & Performance Exclusions

To safeguard memory, protect confidential keys, and maximize performance, files that match the following attributes are omitted from processing:

1. Directories Skipped: .git, .github, node_modules, dist, build, .vscode, target, bin, vendor, __pycache__, virtualenvs (venv/.venv/env), cache dirs (.mypy_cache, .ruff_cache, .pytest_cache, .tox, .eggs, .cache), site-packages, and any *.egg-info directory.
2. Extensions Tracked: .js, .jsx, .ts, .tsx, .java.
3. Blacklisted Configuration Profiles: package-lock.json, .env, .env.local, tsconfig.json.
4. Size Caps: Any source code file larger than 2MB is automatically skipped to prevent execution bottlenecks.

---

💡 How the Safeguard Works

1. Context Window Safety: The default token budget for single-repo searches is set to 4000 tokens, and global cross-repo searches are capped at 6000 tokens.
2. Dynamic Truncation: When the model requests information, the server maps out the top search matches. If a large block threatens to exceed the remaining budget, the engine stops adding data and appends a clean warning flag (⚠️ WARNING: Global cross-repo results truncated...).
3. Model Autonomy: Because these limits are exposed as parameterized inputs (token_budget: int = 6000), sophisticated AI agents like Cursor or Cline can choose to scale the budget up or down depending on their specific model limits.

---