PDF搜索MCP服务器
封装CrewAI的轻量级模型上下文协议（MCP）服务器和CLI工具 PDFSearchTool 因此，您可以使用自己的嵌入/Qdrant堆栈对PDF进行索引和语义搜索。
组件
- MCP服务器 (
pdfsearch.mcp_pdfsearch)：暴露asearch_pdf该工具验证输入的PDF，确保配置的Qdrant集合存在，并运行CrewAI搜索。 - CLI线束 (
scripts/test_pdfsearch_tool.py)：面向开发人员的脚本，可以对PDF进行指纹识别，记录缓存元数据，跳过缓存命中的重新摄取，并允许您在没有使用MCP的客户端的情况下运行即席查询。 - 缓存助手 (
src/pdfsearch/cache.py)：计算SHA-256哈希值的共享实用程序，按PDF集合名称导出(pdf_)，将元数据持久化~/.cache/pdf_search_mcp/cache.json，并跟踪PDF是否已被索引（步骤 1–3 缓存卷展栏）。
需求
- Python 3.8+
- 访问CrewAI支持的嵌入服务提供商（推荐VoyageAI）
- 可访问的Qdrant实例（云或自托管）
安装
pip install -e .
cp .env.example .env
# populate .env with your real credentials配置
Config (src/pdfsearch/config.py)读取以下环境变量：
| 变量 | 必填 | 备注 | |
|---|---|---|---|
EMBEDDER_PROVIDER | 必填 | 例如。 voyageai, openai等等。 | |
EMBEDDER_MODEL | 必需 | 特定于提供商的型号ID（例如。 voyage-code-3). | |
EMBEDDER_API_KEY | 有条件的 | 非Voyage提供商需要。 | |
EMBEDDINGS_VOYAGEAI_API_KEY | 有条件的\* | 需要时 EMBEDDER_PROVIDER=voyageai；自动覆盖 EMBEDDER_API_KEY. | |
QDRANT_URL | 必需 | Qdrant服务的HTTPS URL或本地终结点。 | |
QDRANT_API_KEY | 可选 | 托管Qdrant部署需要。 | |
VECTOR_SIZE | 必需 | 嵌入的整数维度。 | |
VECTOR_DISTANCE | 必填 | 其中之一 Cosine, Euclid, Dot等等。（比赛 qdrant_client.models.Distance). | |
LOG_LEVEL | 可选 | 默认为 INFO. |
提示：.env.example枚举服务器期望的每个变量。复制到.env，填写您的值，CLI/MCP服务器将通过以下方式加载它python-dotenv.
运行CLI线束
python scripts/test_pdfsearch_tool.py \
--pdf sample_pdfs/manual.pdf \
--query "explain the architecture" \
--limit 5 \
--similarity-threshold 0.6 \
--format pretty它的作用：
- 负载
.env，验证PDF（扩展名+%PDF-头球 - 计算PDF哈希值并导出Qdrant集合名称(
pdf_). - 在中记录缓存元数据（路径、哈希、集合、摄取标志）
~/.cache/pdf_search_mcp/cache.json. - 初始化
PDFSearchTool使用embeddings+Qdrant配置，并强制适配器使用派生集合。 - 在第一次运行时，将PDF摄取到Qdrant中，并将缓存条目标记为索引；当缓存显示PDF已被索引时，后续运行跳过摄取并重用现有向量。
- 使用适配器的低级发出相似性搜索
client.search()用于结构化结果的API（包括chunk_index、标准化得分和Qdrantpoint_id).
重置集合：如果需要重新摄取（例如，在删除Qdrant集合后），请从中删除哈希条目~/.cache/pdf_search_mcp/cache.json或切换其"indexed"旗帜到false在重新运行CLI之前。
运行MCP服务器
pdf-search-mcp
# or
python -m pdfsearch.mcp_pdfsearch服务器注册了一个MCP工具：
| 工具 | 描述 | Args |
|---|---|---|
search_pdf | 通过CrewAI验证/摄取PDF并运行语义搜索 | pdf_path （字符串，必填）， query （字符串，必填） |
在内部，服务器引导共享 PDFSearchTool 反对 pdf_search_bootstrap 收集以在启动时验证配置，然后将其重新用于传入的工具调用。
缓存推出
看 docs/caching_rollout_plan.md 对于从简单的指纹识别（已实现）到每个PDF集合、摄取跳过、CLI缓存检查、并发保护，并最终与MCP服务器共享缓存逻辑的分阶段计划。
当前状态：
- Step 1 complete：哈希+JSON缓存助手(
src/pdfsearch/cache.py). - Step 2 完整：确定性集合名称+适配器重定向。
- Step 3 complete：CLI中的缓存感知摄取跳过（除非重置缓存，否则每个PDF集合只填充一次）。
- Step 4 除此之外（CLI缓存检查/清除标志、锁定、MCP重用）仍在路线图上。
开发说明
- 传统的pytest脚手架现在存在
legacy_tests/；它是 不 已连接到活动测试套件，但保留以供参考。看docs/notes/legacy_testing_strategy.md用于原始测试视觉。 docs/notes/gpt_codex_debugging.md捕获CrewAI vectordb配置期望的调试研究。- 默认情况下忽略示例PDF(
sample_pdfs/在.gitignore)；添加您自己的用于本地测试。
故障排除
ValueError: EMBEDDER_PROVIDER environment variable is required–确保.env已加载（CLI使用python-dotenv)并且设置变量。File does not appear to be a valid PDF–验证器检查%PDF-头球如果生成的PDF不正确，请再次导出/下载。- Qdrant收集错误 –配置层调用
client.get_or_create_collection(...).验证VECTOR_SIZE,VECTOR_DISTANCE，以及QDRANT_URL/API key匹配您的部署。 - 多次运行后重复块 –删除Qdrant中的每个PDF集合（例如。，
curl -X DELETE http:///collections/pdf_) *和* 删除或编辑中的匹配条目~/.cache/pdf_search_mcp/cache.json所以"indexed"成为false在重新运行CLI之前。