ff-privaterag 0.3.0

本地私有知识库 MCP 工具：把本地文档导入本地向量库，供 Claude 等 MCP 客户端语义检索，数据不出本机

🧠 ff_PrivateRag – 本地私有知识库 MCP 工具

一个基于 MCP（Model Context Protocol）的本地知识库服务，让 AI 助手（如 Claude Desktop、Cursor）能直接检索你的私人文档和代码库。

---

📌 项目目标

• 私有化：所有数据、模型均运行在本地，无需联网，确保隐私安全。
• 本地检索增强：为 AI 助手提供本地文件（文档、代码）的语义检索能力，提升问答准确性。
• 轻量易用：通过 MCP 协议无缝集成到主流 AI 客户端，操作简单。
• 可追溯：记录文档来源、变更时间，支持审计与版本回溯。

---

🧩 技术选型

组件	选型	说明
编程语言	Python 3.10+	生态成熟，AI/ML 库丰富
MCP 框架	FastMCP	简化 MCP 服务器开发，装饰器风格
向量数据库	ChromaDB	轻量级，持久化，易用
嵌入模型	BAAI/bge-small-zh-v1.5	本地运行，无需 API，面向中文检索，体积小
答案生成	由 MCP 客户端自身 LLM 完成	工具只做本地检索、返回片段；纯本地、隐私不出机
文档解析	按扩展名分发（.txt/.md/.pdf，pdfplumber）	不引入 python-magic，后续可扩展更多格式
版本控制集成	GitPython	读取文件变更历史（用于追溯，Git 非必需）

---

🏗️ 系统架构

graph TD
    A[AI 客户端<br>Claude Desktop / Cursor] -->|MCP协议 stdio| B[ff_PrivateRag MCP Server]
    B --> C[FastMCP 路由]
    C --> D1[工具: ingest_document]
    C --> D2[工具: query_knowledge]
    D1 --> E[文本分块 Chunking]
    E --> F[嵌入模型 Embedding]
    F --> G[ChromaDB 向量存储]
    D2 --> H[向量检索]
    H --> G
    H --> I[返回相关片段]
    I --> J[LLM 生成答案（由客户端调用）]

---

🚀 安装

pip install ff-privaterag

安装后会注册命令行入口 ff-privaterag，用于以 stdio 方式启动 MCP 服务器。

首次执行检索/导入时会自动下载嵌入模型 BAAI/bge-small-zh-v1.5（约 95MB）并缓存到本地，之后离线可用。

🇨🇳 中国大陆网络：huggingface.co 通常无法直连。工具会自动探测并回退到镜像 https://hf-mirror.com，一般无需手动设置。

• 想指定其他端点：export HF_ENDPOINT=https://your-mirror（PowerShell：$env:HF_ENDPOINT="..."）
• 想禁用自动回退：export FF_PRIVATERAG_NO_HF_MIRROR=1

---

🔌 在 Claude Code CLI 中集成

claude mcp add ff-privaterag -- ff-privaterag

注册后重启 / 新开 Claude Code 会话，即可在对话中调用 ingest_document 与 query_knowledge 两个工具。

其他 MCP 客户端（Claude Desktop / Cursor）也兼容，在其配置中把 ff-privaterag 注册为本地 stdio server 即可。

数据目录

向量库默认持久化在全局目录 ~/.ff_privaterag/chroma，与启动目录无关（适配被客户端作为子进程拉起的场景）。如需自定义：

export FF_PRIVATERAG_DATA_DIR=/your/custom/path   # 覆盖默认持久化目录

---

💡 使用示例

在 Claude Code 对话中用自然语言即可，由模型自动调用工具：

导入文档

你：把 D:\docs\需求文档.md 导入知识库
→ 工具 ingest_document(file_path="D:\\docs\\需求文档.md")
← 成功导入文档 '需求文档.md'，共 8 个文本块。

导入整个代码仓库（v0.2 新增）

你：把 D:\Workspace\my-vue-app 这个仓库导入知识库
→ 工具 ingest_directory(dir_path="D:\\Workspace\\my-vue-app")
← 目录 'my-vue-app' 导入完成：新增 187 个、更新 0 个文件，共 1432 个文本块；跳过 23984 个文件（gitignored 23800，unsupported_ext 150，too_large 20，binary 14）。

ingest_directory 会：

• 递归导入目录下所有受支持的文本/代码/配置文件
• 自动剪枝 node_modules、.git、dist、build、__pycache__、.venv 等无关目录
• 跟随仓库 .gitignore 跳过被忽略的文件
• 跳过超大文件（默认 >1MB，可经 FF_PRIVATERAG_MAX_FILE_BYTES 调整）与二进制文件
• 每个文件沿用幂等逻辑：内容未变跳过、变更覆盖

支持的扩展名：文档(.txt/.md/.pdf)、前端(.js/.ts/.jsx/.tsx/.vue/.css/.scss/.less/.html)、Python(.py/.pyi)、后端(.java/.go/.rs/.cpp/.c/.h/.cs/.kt/.rb/.php)、配置(.json/.yaml/.yml/.toml/.xml/.ini)。

⚡ 性能（v0.3）：目录导入采用跨文件批量嵌入，纯 CPU 下比逐文件快约 3 倍。

• 嵌入批大小可调：export FF_PRIVATERAG_EMBED_BATCH_SIZE=64（默认 64，内存紧张可调小）
• 导入大仓库较慢属正常（无 GPU 时模型在 CPU 上算向量）；过程中的进度与规模预估会输出到 stderr 日志（Claude Code 的 MCP 日志面板可见），如「待导入 N 文件、约 M 块」「已嵌入 X/Y 块」
• 仓库很大时建议先导核心子目录（如 src/）而非一次性导整个仓库

检索知识

你：知识库里关于"系统模块划分"是怎么说的？
→ 工具 query_knowledge(query="系统模块划分", n_results=3)
← 找到 3 条相关信息：
   --- 结果 1 (来自: D:\docs\需求文档.md, 作者: zhangsan, 修改: 2026-06-20, 相似度: 0.812) ---
   系统分为用户管理、订单管理...

---

🛠️ 本地开发

python -m venv .venv && .venv/Scripts/activate   # Windows
pip install -e .[dev]                            # 可编辑安装 + 测试依赖
pytest                                           # 运行测试
python -m build                                  # 构建分发包到 dist/