内容
<div align="center">
<img src="https://raw.githubusercontent.com/CyprianFusi/MCP-rag-with-Chromadb/main/assets/binati_logo.png" alt="BINATI AI Logo" width="75"/>
# MCP RAG 与 ChromaDB - 多格式文档支持
_By **BINATI AInalytics**_
</div>
一款强大的MCP（模型上下文协议）服务器，提供RAG（检索增强生成）功能，支持多种文档格式。由LangChain、ChromaDB驱动，支持 **OpenAI 或 Ollama 嵌入**。
## 截图
## 嵌入选项
选择您的嵌入提供商：
- **OpenAI** （推荐用于Claude Desktop/MCP）- 可靠、快速、基于云。参见 [OPENAI_SETUP.md](OPENAI_SETUP.md)
- **Ollama** （免费、本地）- 无成本、本地运行，可能存在MCP连接问题
**使用 OpenAI 快速入门：**
1. 从 https://platform.openai.com/api-keys 获取 API 密钥
2. 将 `.env.example` 复制到 `.env`
3. 设置 `OPENAI_API_KEY=sk-your-key-here`
4. 运行 `python server.py`
参见 [OPENAI_SETUP.md](OPENAI_SETUP.md) 获取详细说明。
## 支持的文档格式
- **PDF** (.pdf) - 通过 PyPDF2
- **Microsoft Word** (.docx, .doc) - 通过 python-docx
- **PowerPoint** (.pptx, .ppt) - 通过 python-pptx
- **Excel** (.xlsx, .xls) - 通过 openpyxl
- **OpenDocument Text** (.odt) - 通过 odfpy
- **HTML** (.html, .htm) - 通过 BeautifulSoup4
- **纯文本** (.txt)
- **Markdown** (.md, .markdown)
- **CSV** (.csv)
- **JSON** (.json)
- **XML** (.xml)
- **RTF** (.rtf)
## 功能
- 多格式文档摄入，自动格式检测
- 使用 ChromaDB 进行向量存储，支持持久化存储
- **双嵌入支持：** OpenAI（推荐用于MCP）或 Ollama（免费，本地）
- 并发文档处理，提高性能
- 批量数据库写入，提高效率（OpenAI 每批处理 100 个文档）
- 支持 URL、单个文件和整个目录
- 语义搜索和检索，带有相似性评分
- 当可选依赖项缺失时，提供优雅的回退
- 通过 `.env` 文件进行基于环境的配置
## 安装
1. 克隆或下载此存储库
2. 安装 Python 依赖项：
```bash
pip install -r requirements.txt
```
或
```bash
uv pip install -r requirements.txt
```
3. 选择您的嵌入提供商：
**选项 A：OpenAI（推荐）**
```bash
# 复制环境文件
cp .env.example .env
# 编辑 .env 并添加您的 API 密钥
# 从 https://platform.openai.com/api-keys 获取密钥
OPENAI_API_KEY=sk-your-key-here
```
**选项 B：Ollama（免费，本地）**
```bash
# 从 https://ollama.ai 下载
# 拉取嵌入模型
ollama pull nomic-embed-text
# 编辑 .env
EMBEDDING_PROVIDER=ollama
```
注意：Ollama 在 MCP/Claude Desktop 环境中可能存在连接问题。
## 使用
### 运行服务器
```bash
python server.py
```
### 与 Claude Desktop 集成
要将此 MCP 服务器与 Claude Desktop 一起使用，请在 Claude Desktop 配置文件中添加以下配置：
**适用于 MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**适用于 Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"mcp-rag-chroma": {
"command": "uv",
"args": [
"--directory",
"/path/to/mcp_rag_server",
"run",
"server.py"
]
}
}
}
```
将 `/path/to/mcp_rag_server` 替换为您的实际安装目录路径。
或者，您也可以通过更新 claude desktop 来直接从 Github 集成：
```json
"mcp-rag-chroma": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/CyprianFusi/MCP-rag-with-Chromadb.git",
"server.py"
]
}
```
如果这是您的第一个 MCP 服务器，请使用以下配置：
```json
{
"mcpServers": {
"mcp-rag-chroma": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/CyprianFusi/MCP-rag-with-Chromadb.git",
"server.py"
]
}
}
}
```
### 可用的 MCP 工具
#### 1. `ingest_document`
从各种来源和格式中摄入文档。
**参数：**
- `source` （str）：URL、文件路径或目录路径
**示例：**
- 从 URL 摄入：`ingest_document("https://example.com/document.pdf")`
- 摄入单个文件：`ingest_document("/path/to/document.docx")`
- 摄入整个目录：`ingest_document("/path/to/documents/")`
**支持的来源：**
- HTTP/HTTPS URL（首先下载文件）
- 本地文件路径（任何支持的格式）
- 目录路径（处理所有支持的文件）
#### 2. `retrieve`
根据查询搜索相关的文档块。
**参数：**
- `query` （str）：搜索查询
- `n` （int，可选）：返回结果数量（默认：5，最大：100）
**返回：** 包含文本、元数据和相似性评分的块列表
#### 3. `db_info`
获取数据库及其内容的信息。
**返回：** 数据库统计信息、配置和唯一来源
#### 4. `clear_db`
清除数据库中的所有数据。
**返回：** 状态消息
#### 5. `ingest_pdf` （旧版）
兼容旧版的 PDF 摄入工具。重定向到 `ingest_document`。
## 配置
编辑 `server.py` 和 `.env` 中的配置部分：
**server.py 设置：**
```python
CHROMA_PATH = "chroma_db" # 向量数据库存储路径
CHUNK_SIZE = 4096 # 文本块大小
CHUNK_OVERLAP = 409 # 块之间的重叠
COLLECTION_NAME = "documents" # ChromaDB 集合名称
DOWNLOAD_DIR = "downloads" # 下载文件目录
```
**.env 设置：**
```bash
# 嵌入提供商（openai 或 ollama）
EMBEDDING_PROVIDER=openai
# OpenAI 设置（如果使用 OpenAI）
OPENAI_API_KEY=sk-your-key-here
# Ollama 设置（如果使用 Ollama）
EMBED_MODEL=nomic-embed-text
OLLAMA_BASE_URL=http://localhost:11434
```
## 架构
### 文档处理管道
1. **源检测**: 确定源是 URL、文件还是目录
2. **下载** （如果为 URL）：下载文件到本地存储
3. **格式检测**: 通过扩展名识别文档格式
4. **文本提取**: 为该格式使用适当的提取器
5. **文本分块**: 将文本分成重叠的块
6. **嵌入**: 使用 OpenAI 或 Ollama（可配置）生成向量嵌入
7. **存储**: 在 ChromaDB 中存储块和嵌入
### 提取方法
每种格式都有专用的提取函数：
- `extract_text_from_pdf()` - 从 PDF 页面提取文本
- `extract_text_from_docx()` - 从 Word 文档中提取段落和表格
- `extract_text_from_pptx()` - 从 PowerPoint 幻灯片中提取文本
- `extract_text_from_xlsx()` - 从 Excel 工作表中提取数据
- `extract_text_from_odt()` - 从 OpenDocument 文件中提取文本
- `extract_text_from_html()` - 解析 HTML 并提取干净的文本
- `extract_text_from_markdown()` - 处理 Markdown 文件
- 等等...
主 `extract_text()` 函数根据文件扩展名路由到适当的提取器。
## 依赖项
### 必需
- `langchain-chroma` - ChromaDB 集成
- `langchain-ollama` - Ollama 嵌入
- `langchain-core` - LangChain 核心功能
- `langchain-text-splitters` - 文本分块
- `requests` - HTTP 下载
- `fastmcp` - MCP 服务器框架
### 文档格式支持
- `PyPDF2` - PDF 提取
- `python-docx` - DOCX 提取
- `beautifulsoup4` + `lxml` - HTML/XML 解析
- `python-pptx` - PowerPoint 提取
- `openpyxl` - Excel 提取
- `odfpy` - OpenDocument 格式支持
- `markdown` - Markdown 处理（可选）
## 错误处理
服务器包含全面的错误处理：
- 当可选依赖项缺失时，提供优雅的降级
- 提取失败时记录日志，而不会导致整个过程崩溃
- 为不支持的文件类型提供信息丰富的错误消息
- 为未知格式提供文本提取的备用方案
## 性能优化
- **并发处理**: 使用 ThreadPoolExecutor 并行处理多个文档
- **批量写入**: 所有块一次性写入数据库
- **异步/等待**: 非阻塞 I/O 操作
- **只读模式**: Excel 文件以只读模式打开以提高性能
- **流式下载**: 大文件分块下载
## 限制
- `.doc` （旧版 Word 格式）支持有限 - 需要 `python-docx`，但最好与 `.docx` 配合使用
- `.ppt` （旧版 PowerPoint 格式）支持有限 - 最好与 `.pptx` 配合使用
- `.xls` （旧版 Excel 格式）支持有限 - 最好与 `.xlsx` 配合使用
- RTF 文件使用基本文本提取
- 没有 OCR 的扫描 PDF 将不会提取文本
- 一些复杂的文档布局可能不会保留格式
## 故障排除
### Ollama 连接问题
确保 Ollama 正在运行且可访问：
```bash
curl http://localhost:11434/api/tags
```
### 空文本提取
- 对于 PDF：可能是扫描图像 - 考虑使用 OCR 工具
- 对于其他格式：检查文件是否损坏或受密码保护
## 许可证
该项目是开源的，遵循 [MIT License](https://raw.githubusercontent.com/Dogfalo/materialize/master/LICENSE) 许可。
## 致谢
该项目使用并依赖于多个优秀的开源技术：
**核心框架和基础设施：**
- [FastMCP](https://github.com/jlowin/fastmcp) - MCP 服务器框架
- [LangChain](https://github.com/langchain-ai/langchain) - 核心 LLM 应用框架
- [ChromaDB](https://github.com/chroma-core/chroma) - 用于嵌入存储的向量数据库
**嵌入提供商：**
- [OpenAI](https://platform.openai.com/) - 基于云的嵌入 API（推荐）
- [Ollama](https://ollama.ai/) - 本地嵌入模型
**文档处理：**
- [PyPDF2](https://github.com/py-pdf/pypdf) - PDF 文本提取
- [python-docx](https://github.com/python-openxml/python-docx) - Microsoft Word 处理
- [python-pptx](https://github.com/scanny/python-pptx) - PowerPoint 处理
- [openpyxl](https://openpyxl.readthedocs.io/) - Excel 电子表格处理
- [Beautiful Soup](https://www.crummy.com/software/BeautifulSoup/) - HTML/XML 解析
- [odfpy](https://github.com/eea/odfpy) - OpenDocument 格式支持
特别感谢这些项目的开发者和维护者，使这个 RAG 服务器成为可能。
## 贡献
欢迎贡献！要添加对新格式的支持：
1. 添加遵循 `extract_text_from_[format]()` 模式的提取函数
2. 将格式扩展名添加到 `SUPPORTED_EXTENSIONS`
3. 在 `extract_text()` 函数中添加映射
4. 更新文档
