@shuji-bonji/pdf-spec-mcp
An MCP server that gives LLMs structured access to ISO 32000 (PDF) specification documents for navigation, search, and requirement extraction — it does not inspect PDF files or validate conformance.
List available specs — discover up to 17 indexed documents (ISO 32000-2/1, TS 32001–32005, PDF/UA-1/2, guides, app notes) with IDs, titles, page counts, and categories; filter by category.
Browse the table of contents — retrieve a spec's section hierarchy with section numbers, titles, and page numbers, at a configurable depth.
Read section content — get structured content (headings, paragraphs, lists, tables, notes) for a section such as
7.3.4.2orAnnex A, including page ranges and boundary info describing how content was cut.Full-text search — keyword/phrase search with section-aware context snippets and a configurable result limit; the index is built once and cached on disk for fast reuse.
Extract normative requirements — pull
shall/shall not/should/should not/maystatements, optionally filtered by section or level.Look up definitions — fetch terms and definitions from the "Terms and definitions" clause (clause 3 of ISO 32000-2, clause 4 of ISO 32000-1), searchable by substring.
Extract tables — retrieve table headers, rows, and captions from a section, with multi-page tables merged and an option to select a single table by index.
Compare versions — diff section structures between PDF 1.7 and PDF 2.0 to find matched, added, and removed sections (requires both PDFs).
Target any spec — nearly every tool accepts a
specparameter (defaultiso32000-2) to query a different document.
PDF SPEC MCP Server
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.
This is a specification reference, not a rule engine.
It retrieves and structures the text of ISO 32000 — clauses, tables, definitions, and
shall/should/may requirements. 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 shall here 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.
What each PDF family server does — and does not do
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 |
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 | |
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 | |
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 |
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.
Features
Multi-spec support — Auto-discovers and manages up to 17 PDF-related documents (ISO 32000-2, PDF/UA, Tagged PDF guides, etc.)
Structured content extraction — Headings, paragraphs, lists, tables, and notes from any section
Full-text search — Keyword search with section-aware context snippets
Requirements extraction — Extracts normative language (shall / must / may) per ISO conventions
Definitions lookup — Term definitions from the "Terms and definitions" clause (clause 3 of ISO 32000-2, clause 4 of ISO 32000-1)
Table extraction — Multi-page table detection with header merging
Version comparison — Diff PDF 1.7 vs PDF 2.0 section structures
Bounded-concurrency processing — Parallel page processing for large documents
On-disk index cache — The search index and the full requirements scan are built once per PDF and reused by every later process (ISO 32000-2: ~6 s → ~0.2 s)
Related MCP server: MCP PDF Reader
Architecture
graph LR
subgraph Client["MCP Client"]
LLM["LLM<br/>(Claude, etc.)"]
end
subgraph Server["PDF Spec MCP Server"]
direction TB
MCP["MCP Server<br/>index.ts"]
subgraph Tools["Tools Layer"]
direction LR
T1["list_specs"]
T2["get_structure"]
T3["get_section"]
T4["search_spec"]
T5["get_requirements"]
T6["get_definitions"]
T7["get_tables"]
T8["compare_versions"]
end
subgraph Services["Services Layer"]
direction LR
REG["Registry<br/>Auto-discovery"]
LOADER["Loader<br/>LRU Cache"]
SVC["PDFService<br/>Orchestration"]
CMP["CompareService<br/>Version Diff"]
end
subgraph Extractors["Extractors"]
direction LR
OUTLINE["OutlineResolver<br/>TOC & Section Index"]
CONTENT["ContentExtractor<br/>Structured Extraction"]
SEARCH["SearchIndex<br/>Full-text Search"]
REQ["RequirementExtractor"]
DEF["DefinitionExtractor"]
end
subgraph Utils["Utils"]
direction LR
CACHE["LRU Cache"]
CONC["Concurrency"]
VALID["Validation"]
end
end
subgraph PDFs["PDF Spec Files (obtained separately)"]
direction LR
PDF1["ISO 32000-2<br/>(PDF 2.0)"]
PDF2["ISO 32000-1<br/>(PDF 1.7)"]
PDF3["TS 32001–32005<br/>PDF/UA, etc."]
end
LLM <-->|"stdio / JSON-RPC"| MCP
MCP --> Tools
Tools --> Services
Services --> Extractors
Services --> Utils
LOADER --> PDFs
REG -->|"Filename pattern<br/>auto-discovery"| PDFs
style Client fill:#e8f4f8,stroke:#2196F3
style PDFs fill:#fff3e0,stroke:#FF9800
style Tools fill:#e8f5e9,stroke:#4CAF50
style Services fill:#f3e5f5,stroke:#9C27B0
style Extractors fill:#fce4ec,stroke:#E91E63
style Utils fill:#f5f5f5,stroke:#9E9E9ELayer Overview
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) |
Setup
1. Obtain PDF Specification Files
PDF specifications arecopyrighted 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) | |
ISO 32000-1 (PDF 1.7) | |
TS 32001–32005, PDF/UA, etc. |
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).
pdf-specs/
│
│ ── Standards ─────────────────────────────
├── ISO_32000-2_sponsored_EC3.pdf # iso32000-2 : PDF 2.0 EC3 (recommended; falls back to -ec2.pdf)
├── ISO_32000-2-2020_sponsored.pdf # iso32000-2-2020 : PDF 2.0 original
├── PDF32000_2008.pdf # pdf17 : PDF 1.7 (for version comparison)
├── pdfreference1.7old.pdf # pdf17old : Adobe PDF Reference 1.7
│
│ ── Technical Specifications (TS) ─────────
├── ISO_TS_32001-2022_sponsored_EC3.pdf # ts32001 : Hash extensions (SHA-3)
├── ISO_TS_32002-2022_sponsored_EC3.pdf # ts32002 : Digital signature extensions (ECC/PAdES)
├── ISO_TS_32003-2023_sponsored.pdf # ts32003 : AES-GCM encryption
├── ISO-TS-32004-2024_sponsored.pdf # ts32004 : Integrity protection
├── ISO-TS-32005-2023-sponsored.pdf # ts32005 : Namespace mapping
│
│ ── PDF/UA (Accessibility) ────────────────
├── ISO-14289-1-2014-sponsored.pdf # pdfua1 : PDF/UA-1
├── ISO-14289-2-2024-sponsored.pdf # pdfua2 : PDF/UA-2
│
│ ── Guides ────────────────────────────────
├── Tagged-PDF-Best-Practice-Guide.pdf # tagged-bpg : Tagged PDF Best Practice
├── Well-Tagged-PDF-WTPDF-1.0.pdf # wtpdf : Well-Tagged PDF
├── PDF-Declarations.pdf # declarations: PDF Declarations
│
│ ── Application Notes ─────────────────────
├── PDF20_AN001-BPC.pdf # an001 : Black Point Compensation
├── PDF20_AN002-AF.pdf # an002 : Associated Files
└── PDF20_AN003-ObjectMetadataLocations.pdf # an003 : Object Metadata2. Install
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):
PDF_SPEC_DIR=/path/to/pdf-specs npx -y @shuji-bonji/pdf-spec-mcp@latestOr install it globally (optional):
npm install -g @shuji-bonji/pdf-spec-mcp
PDF_SPEC_DIR=/path/to/pdf-specs pdf-spec-mcp3. Configure MCP Client
Environment Variable
Variable | Description | Default |
| Directory containing PDF specification files | (required) |
| Where the on-disk index cache lives (see Index cache) |
|
| Set to | on |
Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"pdf-spec": {
"command": "npx",
"args": ["-y", "@shuji-bonji/pdf-spec-mcp@latest"],
"env": {
"PDF_SPEC_DIR": "/path/to/pdf-specs"
}
}
}
}Use @latest (or pin a version). npx -y <pkg> without a version keeps running whatever
it cached the first time — -y only skips the install prompt, it does not check for updates.
A bare specifier will happily run a months-old release. @latest makes npx check the registry
on each start; pin @0.4.0 instead if you want reproducibility.
To clear a stale cache: rm -rf ~/.npm/_npx.
Cursor / VS Code
Add to .cursor/mcp.json or VS Code MCP settings:
{
"mcpServers": {
"pdf-spec": {
"command": "npx",
"args": ["-y", "@shuji-bonji/pdf-spec-mcp@latest"],
"env": {
"PDF_SPEC_DIR": "/path/to/pdf-specs"
}
}
}
}Installed as a Claude Code plugin
The plugin manifest (.claude-plugin/plugin.json) declares "PDF_SPEC_DIR": "${PDF_SPEC_DIR}"
and relies on the host to substitute the reference. Not every host does:
Host | Expands | Where to put the absolute path instead |
Claude Code (terminal) | yes | — |
Grok Build 1.0.30 | no |
|
Claude Desktop, cloud session linked to this computer (plugin tools) | no | the local MCP configuration the desktop app reads |
When the reference is passed through verbatim, every tool answers with REGISTRY_ERROR whose
message starts with PDF_SPEC_DIR is the unexpanded text "${PDF_SPEC_DIR}" and whose first
next_actions entry is set_absolute_path_in_host_config. That is a host-configuration problem,
not a missing directory — write the absolute path into the host's own configuration and restart.
Host-by-host steps: https://shuji-bonji.github.io/pdf-agent-stack/reference/env-vars.
Index cache
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.
Location:
${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.Key: package version,
pdfjs-distversion, 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-cacheremoves everything.Failure is a miss, never an error: an unreadable, truncated, or foreign file is rebuilt; an unwritable directory is reported once on stderr and the server carries on without a cache.
It is derived from your copy of the PDFs and stays on your machine. It is not part of the package and must not be redistributed — the specifications are copyrighted.
Nothing about searching changes: the same in-memory structure is searched by the same code. Only where it comes from (built vs. read) does.
Pre-building the cache
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):
PDF_SPEC_DIR=/path/to/pdf-specs npx -y @shuji-bonji/pdf-spec-mcp@latest --build-cache
# --spec=iso32000-2,pdf17 only these specs
# --force rebuild even when a valid entry exists
npx -y @shuji-bonji/pdf-spec-mcp@latest --cache-info # directory, key, entries
npx -y @shuji-bonji/pdf-spec-mcp@latest --clear-cache # remove the directoryA full build of the 17-spec corpus takes about a minute on a laptop.
Available Tools
All tools accept an optional spec parameter to target a specific specification (default: iso32000-2).
Tool | Description |
| List all discovered PDF specifications with metadata |
| Get section hierarchy (table of contents) with configurable depth |
| Get structured content of a specific section |
| Full-text keyword search across a specification |
| Extract normative requirements (shall/must/may) |
| Lookup term definitions |
| Extract table structures from a section |
| Compare PDF 1.7 and PDF 2.0 section structures |
list_specs — Discover Specifications
List all available specification documents. Use the returned IDs as the spec parameter in other tools.
// List all specs
{ }
// Filter by category
{ "category": "ts" } // Technical specs only
{ "category": "pdfua" } // PDF/UA only
{ "category": "guide" } // Guide documents onlyget_structure — Table of Contents
Get the section hierarchy (TOC tree) of a specification.
// PDF 2.0 top-level sections only
{ "max_depth": 1 }
// Expand to 2 levels
{ "max_depth": 2 }
// TS 32002 (Digital Signatures) full structure
{ "spec": "ts32002" }
// PDF/UA-2 structure
{ "spec": "pdfua2", "max_depth": 2 }get_section — Section Content
Get 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.
Every answer carries pageRange and boundary. boundary says how each end of the content was cut:
| Meaning |
| The section's own heading was found; text before it on the first page was dropped |
| The heading was not found; content starts at the top of the first page and may include the tail of the previous section |
| Meaning |
| Cut at the next section's heading |
| Content ends with its last page; the next section starts on a later page |
| The next section starts on the last page but its heading was not found — content may include the next section's text |
| The next section starts on the following page and its heading was not found there — any tail of this section on that page is not included |
| Last section of the document |
Anything other than heading / heading, heading / page or heading / document means the cut fell on a page edge: read the neighbouring section too before relying on the content. For a parent section, start is the parent's own and end is its last descendant's.
// PDF 2.0 Section 7.3.4.2 (Literal Strings)
{ "section": "7.3.4.2" }
// PDF 2.0 Annex A
{ "section": "Annex A" }
// TS 32002 Section 5
{ "spec": "ts32002", "section": "5" }
// PDF/UA-2 Section 8 (Tagged PDF)
{ "spec": "pdfua2", "section": "8" }search_spec — Full-text Search
Search 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).
// Search PDF 2.0 for "digital signature"
{ "query": "digital signature" }
// Limit results
{ "query": "font", "max_results": 5 }
// Search within TS 32002
{ "spec": "ts32002", "query": "CMS" }get_requirements — Normative Requirements
Extract normative requirements (shall / must / may) per ISO conventions.
sectionsCutByPage lists the sections in scope whose content was cut at a page edge (see boundary under get_section); their requirements may include a neighbour's sentences or miss the tail. It is empty when every section in scope was cut at headings.
// All requirements in section 12.8
{ "section": "12.8" }
// Only "shall" requirements
{ "section": "12.8", "level": "shall" }
// Only "shall not" requirements
{ "section": "7.3", "level": "shall not" }
// PDF/UA-2 requirements
{ "spec": "pdfua2", "section": "8", "level": "shall" }get_definitions — Term Definitions
Look up term definitions from the "Terms and definitions" clause — clause 3 of ISO 32000-2 (71 terms), clause 4 of ISO 32000-1 / pdf17 (48 terms). section in each result is the number printed in the document (3.12, 4.11).
// Search for "font" definitions
{ "term": "font" }
// List all definitions
{ }
// PDF/UA definitions
{ "spec": "pdfua2", "term": "artifact" }get_tables — Table Extraction
Extract table structures (headers, rows, captions) from a section. Multi-page tables are automatically merged.
The answer carries pageRange (the pages the tables were read from) and boundary (see get_section). totalTables: 0 means no Table element was found in those pages — with a page-cut boundary, the pages themselves may not be the whole section.
// All tables in section 7.3.4.2 (Table 3 — Escape sequences)
{ "section": "7.3.4.2" }
// Specific table only (0-based index)
{ "section": "7.3.4.2", "table_index": 0 }
// TS spec tables
{ "spec": "ts32002", "section": "5" }compare_versions — Version Comparison
Compare 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.
This tool requires both PDF 1.7 (PDF32000_2008.pdf) and PDF 2.0 files in PDF_SPEC_DIR.
// Diff section 12.8 (Digital Signatures)
{ "section": "12.8" }
// Compare all top-level sections
{ }Supported Specifications
The server auto-discovers PDF files in PDF_SPEC_DIR by filename pattern matching:
Category | Spec IDs | Documents |
Standard |
| ISO 32000-2 (PDF 2.0), ISO 32000-1 (PDF 1.7) |
Technical Spec |
| Hash, Digital Signatures, AES-GCM, Integrity, Namespace |
PDF/UA |
| Accessibility (ISO 14289-1, 14289-2) |
Guide |
| Tagged PDF, Well-Tagged PDF, Declarations |
App Note |
| BPC, Associated Files, Object Metadata |
Directory Structure
src/
├── index.ts # Entry point: MCP server on stdio, or the cache CLI
├── cli.ts # --build-cache / --clear-cache / --cache-info
├── config.ts # Configuration & spec patterns
├── errors.ts # Error hierarchy (PDFSpecError → sub-classes)
├── services/
│ ├── pdf-registry.ts # Auto-discovery of PDF files
│ ├── pdf-loader.ts # PDF loading with LRU cache
│ ├── pdf-service.ts # Orchestration layer
│ ├── index-store.ts # On-disk cache for the search / requirements indexes
│ ├── compare-service.ts # Version comparison
│ ├── outline-resolver.ts # Section index builder
│ ├── content-extractor.ts # Structured content extraction
│ ├── search-index.ts # Full-text search index
│ ├── requirement-extractor.ts
│ └── definition-extractor.ts
├── tools/
│ ├── definitions.ts # MCP tool schemas
│ └── handlers.ts # Tool implementations
├── types/
│ └── index.ts # Shared type definitions
└── utils/
├── concurrency.ts # mapConcurrent (bounded Promise.all)
├── text.ts # Text normalization
├── cache.ts # LRU cache
├── file-hash.ts # SHA-256 of a PDF (index cache key)
├── validation.ts # Input validation
└── logger.ts # Structured loggerDevelopment
git clone https://github.com/shuji-bonji/pdf-spec-mcp.git
cd pdf-spec-mcp
npm install
npm run build
# Unit tests
npm run test
# E2E tests (requires PDF files in ./pdf-spec/)
npm run test:e2e
# Lint & format
npm run lint
npm run format:checkLicense
Available Tools
8 toolscompare_versionsA
Compare sections between PDF 1.7 (ISO 32000-1) and PDF 2.0 (ISO 32000-2). Returns matched sections (same or moved), added sections (new in 2.0), and removed sections (absent in 2.0). Uses title-based automatic matching.
Inputs: section.
get_definitionsA
Get term definitions from Section 3 of the PDF specification (ISO 32000-2). Returns structured definitions with term, definition text, notes, and sources.
Inputs: spec, term.
get_requirementsA
Extract normative requirements (shall/must/may) from the PDF specification (ISO 32000-2). Returns structured requirements with the sentence context, section, and requirement level.
Inputs: spec, section, level.
get_sectionA
Get the content of a specific section from the PDF specification (ISO 32000-2). Returns structured content including headings, paragraphs, lists, tables, and notes.
Inputs: section (required), spec.
get_structureA
Get the section hierarchy of the PDF specification (ISO 32000-2). Returns the table of contents with section numbers, titles, and page numbers.
Inputs: spec, max_depth.
get_tablesA
Extract table structures from a specified section of the PDF specification (ISO 32000-2). Returns tables with headers, rows, and optional captions.
Inputs: section (required), spec, table_index.
list_specsA
List all available PDF specification documents. Returns document IDs, titles, page counts, and categories. Use the returned IDs as the spec parameter in other tools.
Inputs: category.
search_specA
Search the PDF specification (ISO 32000-2) for a keyword or phrase. Returns matching sections with context snippets. The first call may take a few seconds to build the search index.
Inputs: query (required), spec, max_results.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a distinct aspect of the PDF specification: version comparison, definitions, requirements, sections, structure, tables, listing specs, and searching. No overlap in purpose.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., get_section, search_spec). There is no mixing of conventions.
With 8 tools, the set is well-scoped for exploring and comparing PDF specifications. Each tool serves a clear function without being excessive or insufficient.
The tool surface covers common operations for a reference document: listing, searching, retrieving structure, content, tables, definitions, requirements, and version comparison. No obvious gaps for its read-only domain.
Maintenance
Related MCP Connectors
Hosted MCP server: convert PDFs to clean, LLM-ready Markdown with tables, formulas and OCR.
Query your own PDFs and documents from any MCP client. Every answer cites the page it came from.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Document-to-Markdown MCP server — convert PDF, Office and HTML into LLM-ready Markdown.
Related MCP Servers
- AlicenseAqualityDmaintenanceA Model Context Protocol server that enables the extraction of text, metadata, and embedded images from PDF files. It provides tools for searching text with context, reading specific pages, and counting total pages within a document.722 npm1MIT
- AlicenseAqualityDmaintenanceAn MCP server that enables AI assistants to read, search, and analyze PDF files from local paths or URLs. It provides tools for extracting specific page ranges, searching for terms, and retrieving document metadata.439 npm1MIT
- AlicenseAqualityCmaintenanceAn MCP server for reading, rendering, and searching PDF files, specifically optimized for LLMs to extract text, tables, and technical diagrams. It enables metadata retrieval, multi-format text extraction, and page-to-image rendering using PyMuPDF.583MIT
- AlicenseNot gradedqualityBmaintenanceMCP server that reads PDFs and exposes them as structured Markdown, metadata, outlines, images, and tables to LLM consumers via tools like pdf_read_markdown and pdf_info.Apache 2.0