Pdf Mcpserver

PDF检索MCP服务器

A. 完全免费 模型上下文协议（MCP）服务器，用于使用混合搜索（BM25+矢量搜索）从PDF文档中检索相关块。

🚀 特性

• PDF文档处理：使用Docling自动解析和索引PDF文件
• 混合检索：结合BM25（关键字）和矢量搜索（语义）进行准确检索
• 免费嵌入：使用ChromaDB的默认语句转换器（无API成本！）
• 纯检索模式：返回原始文档块以供代理处理（不生成LLM答案）
• 新的开始：每次启动时清除矢量数据库以进行干净的索引
• MCP集成：暴露 retrieve_pdf_chunks 通过FastMCP实现无缝代理集成的工具

📋 先决条件

• Python 3.11或更高版本
• 要索引的PDF文档
• 不需要API密钥！ ✨

🛠️ 安装

1.克隆存储库（如果尚未完成）

git clone 
cd pdf_mcpserver

2.使用uv安装依赖项

uv sync

这将自动：

• 创建虚拟环境(.venv)
• 从安装所有依赖项 pyproject.toml
• 立项

3.添加PDF文档

创建一个 documents 目录并添加您的PDF文件：

mkdir documents
# Copy your PDF files to the documents/ directory

就是这样！不需要API密钥或其他配置。

🎯 用法

运行服务器

uv run python main.py

或者先激活虚拟环境：

source .venv/bin/activate  # On Windows: .venv\Scripts\activate
python main.py

服务器将：

1. 立即启动（延迟初始化）
2. 首次查询时加载和索引PDF
3. 准备好通过MCP检索文档块

使用 retrieve_pdf_chunks 工具

服务器公开了一个MCP工具： retrieve_pdf_chunks(query: str, max_chunks: int = 5) -> str

示例查询：

retrieve_pdf_chunks("machine learning algorithms", max_chunks=3)

示例响应：

{
  "query": "machine learning algorithms",
  "chunks": [
    {
      "content": "Machine learning algorithms can be categorized into supervised, unsupervised, and reinforcement learning...",
      "document_name": "ml_guide.pdf",
      "page_number": 12,
      "metadata": {"source": "ml_guide.pdf"}
    },
    {
      "content": "Common supervised learning algorithms include linear regression, decision trees, and neural networks...",
      "document_name": "ml_guide.pdf",
      "page_number": 15,
      "metadata": {"source": "ml_guide.pdf"}
    }
  ],
  "total_chunks": 2
}

响应结构

代理商如何使用它

当代理（如Claude）调用此工具时：

1. 代理发送搜索查询
2. 服务器返回相关文档块
3. Agent在其上下文中使用块来回答问题

代理流示例：

User: "What are the main ML algorithms discussed?"
  ↓
Agent calls: retrieve_pdf_chunks("machine learning algorithms")
  ↓
Server returns: 3 relevant chunks from PDFs
  ↓
Agent reads chunks and generates answer for user

🔍 MCP检验员测试

MCP Inspector是一个基于网络的工具，用于交互式测试和调试MCP服务器。

运行检查器

npx @modelcontextprotocol/inspector uv run python main.py

此命令将：

1. 启动MCP Inspector代理服务器
2. 启动PDF检索服务器
3. 使用Inspector UI打开web浏览器

你会看到什么

检查员提供：

• 工具发现：查看可用工具(retrieve_pdf_chunks)
• 交互式测试：使用自定义参数测试查询
• 实时响应：实时查看JSON响应
• 请求/响应日志：调试MCP协议通信

检查员工作流程示例

1. 打开检查器 -浏览器在以下位置自动打开 http://localhost:6274
2. 等待初始化 -服务器在第一次查询时加载并索引PDF（约1-2分钟）
3. 选择工具 -点击 retrieve_pdf_chunks 在工具列表中
4. 输入查询 -键入您的搜索查询（例如，“机器学习”）
5. 设置参数 -可选择调整 max_chunks （默认值：5）
6. 执行 -点击“运行”查看结果
7. 查看响应 -检查返回的块和元数据

检查员提示

• 第一次查询速度慢：PDF索引发生在第一次查询时（典型PDF为87秒）
• 后续查询速度很快：嵌入内容缓存在ChromaDB中
• 全新的开始：服务器每次重新启动时都会清除ChromaDB以进行干净的索引
• 检查日志：终端显示索引过程的详细日志记录

🏗️ 建筑

pdf_mcpserver/
├── src/
│   ├── config.py              # Configuration management
│   ├── constants.py           # Configuration constants
│   ├── models.py              # Pydantic response models
│   ├── pdf_processor.py       # PDF loading and hybrid retrieval
│   └── retrieval_handler.py   # Document chunk retrieval
├── main.py                    # MCP server entry point
├── pyproject.toml             # Project metadata
└── .env                       # Environment configuration

关键组件

• PDF处理器：Singleton类，用于加载PDF，使用Docling转换为Markdown，并构建混合检索器（BM25+矢量搜索）
• 检索处理程序：检索查询的相关块-无LLM答案##🔧 配置

配置是通过环境变量进行管理的。创建一个 .env 项目根目录中的文件：

# Optional: PDF Documents Directory (defaults to ./documents)
PDF_DOCUMENTS_DIR=./documents

# Optional: ChromaDB Directory (defaults to ./chroma_db)
CHROMA_DB_DIR=./chroma_db

# Optional: Log Level (defaults to INFO)
LOG_LEVEL=INFO

配置选项

备注：不需要API密钥！ChromaDB使用免费的本地嵌入（句子转换器）。

🧪 测试

运行单元测试：

uv run pytest tests/

📝 故障排除

未找到PDF文件

错误: No PDF files found in ./documents

解决方案：将PDF文件添加到 documents/ 目录或更新 PDF_DOCUMENTS_DIR 在 .env

导入错误

错误: ModuleNotFoundError: No module named 'docling'

解决方案：确保安装了所有依赖项： uv sync

CUDA内存不足

错误: CUDA out of memory

解决方案：服务器配置为仅使用CPU模式。如果您仍然看到此错误，请检查 CUDA_VISIBLE_DEVICES="" 已设置 src/pdf_processor.py

📚 依赖项

• fastmcp：MCP服务器框架
• 文档：文档处理和解析
• 向量数据库：嵌入自由句子变换器的矢量数据库
• 语言链：RAG框架和检索器
• 卢古鲁：日志记录

无需付费API！ 所有嵌入都是使用ChromaDB的默认模型（全MiniLM-L6-v2）在本地生成的。

🤝 贡献

这是一个概念验证（PoC）实现。对于生产使用，请考虑：

• 为已处理的文档添加缓存
• 通过事实验证实现多代理工作流
• 支持其他文档格式（DOCX、TXT等）
• 添加身份验证和速率限制

📄 许可证

\[您的许可证在这里\]

🙏 致谢

基于 docchat文档 建筑。