麦克佩本地检索助手

Name: 麦克佩本地检索助手
Author: shinpr

作者：shinpr17 星标更新：2025-11-22

安装使用来源：spider==github.com

项目介绍

MCP Local RAG

一款以隐私优先的文档搜索服务器，完全运行在您的机器上。无需API密钥、云服务或数据离开您的计算机。

适用于模型上下文协议（MCP），这使您可以使用Cursor、Codex、Claude Code或任何MCP客户端通过语义搜索来搜索本地文档——无需向外部服务发送任何内容。

快速开始

将MCP服务器添加到您的AI编码工具中。选择下面的工具：

对于Cursor - 添加到~/.cursor/mcp.json：

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

对于Codex - 添加到~/.codex/config.toml：

[mcp_servers.local-rag]
command = "npx"
args = ["-y", "mcp-local-rag"]

[mcp_servers.local-rag.env]
BASE_DIR = "/path/to/your/documents"

对于Claude Code - 运行以下命令：

claude mcp add local-rag --scope user --env BASE_DIR=/path/to/your/documents -- npx -y mcp-local-rag

重新启动您的工具，然后开始使用：

"Ingest api-spec.pdf"
"What does this document say about authentication?"

就是这样。无需安装，无需Docker，无需复杂的设置。

为什么存在这个项目

您希望使用AI来搜索文档。这些文档可能是技术规范、研究论文、内部文档或会议记录。问题在于：大多数解决方案要求将文件发送到外部API。

这会产生三个问题：

隐私问题。 您的文档可能包含敏感信息——客户数据、专有研究、个人笔记。将它们发送给第三方服务意味着信任他们处理这些数据。

成本问题。 外部嵌入式API按使用收费。对于大量文档集或频繁搜索，成本会迅速累积。

网络依赖性。 如果您离线或连接有限，就无法搜索自己的文档。

此项目通过在本地运行一切解决了这些问题。文档永远不会离开您的机器。嵌入式模型只需下载一次，之后即可离线工作。并且可以免费使用。

您将获得什么

该服务器通过MCP提供了五个工具：

文档摄入 处理PDF、DOCX、TXT和Markdown文件。指向一个文件，它会提取文本，将其分割成可搜索的块，使用本地模型生成嵌入，并将所有内容存储在本地向量数据库中。如果您再次摄入相同的文件，它会替换旧版本——不会重复数据。

语义搜索 允许您用自然语言查询。它理解意义，而不是关键词匹配。询问“身份验证是如何工作的”时，即使使用了不同的词如“登录流程”或“凭证验证”，它也能找到相关部分。

文件管理 显示您已摄入的内容及其时间。您可以查看每个文件产生的块数，并验证所有内容是否正确索引。

文件删除 从向量数据库中移除已摄入的文档。当您删除一个文件时，其所有块和嵌入都会永久删除。这对于删除过时文档或不再需要索引的敏感数据很有用。

系统状态 报告您的数据库——文档数量、总块数、内存使用情况。有助于监控性能或调试问题。

这一切都使用：

LanceDB 用于向量存储（基于文件，不需要服务器）
Transformers.js 用于嵌入（在Node.js中运行，无需Python）
all-MiniLM-L6-v2 模型（384维，速度和准确性之间的良好平衡）
RecursiveCharacterTextSplitter 用于智能文本分块

结果是：在标准笔记本电脑上，查询响应通常在3秒内完成，即使有数千个文档块被索引。

首次运行

服务器立即启动，但嵌入式模型在首次使用时下载（首次摄入或搜索时）：

下载大小：约90MB（模型文件）
缓存后磁盘使用：约120MB（包括ONNX运行时缓存）
时间：在良好的连接下大约1-2分钟
首次操作延迟：您的初始摄入或搜索请求将等待模型下载完成

您将在控制台看到类似“初始化模型（下载约90MB，可能需要1-2分钟）...”的消息。模型缓存于CACHE_DIR（默认：./models/）以便离线使用。

为什么懒加载？ 这种方法允许服务器在不预先加载模型的情况下立即启动。只有在实际需要时才下载，使得服务器对快速状态检查或文件管理操作更响应。

离线模式：首次下载后，完全离线工作——无需互联网。

安全性

路径限制：此服务器仅访问BASE_DIR内的文件。任何尝试访问该目录之外的文件（例如，通过../路径遍历）都将被拒绝。

本地处理：所有处理都在您的机器上进行。初始模型下载后，没有网络请求。

模型验证：嵌入式模型从HuggingFace官方仓库（Xenova/all-MiniLM-L6-v2）下载。通过检查官方模型卡片来验证完整性。

配置

服务器开箱即用，具有合理的默认值，但您可以通过环境变量自定义它。

对于Codex

添加到~/.codex/config.toml：

[mcp_servers.local-rag]
command = "npx"
args = ["-y", "mcp-local-rag"]

