项目简介

PDF工具箱是一个基于Model Context Protocol (MCP) 的服务器，旨在让大型语言模型（LLM）客户端能够安全、高效地访问和处理本地PDF文件。它将复杂的PDF操作封装成易于调用的工具，支持文本提取、语义搜索、文档分块以及运行时配置调整。

主要功能点

读取PDF: 提取PDF文件中的有序文本，并支持指定页面范围和最大页面数，方便LLM客户端快速预览文档内容。
语义搜索PDF: 对PDF文件内容进行语义相似性搜索，利用缓存的嵌入向量快速查找与查询内容最相关的部分，支持LLM客户端自定义搜索结果数量和最小相似度阈值。
描述PDF分块: 将PDF内容确定性地分块，生成包含偏移量和元数据的文本块列表，适用于LLM的RAG（检索增强生成）流程；也支持检测并返回页面中的结构化表格数据（包括边界框、表头和单元格）。
配置PDF默认值: 动态调整PDF处理的默认参数，例如文本块大小、重叠量、最大读取页面数以及LLM工具使用的默认嵌入模型。
安全与性能: 严格的文件路径验证，限制在沙盒基础路径内操作，并采用积极的缓存策略提高处理速度。

安装步骤

推荐使用 'uv' 工具进行安装和运行。

确保您的系统已安装 'uv'（一个快速的Python包管理器）。如果未安装，请参考 'uv' 官方文档进行安装。

直接运行MCP服务器: 在命令行中执行以下命令，即可从GitHub仓库直接启动PDF工具箱MCP服务器，无需本地安装。

uvx --from git+https://github.com/patriciomartinns/pdf-toolbox -- pdf-toolbox --quiet

（可选）安装并使用独立的CLI工具 'pdf-reader': 如果您希望在命令行中直接使用PDF工具箱的功能，可以安装其独立的CLI工具：
```
uv tool install --from git+https://github.com/patriciomartinns/pdf-toolbox pdf-reader
pdf-reader --help
```
重要提示: 如果您之前安装过旧版 'mcp-pdf-reader' CLI，请先运行 'uv tool uninstall mcp-pdf-reader' 命令卸载旧版本，以避免冲突。

服务器配置

MCP客户端（如Cursor, VS Code, Claude等）需要以下JSON格式的配置信息来连接并使用PDF工具箱MCP服务器。请将此配置添加到您的LLM客户端的MCP服务器设置中，以便LLM能够发现并调用这些工具。

{
  "server_name": "PDF Toolbox",
  "command": "uvx",
  "args": [
    "--from",
    "git+https://github.com/patriciomartinns/pdf-toolbox",
    "--",
    "pdf-toolbox",
    "--quiet"
  ],
  "description": "本地PDF文件处理服务器，为LLM智能体提供文本提取、语义搜索、内容分块和配置管理等功能。",
  "tools": [
    {
      "name": "read_pdf",
      "description": "从PDF文件的指定页面范围提取纯文本。  \n**参数:**  \n- 'path': 必填，字符串，PDF文件路径。  \n- 'start_page': 可选，整数，起始页码（1-based），默认为1。  \n- 'end_page': 可选，整数，结束页码（包含），默认为文档末尾或配置的限制。  \n- 'max_pages': 可选，整数，本次调用最大读取页面数，会覆盖默认配置。"
    },
    {
      "name": "search_pdf",
      "description": "对嵌入的PDF文本块进行语义搜索，返回与查询最相关的匹配项。  \n**参数:**  \n- 'path': 必填，字符串，要搜索的PDF文件路径。  \n- 'query': 必填，字符串，用于语义相似度搜索的文本。  \n- 'top_k': 可选，整数，返回的最大结果数，默认为5。  \n- 'min_score': 可选，浮点数，保留结果的最小余弦相似度分数，默认为0.25。  \n- 'chunk_size': 可选，整数，本次运行的分块大小覆盖值。  \n- 'chunk_overlap': 可选，整数，本次运行的分块重叠量覆盖值。"
    },
    {
      "name": "describe_pdf_sections",
      "description": "生成带有偏移量和元数据的PDF内容分块列表，或以表格模式返回检测到的结构化表格数据。  \n**参数:**  \n- 'path': 必填，字符串，PDF文件路径。  \n- 'max_chunks': 可选，整数，描述的最大分块数量，默认为20。  \n- 'chunk_size': 可选，整数，本次调用分块大小覆盖值。  \n- 'chunk_overlap': 可选，整数，本次调用分块重叠量覆盖值。  \n- 'mode': 可选，字符串，输出模式，'chunks'（默认）用于文本分块，'tables'用于表格检测。"
    },
    {
      "name": "configure_pdf_defaults",
      "description": "更新PDF处理工具的运行时默认参数，后续调用将继承这些新设置。  \n**参数:**  \n- 'chunk_size': 可选，整数，新的默认分块大小（最小100）。  \n- 'chunk_overlap': 可选，整数，新的默认分块重叠量（0到分块大小的一半）。  \n- 'max_pages': 可选，整数，新的默认每次读取的最大页面数。  \n- 'embedding_model': 可选，字符串，新的默认SentenceTransformer嵌入模型名称。"
    }
  ]
}

基本使用方法

（以下是PDF工具箱的CLI命令示例，旨在帮助您理解其功能。MCP客户端将以JSON-RPC请求的形式在后台调用这些功能，您通常无需手动输入这些命令。）

读取PDF文件内容:

pdf-reader read-pdf reports/Q1.pdf --start-page 3 --end-page 5

此命令将从 'reports/Q1.pdf' 文件的第3页到第5页提取文本内容。

在PDF中进行语义搜索:

pdf-reader search-pdf reports/Q1.pdf "rate limiting" --top-k 8

此命令将在 'reports/Q1.pdf' 中搜索与"rate limiting"语义相似的文本块，并返回最多8个结果。

获取PDF分块或表格结构:

pdf-reader describe-pdf-sections reports/Q1.pdf --max-chunks 5
pdf-reader describe-pdf-sections reports/Q1.pdf --mode tables

第一个命令返回 'reports/Q1.pdf' 的前5个文本分块。第二个命令则返回该PDF中检测到的所有表格结构数据。

配置默认参数:

pdf-reader configure-pdf-defaults --chunk-size 600 --chunk-overlap 120 --max-pages 10

此命令将设置PDF处理的默认文本块大小为600，分块重叠量为120，以及每次读取PDF的最大页面数为10。

关键词

项目简介

主要功能点

安装步骤

服务器配置

基本使用方法

信息