mcp-local-rag

MCP Local RAG

🍴 从 shinpr/mcp-local-rag 分叉而来 — 原作者为 Shinsuke Kagawa

面向 AI 编码助手的本地代码智能引擎。通过 AST 级语义分块和关键词加权，精准定位函数、类和 API — 完全私密，无需任何配置。

📖 中文文档

---

目录

1. 功能
2. 快速开始
   • 2.1 配置 AI 编码工具
   • 2.2 CLI 快速开始
   • 2.3 首次项目索引
3. 核心概念
   • 3.1 双策略分块
   • 3.2 混合搜索
   • 3.3 安全边界
4. MCP 工具参考
   • 4.1 摄取工具
   • 4.2 搜索工具
   • 4.3 管理工具
   • 4.4 代码智能
   • 4.5 系统工具
5. CLI
   • 5.1 基本命令
   • 5.2 CLI 配置
6. 网络与模型
   • 6.1 镜像自动检测
   • 6.2 模型选择
   • 6.3 文件监视
7. 搜索调优
8. 性能调优
   • 8.1 量化精度
   • 8.2 执行设备
   • 8.3 最小分块长度
   • 8.4 推荐配置
9. 配置参考
10. 故障排查
11. 开发

---

1. 功能

• 智能双策略分块 — 通过 tree-sitter 进行 AST 级代码分块（在函数／类／方法边界处拆分，并注入作用域链和导入信息）。文档采用语义分块（按含义拆分，而非按字符数）。
• 语义搜索 + 关键词加权 — 先进行向量搜索，再通过关键词匹配提高精确词项的权重。useEffect、错误代码、类名等的排名会更高，而不只是依靠语义猜测。
• 15 个 MCP 工具 — 在一个服务中整合摄取、搜索、管理、代码智能和系统操作。
• AST 代码智能 — find_definition 和 find_references 可实现 IDE 级代码导航，依托摄取时捕获的 tree-sitter 元数据。
• 三级镜像自动回退 — huggingface.co → hf-mirror.com → modelscope.cn，中国大陆用户无需配置。
• 完全在本地运行 — 无需 API 密钥，无需云服务，数据不会离开你的设备。首次下载模型后即可离线使用。
• 零门槛设置 — 一条 npx 命令即可。无需管理 Docker、Python 或服务。

---

2. 快速开始

将 BASE_DIR 设置为你要搜索的文件夹（多个根目录请使用 BASE_DIRS — 参见配置）。

2.1 配置 AI 编码工具

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 — 设置 → 自定义连接器 → 添加：

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

⚠️ WorkBuddy：添加后，必须在自定义连接器列表中点击“信任”，否则服务会被静默阻止。

2.2 CLI 快速入门

无需 MCP — 直接在终端中运行：

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

就这样。无需 Docker、Python 或服务配置。

2.3 首次项目索引

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. 核心概念

3.1 双策略分块

分块策略按文件类型选择：

• 代码文件（50 多种语言）— CodeChunker 通过 tree-sitter AST 解析源代码，并在结构边界（函数、类、方法）处分块。每个分块的 contextualizedText 都包含其作用域链和导入上下文，以实现精准的语义搜索。
• 文档（PDF/DOCX/TXT/MD/HTML）— SemanticChunker 将内容拆分为句子，再按嵌入相似度分组，以找到自然的主题边界。Markdown 代码块会保持完整 — 绝不会在代码块中间拆分。

3.2 混合搜索

搜索 = 语义相似度 + 关键词加权（RAG_HYBRID_WEIGHT，默认值为 0.6）：

1. 查询向量化 → 语义搜索找到最相关的分块
2. 应用质量筛选（距离阈值、分组）
3. 关键词匹配提高精确术语的排名

像 useEffect 这样的精确标识符不会被语义近似结果淹没。

3.3 安全边界

只有位于 BASE_DIR / BASE_DIRS 下的文件才能用于导入、列出、删除或读取邻近内容。解析到根目录之外的符号链接会被拒绝。也会阻止具有相同前缀的同级路径（例如，根目录为 /foo/bar 时的 /foo/barista）— 防止路径遍历攻击。

---

4. MCP 工具参考

15 个工具分为 5 类。

4.1 导入工具

#	工具	用途	示例
1	ingest_file	单个文件（PDF/DOCX/TXT/MD/代码）	"Ingest ./docs/api-spec.pdf"
2	ingest_data	内存中的文本/HTML	"Fetch this page and ingest the HTML"
3	ingest_directory	批量导入目录	"Ingest everything under ./src"

ingest_file 支持 50 多种代码语言。PDF 支持可选的视觉模式 — 本地 VLM 会为包含图表的页面生成说明文字，让视觉内容也可供搜索。提供两种配置：

