Power your agent
Yayıncının kendi komutu. PlugMCP uç noktası değildir.
Host a copy with our keys and logs.
npx -y @damoqiongqiu/[email protected]Claude Code'un yerel komutlar için kurulum bağlantısı yok. Aşağıdaki komutu kopyalayın ve bir terminalde çalıştırın.
BASE_DIR=<value> BASE_DIRS=<value> DB_PATH=<value> CACHE_DIR=<value> MODEL_NAME=<value> MAX_FILE_SIZE=<value> RAG_MAX_DISTANCE=<value> RAG_GROUPING=<value> RAG_MAX_FILES=<value> CHUNK_MIN_LENGTH=<value> RAG_DEVICE=<value> RAG_DTYPE=<value> RAG_HYBRID_WEIGHT=<value> RAG_WATCH=<value> HF_ENDPOINT=<value> HF_AUTO_MIRROR=<value> HTTPS_PROXY=<value> HTTP_PROXY=<value> claude mcp add io.github.damoqiongqiu-mcp-local-rag -- npx -y @damoqiongqiu/mcp-local-rag@0.21.0Bir terminalde çalıştırın.
{ "mcpServers": { "io.github.damoqiongqiu-mcp-local-rag": { "command": "npx", "args": [ "-y", "@damoqiongqiu/[email protected]" ], "env": { "BASE_DIR": "<value>", "BASE_DIRS": "<value>", "DB_PATH": "<value>", "CACHE_DIR": "<value>", "MODEL_NAME": "<value>", "MAX_FILE_SIZE": "<value>", "RAG_MAX_DISTANCE": "<value>", "RAG_GROUPING": "<value>", "RAG_MAX_FILES": "<value>", "CHUNK_MIN_LENGTH": "<value>", "RAG_DEVICE": "<value>", "RAG_DTYPE": "<value>", "RAG_HYBRID_WEIGHT": "<value>", "RAG_WATCH": "<value>", "HF_ENDPOINT": "<value>", "HF_AUTO_MIRROR": "<value>", "HTTPS_PROXY": "<value>", "HTTP_PROXY": "<value>" } } }}claude_desktop_config.json
Uzak URL mi, yoksa makinenizde bir komut mu? İki kurulum arasındaki fark
PlugMCP’de çalıştır
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
Başlat🍴 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.
📖 中文文档
useEffect, error codes, class names rank higher — not just semantically guessed.find_definition and find_references for IDE-level code navigation, powered by tree-sitter metadata captured at ingest time.huggingface.co → hf-mirror.com → modelscope.cn, zero config for users in mainland China.npx command. No Docker, Python, or servers to manage.Set BASE_DIR to the folder you want to search (BASE_DIRS for multiple roots — see Configuration).
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.
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.
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
Chunking strategy is chosen per file type:
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.SemanticChunker splits into sentences, groups by embedding similarity to find natural topic boundaries. Markdown code blocks remain intact — never split mid-block.Search = semantic similarity + keyword boost (RAG_HYBRID_WEIGHT, default 0.6):
Exact identifiers like useEffect are never buried by semantic approximations.
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.
15 tools organized into 5 categories.
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.
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.
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.
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.
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.
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.
dedup_check is especially useful in monorepos — spot ↔ futures mirror code is typically flagged with similarity 1.0.
# Ingest
npx @damoqiongqiu/mcp-local-rag ingest ./src/
# Search (with scope)
npx @damoqiongqiu/mcp-local-rag query "auth middleware"
npx @damoqiongqiu/mcp-local-rag query "auth" --scope /docs/api
# Context expansion
npx @damoqiongqiu/mcp-local-rag read-neighbors --file-path /abs/path.md --chunk-index 5
# Management
npx @damoqiongqiu/mcp-local-rag list --scope /docs/api
npx @damoqiongqiu/mcp-local-rag status
npx @damoqiongqiu/mcp-local-rag delete ./docs/old.pdf
npx @damoqiongqiu/mcp-local-rag delete --source "https://..."
query, read-neighbors, list, status, delete emit JSON to stdout (pipe to jq). ingest emits progress to stderr.
Global options (--db-path, --cache-dir, --model-name) go before the subcommand:
npx @damoqiongqiu/mcp-local-rag --help
⚠️ The CLI does NOT read your MCP client config (
mcp.json, etc.). Configure via flags or environment variables.
Flags — global options before, subcommand options after:
npx @damoqiongqiu/mcp-local-rag --db-path ./my-db query "auth" --base-dir ./docs
--base-dir is repeatable on ingest and list:
npx @damoqiongqiu/mcp-local-rag ingest --base-dir ./docs --base-dir ./specs ./docs/readme.md
Environment variables:
export DB_PATH=./my-db
export BASE_DIR=./docs
npx @damoqiongqiu/mcp-local-rag query "auth"
For multiple roots, use BASE_DIRS (JSON array):
export BASE_DIRS='["/Users/me/work","/Users/me/specs"]'
Precedence: CLI flags > environment variables > defaults.
huggingface.co is inaccessible from mainland China. Built-in three-tier mirror chain with automatic fallback:
huggingface.co → hf-mirror.com → modelscope.cn
At startup, each mirror is HEAD-probed (3s timeout). The first reachable mirror with a complete API is selected:
HTTPS_PROXY) → direct to huggingface.coNo manual HF_ENDPOINT required. For manual control:
v0.18.5+ uses
setGlobalDispatcher(ProxyAgent)— all Node.js 22 network requests go through the proxy.
6 embedding models with alias resolution via model-registry:
Guidance: code repos → default model + high keyword boost; multilingual → consider embeddinggemma-300m; scientific papers → consider allenai-specter.
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.
Set RAG_WATCH=true — the server starts recursive fs.watch on baseDirs (500ms debounce):
ingest_filedelete_fileIdeal for actively changing projects.
Code-focused tuning (recommended default):
{ "RAG_HYBRID_WEIGHT": "0.7", "RAG_GROUPING": "similar" }
Document-focused tuning:
{ "RAG_HYBRID_WEIGHT": "0.4", "RAG_GROUPING": "related" }
Keyword boost is applied after semantic filtering — improves precision without introducing noise.
Beyond search accuracy, inference performance is also configurable. All optimizations are environment variables — no code changes required.
RAG_DTYPE)Controls ONNX model inference precision. For all-MiniLM-L6-v2, three levels are available:
"env": { "RAG_DTYPE": "fp16", "BASE_DIR": "..." }
⚠️ Changing dtype requires index rebuild — embedding spaces are incompatible.
Verify it works: After restart, call status via MCP and check the dtype field. Should match your setting (e.g., "fp16").
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.
RAG_DEVICE)Controls which ONNX Runtime backend to use:
"env": { "RAG_DEVICE": "webgpu", "RAG_DTYPE": "fp16", "BASE_DIR": "..." }
⚠️ Changing device changes the embedding space — requires index rebuild. Stacks with RAG_DTYPE — fp16 + webgpu gives both model-size reduction and GPU speedup.
Verify it works: MCP startup log should show Loading model on device "webgpu". status should show device: "webgpu".
If it fails:
Unsupported device at startup → WebGPU unavailable in your environment, revert to "cpu""cpu"RAG_DEVICE line to fall back — other config is untouchedCHUNK_MIN_LENGTH)Filters out chunks shorter than this value during ingest. Default 50 keeps nearly everything; 200 drops 30-40% of noise fragments.
"env": { "CHUNK_MIN_LENGTH": "200", "BASE_DIR": "..." }
⚠️ Blunt instrument — short but important code (e.g., config constants) may also be discarded. Requires index rebuild. Sweet spot: 100-200.
All changes require reindex_all (MCP) or re-running ingest (CLI). If something breaks, delete the failing env line to revert to defaults.
MCP server: environment variables only (via your MCP client's env block).
CLI: environment variables + equivalent flags (flags take precedence).
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.
Symptoms: fetch failed, status shows searchMode: fts instead of hybrid.
Solutions:
Network restriction (mainland China, etc.) — use proxy:
"env": { "HTTPS_PROXY": "http://127.0.0.1:7890" }
Set in your MCP client config, not the terminal. v0.18.5+ globally effective via setGlobalDispatcher.
Auto-mirror fallback (v0.18.2+, default) — three-tier probe. Usually works without any config.
Manual override — HF_ENDPOINT=https://modelscope.cn or download models manually into CACHE_DIR.
npx cached old version — clear and restart:
rm -rf ~/.npm/_npx/
npx @damoqiongqiu/mcp-local-rag should run without errorsAfter switching models or when the database is corrupted:
DB_PATH directory (default ./lancedb/) — safe, doesn't affect source filesnpx @damoqiongqiu/mcp-local-rag ingest ./src/
RAG_DEVICE. Support depends on your system, Node.js version, and the ONNX backend.DB_PATH directory.git clone https://github.com/damoqiongqiu/mcp-local-rag.git
cd mcp-local-rag
pnpm install
pnpm test # All tests
pnpm run type-check # TypeScript check
pnpm run check:fix # Lint + format
pnpm run check:all # Full CI pipeline
src/
index.ts # Entry point
server/ # MCP tool handlers
cli/ # CLI subcommands
parser/ # PDF/DOCX/TXT/MD/code parsing
chunker/ # SemanticChunker + CodeChunker
embedder/ # Transformers.js embeddings
vectordb/ # LanceDB operations
utils/ # Shared utilities (security, scan, scope)
__tests__/ # Test suites
MIT License. Free for personal and commercial use.
Built with Model Context Protocol (Anthropic), LanceDB, and Transformers.js.
Semantic code & doc search with keyword boost. AST code nav, auto HF mirror, local, privacy-first.
{ "mcpServers": { "io.github.damoqiongqiu-mcp-local-rag": { "command": "npx", "args": [ "-y", "@damoqiongqiu/[email protected]" ], "env": { "BASE_DIR": "<value>", "BASE_DIRS": "<value>", "DB_PATH": "<value>", "CACHE_DIR": "<value>", "MODEL_NAME": "<value>", "MAX_FILE_SIZE": "<value>", "RAG_MAX_DISTANCE": "<value>", "RAG_GROUPING": "<value>", "RAG_MAX_FILES": "<value>", "CHUNK_MIN_LENGTH": "<value>", "RAG_DEVICE": "<value>", "RAG_DTYPE": "<value>", "RAG_HYBRID_WEIGHT": "<value>", "RAG_WATCH": "<value>", "HF_ENDPOINT": "<value>", "HF_AUTO_MIRROR": "<value>", "HTTPS_PROXY": "<value>", "HTTP_PROXY": "<value>" } } }}Araçlar
Henüz araç listesi yok. Uzak sunucular ilk sağlık kontrolünden sonra bir liste alır.
SSS
Bu sayfadan Cursor, Claude Desktop, Claude Code veya VS Code için stdio yapılandırmasını kopyalayın. PlugMCP proxy'sini değil, yayıncının kurulumunu kullanır.
Yayıncı şu ortam değişkenlerini listeliyor: BASE_DIR, BASE_DIRS, DB_PATH, CACHE_DIR, MODEL_NAME, MAX_FILE_SIZE, RAG_MAX_DISTANCE, RAG_GROUPING, RAG_MAX_FILES, CHUNK_MIN_LENGTH, RAG_DEVICE, RAG_DTYPE, RAG_HYBRID_WEIGHT, RAG_WATCH, HF_ENDPOINT, HF_AUTO_MIRROR, HTTPS_PROXY, HTTP_PROXY.
MCP Local Rag yerel olarak stdio üzerinden çalışır.
Son kontrol: 2026-11-09. Semantic code & doc search with keyword boost. AST code nav, auto HF mirror, local, privacy-first.