mcp-local-knowledge 如何让 AI 在本地语义搜索 DOCX、PPTX 和 PDF？

mcp-local-knowledge 是一个通过 Model Context Protocol 向 AI 助手提供本地文档语义搜索的服务。它先用 Docling 把 PDF、DOCX、PPTX、XLSX 等文件转换为结构化 Markdown，再用本地嵌入模型生成向量并写入 LanceDB。Claude Desktop 或其他 MCP 客户端调用搜索工具后，才能基于返回片段组织答案。

先理解它做什么与不做什么

这个项目负责文档扫描、转换、分块、嵌入、向量检索和 MCP 工具暴露，不包含独立的大语言模型问答层。所谓“让 AI 搜索本地文档”，是客户端模型调用 MCP 工具获取证据，而不是该服务自行生成最终答案。

文档处理和向量数据库可以全部留在本机，但 AI 客户端如何处理搜索结果仍取决于客户端及模型服务。若客户端使用云端模型，检索到的片段可能被发送到远端，不能仅凭本地索引就宣称整个问答链路离线。

安装前准备

README 要求 Node.js 23 或更高版本、npm 10 或更高版本，以及 Python 3.10 或更高版本。虽然包清单声明 Node 22 即可，实际部署应采用文档中更严格的 Node 23，以减少运行时差异。

Office 与 PDF 转换依赖单独安装的 Docling：

python -m pip install docling
python -c "import docling; print('Docling ready')"

Docling 与本地嵌入模型首次安装或下载时需要联网，并会占用数百 MB 以上磁盘。生产资料入库前，应先用无敏感样本验证 Python 环境、OCR 后端和模型缓存目录。

安装三个命令入口

全局安装 npm 包后会提供 MCP 服务、入库工具和管理界面三个命令：

npm install -g @teknologika/mcp-local-knowledge
mcp-local-knowledge --help
mcp-knowledge-ingest --help
mcp-knowledge-manager --help

不希望全局安装时也可在项目中安装，再通过 npx 调用。安装脚本会检查 Docling，但 Docling 本身仍由 Python 环境管理。

默认本地数据与模型配置

示例配置把 LanceDB 存在用户目录下的 knowledge-base 数据目录，本地嵌入模型为 Xenova/all-MiniLM-L6-v2，模型缓存也位于本机。管理界面默认 localhost 的 8009 端口，MCP 服务则通过 stdio 与客户端通信。

{
  "embedding": {
    "modelName": "Xenova/all-MiniLM-L6-v2"
  },
  "ingestion": {
    "batchSize": 100,
    "maxFileSize": 52428800
  },
  "search": {
    "defaultMaxResults": 50,
    "cacheTimeoutSeconds": 60
  }
}

默认最大文件大小为 50 MB。入库前应根据内存、磁盘和文档规模调整批量大小，而不是简单放宽文件限制。

建立第一个知识库

把需要检索的文件放入独立目录，再指定知识库名称：

mcp-knowledge-ingest --path ./my-documents --name my-documents

扫描会递归处理子目录，默认遵守 Git 忽略规则并跳过隐藏目录、超限文件和不支持的二进制文件。若确实要包含被忽略的文件，可使用 --no-gitignore，但应先确认不会把密钥、缓存或临时文件误收入索引。

以相同名称重新执行入库会替换旧数据。重要知识库重建前应保留配置和 LanceDB 备份。

DOCX、PPTX 和 PDF 如何转换

Markdown、文本和 HTML 会被直接读取；PDF、Office 文档和音频等二进制格式通过 Docling CLI 转换。转换命令启用 OCR，并同时请求 Markdown 与 JSON 输出。

• DOCX：提取标题、段落、表格和可识别的结构。
• PPTX：保留幻灯片文本、层级与可获得的页面元数据。
• PDF：解析文字版面，并对扫描内容尝试 OCR。
• XLSX：把工作表与表格内容转换为可分块文本。
• 音频：通过 Whisper ASR 路径生成转写文本。

