# 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 中读取文件前，建议先设置终端编码：

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

## 安装与构建

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

## 启动

```powershell
npm start
```

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

## MCP 配置

### Codex 配置

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

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

然后添加到 Codex：

```powershell
codex mcp add pdf-debug -- pdf-debug-mcp
```

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

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

## 工具

### `get_pdf_object`

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

输入：

```json
{
  "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。

输入：

```json
{
  "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 获取内容流。

页面内容流：

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

指定 stream object：

```json
{
  "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。

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

### `get_pdf_document_info`

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

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

### `get_pdf_page_tree`

获取页面树结构。

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

### `get_pdf_page_resources`

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

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

## 验证

```powershell
npm test
```

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

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

## 说明

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