![\"MCP](\"assets/banner.jpg\")
\n\n \n
\n English |\n 简体中文 |\n Deutsch |\n Español |\n Português (Brasil) |\n Français\n
\n\n通过 MCP 客户端或终端搜索私有文档，无需将内容发送给嵌入 API。\n\nmcp-local-rag 在本机为 PDF、DOCX、Markdown 和文本文件建立索引。搜索结合语义相似度与关键词匹配，既能理解查询意图，也能准确匹配 API 名称、类名和错误代码等技术术语。\n\n## 功能\n\n- **本地运行：** 文档解析、嵌入、存储和搜索全部在本机完成。首次下载模型后，文本导入和搜索均可离线使用。\n- **混合搜索：** 语义检索负责查找相关概念，关键词匹配则提高精确技术术语的排名。\n- **可配置嵌入模型：** 可根据文档的语言和领域选择合适的 Hugging Face 嵌入模型。\n- **语义分块：** 按主题边界而非固定字符数拆分文档，并保持 Markdown 代码块完整。\n- **MCP 和 CLI：** AI 编程工具与终端可使用同一份索引。\n\n无需 API 密钥、Docker、Python 或外部数据库。\n\n## 快速开始\n\n### 使用要求\n\n- Node.js 22 或更高版本\n- 首次使用时需要联网下载 npm 包和嵌入模型\n- 一个包含待搜索文档的目录\n\n将 `BASE_DIR` 设置为该目录。它同时也是文件操作的安全边界。请将下方的 `/absolute/path/to/your/documents` 替换为该目录的绝对路径。\n\nmcp-local-rag 通过本地 stdio 服务器使用标准 MCP 协议，因此可与支持本地 MCP 服务器的 AI 编程工具及其他 MCP 宿主配合使用。\n\n可直接使用以下示例，也可以按照客户端的 MCP 配置格式注册 `npx -y mcp-local-rag` 并设置 `BASE_DIR`。\n\n**Claude Code：** 运行以下命令：\n\n```bash\nclaude mcp add local-rag --scope user --env BASE_DIR=/absolute/path/to/your/documents -- npx -y mcp-local-rag\n```\n\n**Codex：** 在 `~/.codex/config.toml` 中添加：\n\n```toml\n[mcp_servers.local-rag]\ncommand = \"npx\"\nargs = [\"-y\", \"mcp-local-rag\"]\n\n[mcp_servers.local-rag.env]\nBASE_DIR = \"/absolute/path/to/your/documents\"\n```\n\n**OpenCode：** 在 `~/.config/opencode/opencode.json`（或 `opencode.jsonc`）中添加：\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"mcp\": {\n \"local-rag\": {\n \"type\": \"local\",\n \"command\": [\"npx\", \"-y\", \"mcp-local-rag\"],\n \"environment\": {\n \"BASE_DIR\": \"/absolute/path/to/your/documents\"\n }\n }\n }\n}\n```\n\n**Cursor：** 在 `~/.cursor/mcp.json` 中添加：\n\n```json\n{\n \"mcpServers\": {\n \"local-rag\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"mcp-local-rag\"],\n \"env\": {\n \"BASE_DIR\": \"/absolute/path/to/your/documents\"\n }\n }\n }\n}\n```\n\n重启客户端，然后让它创建索引：\n\n```text\n同步已配置根目录中的所有文档，并等待同步完成。\n```\n\n首次同步会下载默认嵌入模型（约 90 MB）。开始导入前可能需要等待 1–2 分钟，之后会直接使用本地缓存。\n\n同步完成后即可提问：\n\n```text\nAPI 文档如何说明身份验证？\n```\n\n### CLI 快速开始\n\n不使用 MCP 客户端时，可直接通过 CLI 操作：\n\n```bash\nnpx mcp-local-rag ingest ./docs/\nnpx mcp-local-rag query \"身份验证 API\"\n```\n\nCLI 默认将当前目录作为文档根目录。请在同一目录中运行这两条命令，以便共用默认索引；也可以显式设置 `BASE_DIR` 和 `DB_PATH`。\n\n## 为什么开发它\n\n出于保密要求或组织政策，有些文档不能发送给托管式嵌入服务。将索引保留在本机，既能搜索这些文档，也不会产生按查询计费的 API 成本。\n\n单纯依赖语义搜索，可能会漏掉技术文档中重要的精确标识符。关键词重排可以保留这些精确匹配，同时继续利用自然语言检索。\n\n## 支持的内容\n\n| 输入 | 导入方式 |\n|---|---|\n| PDF、DOCX、TXT、Markdown | 导入文件或同步目录 |\n| 客户端已获取的 HTML | 使用 `ingest_data`；通过 Readability 清理后转换为 Markdown |\n| 内存中的纯文本或 Markdown | 使用 `ingest_data`，并提供稳定的来源标识符 |\n\n服务器本身不负责获取 HTML。MCP 客户端可以先获取网页，再将 HTML 传给 `ingest_data`。\n\n文件导入不支持 Excel、PowerPoint、独立图片和源代码文件扩展名。PDF 可以选择使用本地视觉模型描述图像内容，但该功能不属于 OCR 或图片搜索。\n\n## MCP 工具\n\n| 工具 | 用途 |\n|---|---|\n| `sync_start` | 将全部已配置根目录或指定路径与索引同步 |\n| `sync_status` | 查询正在运行的同步任务 |\n| `ingest_file` | 导入或替换单个文件 |\n| `ingest_data` | 导入客户端已有的文本、Markdown 或 HTML |\n| `query_documents` | 使用语义匹配和关键词加权进行搜索 |\n| `read_chunk_neighbors` | 读取搜索结果相邻的文本块 |\n| `list_files` | 显示支持的文件及其导入状态 |\n| `delete_file` | 删除已建立索引的文件或 `ingest_data` 条目 |\n| `status` | 显示索引和搜索状态 |\n\n### 同步文档根目录\n\n`sync_start` 会导入新增和已修改的文件，跳过字节完全相同的文件，并删除已不存在文件的索引记录：\n\n```text\n同步已配置文档根目录中的所有内容，并等待完成。\n```\n\n该工具会立即返回 `jobId`。客户端应持续查询 `sync_status`，直到状态变为 `succeeded` 或 `failed`。发生变化的 PDF 会沿用索引时所用的模式重新导入；索引时未使用视觉模式的 PDF 仍按纯文本处理。`sync_start` 无法更改该模式。\n\n服务器进程只保留一个同步任务记录。新任务会替换已经结束的记录，服务器重启后该记录也会丢失。\n\n### 导入单个文件\n\n`ingest_file` 支持 PDF、DOCX、TXT 和 Markdown。通过 MCP 传入的文件路径必须是绝对路径，并且必须位于已配置的文档根目录内：\n\n```text\n导入 /Users/me/docs/api-spec.pdf。\n```\n\n再次导入同一路径会替换原有文本块。\n\n### 搜索并读取更多上下文\n\n```text\nAPI 文档如何说明身份验证？\n查找 ERR_CONNECTION_REFUSED 的文档说明。\n```\n\n搜索结果包含文本、来源路径、标题、文本块编号和相关度分数。需要更多上下文时，将结果中的 `chunkIndex` 以及 `filePath` 或 `source` 传给 `read_chunk_neighbors`：\n\n```text\n读取该身份验证结果前后的文本块。\n```\n\n`query_documents` 和 `list_files` 都接受可选的绝对 `scope` 路径前缀或前缀列表。前缀会匹配指定路径及其全部子路径。\n\n### 导入 HTML\n\n由 MCP 客户端获取网页后，再使用 `ingest_data`：\n\n```text\n获取 https://example.com/docs 并导入其中的 HTML。\n```\n\n服务器会提取正文、转换为 Markdown，并使用提供的来源标识符保存。再次使用同一来源会更新已有内容。\n\n为外部内容建立索引时，请遵守来源网站的条款和版权规定。\n\n### PDF 图像\n\n视觉模式会为图像内容较多的 PDF 页面生成说明文字。该功能需要主动开启，常规导入不会加载视觉模型。\n\n```text\n使用 visual: true 导入 /Users/me/docs/research-paper.pdf。\n```\n\n```bash\nnpx mcp-local-rag ingest ./docs/research-paper.pdf --visual\n```\n\n| 模式 | 模型缓存 | 适用场景 |\n|---|---:|---|\n| `fast`（默认） | 约 250 MB | 轻量视觉索引 |\n| `quality` | 约 1.7 GB | 包含标签、标注或其他图中文字的图像 |\n\n通过 MCP 使用 `visualQuality: \"quality\"`，或通过 CLI 使用 `--visual-quality quality`，即可选择较大的模型。实测 CPU 推理耗时约为 `fast` 的三倍，但实际结果取决于硬件和模型更新。\n\n#### 更新已索引的 `quality` 说明文字\n\n从 0.18.4 起，`quality` 使用 Qwen3.5-2B，旧版本使用 Qwen2.5-VL-3B。已索引的说明文字仍是旧模型生成的内容，`sync` 不会重新生成，需要更新的文件请重新导入：\n\n```bash\nnpx mcp-local-rag ingest ./docs/research-paper.pdf --visual --visual-quality quality\n```\n\n如果该文件当初是带 `--images` 导入的，请一并加上该选项，否则本次导入会替换已保存的图像。旧模型仍留在磁盘上。确认不再使用后，可删除模型缓存目录（`