内容
# PDF 反编译器 MCP
PDF 反编译器 MCP 是一个本地优先的模型上下文协议服务器，它将 PDF 文档分解为可寻址的文本、表格、图形、注释、元数据、OCR 输出和页面级结构。
与其将 PDF 视为一个大型响应，不如采用两步模型：
1. 一次分解和索引文档。
2. 仅检索当前任务所需的页面、块、表格、图形或渲染区域。
## 为什么项目更名
原始项目声称使 PDF 使用成本大大降低。测试表明，这并不是一个可靠的普遍声明。
结构化的多模态响应可能比基于文本的 PDF 路径更昂贵，因为它可能包括提取的文本、表格、图像、截图、注释、页面结构和备用渲染。虽然额外的上下文可以提高文档的保真度，尤其是在图表、图表、截图、扫描页面和复杂布局方面，但它也可以增加令牌消耗。
新名称描述了服务器的预期功能，而不承诺特定的成本结果：
令牌使用取决于工作负载。它根据所选的检索模式、文档类型、图像的数量和分辨率、返回的文本量、客户端实现、模型和令牌记账方法而有所不同。
## “反编译器”在这里的含义
在这个项目中，**反编译器** 意味着将 PDF 从其面向页面的表示转换为规范的文档模型，该模型公开了诸如以下有用元素：
- 文档元数据和大纲条目
- 页面文本和阅读顺序
- 标题和文本块
- 结构化表格和单元格
- 嵌入式图形和标题
- 页面渲染和裁剪区域
- 链接和注释
- 扫描页面的 OCR 输出
- 页面尺寸、旋转和布局坐标
- 页面和文档元素的稳定 ID
- 提取的图像
该项目并不声称以完美的保真度重建原始源文档、创作应用程序或可编辑布局。
## 设计目标
PDF 反编译器 MCP 围绕以下目标设计：
- **选择性检索：** 仅返回任务所需的证据。
- **多模态访问：** 在文本不足以满足需求时，保留对视觉内容的访问。
- **稳定引用：** 将每个结果可追溯到其文档、页面和源元素。
- **预算感知：** 强制执行可配置的文本、图像、页面、响应字节和估计令牌的限制。
- **本地优先操作：** 默认情况下在本地处理文档，除非明确配置，否则避免外部 AI 或嵌入服务。
- **可重用分解：** 解析文档一次，将结果缓存并在多个问题中重用。
- **客户端独立性：** 支持与 MCP 兼容的客户端，而不将特定模型或供应商作为项目身份的一部分。
- **透明基准：** 使用可复制的配置比较成本、延迟、可靠性和答案质量。
## 当前和计划的功能
下一个主要版本正在分阶段开发。在它们出现在标记版本中且兼容性矩阵将其标记为已验证之前，请勿将计划项视为已发布。
| 功能 | 旧版发布 | 下一个主要版本目标 |
| --- | ---: | ---: |
| 页面文本提取 | 可用 | 保留和模块化 |
| 元数据和大纲提取 | 可用 | 保留稳定的模式 |
| 页眉和页脚过滤 | 可用 | 保留诊断信息 |
| 结构化表格提取 | 可用 | 扩展独立检索 |
| 嵌入式图像提取 | 可用 | 扩展稳定图形 ID |
| 整页视觉备用 | 可用 | 转换为按需渲染 |
| 通过 Tesseract 进行 OCR | 可用 | 扩展超时和页面级诊断 |
| 页面范围提取 | 可用 | 替换为选择性页面和元素检索 |
| 稳定文档句柄 | 不可用 | 计划中 |
| 持久缓存 | 不可用 | 计划中 |
| 文本、平衡和保真模式 | 不可用 | 计划中 |
| 全文检索索引 | 不可用 | 计划中 |
| 可选语义检索 | 不可用 | 计划中 |
| 令牌和响应预算 | 有限 | 计划中 |
| 继续光标 | 不可用 | 计划中 |
| 页面级和元素级引用 | 有限 | 计划中 |
| 客户端功能回退 | 有限 | 计划中 |
| 可复制的基准测试套件 | 部分手动测试 | 计划中 |
## 检索模式
下一个主要版本将把检索模式作为显式参数的预设公开。
### 文本模式
返回文本、标题、元数据、注释和紧凑的表格表示。除非明确请求，否则省略图像和页面渲染。
最适合：重文本报告、论文、书籍、政策和合同。
### 平衡模式
返回相关的文本和表格，然后在视觉证据可能改善答案时包含图形或页面区域。
最适合：混合布局文档、技术手册、财务报告和包含偶尔的图表或截图的文档。
### 保真模式
在明确选定的范围内返回所有支持的元素，例如页面范围或元素 ID 列表。
保真模式不旨在转储无限文档。它仍然受配置的页面、字节、图像和令牌预算的约束。
## 目标 MCP 工具表面
重新设计的服务器围绕小型、可组合的工具而非单一的全能提取响应而设计。
| 工具 | 目的 |
| --- | --- |
| `pdf_open` | 验证、分解、索引或从缓存加载 PDF 并返回文档句柄。 |
| `pdf_document_info` | 返回元数据、大纲、页面分类、元素计数、警告和缓存信息。 |
| `pdf_search` | 在明确的筛选器和预算下搜索文本、标题、OCR、标题、注释和表格单元格。 |
| `pdf_get_pages` | 使用文本、平衡或保真设置检索选定的页面。 |
| `pdf_get_element` | 检索已识别的文本块、表格、图形、注释或区域。 |
| `pdf_render_page` | 仅在需要视觉检查时渲染页面或边界框。 |
| `pdf_close` | 释放活动的文档会话并可选地保留或删除缓存状态。 |
旧版 `extract_pdf_content` 工具可能会在迁移期间暂时保留为已弃用的兼容性包装。其最终可用性将在发布说明中记录。
## 规范文档模型
分解的文档应包含稳定、可序列化的记录，记录内容包括：
- 文档身份、来源、哈希、元数据、大纲和警告
- 页面、尺寸、旋转、提取方法和内容分类
- 文本块、边界框、阅读顺序和标题信息
- 表格、单元格、标题、置信度和可选的渲染预览
- 图形、标题、尺寸、哈希和重复引用
- 注释、链接、作者、内容和坐标
- 将每个结果链接到页面和元素 ID 的引用
查看 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) 以获取目标架构。
## 选择性检索和 RAG
计划的检索层将索引：
- 页面文本
- 文本块和标题
- OCR 输出
- 图形标题
- 注释文本
- 表格标题和单元格
- 元数据和大纲条目
初始实现应使用确定性的本地全文检索。以后可以根据需要添加可选的嵌入以进行语义或混合排名。
语义检索将保持可选。基础服务器应在无需外部嵌入服务或 API 密钥的情况下工作。
## 预算控制
计划的检索请求将支持以下限制：
- 最大估计输出令牌
- 最大响应字节
- 最大页面
- 最大文本块
- 最大表格
- 最大图形
- 最大渲染页面
- 最大图像尺寸
响应应报告已返回的内容、已省略的内容、省略的原因、估计的预算使用情况以及是否可以通过继续光标获取更多结果。
除非配置了客户端或模型特定的标记器，否则标记估计值是近似的。
## 页面和元素引用
每个检索结果都应通过以下方式可追溯到其来源：
- 文档 ID
- 页码
- 元素 ID
- 元素类型
- 适用时边界框
- 源摘录或标签
- 适用时检索分数
生成的摘要应引用底层源元素，而不是成为唯一的证据记录。
## 安装
下一个主要版本的源树和安装过程正在规范化。在发布标记的预发布版本之前，请使用最新的旧版发布版本以获取现有行为，或在新源布局完成后按照开发说明进行操作。
### 开发安装目标
需求：
- Node.js 18 或更高版本
- npm
- 用于 OCR 支持的 Tesseract 5.x
- 用于图像提取和渲染的支持本机 canvas 包
```bash
# 仓库重命名后
git clone https://github.com/noobieisgod/PDF-Decompiler-MCP.git
cd PDF-Decompiler-MCP
npm install
npm run build
```
通过 stdio 运行服务器：
```bash
node dist/server.js --stdio
```
确切的入口点可能会在第一个预发布版本之前更改。标记版本是安装命令的真实来源。
## MCP 客户端配置
开发配置应使用本地 Node.js 入口点：
```json
{
"mcpServers": {
"pdf-decompiler": {
"command": "node",
"args": [
"C:/path/to/PDF-Decompiler-MCP/dist/server.js",
"--stdio"
]
}
}
}
```
在 Windows JSON 路径中使用正斜杠。更改 MCP 客户端配置后，请重启客户端。
将来的 npm 发布配置可能如下所示：
```json
{
"mcpServers": {
"pdf-decompiler": {
"command": "npx",
"args": [
"-y",
"pdf-decompiler-mcp",
"--stdio"
]
}
}
}
```
在软件包发布且发布说明确认命令之前，请勿使用 npm 示例。
## 示例工作流
这些示例描述了预期的重新设计工作流。
### 打开和检查文档
```text
使用 PDF 反编译器 MCP 打开此 PDF 并报告其页数、大纲、表格数量、图形数量、扫描页面数量：PDF_PATH
```
### 基于文本的分析
```text
使用文本模式查找文档的建议。引用相关页面，如果文本不足以提供信息，请不要检索图像。
```
### 表格检索
```text
在此文档中搜索收益表，检索结构化表格，并引用其页面和表格 ID。
```
### 视觉分析
```text
查找讨论系统架构的图形。首先检索标题和相关文本，然后在需要视觉检查时检索图形。
```
### 预算控制的检索
```text
使用最多配置的检索预算回答。使用相关文本和表格，省略装饰图像，并列出任何无法适应证据。
```
## 支持的 PDF 类别
基准测试套件将包括：
- 重文本文档
- 重图像文档
- 扫描文档
- 重表格文档
- 混合内容报告
- 多列论文
- 表单
- 财务报告
- 手册
- 导出为 PDF 的幻灯片
- 具有不常见字体或旋转的文档
- 大型和畸形 PDF
没有 PDF 解析器能够保证正确处理每个文件。 不支持的、畸形的、加密的或异常复杂的 PDF 应产生结构化警告或部分结果，而不是静默失败。
## 安全模型
PDF 处理可以暴露本地文件，下载远程内容，调用 OCR 子进程，消耗大量内存，并解析敌对输入。
重新设计的服务器应提供：
- 可配置的允许文件系统根目录
- 可选拒绝任意绝对路径
- PDF 签名和大小检查
- 下载、重定向和超时限制
- 阻止环回、私有和链路本地远程地址
- OCR 和渲染超时
- 页面、图像、内存和解压限制
- 临时文件清理
- 消毒错误
- 默认情况下无遥测
在共享或联网环境中部署服务器前，请查看 [`SECURITY.md`](SECURITY.md)。
## 隐私
该项目是本地优先的。默认情况下，意图在运行 MCP 服务器的机器上处理 PDF 内容。
远程 URL 需要服务器下载文件。 如果启用了可选的嵌入提供程序，则根据其配置和策略，它们可能会接收提取的文本。 此类集成必须默认禁用并明确记录。
查看 [`docs/PRIVACY.md`](docs/PRIVACY.md)。
## 客户端兼容性
该项目旨在支持多个与 MCP 兼容的客户端，包括编码助手和桌面应用程序。仅在客户端通过文档化的兼容性检查后，才会声称支持。
查看 [`docs/CLIENT-COMPATIBILITY.md`](docs/CLIENT-COMPATIBILITY.md) 以获取验证矩阵。
## 基准测试政策
该项目不会在没有可复制证据的情况下发布广泛的成本或质量声明。
每个比较应标识：
- 客户端和版本
- 模型和确切的模型标识符
- 提供商和 API 路径
- PDF 处理模式
- 视觉和引用设置
- PDF 反编译器 MCP 版本和模式
- 令牌和响应预算
- 图像分辨率
- 缓存状态
- 硬件和操作系统
- 重复次数
基准测试应衡量：
- 工具结果字节和令牌
- 冷启动和热启动延迟
- 提取和检索可靠性
- 峰值内存和缓存使用量
- 文本、表格和视觉答案质量
- 检索精度和召回率
- 引用正确性
查看 [`docs/BENCHMARKING.md`](docs/BENCHMARKING.md)。
## 仓库结构目标
```text
PDF-Decompiler-MCP/
src/
server/
tools/
extraction/
models/
retrieval/
ranking/
caching/
rendering/
ocr/
security/
clients/
utilities/
tests/
unit/
integration/
fixtures/
benchmarks/
docs/
examples/
scripts/
schemas/
.github/
README.md
CONTRIBUTING.md
SECURITY.md
SUPPORT.md
CODE_OF_CONDUCT.md
GOVERNANCE.md
CHANGELOG.md
MIGRATION.md
ROADMAP.md
LICENSE
```
## 路线图
重新设计分为三个阶段：
1. 重新品牌，规范存储库，模块化提取，并定义规范文档模型。
2. 添加文档句柄、缓存、选择性检索、检索模式、引用、预算、可靠性控制和安全保护。
3. 验证多个客户端、发布可复制的基准测试、稳定模式并准备第一个稳定版本。
查看 [`ROADMAP.md`](ROADMAP.md) 以获取完成标准。
## 迁移
Claude AI 的 Lightweight PDF MCP 用户在更改存储库 URL、MCP 服务器密钥、软件包名称、入口点或工具调用之前，请阅读 [`MIGRATION.md`](MIGRATION.md)。
## 贡献
在恢复源树并记录开发工作流之前，欢迎贡献。
在打开拉取请求之前：
1. 阅读 [`CONTRIBUTING.md`](CONTRIBUTING.md)。
2. 添加或更新测试。
3. 描述任何架构、令牌、安全或兼容性影响。
4. 避免不受支持的性能声明。
5. 包括可复制的固定程序或 PDF 特定错误的说明。
## 支持和安全
- 一般问题和故障排除： [`SUPPORT.md`](SUPPORT.md)
- 漏洞报告： [`SECURITY.md`](SECURITY.md)
- 社区期望： [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)
- 项目决策： [`GOVERNANCE.md`](GOVERNANCE.md)
## 许可证
PDF 反编译器 MCP 仅在 GNU Affero 通用公共许可证 v3.0 下许可，除非存储库所有者将来在未来提交中明确更改许可证。
保留存储库的精确 `LICENSE` 文件作为合法的真实来源。确保 `package.json`、发布工件和文档使用 SPDX 标识符 `AGPL-3.0-only`。
## 前项目的确认
PDF 反编译器 MCP 以 **Claude AI 的 Lightweight PDF MCP** 为起点。原始项目探索了 PDF 文本、表格、链接、图像、OCR 输出和页面回落的本地预处理，用于 Claude Desktop。
重新品牌反映了测试结果：更多的文档保真度可能需要更多的上下文，而效率应该来自选择性检索和明确的预算，而不是普遍的轻量级声明。
