pdf-debug-mcp

pdf-debug-mcp 是一个用于检查 PDF 底层结构的 MCP Server。它提供类似 PDF inspector/debugger 的能力：读取 indirect object、递归展开对象引用、查看内容流、列出页面树和页面资源。

实现使用 pdf-lib 解析 PDF 对象模型，并在项目内补充了 stream filter 解码和原始对象片段定位逻辑。选择 pdf-lib 的原因是它稳定、纯 JavaScript、维护成熟，且可以访问 indirect objects、catalog、page tree、page dictionaries 和 raw streams，适合作为 MCP 本地调试工具的基础。

编码要求

所有项目文件都使用 UTF-8 创建和编辑。在 Windows PowerShell 中读取文件前，建议先设置终端编码：

[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
$OutputEncoding = [Console]::OutputEncoding

安装与构建

cd C:\src\pdf-debug-mcp
npm install
npm run build

启动

npm start

该进程通过 stdio 提供 MCP 服务。

MCP 配置

Codex 配置

推荐先把项目链接成本地命令：

cd C:\src\pdf-debug-mcp
npm link

然后添加到 Codex：

codex mcp add pdf-debug -- pdf-debug-mcp

通用 MCP 客户端也可以直接执行构建后的入口文件：

{
  "mcpServers": {
    "pdf-debug": {
      "command": "node",
      "args": ["C:/src/pdf-debug-mcp/dist/index.js"]
    }
  }
}

工具

get_pdf_object

根据 object number 和 generation number 获取指定 PDF indirect object。

输入：

{
  "filePath": "C:/path/to/file.pdf",
  "objectNumber": 4,
  "generationNumber": 0,
  "maxBytes": 65536,
  "decodeStream": true
}

输出包含：

• rawObject: 原始对象片段预览；
• parsed: 解析后的结构化对象；
• objectType: pdf-lib 对象类型；
• hasStream: 是否包含 stream；
• stream: stream 长度、filters、解码状态等 metadata。

get_pdf_object_structure

递归展开对象结构和 indirect references。

输入：

{
  "filePath": "C:/path/to/file.pdf",
  "objectNumber": 3,
  "generationNumber": 0,
  "maxDepth": 4,
  "maxBytes": 65536,
  "decodeStream": true
}

循环引用会标记为 [Circular Reference]，达到深度限制会标记为 [Max depth N reached]。

get_pdf_content_stream

根据页面或 stream object 获取内容流。

页面内容流：

{
  "filePath": "C:/path/to/file.pdf",
  "pageNumber": 1,
  "decodeStream": true,
  "parseOperators": true,
  "maxBytes": 65536
}

指定 stream object：

{
  "filePath": "C:/path/to/file.pdf",
  "objectNumber": 7,
  "generationNumber": 0,
  "decodeStream": true
}

输出会返回每个 stream 的来源对象、raw bytes 预览、decoded bytes/text 预览、filter 列表，以及可选 operator/token 分析。页面有多个内容流时会分别返回并提供 mergedDecoded。

当前支持的 stream filters：

• FlateDecode / Fl
• ASCIIHexDecode / AHx
• ASCII85Decode / A85
• RunLengthDecode / RL

不支持的 filter 会保留当前 bytes 并在 decodeError 中说明。

list_pdf_objects

列出 PDF 中的 indirect objects。

{
  "filePath": "C:/path/to/file.pdf",
  "maxObjects": 1000
}

get_pdf_document_info

获取 PDF header、trailer、catalog、xref 摘要和对象数量。

{
  "filePath": "C:/path/to/file.pdf",
  "maxDepth": 3
}

get_pdf_page_tree

获取页面树结构。

{
  "filePath": "C:/path/to/file.pdf",
  "maxDepth": 8
}

get_pdf_page_resources

获取指定页面关联的 Resources、Fonts、XObjects、Annots 等引用。

{
  "filePath": "C:/path/to/file.pdf",
  "pageNumber": 1,
  "maxDepth": 3
}

验证

npm test

Smoke test 会生成一个小 PDF，并验证：

• 构建后的模块可以列出 indirect objects；
• 可以读取 catalog 对象；
• 可以递归展开 page tree；
• 可以解码页面内容流并解析 operator；
• 可以读取页面资源；
• MCP Server 可以通过 stdio 响应 initialize 请求。

说明

该工具优先返回结构化 JSON，适合 AI 后续分析。对大型对象和大型 stream 使用 maxBytes、maxDepth、decodeStream 控制输出规模。