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.

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.

Related MCP server: interface-audit-mcp

Install

# Run without installing
npx -y pdf-a11y-audit ./document.pdf

# Or install the CLI
npm install -g pdf-a11y-audit
pdf-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 terminal
pdf-a11y-audit budget.pdf

# A self-contained HTML report
pdf-a11y-audit budget.pdf --format html --out budget-a11y.html

# JSON for a pipeline
pdf-a11y-audit budget.pdf --format json --out budget-a11y.json

# Fail a build on serious or critical findings
pdf-a11y-audit budget.pdf --fail-on serious

# Audit every PDF in a folder
pdf-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.pdf
MCP_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-audit
npm install
npm 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.