Metadata-Version: 2.4
Name: ff-privaterag
Version: 0.1.0
Summary: 本地私有知识库 MCP 工具：把本地文档导入本地向量库，供 Claude 等 MCP 客户端语义检索，数据不出本机
Project-URL: Homepage, https://gitee.com/fanmengfei/ff_PrivateRag
Project-URL: Repository, https://gitee.com/fanmengfei/ff_PrivateRag.git
Project-URL: Issues, https://gitee.com/fanmengfei/ff_PrivateRag/issues
Author: fanmf
License-Expression: MIT
License-File: LICENSE
Keywords: chromadb,claude,embeddings,knowledge-base,mcp,private,rag,vector-search,本地知识库,语义检索
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: >=3.10
Requires-Dist: chromadb
Requires-Dist: fastmcp
Requires-Dist: gitpython
Requires-Dist: pdfplumber
Requires-Dist: sentence-transformers
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# 🧠 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 非必需） |

---

## 🏗️ 系统架构

```mermaid
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 生成答案（由客户端调用）]
```

---

## 🚀 安装

```bash
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 中集成

```bash
claude mcp add ff-privaterag -- ff-privaterag
```

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

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

### 数据目录

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

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

---

## 💡 使用示例

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

**导入文档**

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

**检索知识**

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

---

## 🛠️ 本地开发

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