Pdf Vectordb MCP

PDF矢量数据库MCP服务器

一种模型上下文协议（MCP）服务器，为PDF文档提供RAG（检索增强生成）功能。该服务器自动索引PDF文件，使用句子转换器（全mpnet-base-v2）生成嵌入，将其存储在ChromaDB中，并为LLM提供语义搜索工具以查询文档。 不需要API密钥-一切都在本地运行！

特性

• 自动PDF索引：监视文件夹并自动为新的/修改的PDF建立索引
• 语义搜索：使用自然语言查询文档
• 来源引用：返回包含文档名称和页码的结果
• 多种MCP工具：查询、列出和管理索引文档
• ChromaDB矢量存储：具有持久性的高效本地矢量数据库
• 本地嵌入：使用语句转换器（all-mpnet-base-v2）-不需要API密钥！
• 100%隐私：所有内容都在您的机器上运行，不依赖于云
• 完全免费：无API成本，无订阅
• 离线功能：初始设置后无需互联网即可工作
• 文件监视：实时监控和重新索引PDF更改
• 智能分块：智能文本分割与重叠，以获得更好的上下文

为什么选择此服务器？

✅ 不需要API密钥 -立即开始使用 ✅ 100%本地和私人 -您的数据永远不会离开您的机器 ✅ 零成本 -完全自由运行 ✅ 高质量 -全mpnet-base-v2可生成出色的768维嵌入 ✅ 离线优先 -模型下载后无需互联网即可使用（一次性约420MB）

建筑

pdf-vectordb-mcp/
├── src/
│   ├── config.py              # Configuration management
│   ├── pdf_processor.py       # PDF extraction and chunking
│   ├── embeddings.py          # OpenAI embedding generation
│   ├── vector_store.py        # ChromaDB operations
│   ├── file_watcher.py        # File system monitoring
│   ├── mcp_server.py          # MCP server implementation
│   └── utils.py               # Helper functions
├── data/
│   ├── pdfs/                  # Place your PDF files here
│   └── chroma_db/             # ChromaDB persistence
├── requirements.txt
├── .env                       # Your configuration
└── README.md

安装

先决条件

• Python 3.10或更高版本
• OpenAI API密钥

设置步骤

1. 克隆或下载此存储库

1. 创建虚拟环境

python -m venv venv

# On Windows
venv\Scripts\activate

# On macOS/Linux
source venv/bin/activate

1. 安装依赖项

pip install -r requirements.txt

1. 配置环境变量

复制 .env.example 到 .env 并填写您的设置：

cp .env.example .env

编辑 .env 根据您的配置：

OPENAI_API_KEY=sk-your-openai-api-key-here
PDF_FOLDER=./data/pdfs
CHROMA_DB_PATH=./data/chroma_db
EMBEDDING_MODEL=text-embedding-3-small
CHUNK_SIZE=800
CHUNK_OVERLAP=200
DEFAULT_TOP_K=5
LOG_LEVEL=INFO

1. 添加您的PDF文件

将PDF文件放入 data/pdfs/ 文件夹。服务器启动时，它们将被自动索引。

用法

运行MCP服务器

python -m src.mcp_server

服务器将：

1. 验证您的配置
2. 索引中的任何现有PDF data/pdfs/ 文件夹
3. 开始监视文件夹的更改
4. 启动MCP服务器，准备接受工具调用

连接到克劳德桌面

将此配置添加到您的Claude Desktop配置文件中：

在Windows上: %APPDATA%\Claude\claude_desktop_config.json 在 macOS 上: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "pdf-vectordb": {
      "command": "python",
      "args": [
        "-m",
        "src.mcp_server"
      ],
      "cwd": "C:\\Users\\arif\\PycharmProjects\\pdf-vectordb-mcp",
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key-here"
      }
    }
  }
}

更新 cwd 路径以匹配您的项目位置。

MCP工具

1.查询_文档

使用自然语言搜索索引的PDF文档。

参数：

• query （必填）：自然语言搜索查询
• top_k （可选）：要返回的结果数（默认值：5）
• document （可选）：将结果筛选到特定文档

例子：

Query: "What are the key findings about climate change?"

退货：

• 带有源引用的相关文本块
• 页码和文件名
• 相关性得分

2.列表_文档

列出所有带有统计信息的索引PDF文档。

参数： 无

退货：

• 文件名称
• 每份文档的页数
• 每个文档的块数

3.获取文档信息

获取特定文档的详细信息。

参数：

• document （必填）：文件名称

退货：

• 总页数
• 块总数
• 页码列表

4.重新索引_文档

手动触发特定PDF的重新索引。

参数：

