MCP Local RAG

本地文档检索服务：在本机完成文档解析、向量化、LanceDB 存储和混合检索，不上传文档。 可通过 MCP 客户端或命令行使用。

快速开始

要求：Node.js 22+。首次运行需要网络下载 npm 依赖和 embedding 模型；模型缓存后可离线运行。

pnpm install
pnpm build

$env:BASE_DIR = 'D:\Rag\documents'
npx mcp-local-rag sync
npx mcp-local-rag query '查询内容'

默认索引为当前工作目录下的 lancedb。本项目 Windows 脚本统一使用 D:\Rag，目录结构为：

D:\Rag\documents
D:\Rag\models
D:\Rag\indexes\lancedb
D:\Rag\indexes\lancedb-intel-npu

使用 npm CLI 时，建议显式设置绝对路径：

$env:BASE_DIR = 'D:\Rag\documents'
$env:DB_PATH = 'D:\Rag\indexes\lancedb'
npx mcp-local-rag sync
npx mcp-local-rag query '查询内容' --scope 'D:\Rag\documents\gmsl'

也可以直接运行 npx -y mcp-local-rag 作为 MCP server，并在 MCP 客户端配置同样的 BASE_DIR、DB_PATH 等环境变量。

支持内容

• 文件：PDF、DOCX、Markdown、TXT。
• HTML：由 MCP 客户端抓取后通过 ingest_data 传入。
• 检索：语义相似度与关键词匹配结合。
• 工具：sync_start、sync_status、ingest_file、ingest_data、query_documents、 read_chunk_neighbors、list_files、delete_file、status。

文件操作只能访问配置的文档根目录。修改模型、设备、精度或分块规则后，必须使用新的索引目录或重新建库。

Windows 后端

全局安装后可直接使用以下命令：

npm install -g mcp-local-rag

项目内安装时，在命令前加 npx，例如 npx mcp-local-rag-onnx sync。npm 包内部仍包含 tools/ 与 requirements-openvino.txt，无需手动定位它们。

以下脚本需要 Python 3.10+；标准 npm CLI 不需要 Python。默认文档根目录为 D:\Rag\documents，模型缓存为 D:\Rag\models。

ONNX Runtime（CPU / WebGPU / DirectML）

与 NPU 脚本一样，通过子命令区分建库和查询。默认索引为 D:\Rag\indexes\lancedb：

mcp-local-rag-onnx sync
mcp-local-rag-onnx query '查询内容' `
  --scope 'D:\Rag\documents\gmsl'

sync 默认 webgpu，query 默认 cpu；两者均可通过 --device cpu|webgpu|dml 显式覆盖。例如使用 DirectML 建库： mcp-local-rag-onnx sync --device dml。 建库批次默认是 8，可通过 sync --batch-size <数量> 调整；查询一次只嵌入一个问题， 批次固定为 1。

Intel NPU（OpenVINO）

首次使用、删除 .openvino-venv 或更新 OpenVINO/NPU 驱动后执行一次。脚本会准备 FP32 模型并编译四个固定形状 [1,128]、[1,256]、[1,512]、[1,1024] 的 NPU blob：

mcp-local-rag-npu-setup

在单独终端启动服务，并在建库或查询期间保持运行：

mcp-local-rag-npu-start

健康检查只在排查问题时执行，不需要每次运行：

Invoke-RestMethod http://127.0.0.1:8765/health

返回的 device 应为 NPU。服务不会自动回退 CPU，关闭服务进程或终端后服务才会停止。

在另一个终端建库或查询。默认 NPU 索引为 D:\Rag\indexes\lancedb-intel-npu：

mcp-local-rag-npu sync
mcp-local-rag-npu query '查询内容' `
  --scope 'D:\Rag\documents\gmsl'

可用 --database-path、--documents-root、--models-path 和 --endpoint 覆盖默认值。 NPU 服务按文本 token 数选择最小可容纳的固定长度，batch 固定为 1。

常用配置

RAG_EMBEDDER_BACKEND=openvino 时，必须先启动 OpenVINO 服务。不同模型或后端生成的向量 不可混用，应分别使用不同的 DB_PATH。

开发

pnpm build
pnpm test
pnpm run check:all

项目许可证为 MIT。