# MCP Local RAG

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

## 快速开始

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

```powershell
pnpm install
pnpm build

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

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

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

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

```powershell
$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 后端

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

```powershell
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`：

```powershell
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：

```powershell
mcp-local-rag-npu-setup
```

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

```powershell
mcp-local-rag-npu-start
```

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

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

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

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

```powershell
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。

## 常用配置

| 环境变量                  | 默认值                                      | 作用                                     |
| ------------------------- | ------------------------------------------- | ---------------------------------------- |
| `BASE_DIR`              | 当前目录                                    | 文档根目录                               |
| `DB_PATH`               | `./lancedb`                               | LanceDB 索引目录                         |
| `CACHE_DIR`             | `./models`                                | 模型缓存目录                             |
| `MODEL_NAME`            | `onnx-community/embeddinggemma-300m-ONNX` | embedding 模型                           |
| `RAG_DEVICE`            | `cpu`                                     | Transformers.js 设备，如`cpu`、`dml` |
| `RAG_DTYPE`             | `fp32`                                    | embedding 精度                           |
| `RAG_EMBEDDER_BACKEND`  | `transformers`                            | `transformers` 或 `openvino`         |
| `RAG_OPENVINO_ENDPOINT` | `http://127.0.0.1:8765`                   | OpenVINO 服务地址                        |

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

## 开发

```powershell
pnpm build
pnpm test
pnpm run check:all
```

项目许可证为 MIT。