[mcp_servers.local-rag.env]
BASE_DIR = "/path/to/your/documents"
DB_PATH = "./lancedb"
CACHE_DIR = "./models"

注意：部分名称必须是mcp_servers（带下划线）。使用m-或mcpservers会导致Codex忽略配置。

对于Cursor

添加到您的Cursor设置中：

全局（所有项目）：~/.cursor/mcp.json
特定项目：项目根目录中的.cursor/mcp.json

{
  "mcpServers": {
    "local-rag": {
      "command": "npx",
      "args": ["-y", "mcp-local-rag"],
      "env": {
        "BASE_DIR": "/path/to/your/documents",
        "DB_PATH": "./lancedb",
        "CACHE_DIR": "./models"
      }
    }
  }
}

对于Claude Code

在项目目录中运行以启用该项目：

cd /path/to/your/project
claude mcp add local-rag --env BASE_DIR=/path/to/your/documents -- npx -y mcp-local-rag

或者为所有项目全局添加：

claude mcp add local-rag --scope user --env BASE_DIR=/path/to/your/documents -- npx -y mcp-local-rag

带有额外环境变量：

claude mcp add local-rag --scope user \
  --env BASE_DIR=/path/to/your/documents \
  --env DB_PATH=./lancedb \
  --env CACHE_DIR=./models \
  -- npx -y mcp-local-rag

环境变量

变量	默认值	描述	合法范围
`BASE_DIR`	当前目录	文档根目录。服务器仅访问此路径内的文件（防止意外访问系统文件）。	任何有效路径
`DB_PATH`	`./lancedb/`	向量数据库存储位置。随着文档增多，可能会变得很大。	任何有效路径
`CACHE_DIR`	`./models/`	模型缓存目录。首次下载后，模型将保留在这里供离线使用。	任何有效路径
`MODEL_NAME`	`Xenova/all-MiniLM-L6-v2`	HuggingFace模型标识符。必须与Transformers.js兼容。参见可用模型。注意：更改模型需要重新摄入所有文档，因为不同模型的嵌入是不兼容的。	HF模型ID
`MAX_FILE_SIZE`	`104857600`（100MB）	文件的最大大小（字节）。更大的文件会被拒绝以防止内存问题。	1MB - 500MB
`CHUNK_SIZE`	`512`	每个块的字符数。越大表示更多上下文但处理速度较慢。	128 - 2048
`CHUNK_OVERLAP`	`100`	块之间的重叠。保留跨边界上下文。	0 - (CHUNK_SIZE/2)

使用

配置后，重启您的MCP客户端：

Cursor：完全退出并重新启动（Mac上的Cmd+Q，不仅仅是关闭窗口）
Codex：重启IDE/扩展
Claude Code：无需重启——更改立即生效

服务器将作为您的AI助手可以使用的工具出现。

摄入文档

在Cursor中，Composer Agent会在需要时自动使用MCP工具：

"Ingest the document at /Users/me/docs/api-spec.pdf"

在Codex CLI中，助手会在需要时自动使用配置的MCP工具：

codex "Ingest the document at /Users/me/docs/api-spec.pdf into the RAG system"

在Claude Code中，只需自然地询问：

"Ingest the document at /Users/me/docs/api-spec.pdf"

路径要求：服务器需要文件的绝对路径。您的AI助手通常会自动将自然语言请求转换为绝对路径。BASE_DIR设置限制了对那个目录树内文件的访问以保证安全，但您仍需提供完整路径。

服务器：

验证文件存在且小于100MB
提取文本（处理PDF/DOCX/TXT/MD格式）
分割成块（512字符，100字符重叠）
为每个块生成嵌入
存储在向量数据库中

这在标准笔记本电脑上每MB大约需要5-10秒。完成后，您会看到确认消息，包括创建了多少块。

搜索文档

用自然语言提问：

"What does the API documentation say about authentication?"
"Find information about rate limiting"
"Search for error handling best practices"

服务器：

将您的查询转换为嵌入向量
在向量数据库中搜索相似的块
返回前5个匹配项及其相似度分数

结果包括文本内容、来自哪个文件以及相关性评分。您的AI助手将使用这些结果回答您的问题。

您可以请求更多的结果：

"Search for database optimization tips, return 10 results"

限制参数接受1-20个结果。

管理文件

查看已索引的内容：

"List all ingested files"

这显示每个文件的路径、产生的块数及摄入时间。

从数据库中删除文件：

"Delete /Users/me/docs/old-spec.pdf from the RAG system"

这将永久删除该文件及其所有块。此操作幂等——删除不存在的文件不会报错。

检查系统状态：

"Show the RAG server status"

这报告总文档数、总块数、当前内存使用情况及运行时间。

再次摄入文件

如果更新了一个文档，请再次摄入：