配置	模型	缓存	适用场景
fast（默认）	SmolVLM-256M	~250 MB	轻量视觉索引
quality	Qwen2.5-VL-3B-ONNX	~2.9 GB	含有图片内文字的图表

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

ingest_data 依次执行 Readability → Markdown → 索引。非常适合导入 AI 助手获取的网页内容。重新导入会自动替换旧版本。

ingest_directory 递归扫描、遵循 .gitignore，并通过 MCP 通知实时显示进度。

4.2 搜索工具

#	工具	用途	关键参数
4	query_documents	混合搜索（语义 + 关键词）	query、limit、scope、highlightContext、fromTimestamp
5	read_chunk_neighbors	扩展搜索结果周围的上下文	filePath、chunkIndex、before、after

query_documents — scope 接受单个路径前缀或列表，将结果限制在相应子树中。highlightContext 返回匹配词周围的片段。fromTimestamp / untilTimestamp 支持按时间范围筛选。

read_chunk_neighbors — 默认读取前后各 2 个分块（类似 grep -C 2），每侧最多 50 个。响应会将目标分块标记为 isTarget: true。

4.3 管理工具

#	工具	用途
6	list_files	列出文件及其摄取状态（ingested: true/false）
7	delete_file	按文件路径或源 URL 删除
8	status	索引统计信息：文档、分块、内存、搜索模式

list_files 支持使用 scope 过滤，其前缀匹配规则与搜索相同。在大型目录中，scope 可通过跳过范围外的子树来加快扫描速度。

4.4 代码智能

#	工具	用途	输入
9	find_definition	定位符号定义（文件、行范围、作用域）	完整符号名称
10	find_references	查找所有引用（导入 + 文本提及）	符号名称

这两个工具依赖摄取时由 tree-sitter 提取的 AST 元数据（导入、实体、作用域链）。仅适用于使用 CodeChunker 摄取的代码文件——在 v0.18.7 之前摄取的文件缺少此元数据，需要运行 reindex_all 重新构建。

find_references 使用两阶段策略：（1）在 codeMeta.imports 中精确匹配 →（2）使用 FTS 全文搜索符号名称。结果按（filePath、chunkIndex）去重，导入引用排在前面。

4.5 系统工具

#	工具	用途
11	config	运行时热读/写配置——无需重启
12	dedup_check	使用 SHA256 + Jaccard 相似度检测重复文件
13	export_index	将整个索引导出为 JSON（用于备份或迁移）
14	reindex_all	完整重新分块 + 重新嵌入（更换模型后使用）
15	reindex_stale	仅重新摄取磁盘上已修改的文件（增量同步）

config 可热切换 hybridWeight、modelName、cacheDir、baseDir/baseDirs 等。切换模型时会自动释放旧的 Embedder 并初始化新的 Embedder——注意：更换模型会改变嵌入空间，需要运行 reindex_all。

dedup_check 在单体代码库中特别有用——spot ↔ futures 镜像代码通常会被标记为相似度 1.0。

---

5. 命令行

5.1 基本命令

# 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 会将 JSON 输出到 stdout（可通过管道传给 jq）。ingest 会将进度输出到 stderr。

全局选项（--db-path、--cache-dir、--model-name）应放在子命令之前：

npx @damoqiongqiu/mcp-local-rag --help

⚠️ CLI 不会读取你的 MCP 客户端配置（mcp.json 等）。请通过标志或环境变量进行配置。

5.2 CLI 配置

标志——全局选项放在前面，子命令选项放在后面：

npx @damoqiongqiu/mcp-local-rag --db-path ./my-db query "auth" --base-dir ./docs

--base-dir 可在 ingest 和 list 中重复使用：

npx @damoqiongqiu/mcp-local-rag ingest --base-dir ./docs --base-dir ./specs ./docs/readme.md

环境变量：

export DB_PATH=./my-db
export BASE_DIR=./docs
npx @damoqiongqiu/mcp-local-rag query "auth"

对于多个根目录，请使用 BASE_DIRS（JSON 数组）：

export BASE_DIRS='["/Users/me/work","/Users/me/specs"]'

优先级：CLI 标志 > 环境变量 > 默认值。

---

6. 网络与模型

6.1 镜像自动检测

中国大陆无法访问 huggingface.co。内置三级镜像链，并支持自动回退：

huggingface.co → hf-mirror.com → modelscope.cn

启动时会对每个镜像进行 HEAD 探测（超时 3 秒）。系统会选择第一个可访问且 API 完整的镜像：

