agentleFS
shuji-bonjishuji-bonji/pdf-verify-mcp/CLAUDE.md

pdf-verify-mcp

CLAUDE.md0 starsChanged 15 days agoMITView on GitHub

仕様の正本は openspec/specs/(OpenSpec)。仕様 ID・PR の種類・承認の記録の規則は AGENTS.md。 PDF の*真正性・準拠性を判定する MCP サーバ。PDF family における「判定*」担当。 - 責務分担の提案: mcps/pdf-family-role-architecture.md - 上位仕様: pdf-agent-stack/docs/specs/01-pdf-verify-mcp.md ⚠️ 名称衝突に注意: specs/01 の主題は「AI 抽出結果と原本の照合」で*未実装*。 本リポジトリの実装は「原本の真正性検証」であり、別スコープ(specs/00 付記 6 参照) ISO 規格等に照らした compliant / valid / pass-fail を返すなら本サーバ、 観測結果を返すだけなら pdf-reader-mcp。 - identify_conformance(宣言を読むだけ)が本サーバにあるのは、判定の入口だから - reader の inspect_signatures(署名フィールドの存在=事実)と 本サーバの verify_signatures(暗号検証=判定)の棲み分けはこの規則どおり - v0.6 で PDF/UA 判定を reader の validate_tagged から移管したのも同じ理由 (reader は構造ツリーを*報告する、本サーバが判定*する) - ツール追加は tools/xxx.ts を作り tools/index.ts の registerAllTools に 1 行 - 依存は軽量に保つ(pkijs / asn1js / pdf-lib / zod のみ)。 pdfjs は入れない — reader の領分であり、判定に必要な範囲は pdf-lib…

  • Commits and pushes

The file

Files
CLAUDE.md

pdf-verify-mcp - 開発ガイド

仕様の正本は openspec/specs/(OpenSpec)。仕様 ID・PR の種類・承認の記録の規則は AGENTS.md。

プロジェクト概要

PDF の真正性・準拠性を判定する MCP サーバ。PDF family における「判定」担当。

層サーバ一行定義
正典pdf-spec-mcp仕様は何を要求するか
実体pdf-reader-mcp中身に何があるか(合否は言わない)
判定本サーバそれは本物で、規格に適っているか
生成pdf-writer-mcp仕様どおりに書けるか
  • 責務分担の提案: mcps/pdf-family-role-architecture.md
  • 上位仕様: pdf-agent-stack/docs/specs/01-pdf-verify-mcp.md ⚠️ 名称衝突に注意: specs/01 の主題は「AI 抽出結果と原本の照合」で未実装。 本リポジトリの実装は「原本の真正性検証」であり、別スコープ(specs/00 付記 6 参照)

ツール一覧

ツール説明
verify_signatures暗号学的検証・信頼チェーン評価・失効確認(OCSP/CRL)・RFC 3161 タイムスタンプ
verify_integrity改ざん検知(増分更新・署名後の変更・DocMDP 違反)
detect_pades_levelPAdES ベースライン(B-B / B-T / B-LT / B-LTA)
identify_conformanceXMP 上の PDF/A・PDF/UA 宣言の識別(判定はしない)
validate_conformancePDF/A(ISO 19005)・PDF/UA(ISO 14289)の準拠判定

境界ルール(ツール追加時の判断基準)

ISO 規格等に照らした compliant / valid / pass-fail を返すなら本サーバ、 観測結果を返すだけなら pdf-reader-mcp。

  • identify_conformance(宣言を読むだけ)が本サーバにあるのは、判定の入口だから
  • reader の inspect_signatures(署名フィールドの存在=事実)と 本サーバの verify_signatures(暗号検証=判定)の棲み分けはこの規則どおり
  • v0.6 で PDF/UA 判定を reader の validate_tagged から移管したのも同じ理由 (reader は構造ツリーを報告する、本サーバが判定する)

アーキテクチャの要点

