PDF Accessibility Audit

pdf-a11y-audit

A local-first PDF accessibility auditor for people and AI agents.

No upload. No account. No API key. No model call. It reads a local PDF, inspects the actual object model and text layer, and returns a structured report, a Markdown audit, or a self-contained HTML report you can send to a colleague.

[A sample report]

Why this exists

Most PDF accessibility checks are either a Windows GUI, a paid service, or a black-box score. This tool is the opposite:

• Local — the document never leaves the machine.
• Deterministic — the same PDF produces the same findings.
• Evidence-based — every finding names the rule, the page, the standards reference and the remediation step.
• Honest — checks that need a screen reader or a human are listed as manual, never reported as passed.
• Free — no server, no per-document fee, no inference cost.

It is built and maintained by Remediate for teams publishing public-sector documents.

Install

# Run without installingnpx -y pdf-a11y-audit ./document.pdf
# Or install the CLInpm install -g pdf-a11y-auditpdf-a11y-audit ./document.pdf --format html --out report.html

Published on npm as pdf-a11y-audit and listed in the official MCP Registry as io.github.Veduis/pdf-a11y-audit.

Prefer to work from a checkout? Clone the repository, run npm install, and use node bin/cli.js instead.

CLI

# Markdown to the terminalpdf-a11y-audit budget.pdf
# A self-contained HTML reportpdf-a11y-audit budget.pdf --format html --out budget-a11y.html
# JSON for a pipelinepdf-a11y-audit budget.pdf --format json --out budget-a11y.json
# Fail a build on serious or critical findingspdf-a11y-audit budget.pdf --fail-on serious
# Audit every PDF in a folderpdf-a11y-audit ./public-docs --format csv

MCP server

The package exposes a stdio MCP server. It never opens a network connection.

Claude Desktop / Cursor / any MCP client

{  "mcpServers": {    "pdf-a11y-audit": {      "command": "npx",      "args": ["-y", "pdf-a11y-audit", "--mcp"]    }  }}

For a local checkout:

{  "mcpServers": {    "pdf-a11y-audit": {      "command": "node",      "args": ["/absolute/path/to/pdf-a11y-audit/bin/mcp.js"]    }  }}

A minimal client is included. It starts the server, calls audit_pdf and prints the result exactly as the server returned it:

node examples/mcp-client.mjs ./document.pdfMCP_TRACE=1 node examples/mcp-client.mjs ./document.pdf | head -n 30

The same server can be started through the CLI entry point with --mcp; this is the form used by the registry manifest and by the npx configuration above.

Tools

Resources and prompt

• remediate://rules — the full rule catalog.
• remediate://methodology — what the audit can and cannot decide.
• audit_and_plan — a prompt that turns findings into a prioritized remediation plan without claiming conformance.

What it checks

The automated engine covers:

• Document: tagging, /MarkInfo, parent tree, suspects, role map, language, display title, document title, XMP title, PDF/UA claims.
• Headings: presence, first level, skipped levels, empty headings, multiple H1s.
• Tables: header cells, empty headers, Scope/Headers, rows, irregular rows.
• Figures: missing alt, empty alt, filename-like alt.
• Forms: field names, tooltips, duplicate names, widget structure, tab order.
• Lists: empty list items.
• Links: structure parent and accessible names.
• Fonts: embedded fonts and ToUnicode maps.
• Pages: scanned pages, blank pages, sparse text.
• Reading order: orphaned or missing MCIDs and order mismatches.
• Navigation: missing bookmarks in long documents, empty bookmark entries.

The report also lists manual checks for colour contrast, alt-text quality, screen-reader order, complex tables, link purpose, OCR accuracy, form errors and a full assistive-technology pass. An automated pass is not a conformance certificate.

The HTML report

The HTML report is a single file with no external fonts, images, scripts or tracking. It includes:

• an accessibility score and severity counts;
• the highest-impact findings first;
• evidence and remediation for every finding;
• the standards mapping;
• the full automated check register, including skipped checks;
• the manual review checklist and limitations;
• a machine-readable JSON copy of the report in a <script type="application/json"> block.

It is responsive, print-friendly and supports light and dark colour schemes.

Design principles

• No recurring cost. No hosted service, no inference, no storage, no account.
• No AI theatre. No purple gradients, glowing blobs or “AI-powered” copy. The report is an editorial document, not a dashboard toy.
• Evidence over scores. The score is a summary; the findings are the product.
• Fail visibly, not silently. Unsupported checks are reported as skipped or manual; they are never silently treated as passes.

Development

cd pdf-a11y-auditnpm installnpm test

The test suite generates its own tagged and untagged PDF fixtures, exercises the CLI and MCP server, and verifies the HTML report is self-contained.

Limitations

• The audit reads the PDF, not a customer's website or third-party embeds.
• Colour contrast, alt-text quality and the meaning of the reading order require a human and a screen reader.
• Malformed or encrypted PDFs can hide structure from any parser.
• This is not legal advice and not a conformance certificate.

License

MIT © Veduis. Built by Remediate.