The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the PDF Spec (PDF Agent Stack) listing page.
An MCP (Model Context Protocol) server that provides structured access to ISO 32000 (PDF) specification documents. Enables LLMs to navigate, search, and analyze PDF specifications through well-defined tools.
[!IMPORTANT] This is a specification reference, not a rule engine. It retrieves and structures the text of ISO 32000 — clauses, tables, definitions, and
shall/should/mayrequirements. It does not examine a PDF file, and it cannot tell you whether a document conforms to anything. Conformance verdicts come from pdf-verify-mcp (validate_conformance/evaluate_policy).The distinction matters because three different things get conflated: declaration — a label the file wrote about itself ("I am PDF/A" in the metadata). Writing it is not evidence / conformance — whether the file actually meets the standard. There is no way to prove it in full; you can only find where it breaks the rules / validation — what a validator (veraPDF and the like) reports against the checks it implements. A pass means "this inspection did not fail", not "the file conforms to the standard". Reading a
shallhere tells you what the standard requires — not whether your file meets it.A search that returns nothing means "cannot answer", not "no such requirement." ISO 19005 (PDF/A) and ETSI PAdES are outside this corpus; see
list_specs→coverage.gaps.
| Server | Does | Does not |
|---|---|---|
| pdf-spec-mcp (this) | Search, retrieve and extract requirements from 17 PDF-related documents | Is not a rule engine. Does not define business rules, inspect PDF files, or validate schemas. ISO 19005 (PDF/A) is not part of the corpus |
| pdf-reader-mcp | Extract text / tables / structure tree / fonts / annotations / images / signature fields | Does not verify cryptography. Does not read the incremental-update history, does not map object IDs to coordinates, does not OCR |
| pdf-writer-mcp | Create, page operations, tagging, forms, annotations, metadata, attachments, PDF/A-3b scaffolding | Does not sign. Does not make the file meet the standard — it can write a label, not conformance |
| pdf-verify-mcp | Conformance validation (delegated to veraPDF), cryptographic signature verification, tamper detection, policy verdicts | Does not prove the file meets the standard (it can only find where it breaks the rules). Does not vouch for the signer's identity. Does not judge whether the content is true |
[!IMPORTANT] PDF specification files are NOT included in this package. You must obtain the PDF specification documents separately and place them in a local directory.
Download from: PDF Association — Sponsored Standards
See "Setup" for details.
| Layer | Responsibility |
|---|---|
| Tools | MCP tool schema definitions & handlers (input validation) |
| Services | Business logic (PDF registry, loader, orchestration) |
| Extractors | Information extraction from PDFs (TOC, content, search, requirements, definitions) |
| Utils | Shared utilities (cache, concurrency, validation) |
[!WARNING] PDF specifications are copyrighted documents and are not included in this package. Download them from the sources below and place them in a local directory.
| Document | Source |
|---|---|
| ISO 32000-2 (PDF 2.0) | PDF Association |
| ISO 32000-1 (PDF 1.7) | Adobe (free) |
| TS 32001–32005, PDF/UA, etc. | PDF Association — Sponsored Standards |
All 17 files below are supported. You do not need all of them — place only the specs you need (at minimum, ISO 32000-2 is recommended).
This package ships a CLI binary (pdf-spec-mcp) intended to be launched by an MCP client.
You do not need to install it manually — just point your MCP client to npx @shuji-bonji/pdf-spec-mcp@latest as shown in the next step.
If you want to run it directly from the shell (e.g. for debugging):
Or install it globally (optional):
| Variable | Description | Default |
|---|---|---|
PDF_SPEC_DIR | Directory containing PDF specification files | (required) |
PDF_SPEC_CACHE_DIR | Where the on-disk index cache lives (see Index cache) | ${XDG_CACHE_HOME:-~/.cache}/pdf-spec-mcp |
PDF_SPEC_CACHE | Set to off to neither read nor write the index cache | on |
Add to claude_desktop_config.json:
[!IMPORTANT] Use
@latest(or pin a version).npx -y <pkg>without a version keeps running whatever it cached the first time —-yonly skips the install prompt, it does not check for updates. A bare specifier will happily run a months-old release.@latestmakes npx check the registry on each start; pin@0.4.0instead if you want reproducibility. To clear a stale cache:rm -rf ~/.npm/_npx.
Add to .cursor/mcp.json or VS Code MCP settings:
Two operations walk every page of a specification: the first search_spec on a spec builds
its full-text index (ISO 32000-2, 1023 pages: about 6 s on a laptop), and get_requirements
without a section scans every section (about 11 s). Everything else opens only the pages it
needs and answers in well under a second.
Since 0.5.0 those two results are written to disk after the first build and read back by every
later process — an MCP client that starts one server per session no longer pays the build each
time. The second process answers the same search_spec in about 0.2 s and the full
requirements scan in about 0.02 s, from byte-for-byte the same index.
${PDF_SPEC_CACHE_DIR:-${XDG_CACHE_HOME:-~/.cache}/pdf-spec-mcp}/v1/<version>/<spec>.<kind>.<sha256[0:16]>.json.
The whole 17-spec corpus is about 18 MB per package version.pdfjs-dist version, spec id, and the SHA-256 of the PDF. A
replaced PDF, an upgraded server, or an upgraded pdfjs all miss and rebuild. Entries of
older versions are left in place (another install may still use them); --clear-cache
removes everything.Nothing about searching changes: the same in-memory structure is searched by the same code. Only where it comes from (built vs. read) does.
The cache fills lazily, one spec at a time as tools touch it. To warm every spec up front — after installing, after upgrading, or from cron — run the CLI (it uses the same code path as the tools, processes specs sequentially, and exits):
A full build of the 17-spec corpus takes about a minute on a laptop.
All tools accept an optional spec parameter to target a specific specification (default: iso32000-2).
| Tool | Description |
|---|---|
list_specs | List all discovered PDF specifications with metadata |
get_structure | Get section hierarchy (table of contents) with configurable depth |
get_section | Get structured content of a specific section |
search_spec | Full-text keyword search across a specification |
get_requirements | Extract normative requirements (shall/must/may) |
get_definitions | Lookup term definitions |
get_tables | Extract table structures from a section |
compare_versions | Compare PDF 1.7 and PDF 2.0 section structures |
list_specs — Discover SpecificationsList all available specification documents. Use the returned IDs as the spec parameter in other tools.
get_structure — Table of ContentsGet the section hierarchy (TOC tree) of a specification.
get_section — Section ContentGet structured content (headings, paragraphs, lists, tables, notes) of a specific section.
A parent section returns its entire subtree (its preamble followed by all subsections, in document order). Top-level clauses can be very large — prefer the most specific section number.
search_spec — Full-text SearchSearch across a specification with section-aware context snippets. The first call on a spec builds its index (a few seconds); the index is then cached on disk (see Index cache).
get_requirements — Normative RequirementsExtract normative requirements (shall / must / may) per ISO conventions.
get_definitions — Term DefinitionsLook up term definitions from Section 3 (Definitions).
get_tables — Table ExtractionExtract table structures (headers, rows, captions) from a section. Multi-page tables are automatically merged.
compare_versions — Version ComparisonCompare section structures between PDF 1.7 (ISO 32000-1) and PDF 2.0 (ISO 32000-2). Uses title-based automatic matching to detect matched, added, and removed sections.
[!NOTE] This tool requires both PDF 1.7 (
PDF32000_2008.pdf) and PDF 2.0 files inPDF_SPEC_DIR.
The server auto-discovers PDF files in PDF_SPEC_DIR by filename pattern matching:
| Category | Spec IDs | Documents |
|---|---|---|
| Standard | iso32000-2, iso32000-2-2020, pdf17, pdf17old | ISO 32000-2 (PDF 2.0), ISO 32000-1 (PDF 1.7) |
| Technical Spec | ts32001 – ts32005 | Hash, Digital Signatures, AES-GCM, Integrity, Namespace |
| PDF/UA | pdfua1, pdfua2 | Accessibility (ISO 14289-1, 14289-2) |
| Guide | tagged-bpg, wtpdf, declarations | Tagged PDF, Well-Tagged PDF, Declarations |
| App Note | an001 – an003 | BPC, Associated Files, Object Metadata |