使用说明

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 <repository-url>
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

服务器将：

立即启动（延迟初始化）
首次查询时加载和索引PDF
准备好通过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
}

响应结构

字段	类型	描述
`query`	string	原始搜索查询
`chunks`	array	相关文档块列表
`chunks[].content`	string	块的文本内容
`chunks[].document_name`	string	源PDF文件名
`chunks[].page_number`	int	页码（如果可用）
`chunks[].metadata`	object	其他元数据
`total_chunks`	int	返回的块数

代理商如何使用它

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

代理发送搜索查询
服务器返回相关文档块
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

此命令将：

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

你会看到什么

检查员提供：

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

检查员工作流程示例

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

检查员提示

第一次查询速度慢：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

配置选项

变量	必填	默认	描述
`PDF_DOCUMENTS_DIR`	没有	`./documents`	包含要索引的PDF文件的目录
`CHROMA_DB_DIR`	没有	`./chroma_db`	ChromaDB矢量存储目录
`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文档建筑。