PDF Accessibility Audit

pdf-a11y-audit

人と AI エージェントのためのローカルファーストな PDF アクセシビリティ監査ツールです。

アップロード不要。アカウント不要。API キー不要。モデル呼び出し不要。ローカルの PDF を読み込み、実際のオブジェクトモデルとテキストレイヤーを検査して、構造化レポート、Markdown 形式の監査結果、または同僚に送れる自己完結型 HTML レポートを返します。

このツールを作った理由

PDF のアクセシビリティチェックの多くは、Windows GUI、有料サービス、またはブラックボックスのスコアです。このツールはその逆です。

• ローカル — 文書がマシンの外に出ることはありません。
• 決定論的 — 同じ PDF には常に同じ指摘が返されます。
• 証拠に基づく — 各指摘には、ルール、ページ、基準の参照先、修正手順が記載されます。
• 誠実 — スクリーンリーダーや人による確認が必要な項目は手動確認として記載し、合格とは報告しません。
• 無料 — サーバー不要、文書ごとの料金不要、推論コスト不要です。

公共部門向けの文書を公開するチームのために、Remediate が開発・保守しています。

インストール

# 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

npm では pdf-a11y-audit として公開されており、公式 MCP Registry では io.github.Veduis/pdf-a11y-audit として掲載されています。

チェックアウトから作業する場合は、リポジトリをクローンし、npm install を実行して、代わりに node bin/cli.js を使用してください。

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

オプション	デフォルト	意味
--format json|markdown|html|csv	markdown	出力形式
--out <path>	stdout、または HTML の場合は <name>-a11y-report.html	ファイルに書き込みます
--fail-on <severity|none>	serious	この重大度以上の場合に終了コード 1 を返します
--max-findings <n>	500	文書ごとの指摘数の上限
--quiet	off	最終サマリーのみを表示します

MCP サーバー

このパッケージは stdio MCP サーバーを公開します。ネットワーク接続を開くことはありません。

Claude Desktop／Cursor／任意の MCP クライアント

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

ローカルのチェックアウトを使用する場合：

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

最小構成のクライアントが含まれています。サーバーを起動して audit_pdf を呼び出し、サーバーから返された結果をそのまま出力します。

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

同じサーバーは CLI エントリーポイントから --mcp を指定して起動することもできます。これは、レジストリマニフェストと上記の npx 設定で使用される形式です。

ツール

ツール	機能
audit_pdf	ローカルの PDF を 1 件監査します。JSON、Markdown、または自己完結型 HTML レポートを返します。output を指定するとファイルに書き込みます。
audit_batch	1 つ以上のフォルダー内にあるすべての PDF を監査し、比較表を返します。
explain_finding	ルール、基準との対応付け、および修正方法を説明します。
list_checks	手動確認を含むルールカタログを一覧表示します。
compare_reports	2 つの JSON レポートを比較し、新規、修正済み、継続中の指摘を一覧表示します。
render_report	既存の JSON レポートを HTML として再レンダリングし、ファイルに書き込みます。

リソースとプロンプト

• remediate://rules — ルールカタログ全体。
• remediate://methodology — 監査で判断できることとできないこと。
• audit_and_plan — 適合を主張することなく、指摘を優先順位付けした修正計画にまとめるプロンプト。

チェック項目

自動エンジンでは、以下の項目をチェックします。

• ドキュメント： タグ付け、/MarkInfo、親ツリー、suspects、ロールマップ、言語、表示タイトル、ドキュメントタイトル、XMPタイトル、PDF/UA の適合性表示。
• 見出し： 見出しの有無、最初のレベル、レベルの飛ばし、空の見出し、H1 が複数あるか。
• 表： ヘッダーセル、空のヘッダー、Scope/Headers、行、不規則な行。
• 図： 代替テキストの欠落、空の代替テキスト、ファイル名のような代替テキスト。
• フォーム： フィールド名、ツールチップ、重複する名前、ウィジェット構造、タブ順序。
• リスト： 空のリスト項目。
• リンク： 構造上の親要素とアクセシブルな名前。
• フォント： フォントの埋め込みとToUnicodeマップ。
• ページ： スキャンされたページ、空白ページ、テキストが少ないページ。
• 読み上げ順序： 孤立または欠落した MCID、順序の不一致。
• ナビゲーション： 長いドキュメントでのしおりの欠落、空のしおり項目。

レポートには、色のコントラスト、代替テキストの品質、スクリーンリーダーでの読み上げ順序、複雑な表、リンクの目的、OCR の精度、フォームのエラー、支援技術を使った全項目の確認について、手動チェックも記載されます。自動チェックに合格しても、適合性証明にはなりません。

HTML レポート

HTML レポートは、外部フォント、画像、スクリプト、トラッキングを使わない単一ファイルです。以下が含まれます。

• アクセシビリティスコアと重大度別の件数。
• 影響度の高い指摘から順に表示。
• すべての指摘に対する根拠と修正方法。
• 規格との対応関係。
• スキップされたチェックを含む、自動チェック項目の全リスト。
• 手動レビュー用チェックリストと制限事項。
• <script type="application/json">ブロック内の、機械可読なレポートの JSON コピー。

レスポンシブ対応で、印刷に適しており、ライトモードとダークモードの配色をサポートします。

設計原則

• 継続的な費用は不要です。 ホステッドサービス、推論、ストレージ、アカウントは必要ありません。
• AI を演出に使いません。 紫のグラデーション、光る図形、「AI を活用」といった文言は使いません。レポートは編集されたドキュメントであり、ダッシュボードのおもちゃではありません。
• スコアより根拠を重視します。 スコアは要約であり、主役は指摘事項です。
• 問題を隠さず明示します。 対応していないチェックはスキップまたは手動として報告し、合格として黙って扱うことはありません。

開発

cd pdf-a11y-audit
npm install
npm test

テストスイートは、タグ付きとタグなしの PDF テスト用ファイルを独自に生成し、CLI と MCP サーバーをテストして、HTML レポートが自己完結していることを検証します。

制限事項

• 監査対象は PDF であり、顧客のウェブサイトやサードパーティーの埋め込みコンテンツではありません。
• 色のコントラスト、代替テキストの品質、読み上げ順序の意味の確認には、人による確認とスクリーンリーダーが必要です。
• 形式が不正な PDF や暗号化された PDF は、どのパーサーでも構造を読み取れない場合があります。
• 法的助言でも、適合性証明でもありません。

ライセンス

MIT © Veduis。Remediate が開発しました。