index.ts(stdout-guard を最初に import)→ tools/index.ts で全ツール登録
  各 tools/*.ts : zod スキーマ + ハンドラ(parse → service → renderBody)
    renderBody: json はそのまま・markdown だけ CHARACTER_LIMIT で切る(v0.29.0 / #18)
  services/     : 判定ロジック本体
  utils/        : formatter(markdown 化)・error-handler・logger
  • ツール追加は tools/xxx.ts を作り tools/index.ts の registerAllTools に 1 行
  • 依存は軽量に保つ(pkijs / asn1js / pdf-lib / zod のみ)。 pdfjs は入れない — reader の領分であり、判定に必要な範囲は pdf-lib で足りる

落とし穴(知らないと壊すもの)

1. stdout-guard.ts は必ず最初の import

MCP は stdout で JSON-RPC を話すため、依存ライブラリの console.log 1 つで通信が壊れる。 ESM は import を巻き上げるので、index.ts に直書きしても手遅れ(依存モジュールの評価が先に走る)。 副作用専用モジュールとして切り出し、他のどの import よりも先に置くこと。この順序を崩さない。

2. veraPDF があるときは委譲する(native は保険)

validate_conformance はハイブリッド。veraPDF(PDF_VERIFY_VERAPDF or PATH)があれば委譲し、 無ければ内蔵ルールを走らせる。内蔵ルールは意図的なサブセットであり、 「全部通った = 適合」ではない。この非対称性は compliant の型に表れている。

enginecompliant
verapdftrue / false(確定)
nativefalse(違反あり=確定)/ null(チェック範囲内で違反なし=適合証明ではない)

null を true に丸めてはいけない。 正直さがこのサーバの価値。

3. native ルールは pdf-lib で届く範囲に限定する

PDF/UA でコンテンツストリーム解析が要る要件(7.1-3 コンテンツの Artifact/タグ付け、 7.2-34 ページ内容の自然言語、7.18.1-1 注釈の Annot タグ内包、7.18.3-1 /Tabs)は 近似せず veraPDF に委ねる。中途半端な近似は誤判定を生み、判定サーバとしての信頼を損なう。

実測(2026-07-16・writer v0.4.0 の出力): veraPDF ua1 は 106 規則で 10 違反、 native 12 規則はそのうち 6 件を検出。native の指摘は veraPDF と矛盾しなかったが、 上記 4 項目は native では届かない。

4. PDF/UA には severity がある(PDF/A には無い)

アクセシビリティは機械で判定しきれない(alt テキストがあるかは検査できるが適切かは不能)。 そのため PDF/UA のネイティブ規則のみ severity: 'error' | 'warning' を持ち、 error だけが compliant: false を確定させる。warning は人間の確認対象。

5. flavour の自動選択は PDF/A 優先

PDF/A-2a + PDF/UA-1 の両方を宣言する文書は実運用で頻出する。 flavour 未指定時は PDF/A を優先し(後方互換)、PDF/UA を宣言していれば notes で pdfua-1 を案内する。 PDF/UA を自動選択するのは「PDF/UA を宣言し、かつ PDF/A を宣言していない」場合のみ。

6. JSON は文字数で切らない(v0.29.0 / #18)

CHARACTER_LIMIT(50,000)が掛かるのは markdown だけ。JSON を途中で切ると isError: false のまま読めない本文が届く。JSON の大きさを抑えるのは配列ごとの件数上限 (MAX_SIGNATURES 32 / MAX_REVISIONS 32 / MAX_FINDINGS 200)で、切ったときは 必ず隣に xxxTruncated: { returned, total } を置く。判定(verdict・compliant・byStatus)は 全件で計算し、一覧だけを切る。例外は verify_signatures で、上限を超えた署名は 検証もしない(重いため)—— evaluate_policy は全件検証する。新しい配列を返す項目を 足すときは、この規律に従うこと。

7. reader に依存しない

実装版 verify は pdf-reader-mcp 非依存(specs/00 の Pattern A は不採用)。 この独立性が A2A 時代の生存戦略であり、北極星(PDF 専門 LLM)における テストオラクルとしての信頼性の根拠でもある。安易に依存を足さない。

テスト

npm test              # vitest(60 件)
npm run typecheck
npm run check         # biome(lint + format)
  • fixture は tests/helpers/signed-pdf.ts のビルダで組む(createSignedPdf(identity, {...}))。 XMP は { xmp: { pdfaPart, pdfaConformance, pdfuaPart } } で宣言を注入できる
  • PDF/UA のテスト(validate-pdfua.test.ts)は pdf-lib で構造木ごと組み立て、 欠陥を 1 つずつ注入して規則を特定する形にしている
  • veraPDF 依存のテストは書かない(CI に veraPDF が無いため)。engine は native で固定する

リリース

  1. package.json の version を上げる
  2. CHANGELOG.md に追記(英語)
  3. コミット → push
  4. git tag vX.Y.Z && git push origin vX.Y.Z → publish.yml が Trusted Publisher (OIDC) で公開

タグと version が一致しないと publish workflow が停止する。

ドキュメント方針

  • README.md = 英語(メイン)、README.ja.md = 日本語。両者を同時に更新する
  • CHANGELOG.md = 英語。判定の変更は何を検出できるようになったか / 何は依然できないかを書く
  • 判定の限界を隠さない。「できないこと」の明示がこのサーバの信頼性そのもの

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.