pdfcheck-mcp

# pdfcheck-mcp

MCP server that validates PDF page-tree structure. Two tools, stdio transport, zero native dependencies.

## Why

Most PDF checks stop at "does a stream object exist". That misses the real failure mode: a PDF can have 24 stream objects and still be unreadable because the page tree never points at them. We shipped 13 broken product PDFs this way. Every page dictionary was orphaned, `/Contents` pointed at font objects, and the stream-count QA passed anyway.

This server walks the object graph instead:

- every `/Kids` entry resolves to a `/Type /Page` object
- every page `/Contents` points to a stream object
- no orphan `/Type /Page` objects unreachable from `/Kids`
- reachable page count matches the `/Count` claim
- blank-page check: inflated content streams contain at least one `Tj`/`TJ` text op

It handles classic (uncompressed) xref tables, which covers output from typical PDF generators. Compressed xref streams are rejected with a clear error rather than a false pass.

## Install

```sh
npm install -g @jayjex/pdfcheck-mcp
```

Or run from GitHub without npm:

```sh
npx -y github:jayjex/pdfcheck-mcp
```

## Claude Desktop config

```json
{
  "mcpServers": {
    "pdfcheck": {
      "command": "npx",
      "args": ["-y", "@jayjex/pdfcheck-mcp"]
    }
  }
}
```

## Tools

### pdf_qa(path)

Full report for one PDF:

```json
{
  "file": "/tmp/report.pdf",
  "ok": false,
  "problems": [
    "contents-not-stream=3 [{\"page\":7,\"reason\":\"obj 5 not stream (type Font)\"}]",
    "orphan-pages=1 [13]",
    "count-mismatch claimed=4 reachable=3"
  ],
  "report": {
    "size_claim": 4, "kids": 4, "kids_ok": 3,
    "contents_ok": 0, "contents_bad": 3,
    "zero_tj": [], "orphans": [13], "xref_entries": 14, "size_field": 14
  }
}
```

### pdf_batch(dir)

Flat scan of a directory, one `pdf_qa` per `*.pdf` (max 200 files, 50 MB each). Returns totals, a per-file `kids/contents/orphans` summary, and the full problem list for every broken file.

## Local development

```sh
git clone https://github.com/jayjex/pdfcheck-mcp
cd pdfcheck-mcp && npm install
node test/smoke.mjs
```

`test/fixtures/` holds two healthy PDFs and one deliberately broken (`broken-wiring.pdf`, a page-tree pointer-shift bug). The smoke test asserts 2 pass, 1 fails with the exact graph problems.

## License

MIT