MCP Local RAG

🍴 Forked from shinpr/mcp-local-rag — original work by Shinsuke Kagawa

Local code intelligence engine for AI coding assistants. AST-level semantic chunking + keyword boost for pinpointing functions, classes, and APIs — fully private, zero setup.

📖 中文文档

Table of Contents

1. Features
2. Quick Start
   • 2.1 Configure Your AI Coding Tool
   • 2.2 CLI Quick Start
   • 2.3 First-Time Project Indexing
3. Core Concepts
   • 3.1 Dual-Strategy Chunking
   • 3.2 Hybrid Search
   • 3.3 Security Boundary
4. MCP Tool Reference
   • 4.1 Ingest Tools
   • 4.2 Search Tools
   • 4.3 Management Tools
   • 4.4 Code Intelligence
   • 4.5 System Tools
5. CLI
   • 5.1 Basic Commands
   • 5.2 CLI Configuration
6. Network & Models
   • 6.1 Mirror Auto-Detection
   • 6.2 Model Selection
   • 6.3 File Watching
7. Search Tuning
8. Performance Tuning
   • 8.1 Quantization Precision
   • 8.2 Execution Device
   • 8.3 Minimum Chunk Length
   • 8.4 Recommended Configurations
9. Configuration Reference
10. Troubleshooting
11. Development

1. Features

• Smart dual-strategy chunking — AST-level code chunking via tree-sitter (splits at function/class/method boundaries, injects scope chain + imports). Semantic chunking for documents (splits by meaning, not character count).
• Semantic search + keyword boost — Vector search first, then keyword matching boosts exact terms. useEffect, error codes, class names rank higher — not just semantically guessed.
• 15 MCP tools — Ingest, search, manage, code intelligence, and system ops in one server.
• AST code intelligence — find_definition and find_references for IDE-level code navigation, powered by tree-sitter metadata captured at ingest time.
• Three-tier mirror auto-fallback — huggingface.co → hf-mirror.com → modelscope.cn, zero config for users in mainland China.
• Runs entirely locally — No API keys, no cloud, no data leaving your machine. Works offline after the first model download.
• Zero-friction setup — One npx command. No Docker, Python, or servers to manage.

2. Quick Start

Set BASE_DIR to the folder you want to search (BASE_DIRS for multiple roots — see Configuration).

2.1 Configure Your AI Coding Tool

Cursor — ~/.cursor/mcp.json:

{
  "mcpServers": {
    "local-rag": {
      "command": "npx",
      "args": ["-y", "@damoqiongqiu/mcp-local-rag"],
      "env": { "BASE_DIR": "/path/to/your/project" }
    }
  }
}

Claude Code:

claude mcp add local-rag --scope user --env BASE_DIR=/path/to/your/project -- npx -y @damoqiongqiu/mcp-local-rag

Codex — ~/.codex/config.toml:

[mcp_servers.local-rag]
command = "npx"
args = ["-y", "@damoqiongqiu/mcp-local-rag"]

[mcp_servers.local-rag.env]
BASE_DIR = "/path/to/your/project"

WorkBuddy — Settings → Custom Connectors → Add:

{
  "mcpServers": {
    "local-rag": {
      "command": "npx",
      "args": ["-y", "@damoqiongqiu/mcp-local-rag"],
      "env": { "BASE_DIR": "/path/to/your/project" }
    }
  }
}

⚠️ WorkBuddy: you MUST click "Trust" in the Custom Connectors list after adding, otherwise the server is silently blocked.

2.2 CLI Quick Start

No MCP needed — run directly from the terminal:

npx @damoqiongqiu/mcp-local-rag ingest ./src/
npx @damoqiongqiu/mcp-local-rag query "auth middleware"
npx @damoqiongqiu/mcp-local-rag status

That's it. No Docker, Python, or server setup.

2.3 First-Time Project Indexing

You: "Index the src directory of this project"
Assistant: Successfully ingested 156 files (2,847 chunks created)

You: "Where's the middleware that handles API rate limiting?"
Assistant: src/middleware/rateLimiter.ts — useRateLimiter(), lines 42–89

You: "How is the database connection pool configured?"
Assistant: src/config/database.ts — createPool() default max: 20, idle: 5

3. Core Concepts

3.1 Dual-Strategy Chunking

Chunking strategy is chosen per file type:

• Code files (50+ languages) — CodeChunker parses source via tree-sitter AST, splits at structural boundaries (functions, classes, methods). Each chunk's contextualizedText includes its scope chain and import context for precise semantic search.
• Documents (PDF/DOCX/TXT/MD/HTML) — SemanticChunker splits into sentences, groups by embedding similarity to find natural topic boundaries. Markdown code blocks remain intact — never split mid-block.

3.2 Hybrid Search

Search = semantic similarity + keyword boost (RAG_HYBRID_WEIGHT, default 0.6):

1. Query vectorization → semantic search finds most relevant chunks
2. Quality filters apply (distance threshold, grouping)
3. Keyword matching boosts exact-term rankings

Exact identifiers like useEffect are never buried by semantic approximations.

3.3 Security Boundary

Only files under BASE_DIR / BASE_DIRS are accessible for ingest, list, delete, or read-neighbor operations. Symlinks resolved outside roots are rejected. Sibling-prefix paths (e.g., /foo/barista when root is /foo/bar) are also blocked — prevents path traversal attacks.

4. MCP Tool Reference

15 tools organized into 5 categories.

4.1 Ingest Tools

ingest_file supports 50+ code languages. PDFs support an optional visual mode — a local VLM generates captions for figure pages, making visual content searchable. Two profiles available:

# CLI
npx @damoqiongqiu/mcp-local-rag ingest ./spec.pdf --visual --visual-quality quality
# MCP
"Ingest ./spec.pdf with visual: true, visualQuality: 'quality'"

ingest_data runs Readability → Markdown → index. Perfect for web content fetched by your AI assistant. Re-ingesting replaces old versions automatically.

ingest_directory scans recursively, respects .gitignore, shows real-time progress via MCP notifications.

4.2 Search Tools

query_documents — scope accepts a single path prefix or list, restricting results to that subtree. highlightContext returns snippets around matched terms. fromTimestamp / untilTimestamp enable time-range filtering.

read_chunk_neighbors — defaults to 2 chunks before and after (like grep -C 2), max 50 each. Response includes the target chunk marked isTarget: true.

4.3 Management Tools

list_files supports scope filtering with the same prefix-match semantics as search. In large directories, scope accelerates the scan by skipping out-of-scope subtrees.

4.4 Code Intelligence

Both tools depend on AST metadata (imports, entities, scope chains) extracted by tree-sitter at ingest time. Only works for code files ingested with CodeChunker — files ingested before v0.18.7 lack this metadata and require reindex_all to rebuild.