PDF Spec (PDF Agent Stack)

PDF SPEC MCP Server

[CI] [npm version]

日本語版 README はこちら

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/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

[!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.

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)

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:#9E9E9E

Layer Overview

Setup

1. Obtain PDF Specification Files

[!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.

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 Metadata

2. 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@latest

Or install it globally (optional):

npm install -g @shuji-bonji/pdf-spec-mcpPDF_SPEC_DIR=/path/to/pdf-specs pdf-spec-mcp

3. Configure MCP Client

Environment Variable

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

[!IMPORTANT] 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:

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-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.
• 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 existsnpx -y @shuji-bonji/pdf-spec-mcp@latest --cache-info     # directory, key, entriesnpx -y @shuji-bonji/pdf-spec-mcp@latest --clear-cache    # remove the directory

A 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).

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 only

get_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:

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.

[!NOTE] 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:

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 logger

Development

git clone https://github.com/shuji-bonji/pdf-spec-mcp.gitcd pdf-spec-mcpnpm installnpm run build
# Unit testsnpm run test
# E2E tests (requires PDF files in ./pdf-spec/)npm run test:e2e
# Lint & formatnpm run lintnpm run format:check

License

MIT