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

npm install -g @jayjex/pdfcheck-mcp

Or run from GitHub without npm:

npx -y github:jayjex/pdfcheck-mcp

Claude Desktop config

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

Tools

pdf_qa(path)

Full report for one PDF:

{
  "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

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