• 使用代理时（HTTPS_PROXY）→ 直连 huggingface.co
• 未使用代理时 → 自动切换到 hf-mirror.com
• hf-mirror API 不可用时 → 回退到 modelscope.cn

无需手动设置 HF_ENDPOINT。 如需手动控制：

环境变量	效果
HF_AUTO_MIRROR=false	禁用自动检测，仅使用 huggingface.co
HF_ENDPOINT=<url>	强制使用指定镜像，跳过自动检测

v0.18.5+ 使用 setGlobalDispatcher(ProxyAgent)——所有 Node.js 22 网络请求都会通过代理。

6.2 模型选择

6 种嵌入模型，通过 model-registry 解析别名：

模型	别名	大小	维度
Xenova/all-MiniLM-L6-v2（默认）	mini	~90 MB	384
Xenova/all-MiniLM-L12-v2	—	~120 MB	384
Xenova/bge-small-en-v1.5	bge-small	~130 MB	384
Xenova/all-mpnet-base-v2	mpnet	~420 MB	768
Xenova/bge-base-en-v1.5	—	~420 MB	768
Xenova/multi-qa-mpnet-base-dot-v1	multi-qa	~420 MB	768

建议：代码仓库 → 默认模型 + 较高的关键词权重；多语言内容 → 可考虑 embeddinggemma-300m；科学论文 → 可考虑 allenai-specter。

RAG_DTYPE 控制 ONNX 精度（fp32 / fp16 / q8）。默认值为 fp32；内存受限时使用 q8。⚠️ 更换模型或 dtype 需要删除 DB_PATH 并重新建立索引。

6.3 文件监视

设置 RAG_WATCH=true——服务会在 baseDirs 上启动递归 fs.watch（防抖 500ms）：

• 创建/修改文件 → 自动执行 ingest_file
• 删除文件 → 自动执行 delete_file

适用于内容会频繁变更的项目。

---

7. 搜索调优

变量	默认值	说明
RAG_HYBRID_WEIGHT	0.6	关键词权重：0 = 仅语义搜索，1 = 仅关键词搜索
RAG_GROUPING	未设置	similar = 仅返回排名最高的分组，related = 返回排名前 2 的分组
RAG_MAX_DISTANCE	未设置	过滤相关性较低的结果（例如，0.5）
RAG_MAX_FILES	未设置	结果仅限排名前 N 的文件

面向代码的调优（推荐默认设置）：

{ "RAG_HYBRID_WEIGHT": "0.7", "RAG_GROUPING": "similar" }

面向文档的调优：

{ "RAG_HYBRID_WEIGHT": "0.4", "RAG_GROUPING": "related" }

关键词权重在语义过滤之后应用——提升精确度，同时避免引入噪声。

---

8. 性能调优

除了搜索准确度，推理性能也可配置。所有优化项均通过环境变量设置，无需修改代码。

8.1 量化精度（RAG_DTYPE）

控制 ONNX 模型的推理精度。对于 all-MiniLM-L6-v2，有以下三种级别：

值	模型大小	速度	内存	精度损失	适用场景
fp32（默认）	~90 MB	基准	~80 MB	无	首次使用，追求最高准确度
fp16	~45 MB	快 20-30%	~45 MB	可忽略	日常使用的推荐选择
q8	~45 MB	快 30-50%	~45 MB	较小	内存有限、大型项目

"env": { "RAG_DTYPE": "fp16", "BASE_DIR": "..." }

⚠️ 更改 dtype 需要重建索引——嵌入空间彼此不兼容。

验证是否生效： 重启后，通过 MCP 调用 status 并检查 dtype 字段。它应与你的设置一致（例如，"fp16"）。

如果失败： 启动时会抛出 EmbeddingError，并列出支持的 dtype。常见原因：模型未提供 q8 版本——请改用 fp16。

8.2 执行设备（RAG_DEVICE）

控制使用哪个 ONNX Runtime 后端：

值	后端	备注
cpu（默认）	CPU	最稳定，无需额外依赖
webgpu	GPU（WebGPU）	⚠️ 实验性：M1/M2 Mac 使用 Metal，NVIDIA 使用 Vulkan

"env": { "RAG_DEVICE": "webgpu", "RAG_DTYPE": "fp16", "BASE_DIR": "..." }

⚠️ 更换设备会改变嵌入空间——需要重建索引。可与 RAG_DTYPE 组合使用——fp16 + webgpu 可同时缩小模型并提升 GPU 速度。

验证是否生效： MCP 启动日志应显示 Loading model on device "webgpu"。status 应显示 device: "webgpu"。

如果失败：

• 启动时出现 Unsupported device → 你的环境中无法使用 WebGPU，请恢复为 "cpu"
• 成功启动但推理时崩溃 → 可能是 ONNX WebGPU 后端错误，请恢复为 "cpu"
• 只需删除 RAG_DEVICE 行即可回退——其他配置不受影响

