LeannMcp 1.0.11

LEANN .NET

A native .NET 10 MCP server for semantic code search. Chunks source repositories, computes embeddings via ONNX (GPU-accelerated), and serves results over the Model Context Protocol.

Ported from LEANN by Yichuan Wang — an innovative Python-based vector database and MCP server for personal AI. The original project pioneered graph-based selective recomputation for ultra-compact vector indexes (97% less storage than traditional solutions) and supports indexing everything from codebases to emails to browser history — all locally with zero cloud costs. This .NET port focuses on the semantic code search and MCP server pipeline, rebuilt natively for Windows/macOS with GPU acceleration via ONNX Runtime.

Why a .NET port?

The original LEANN requires Python, WSL (on Windows), PyTorch, and several other dependencies — a significant setup burden, especially on corporate machines with limited install permissions. This port is a single self-contained executable with zero external dependencies. No Python, no WSL, no pip, no virtual environments. Just download and run.

It works natively on Windows (DirectML GPU acceleration) and macOS (CoreML on Apple Silicon), with automatic CPU fallback on any platform.

How It Works

Source Code → Chunk → Embed (GPU) → Index → MCP Search

1. Chunk — splits source files into overlapping passages (code-aware: respects functions, classes, blocks)
2. Embed — computes 768-dim vectors using facebook/contriever via ONNX Runtime (DirectML on Windows, CoreML on macOS)
3. Index — stores embeddings in a flat vector index with L2-normalized cosine similarity
4. Search — any MCP client (VS Code Copilot, Claude Desktop, etc.) queries the index via semantic search

Quick Start

Prerequisites

• .NET 10 SDK
• GPU recommended but not required (falls back to CPU)
• macOS: Apple Silicon (M1/M2/M3/M4) required — Intel Macs are not supported

Option A: Install from NuGet (recommended)

dotnet tool install -g LeannMcp
leann-mcp --setup    # downloads the 418 MB ONNX model to ~/.leann/models/

Option B: Build from source

# Git LFS required — the repo includes the 418 MB ONNX model
git lfs install
git clone https://github.com/d-german/leann-dotnet.git
cd leann-dotnet
dotnet publish src/LeannMcp -r win-x64 --self-contained -c Release -o publish/win-x64

Forgot git lfs install? Run git lfs pull to download model.onnx.

Note: When built from source the executable is named leann-dotnet (the AssemblyName). All command examples in this README use leann-mcp, which is the command installed by dotnet tool install -g LeannMcp. Substitute leann-dotnet (or the full path to your published binary) if you are running a source build.

Index Your Code

cd <data-root>

# Step 1: Chunk source code into passages
leann-mcp --build-passages --docs /path/to/my-repo --index-name my-repo

# Step 2: Compute embeddings (GPU-accelerated)
leann-mcp --build-indexes --index my-repo

# Or do both in one command:
leann-mcp --rebuild --docs /path/to/my-repo --index-name my-repo

This creates <data-root>/.leann/indexes/my-repo/ with passages + embeddings.

4. Connect an MCP Client

Add to your MCP client config (e.g., .vscode/mcp.json):

{
  "servers": {
    "leann": {
      "type": "stdio",
      "command": "leann-mcp",
      "args": ["--mcp"],
      "env": {
        "LEANN_DATA_ROOT": "/path/to/your/data"
      }
    }
  }
}

LEANN_DATA_ROOT points to the directory containing .leann/indexes/. The model is loaded from ~/.leann/models/ by default (override with LEANN_MODEL_DIR).

5. Search

From your MCP client, use these tools:

• leann_search — semantic search across all indexed repos
• leann_list — list available indexes
• leann_warmup — pre-load embedding model (faster first search)

Data Layout

<data-root>/
└── .leann/
    ├── models/
    │   └── contriever-onnx/       # ONNX model + tokenizer
    │       ├── model.onnx
    │       └── vocab.txt
    └── indexes/
        ├── my-repo/
        │   ├── documents.leann.meta.json
        │   ├── documents.leann.passages.jsonl
        │   ├── documents.ids.txt
        │   ├── documents.embeddings.bin
        │   └── documents.embeddings.meta.json
        └── another-repo/
            └── ...

CLI Reference

Modes

Passage Builder Flags

Index Builder Flags

Watch Mode Flags

Environment Variables

GPU Acceleration

GPU is used for both indexing and search query embedding. For MCP server use (search only), you can set LEANN_FORCE_CPU=1 to free your GPU — single query embedding is fast on CPU.

Examples

# Index a single repo
leann-mcp --rebuild --docs ~/projects/my-app --index-name my-app

# Index multiple directories into one index
leann-mcp --build-passages --docs ~/proj/frontend ~/proj/backend --index-name my-app

# Rebuild all embeddings with smaller batches (low VRAM GPU)
leann-mcp --build-indexes --force --batch-size 8

# Rebuild everything except one large index
leann-mcp --build-indexes --exclude large-mono-repo

# Use shorter token sequences for faster indexing (slight quality trade-off)
leann-mcp --build-indexes --force --max-tokens 256

# Auto-watch repos for changes
leann-mcp --watch --interval 120

Tuning Guide

Chunk Size vs. Batch Size vs. Max Tokens

These three settings control different parts of the pipeline:

Chunk Size (search quality)

Chunk size controls how much context each passage contains. This is independent of GPU power.

• Smaller chunks (128-256 chars) → more precise search hits, less context per result
• Larger chunks (512-1024 chars) → more context per result, but may dilute relevance
• Code chunks default larger (512) because functions/methods need more context than prose

Note: Passages longer than --max-tokens (default 512 tokens ≈ ~2000 chars) are truncated during embedding. Making chunks larger than ~2000 chars wastes disk without improving search.

Batch Size (GPU utilization)

Batch size determines how many passages are embedded simultaneously. This is where GPU VRAM matters.

# RTX 3500 Ada (12 GB) — crank up the batch size
leann-mcp --rebuild --docs ./my-repo --index-name my-repo --batch-size 128

# Low-VRAM GPU or integrated graphics
leann-mcp --rebuild --docs ./my-repo --index-name my-repo --batch-size 8

Max Tokens (speed vs. context)

The contriever model processes up to 512 tokens per passage. Lowering this speeds up embedding (attention is O(n²)) at the cost of truncating longer passages.

# Faster indexing, slight quality trade-off on long passages
leann-mcp --build-indexes --max-tokens 256

# Full context (default)
leann-mcp --build-indexes --max-tokens 512

Performance

Embedding throughput on NVIDIA RTX A1000 (4GB VRAM):

Optimizations included:

• Length-sorted batching (groups similar-length passages to minimize padding waste)
• Bulk file writes (single I/O call for embedding output, critical for network drives)
• Configurable --max-tokens to reduce O(n²) attention cost on long passages

Platform Support

GPU support is automatic with graceful fallback — if the GPU provider isn't available, it logs a warning and uses CPU.

Building & Publishing

# Build
dotnet build

# Test
dotnet test

# Publish self-contained binary
dotnet publish src/LeannMcp -r win-x64 --self-contained -c Release -o publish/win-x64

# macOS
dotnet publish src/LeannMcp -r osx-arm64 --self-contained -c Release -o publish/osx-arm64

# Install as dotnet tool (framework-dependent)
dotnet pack src/LeannMcp -c Release
dotnet tool install --global --add-source src/LeannMcp/bin/Release LeannMcp

Troubleshooting

License

MIT — see LICENSE