转换器的默认超时为 30 秒。大型 PDF、复杂演示文稿或 OCR 密集文件可能超时，不能把一次失败解释成格式完全不支持。

结构化分块和本地嵌入

转换后的 Markdown 不会只按固定字符粗暴切开。项目会尽量保留段落、章节、表格、标题和层级路径，再由 Transformers 在本机计算嵌入。首次使用时模型需要下载，后续可从本地缓存加载。

LanceDB 为不同知识库保存向量表。搜索结果包含文件路径、文档类型、块类型、页号、标题路径、内容和相似度分数，便于 AI 客户端把结论与来源片段对应起来。

配置 MCP 客户端

以 Claude Desktop 为例，需要在 MCP 客户端配置中注册 stdio 服务：

{
  "mcpServers": {
    "local-knowledge": {
      "command": "mcp-local-knowledge",
      "args": []
    }
  }
}

保存后重启客户端，并确认服务能够列出工具。若客户端找不到全局命令，应使用命令的绝对路径，或在同一运行环境中确认 npm 全局二进制目录。

AI 客户端可以调用哪些工具

工具	作用	关键输入
list_knowledgebases	列出已索引知识库	无
search_knowledgebases	执行语义搜索	查询、库名、类型、结果数
get_knowledgebase_stats	查看文档和分块统计	知识库名称
list_documents	列出库内文档	按实现提供的筛选参数
open_knowledgebase_manager	启动或打开管理页面	无

搜索工具最多允许请求 200 条结果，默认返回 50 条。实际问答通常不应把大量片段全部交给模型，应先缩小知识库和文档类型，再选择最相关证据。

用管理界面检查索引

运行 mcp-knowledge-manager 可打开本地管理页面。它适合查看知识库、搜索结果、格式分布、文档数量和分块数量，也可以观察入库进度。

管理页面是本地运维入口，不等于具备完整身份认证的多用户服务。默认保持 localhost ，不应直接暴露到公网或不受信任局域网。

验证语义搜索质量

1. 精确词测试：搜索文件中独有的项目编号或术语。
2. 语义改写测试：不用原句表达同一问题。
3. 结构测试：检查表格、标题和页面定位是否保留。
4. OCR 测试：用清晰扫描件与低质量扫描件比较。
5. 过滤测试：限定知识库和 documentType，确认结果边界。

相似度分数是经过距离转换得到的排序指标，不是事实正确率。高分结果仍需回到源文件核验，尤其是数字、否定条件和跨页结论。

隐私与安全边界

文档转换、嵌入和 LanceDB 存储均在本地运行，项目自身不依赖云端处理接口。但完整系统还包括 MCP 客户端和它使用的模型。客户端调用搜索后，返回内容是否离开设备由客户端配置决定。

• 将向量库和模型缓存放在受账户权限保护的目录。
• 不要索引包含密钥、访问令牌和无权处理的资料。
• 审查日志是否包含文件路径或检索片段。
• 限制管理界面的地址和端口访问。
• 删除知识库时同时检查 LanceDB、转换临时文件与缓存。

常见问题排查

现象	优先检查
Office 文件无法转换	Python 环境、Docling CLI 和 30 秒超时
MCP 服务无法启动	Node 版本、全局命令路径和 stdio 配置
首次搜索很慢	嵌入模型是否仍在下载或冷加载
找不到被忽略文件	Git 忽略规则、隐藏目录和文件大小
结果相关但答案错误	客户端模型是否正确引用返回片段

mcp-local-knowledge 的关键价值是把多格式文档转换、本地嵌入和向量检索封装为标准 MCP 工具。可靠使用它，需要分别验收 Docling 转换质量、分块结构、语义召回和 AI 客户端的数据边界，不能把“本地搜索”直接等同于“全链路离线且答案可信”。