8.3 最小分块长度（CHUNK_MIN_LENGTH）

摄取时过滤掉短于此值的分块。默认值 50 几乎会保留所有内容；200 会过滤掉 30-40% 的噪声片段。

"env": { "CHUNK_MIN_LENGTH": "200", "BASE_DIR": "..." }

⚠️ 这是个粗糙的过滤手段——较短但重要的代码（例如配置常量）也可能被丢弃。需要重建索引。最佳范围：100-200。

8.4 推荐配置

场景	配置
日常开发	RAG_DTYPE=fp16
大型项目 + M1/M2 Mac	RAG_DTYPE=fp16, RAG_DEVICE=webgpu
内存受限	RAG_DTYPE=q8

所有更改都需要执行 reindex_all（MCP）或重新运行 ingest（CLI）。如果出现问题，删除出错的环境变量行即可恢复默认值。

---

9. 配置参考

MCP 服务：仅使用环境变量（通过 MCP 客户端的 env 块）。 CLI：环境变量 + 对应的标志（标志优先）。

环境变量	CLI 标志	默认值	描述
BASE_DIR	--base-dir（可重复）	cwd	文档根目录（安全边界）
BASE_DIRS	—	未设置	根目录的 JSON 数组，会覆盖 BASE_DIR
DB_PATH	--db-path	./lancedb/	向量数据库路径
CACHE_DIR	--cache-dir	./models/	模型缓存——建议使用绝对路径
MODEL_NAME	--model-name	all-MiniLM-L6-v2	HuggingFace 模型 ID
MAX_FILE_SIZE	--max-file-size	100 MB	最大文件大小（字节）
CHUNK_MIN_LENGTH	--chunk-min-length	50	最小分块长度（1–10000 个字符）
RAG_DEVICE	—	cpu	ONNX 执行设备
RAG_DTYPE	—	fp32	量化（fp32/fp16/q8）
HTTPS_PROXY	—	未设置	模型下载代理。v0.18.5+ 全局生效
HF_ENDPOINT	—	huggingface.co	手动指定镜像
HF_AUTO_MIRROR	—	true	自动检测开关
RAG_WATCH	—	未设置	文件监视（true/1）

根目录解析顺序：CLI --base-dir > BASE_DIRS > BASE_DIR > cwd。BASE_DIRS 和 BASE_DIR 不会合并。BASE_DIRS 仅支持 JSON 数组语法——有意拒绝分隔符语法。

---

10. 故障排除

模型下载失败

症状：fetch failed，status 显示 searchMode: fts 而不是 hybrid。

解决方案：

1. 网络受限（中国大陆等）——使用代理：

   "env": { "HTTPS_PROXY": "http://127.0.0.1:7890" }
   

   在 MCP 客户端配置中设置，而不是在终端中设置。v0.18.5+ 通过 setGlobalDispatcher 全局生效。

2. 自动镜像回退（v0.18.2+，默认）——三级探测。通常无需任何配置即可正常工作。

3. 手动覆盖——设置 HF_ENDPOINT=https://modelscope.cn，或将模型手动下载到 CACHE_DIR。

4. npx 缓存了旧版本——清理并重启：

   rm -rf ~/.npm/_npx/
   

MCP 客户端看不到工具

1. 检查配置文件语法
2. WorkBuddy 用户：确认已点击“Trust”按钮
3. 完全重启客户端（macOS 上按 Cmd+Q）
4. 直接测试：npx @damoqiongqiu/mcp-local-rag 应能无错误运行

重建索引

切换模型后或数据库损坏时：

1. 停止 MCP 服务
2. 删除 DB_PATH 目录（默认 ./lancedb/）——安全，不会影响源文件
3. 重启 MCP → 自动创建全新数据库
4. 批量重新摄取：

   npx @damoqiongqiu/mcp-local-rag ingest ./src/
   

常见问题

• 隐私？ 是。模型下载后，任何内容都不会离开你的设备。
• 离线使用？ 可以，模型缓存后即可离线使用。
• 支持哪些格式？ 50 多种代码语言 + PDF/DOCX/TXT/MD/HTML。不支持 Excel、PPT 或图像。
• GPU 加速？ 可通过 RAG_DEVICE 选择启用。支持情况取决于你的系统、Node.js 版本和 ONNX 后端。
• 备份？ 复制 DB_PATH 目录即可。

---

11. 开发

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 许可证。可免费用于个人和商业用途。

致谢

基于 Model Context Protocol（Anthropic）、LanceDB 和 Transformers.js 构建。