• document （必填）：PDF文件的名称

使用案例：

• 手动编辑后强制重新处理
• 从索引错误中恢复

5.get_system_stats

获取整体系统统计数据和配置。

参数： 无

退货：

• 文档和块总数
• 当前配置设置
• 文件监视器状态

配置选项

环境变量

分块策略

该系统使用智能组块，包括：

• 断句：更喜欢在句末打断
• 单词边界回退：回到单词边界
• 重叠：跨块维护上下文
• 元数据保存：跟踪文档名称、页码、块索引

运作原理

1.PDF处理流水线

PDF File → Text Extraction → Smart Chunking → Embedding Generation → Vector Store

1. 文本提取：使用pypdf逐页提取文本
2. 清洁：删除工件并规范空白
3. 分块：将文本分割成重叠的块
4. 嵌入：为每个块生成OpenAI嵌入
5. 存储：将元数据存储在ChromaDB中

2.查询管道

Query → Generate Embedding → Similarity Search → Rank Results → Return with Sources

1. 查询嵌入：将查询转换为向量
2. 相似性搜索：使用余弦相似度查找相似块
3. 排名：按相关性得分排序
4. 消息来源：包括文件和页面信息

3.文件监视

服务器监控PDF文件夹并：

• 关于创建：自动为新PDF建立索引
• 关于修改：重新索引已更改的PDF
• 删除时：从矢量存储中删除
• 防抖：等待文件写入完成

高级用法

自定义嵌入模型

您可以使用不同的OpenAI嵌入模型：

# Smaller, faster, cheaper
EMBEDDING_MODEL=text-embedding-3-small

# Larger, more accurate, more expensive
EMBEDDING_MODEL=text-embedding-3-large

调整块大小

对于不同的文档类型：

# Technical documents with dense information
CHUNK_SIZE=500
CHUNK_OVERLAP=100

# Narrative documents
CHUNK_SIZE=1000
CHUNK_OVERLAP=200

批量重新索引

要重新索引所有文档，请执行以下操作：

1. 停止服务器
2. 删除 data/chroma_db/ 文件夹
3. 重新启动服务器

故障排除

PDF未被索引

• 检查PDF是否在正确的文件夹中(data/pdfs/)
• 确保PDF不受密码保护
• 检查日志中的提取错误
• 验证文件权限

OpenAI API错误

• 验证您的API密钥是否正确
• 检查您的OpenAI帐户是否有可用积分
• 如果处理许多文档，请查看速率限制

ChromaDB问题

• 确保 data/chroma_db/ 目录可写
• 检查磁盘空间
• 尝试删除并重新创建数据库

内存问题

对于大型PDF集合：

• 分批处理
• 增加系统RAM
• 使用较小的块大小

发展

运行测试

pytest tests/

日志记录

日志将写入：

• 控制台输出
• pdf_vectordb_mcp.log 文件

在中调整日志级别 .env:

LOG_LEVEL=DEBUG  # For detailed debugging
LOG_LEVEL=INFO   # Normal operation
LOG_LEVEL=WARNING # Only warnings and errors

性能注意事项

嵌入成本

OpenAI嵌入成本（截至2024年）：

• text-embedding-3-small：每100万代币约0.02美元
• text-embedding-3-large：每100万代币约0.13美元

一个典型的PDF页面（约500字）的嵌入成本不到0.001美元。

处理速度

• PDF提取：每份文档约1-2秒
• 嵌入生成：每批约1-2秒（100个块）
• 矢量存储：每份文档约0.1秒

存储

• ChromaDB：每块约1-2KB
• 一个100页的PDF通常会生成200-400个块（~400-800KB）

局限性

• PDF支持：仅基于文本的PDF（扫描文档无OCR）
• 语言：最适合英语（取决于嵌入模型）
• 文件大小：处理大型PDF（>1000页）可能需要时间
• 并发访问：单服务器架构

未来的增强功能

潜在改进：

• 扫描PDF的OCR支持
• 桌子提取和特殊处理
• 图像/图表说明
• 多模态嵌入
• 混合搜索（矢量+关键字）
• 使用交叉编码器重新排序
• 查询扩展和重写
• 文档摘要工具
• 支持其他文档格式（Word等）

许可证

MIT许可证-您可以根据需要自由使用和修改。

贡献

欢迎投稿！请随时提交问题和拉取请求。

支持

对于问题和疑问：

1. 检查故障排除部分
2. 查看登录 pdf_vectordb_mcp.log
3. 在GitHub上打开一个问题

致谢

• 内置于 主控程序
• 用途 色度数据库 用于矢量存储
• 由...驱动 OpenAI嵌入
• PDF处理 pypdf