{
  "markdown": "<p align=\"center\">\n  <img src=\"assets/banner.jpg\" alt=\"MCP Local RAG — Search below the surface.\" width=\"600\" />\n</p>\n\n# MCP Local RAG\n\n[![GitHub stars](https://img.shields.io/github/stars/damoqiongqiu/mcp-local-rag?style=social)](https://github.com/damoqiongqiu/mcp-local-rag)\n[![npm version](https://img.shields.io/npm/v/@damoqiongqiu/mcp-local-rag.svg)](https://www.npmjs.com/package/@damoqiongqiu/mcp-local-rag)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-6.0-blue.svg?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)\n[![MCP Registry](https://img.shields.io/badge/MCP-Registry-green.svg)](https://registry.modelcontextprotocol.io/)\n\n> 🍴 Forked from [shinpr/mcp-local-rag](https://github.com/shinpr/mcp-local-rag) — original work by [Shinsuke Kagawa](https://github.com/shinpr)\n>\n> Local code intelligence engine for AI coding assistants. AST-level semantic chunking + keyword boost for pinpointing functions, classes, and APIs — fully private, zero setup.\n\n📖 [中文文档](README_CN.md)\n\n---\n\n## Table of Contents\n\n1. [Features](#1-features)\n2. [Quick Start](#2-quick-start)\n   - 2.1 [Configure Your AI Coding Tool](#21-configure-your-ai-coding-tool)\n   - 2.2 [CLI Quick Start](#22-cli-quick-start)\n   - 2.3 [First-Time Project Indexing](#23-first-time-project-indexing)\n3. [Core Concepts](#3-core-concepts)\n   - 3.1 [Dual-Strategy Chunking](#31-dual-strategy-chunking)\n   - 3.2 [Hybrid Search](#32-hybrid-search)\n   - 3.3 [Security Boundary](#33-security-boundary)\n4. [MCP Tool Reference](#4-mcp-tool-reference)\n   - 4.1 [Ingest Tools](#41-ingest-tools)\n   - 4.2 [Search Tools](#42-search-tools)\n   - 4.3 [Management Tools](#43-management-tools)\n   - 4.4 [Code Intelligence](#44-code-intelligence)\n   - 4.5 [System Tools](#45-system-tools)\n5. [CLI](#5-cli)\n   - 5.1 [Basic Commands](#51-basic-commands)\n   - 5.2 [CLI Configuration](#52-cli-configuration)\n6. [Network & Models](#6-network--models)\n   - 6.1 [Mirror Auto-Detection](#61-mirror-auto-detection)\n   - 6.2 [Model Selection](#62-model-selection)\n   - 6.3 [File Watching](#63-file-watching)\n7. [Search Tuning](#7-search-tuning)\n8. [Performance Tuning](#8-performance-tuning)\n   - 8.1 [Quantization Precision](#81-quantization-precision-rag_dtype)\n   - 8.2 [Execution Device](#82-execution-device-rag_device)\n   - 8.3 [Minimum Chunk Length](#83-minimum-chunk-length-chunk_min_length)\n   - 8.4 [Recommended Configurations](#84-recommended-configurations)\n9. [Configuration Reference](#9-configuration-reference)\n10. [Troubleshooting](#10-troubleshooting)\n11. [Development](#11-development)\n\n---\n\n## 1. Features\n\n- **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).\n- **Semantic search + keyword boost** — Vector search first, then keyword matching boosts exact terms. `useEffect`, error codes, class names rank higher — not just semantically guessed.\n- **15 MCP tools** — Ingest, search, manage, code intelligence, and system ops in one server.\n- **AST code intelligence** — `find_definition` and `find_references` for IDE-level code navigation, powered by tree-sitter metadata captured at ingest time.\n- **Three-tier mirror auto-fallback** — `huggingface.co → hf-mirror.com → modelscope.cn`, zero config for users in mainland China.\n- **Runs entirely locally** — No API keys, no cloud, no data leaving your machine. Works offline after the first model download.\n- **Zero-friction setup** — One `npx` command. No Docker, Python, or servers to manage.\n\n---\n\n## 2. Quick Start\n\nSet `BASE_DIR` to the folder you want to search (`BASE_DIRS` for multiple roots — see [Configuration](#8-configuration-reference)).\n\n### 2.1 Configure Your AI Coding Tool\n\n**Cursor** — `~/.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"local-rag\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@damoqiongqiu/mcp-local-rag\"],\n      \"env\": { \"BASE_DIR\": \"/path/to/your/project\" }\n    }\n  }\n}\n```\n\n**Claude Code**:\n\n```bash\nclaude mcp add local-rag --scope user --env BASE_DIR=/path/to/your/project -- npx -y @damoqiongqiu/mcp-local-rag\n```\n\n**Codex** — `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.local-rag]\ncommand = \"npx\"\nargs = [\"-y\", \"@damoqiongqiu/mcp-local-rag\"]\n\n[mcp_servers.local-rag.env]\nBASE_DIR = \"/path/to/your/project\"\n```\n\n**WorkBuddy** — Settings → Custom Connectors → Add:\n\n```json\n{\n  \"mcpServers\": {\n    \"local-rag\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@damoqiongqiu/mcp-local-rag\"],\n      \"env\": { \"BASE_DIR\": \"/path/to/your/project\" }\n    }\n  }\n}\n```\n\n> ⚠️ WorkBuddy: you MUST click \"Trust\" in the Custom Connectors list after adding, otherwise the server is silently blocked.\n\n### 2.2 CLI Quick Start\n\nNo MCP needed — run directly from the terminal:\n\n```bash\nnpx @damoqiongqiu/mcp-local-rag ingest ./src/\nnpx @damoqiongqiu/mcp-local-rag query \"auth middleware\"\nnpx @damoqiongqiu/mcp-local-rag status\n```\n\nThat's it. No Docker, Python, or server setup.\n\n### 2.3 First-Time Project Indexing\n\n```\nYou: \"Index the src directory of this project\"\nAssistant: Successfully ingested 156 files (2,847 chunks created)\n\nYou: \"Where's the middleware that handles API rate limiting?\"\nAssistant: src/middleware/rateLimiter.ts — useRateLimiter(), lines 42–89\n\nYou: \"How is the database connection pool configured?\"\nAssistant: src/config/database.ts — createPool() default max: 20, idle: 5\n```\n\n---\n\n## 3. Core Concepts\n\n### 3.1 Dual-Strategy Chunking\n\nChunking strategy is chosen per file type:\n\n- **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.\n- **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.\n\n### 3.2 Hybrid Search\n\nSearch = semantic similarity + keyword boost (`RAG_HYBRID_WEIGHT`, default 0.6):\n\n1. Query vectorization → semantic search finds most relevant chunks\n2. Quality filters apply (distance threshold, grouping)\n3. Keyword matching boosts exact-term rankings\n\nExact identifiers like `useEffect` are never buried by semantic approximations.\n\n### 3.3 Security Boundary\n\nOnly 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.\n\n---\n\n## 4. MCP Tool Reference\n\n15 tools organized into 5 categories.\n\n### 4.1 Ingest Tools\n\n| # | Tool | Purpose | Example |\n|---|------|---------|---------|\n| 1 | `ingest_file` | Single file (PDF/DOCX/TXT/MD/code) | `\"Ingest ./docs/api-spec.pdf\"` |\n| 2 | `ingest_data` | In-memory text/HTML | `\"Fetch this page and ingest the HTML\"` |\n| 3 | `ingest_directory` | Bulk directory ingest | `\"Ingest everything under ./src\"` |\n\n**`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:\n\n| Profile | Model | Cache | Suited for |\n|---------|------|------|------------|\n| `fast` (default) | SmolVLM-256M | ~250 MB | Light visual indexing |\n| `quality` | Qwen2.5-VL-3B-ONNX | ~2.9 GB | Figures with in-image text |\n\n```bash\n# CLI\nnpx @damoqiongqiu/mcp-local-rag ingest ./spec.pdf --visual --visual-quality quality\n# MCP\n\"Ingest ./spec.pdf with visual: true, visualQuality: 'quality'\"\n```\n\n**`ingest_data`** runs Readability → Markdown → index. Perfect for web content fetched by your AI assistant. Re-ingesting replaces old versions automatically.\n\n**`ingest_directory`** scans recursively, respects `.gitignore`, shows real-time progress via MCP notifications.\n\n### 4.2 Search Tools\n\n| # | Tool | Purpose | Key Parameters |\n|---|------|---------|----------------|\n| 4 | `query_documents` | Hybrid search (semantic + keyword) | `query`, `limit`, `scope`, `highlightContext`, `fromTimestamp` |\n| 5 | `read_chunk_neighbors` | Expand context around results | `filePath`, `chunkIndex`, `before`, `after` |\n\n**`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.\n\n**`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`.\n\n### 4.3 Management Tools\n\n| # | Tool | Purpose |\n|---|------|---------|\n| 6 | `list_files` | List files with ingestion status (`ingested: true/false`) |\n| 7 | `delete_file` | Delete by file path or source URL |\n| 8 | `status` | Index stats: docs, chunks, memory, search mode |\n\n`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.\n\n### 4.4 Code Intelligence\n\n| # | Tool | Purpose | Input |\n|---|------|---------|-------|\n| 9 | `find_definition` | Locate symbol definition (file, line range, scope) | Exact symbol name |\n| 10 | `find_references` | Find all references (import + text mention) | Symbol name |\n\nBoth 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.\n\n**`find_references`** uses a two-phase strategy: (1) exact match in `codeMeta.imports` → (2) FTS full-text search for the symbol name. Results are deduplicated by (filePath, chunkIndex), with import references listed first.\n\n### 4.5 System Tools\n\n| # | Tool | Purpose |\n|---|------|---------|\n| 11 | `config` | Runtime hot read/write config — no restart needed |\n| 12 | `dedup_check` | SHA256 + Jaccard similarity to detect duplicate files |\n| 13 | `export_index` | Export entire index as JSON (backup or migration) |\n| 14 | `reindex_all` | Full re-chunk + re-embed (after model change) |\n| 15 | `reindex_stale` | Re-ingest only files modified on disk (incremental sync) |\n\n**`config`** hot-swaps `hybridWeight`, `modelName`, `cacheDir`, `baseDir`/`baseDirs`, etc. Switching models auto-disposes the old Embedder and initializes the new one — note: changing models alters the embedding space and requires `reindex_all`.\n\n**`dedup_check`** is especially useful in monorepos — `spot` ↔ `futures` mirror code is typically flagged with similarity 1.0.\n\n---\n\n## 5. CLI\n\n### 5.1 Basic Commands\n\n```bash\n# Ingest\nnpx @damoqiongqiu/mcp-local-rag ingest ./src/\n\n# Search (with scope)\nnpx @damoqiongqiu/mcp-local-rag query \"auth middleware\"\nnpx @damoqiongqiu/mcp-local-rag query \"auth\" --scope /docs/api\n\n# Context expansion\nnpx @damoqiongqiu/mcp-local-rag read-neighbors --file-path /abs/path.md --chunk-index 5\n\n# Management\nnpx @damoqiongqiu/mcp-local-rag list --scope /docs/api\nnpx @damoqiongqiu/mcp-local-rag status\nnpx @damoqiongqiu/mcp-local-rag delete ./docs/old.pdf\nnpx @damoqiongqiu/mcp-local-rag delete --source \"https://...\"\n```\n\n`query`, `read-neighbors`, `list`, `status`, `delete` emit JSON to stdout (pipe to `jq`). `ingest` emits progress to stderr.\n\nGlobal options (`--db-path`, `--cache-dir`, `--model-name`) go before the subcommand:\n\n```bash\nnpx @damoqiongqiu/mcp-local-rag --help\n```\n\n> ⚠️ The CLI does NOT read your MCP client config (`mcp.json`, etc.). Configure via flags or environment variables.\n\n### 5.2 CLI Configuration\n\n**Flags** — global options before, subcommand options after:\n\n```bash\nnpx @damoqiongqiu/mcp-local-rag --db-path ./my-db query \"auth\" --base-dir ./docs\n```\n\n`--base-dir` is repeatable on `ingest` and `list`:\n\n```bash\nnpx @damoqiongqiu/mcp-local-rag ingest --base-dir ./docs --base-dir ./specs ./docs/readme.md\n```\n\n**Environment variables**:\n\n```bash\nexport DB_PATH=./my-db\nexport BASE_DIR=./docs\nnpx @damoqiongqiu/mcp-local-rag query \"auth\"\n```\n\nFor multiple roots, use `BASE_DIRS` (JSON array):\n\n```bash\nexport BASE_DIRS='[\"/Users/me/work\",\"/Users/me/specs\"]'\n```\n\nPrecedence: CLI flags > environment variables > defaults.\n\n---\n\n## 6. Network & Models\n\n### 6.1 Mirror Auto-Detection\n\nhuggingface.co is inaccessible from mainland China. Built-in three-tier mirror chain with automatic fallback:\n\n```\nhuggingface.co → hf-mirror.com → modelscope.cn\n```\n\nAt startup, each mirror is HEAD-probed (3s timeout). The first reachable mirror with a complete API is selected:\n\n- **With proxy** (`HTTPS_PROXY`) → direct to huggingface.co\n- **No proxy** → auto-switch to hf-mirror.com\n- **hf-mirror API unavailable** → fallback to modelscope.cn\n\n**No manual `HF_ENDPOINT` required.** For manual control:\n\n| Env Var | Effect |\n|---------|--------|\n| `HF_AUTO_MIRROR=false` | Disable auto-detection, use huggingface.co only |\n| `HF_ENDPOINT=<url>` | Force a specific mirror, skip auto-detection |\n\n> v0.18.5+ uses `setGlobalDispatcher(ProxyAgent)` — all Node.js 22 network requests go through the proxy.\n\n### 6.2 Model Selection\n\n6 embedding models with alias resolution via model-registry:\n\n| Model | Alias | Size | Dims |\n|-------|-------|------|------|\n| `Xenova/all-MiniLM-L6-v2` (default) | `mini` | ~90 MB | 384 |\n| `Xenova/all-MiniLM-L12-v2` | — | ~120 MB | 384 |\n| `Xenova/bge-small-en-v1.5` | `bge-small` | ~130 MB | 384 |\n| `Xenova/all-mpnet-base-v2` | `mpnet` | ~420 MB | 768 |\n| `Xenova/bge-base-en-v1.5` | — | ~420 MB | 768 |\n| `Xenova/multi-qa-mpnet-base-dot-v1` | `multi-qa` | ~420 MB | 768 |\n\n**Guidance**: code repos → default model + high keyword boost; multilingual → consider `embeddinggemma-300m`; scientific papers → consider `allenai-specter`.\n\n**RAG_DTYPE** controls ONNX precision (`fp32` / `fp16` / `q8`). Default `fp32`; use `q8` when memory-constrained. ⚠️ Changing models or dtype requires deleting `DB_PATH` and re-indexing.\n\n### 6.3 File Watching\n\nSet `RAG_WATCH=true` — the server starts recursive `fs.watch` on baseDirs (500ms debounce):\n\n- File creation/modification → auto `ingest_file`\n- File deletion → auto `delete_file`\n\nIdeal for actively changing projects.\n\n---\n\n## 7. Search Tuning\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `RAG_HYBRID_WEIGHT` | `0.6` | Keyword boost: 0 = semantic only, 1 = keyword only |\n| `RAG_GROUPING` | unset | `similar` = top group only, `related` = top 2 groups |\n| `RAG_MAX_DISTANCE` | unset | Filter low-relevance results (e.g., `0.5`) |\n| `RAG_MAX_FILES` | unset | Limit results to top N files |\n\n**Code-focused tuning (recommended default):**\n\n```json\n{ \"RAG_HYBRID_WEIGHT\": \"0.7\", \"RAG_GROUPING\": \"similar\" }\n```\n\n**Document-focused tuning:**\n\n```json\n{ \"RAG_HYBRID_WEIGHT\": \"0.4\", \"RAG_GROUPING\": \"related\" }\n```\n\nKeyword boost is applied *after* semantic filtering — improves precision without introducing noise.\n\n---\n\n## 8. Performance Tuning\n\nBeyond search accuracy, inference performance is also configurable. All optimizations are environment variables — no code changes required.\n\n### 8.1 Quantization Precision (`RAG_DTYPE`)\n\nControls ONNX model inference precision. For `all-MiniLM-L6-v2`, three levels are available:\n\n| Value | Model Size | Speed | Memory | Precision Loss | Best For |\n|-------|-----------|-------|--------|---------------|----------|\n| `fp32` (default) | ~90 MB | baseline | ~80 MB | none | First use, maximum accuracy |\n| `fp16` | ~45 MB | 20-30% faster | ~45 MB | negligible | **Recommended** for daily use |\n| `q8` | ~45 MB | 30-50% faster | ~45 MB | minor | Low memory, large projects |\n\n```json\n\"env\": { \"RAG_DTYPE\": \"fp16\", \"BASE_DIR\": \"...\" }\n```\n\n⚠️ Changing dtype **requires index rebuild** — embedding spaces are incompatible.\n\n**Verify it works:** After restart, call `status` via MCP and check the `dtype` field. Should match your setting (e.g., `\"fp16\"`).\n\n**If it fails:** Startup throws `EmbeddingError` with a list of supported dtypes. Common cause: the model doesn't provide the `q8` variant — switch to `fp16`.\n\n### 8.2 Execution Device (`RAG_DEVICE`)\n\nControls which ONNX Runtime backend to use:\n\n| Value | Backend | Notes |\n|-------|---------|-------|\n| `cpu` (default) | CPU | Most stable, no extra dependencies |\n| `webgpu` | GPU (WebGPU) | ⚠️ Experimental: M1/M2 Mac uses Metal, NVIDIA uses Vulkan |\n\n```json\n\"env\": { \"RAG_DEVICE\": \"webgpu\", \"RAG_DTYPE\": \"fp16\", \"BASE_DIR\": \"...\" }\n```\n\n⚠️ Changing device changes the embedding space — requires index rebuild. **Stacks with `RAG_DTYPE`** — `fp16 + webgpu` gives both model-size reduction and GPU speedup.\n\n**Verify it works:** MCP startup log should show `Loading model on device \"webgpu\"`. `status` should show `device: \"webgpu\"`.\n\n**If it fails:**\n- `Unsupported device` at startup → WebGPU unavailable in your environment, revert to `\"cpu\"`\n- Starts successfully but inference crashes → likely an ONNX WebGPU backend bug, revert to `\"cpu\"`\n- Just delete the `RAG_DEVICE` line to fall back — other config is untouched\n\n### 8.3 Minimum Chunk Length (`CHUNK_MIN_LENGTH`)\n\nFilters out chunks shorter than this value during ingest. Default `50` keeps nearly everything; `200` drops 30-40% of noise fragments.\n\n```json\n\"env\": { \"CHUNK_MIN_LENGTH\": \"200\", \"BASE_DIR\": \"...\" }\n```\n\n⚠️ Blunt instrument — short but important code (e.g., config constants) may also be discarded. Requires index rebuild. Sweet spot: `100-200`.\n\n### 8.4 Recommended Configurations\n\n| Scenario | Config |\n|----------|--------|\n| Daily development | `RAG_DTYPE=fp16` |\n| Large project + M1/M2 Mac | `RAG_DTYPE=fp16, RAG_DEVICE=webgpu` |\n| Memory-constrained | `RAG_DTYPE=q8` |\n\nAll changes require `reindex_all` (MCP) or re-running `ingest` (CLI). If something breaks, delete the failing env line to revert to defaults.\n\n---\n\n## 9. Configuration Reference\n\nMCP server: environment variables only (via your MCP client's `env` block).\nCLI: environment variables + equivalent flags (flags take precedence).\n\n| Env Var | CLI Flag | Default | Description |\n|---------|----------|---------|-------------|\n| `BASE_DIR` | `--base-dir` (repeatable) | `cwd` | Document root (security boundary) |\n| `BASE_DIRS` | — | unset | JSON array of roots, overrides `BASE_DIR` |\n| `DB_PATH` | `--db-path` | `./lancedb/` | Vector database path |\n| `CACHE_DIR` | `--cache-dir` | `./models/` | Model cache — recommend absolute path |\n| `MODEL_NAME` | `--model-name` | `all-MiniLM-L6-v2` | HuggingFace model ID |\n| `MAX_FILE_SIZE` | `--max-file-size` | 100 MB | Max file size in bytes |\n| `CHUNK_MIN_LENGTH` | `--chunk-min-length` | `50` | Min chunk length (1–10000 chars) |\n| `RAG_DEVICE` | — | `cpu` | ONNX execution device |\n| `RAG_DTYPE` | — | `fp32` | Quantization (`fp32`/`fp16`/`q8`) |\n| `HTTPS_PROXY` | — | unset | Model download proxy. v0.18.5+ globally effective |\n| `HF_ENDPOINT` | — | `huggingface.co` | Manual mirror override |\n| `HF_AUTO_MIRROR` | — | `true` | Auto-detection toggle |\n| `RAG_WATCH` | — | unset | File watching (`true`/`1`) |\n\n**Root resolution order**: CLI `--base-dir` > `BASE_DIRS` > `BASE_DIR` > `cwd`. `BASE_DIRS` and `BASE_DIR` are never merged. Only JSON array syntax supported for `BASE_DIRS` — delimiter syntax is intentionally rejected.\n\n---\n\n## 10. Troubleshooting\n\n<details open>\n<summary><strong>Model download failed</strong></summary>\n\nSymptoms: `fetch failed`, `status` shows `searchMode: fts` instead of `hybrid`.\n\n**Solutions:**\n\n1. **Network restriction** (mainland China, etc.) — use proxy:\n   ```json\n   \"env\": { \"HTTPS_PROXY\": \"http://127.0.0.1:7890\" }\n   ```\n   Set in your MCP client config, not the terminal. v0.18.5+ globally effective via `setGlobalDispatcher`.\n\n2. **Auto-mirror fallback** (v0.18.2+, default) — three-tier probe. Usually works without any config.\n\n3. **Manual override** — `HF_ENDPOINT=https://modelscope.cn` or [download models manually](https://huggingface.co/Xenova/all-MiniLM-L6-v2) into `CACHE_DIR`.\n\n4. **npx cached old version** — clear and restart:\n   ```bash\n   rm -rf ~/.npm/_npx/\n   ```\n\n</details>\n\n<details>\n<summary><strong>MCP client doesn't see tools</strong></summary>\n\n1. Verify config file syntax\n2. WorkBuddy users: confirm \"Trust\" button clicked\n3. Restart client completely (Cmd+Q on macOS)\n4. Test directly: `npx @damoqiongqiu/mcp-local-rag` should run without errors\n\n</details>\n\n<details>\n<summary><strong>Rebuilding the index</strong></summary>\n\nAfter switching models or when the database is corrupted:\n\n1. Stop the MCP service\n2. Delete `DB_PATH` directory (default `./lancedb/`) — safe, doesn't affect source files\n3. Restart MCP → fresh database auto-created\n4. Bulk re-ingest:\n   ```bash\n   npx @damoqiongqiu/mcp-local-rag ingest ./src/\n   ```\n\n</details>\n\n<details>\n<summary><strong>FAQ</strong></summary>\n\n- **Private?** Yes. After model download, nothing leaves your machine.\n- **Offline?** Yes, once models are cached.\n- **Supported formats?** 50+ code languages + PDF/DOCX/TXT/MD/HTML. No Excel, PPT, or images.\n- **GPU acceleration?** Opt-in via `RAG_DEVICE`. Support depends on your system, Node.js version, and the ONNX backend.\n- **Backup?** Copy the `DB_PATH` directory.\n\n</details>\n\n---\n\n## 11. Development\n\n```bash\ngit clone https://github.com/damoqiongqiu/mcp-local-rag.git\ncd mcp-local-rag\npnpm install\n```\n\n```bash\npnpm test              # All tests\npnpm run type-check    # TypeScript check\npnpm run check:fix     # Lint + format\npnpm run check:all     # Full CI pipeline\n```\n\n```text\nsrc/\n  index.ts      # Entry point\n  server/       # MCP tool handlers\n  cli/          # CLI subcommands\n  parser/       # PDF/DOCX/TXT/MD/code parsing\n  chunker/      # SemanticChunker + CodeChunker\n  embedder/     # Transformers.js embeddings\n  vectordb/     # LanceDB operations\n  utils/        # Shared utilities (security, scan, scope)\n  __tests__/    # Test suites\n```\n\n---\n\n## License\n\nMIT License. Free for personal and commercial use.\n\n## Acknowledgments\n\nBuilt with [Model Context Protocol](https://modelcontextprotocol.io/) (Anthropic), [LanceDB](https://lancedb.com/), and [Transformers.js](https://huggingface.co/docs/transformers.js).\n",
  "bytes": 22334,
  "sha": "99c6d816dfd7c1ed34068a5b963f8d968d05da7acd65375ffbad46bd9c22e387",
  "repo_slug": "damoqiongqiu/mcp-local-rag",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_damoqiongqiu_mcp_local_rag_71c277ce/readme"
}