"Re-ingest api-spec.pdf with the latest changes"

服务器会自动删除旧块后再添加新块。没有重复，没有过时的数据。

开发

从源代码构建

git clone https://github.com/shinpr/mcp-local-rag.git
cd mcp-local-rag
npm install

运行测试

# 运行所有测试
npm test

# 运行带有覆盖率的测试
npm run test:coverage

# 开发模式下的监视模式
npm run test:watch

测试套件包括：

每个组件的单元测试
完整摄入和搜索流程的集成测试
路径遍历保护的安全测试
验证查询速度目标的性能测试

代码质量

# 类型检查
npm run type-check

# 格式化和检查
npm run check:fix

# 检查循环依赖
npm run check:deps

# 全面的质量检查（运行所有）
npm run check:all

项目结构

src/
  index.ts          # 入口点，启动MCP服务器
  server/           # RAGServer类，MCP工具处理器
  parser/           # 文档解析（PDF、DOCX、TXT、MD）
  chunker/          # 文本分割逻辑
  embedder/         # 使用Transformers.js生成嵌入
  vectordb/         # LanceDB操作
  __tests__/        # 测试套件

每个模块都有清晰的界限：

Parser 验证文件路径并提取文本
Chunker 将文本分割成重叠段
Embedder 生成384维向量
VectorStore 处理所有数据库操作
RAGServer 协调一切并暴露MCP工具

性能

测试环境：MacBook Pro M1（16GB RAM），使用v0.1.3在Node.js 22（2025年1月）上测试

查询性能：

平均：10,000个索引块（5个结果）1.2秒
目标：p90 < 3秒 ✓

摄入速度（10MB PDF）：

总计：约45秒
- PDF解析：约8秒（17%）
- 文本分块：约2秒（4%）
- 嵌入生成：约30秒（67%）
- 数据库插入：约5秒（11%）

内存使用：

基线：空闲时约200MB
峰值：摄入50MB文件时约800MB
目标：<1GB ✓

并发查询：处理5个并行查询而无降级。LanceDB的异步API允许非阻塞操作。

注意：您的结果会因硬件而异，特别是CPU速度（嵌入在CPU上运行，而非GPU）。

故障排除

“未找到结果”搜索时

原因：必须先摄入文档才能搜索。

解决办法：

首先摄入文档："Ingest /path/to/document.pdf"
验证摄入："List all ingested files"
然后搜索："Search for [您的查询]"

常见错误：配置后立即尝试搜索而未摄入任何文档。

“模型下载失败”

嵌入式模型在首次使用时从HuggingFace下载（首次摄入或搜索时）。如果您在代理或防火墙后面，可能需要配置网络设置。

何时发生：您的首次摄入或搜索操作将触发下载。如果失败，您将看到详细的错误消息和故障排除指南（网络问题、磁盘空间、缓存损坏）。

如何解决：错误消息提供具体建议。常见解决方案：

检查您的互联网连接并重试操作
确保有足够的磁盘空间（约120MB）
如果问题持续，删除缓存目录并重试

或者手动下载模型：

访问 https://huggingface.co/Xenova/all-MiniLM-L6-v2
下载模型文件
设置CACHE_DIR为您保存的位置

“文件太大”错误

默认限制为100MB。对于更大文件：

将其拆分为较小文档
或增加配置中的MAX_FILE_SIZE（注意内存使用）

查询性能缓慢

如果查询耗时超过预期：

检查已索引的块数（status命令）
考虑硬件（嵌入是CPU密集型）
尝试减少CHUNK_SIZE以创建较少的块

“路径超出BASE_DIR”错误

服务器为了安全限制文件访问至BASE_DIR。确保您的文件路径位于该目录内。检查：

您的MCP配置中的BASE_DIR设置是否正确
相对路径与绝对路径
文件路径中的拼写错误

MCP客户端看不到工具

对于Cursor：

打开设置 → 功能 → 模型上下文协议
验证服务器配置已保存
完全重启Cursor
检查状态栏中的MCP连接状态

对于Codex CLI：

检查~/.codex/config.toml以验证配置
确保部分名称是[mcp_servers.local-rag]（带下划线）
直接测试服务器：npx mcp-local-rag应无错误运行
重启Codex CLI或IDE扩展
Codex启动时检查错误消息

对于Claude Code：

运行claude mcp list以查看配置的服务器
验证服务器出现在列表中
检查~/.config/claude/mcp_config.json是否有语法错误
直接测试服务器：npx mcp-local-rag应无错误运行

常见问题：

配置文件中的无效JSON语法
BASE_DIR设置中的错误文件路径
未找到服务器二进制文件（尝试全局安装：npm install -g mcp-local-rag）
防火墙阻止本地通信

工作原理

当您摄入文档时，解析器根据文件类型提取文本。PDF使用pdf-parse，DOCX使用`