PDF Writer (PDF Agent Stack)

pdf-writer-mcp

日本語

テキスト、Markdown、表形式データからPDFを作成し、既存のPDF（メタデータとページ操作）を編集するMCP サーバーです。normativepdfを基盤としており、あらゆる動作がISO 32000の条項に結び付けられた、条項駆動型のPDFライブラリです。harfbuzzによるサブセット化を利用したCJKフォントの埋め込みにも対応しています。

PDFファミリーの一員であり、pdf-reader-mcp（構造分析）とpdf-verify-mcp（真正性の検証）とともに提供されています。pdf-reader-mcpがPDFに何が含まれているかを伝え、pdf-verify-mcpが本物かどうかを伝えるのに対し、pdf-writer-mcpはPDFを作成するツールです。

ツール

重要

すべてのファイルパスは絶対パスである必要があります（v0.7.0以降）。相対パスと..を含むパスは拒否されます。相対パスはMCPホストの作業ディレクトリを基準に解決されますが、そのディレクトリは想定している場所ではない可能性があります。これはinputPath、inputPaths、outputPath、outputDir、fontPath、attachmentPathに適用されます。100 MBを超える入力PDFも拒否されます。

作成

ツール	目的
create_text_pdf	プレーンテキスト — \nを処理し、空行で段落を分け、長い行を折り返します
create_markdown_pdf	Markdown — 見出し、段落、箇条書き／番号付きリスト、コードブロック、引用、罫線、表
create_table_pdf	罫線付きの表 — 列幅の自動調整、セル内の折り返し、ページ区切りをまたいだヘッダーの繰り返し

共通オプション：outputPath、returnBase64、fontPath、fontSize、pageSize（A4/A3/A5/LETTER/LEGAL）、margin、title、author、onMissingGlyph、tagged、lang、pdfVersion。

PDF 2.0出力（v0.16.0）

pdfVersion: "2.0"を渡すと、ISO 32000-2ファイルを書き出します。デフォルトは引き続き"1.7"で、そのバイト列に変更はありません。

バージョンは単なるヘッダーではありません。ISO 32000-2では、これに2つの要件が伴い、どちらも満たしています。

• **トレーラーの/ID**が必須になります（表15）。初回の書き込みでは両方の要素が等しく（R-14.4-6）、値はSOURCE_DATE_EPOCHを設定しても決定論的です。
• Info辞書にはCreationDateとModDateのみが残ります（§14.3.3）。タイトル、作成者、プロデューサーはXMPメタデータストリームに移されます。PDF 2.0では、文書メタデータはここに置くことになっています。

{ "text": "Body.", "title": "Report", "pdfVersion": "2.0" }

tagged: trueとの併用はできません。このサーバーが出力する唯一のアクセシビリティ宣言はPDF/UA-1（ISO 14289-1）で、PDF 1.7を基盤としています。これを2.0ファイルに含めると、何によっても測定できない適合性の主張になってしまいます。PDF/UA-2の出力は未実装のため、黙って生成するのではなく、この組み合わせは拒否されます。

タグ付き PDF / PDF/UA（v0.5.0）

tagged: true を渡すと、**PDF/UA-1（ISO 14289）**に準拠した、アクセシビリティ対応のタグ付き PDF を生成します。出力は veraPDF（--flavour ua1、106/106 ルール）で準拠していることが検証されます。

{ "markdown": "# Title\n\nBody.", "title": "Report", "tagged": true, "lang": "en" }

Markdown は構造ツリーにマッピングされます。見出し → H1–H6、リスト → L/LI/LBody、表 → Table/TR/TH/TD（ヘッダーには /Scope が設定されます）、引用 → BlockQuote、コード → Code となります。罫線、境界線、コードの背景はアーティファクトになります。見出しレベルは、H1 から始まり、途中を飛ばさないよう正規化されます。Markdown の # → ### という飛び越しは、構造上は H1 → H2 になりますが、見た目のサイズは記述どおりに保たれます。

PDF/UA では文書タイトルが必須のため、tagged: true を指定するには title が必要です。lang（BCP 47）は省略するとテキストから推定され、warnings で報告されます。誤った /Lang はスクリーンリーダーの読み上げを誤らせるため、わかっている場合は明示的に指定してください。

メモ

タグ付けはオプトイン方式です。デフォルトの出力に変更はありません。

機械による検証（veraPDF）で確認できるのは、要素が存在するかどうかだけです。読み上げ順序や代替テキストが適切かどうかは判断できないため、人による確認も引き続き重要です。

編集 — ページ操作

ツール	目的
merge_pdfs	2～50 個の PDF を順番に連結します。メタデータは最初のファイルから引き継がれます
split_pdf	ページ範囲ごとに 1 つの出力ファイルを作成します
extract_pages	指定した順序でページを抽出します（並べ替えにも使用できます）
delete_pages	ページを削除します（すべてのページの削除は拒否されます）
reorder_pages	全ページを明示的な順列に従って並べ替えます
rotate_pages	既存の回転に加算する形で時計回りに回転します（90/180/270）。インプレースで編集するため、以下の警告は適用されません

警告

rotate_pages 以外の 5 つのツールは、各ページから文書を再構築します。

• 引き継がれるもの：添付ファイル（/Names /EmbeddedFiles、/AF）、/Lang、/ViewerPreferences、/OutputIntents
• 引き継がれないもの：タグ付き構造ツリー、XMP、ページ番号やページ参照に関連するもの（ブックマーク、ページラベル、名前付き移動先）
• 失われたものはすべて warnings で報告されます。何も通知なく消えることはありません

ページ指定には "1,3-5,8-" を使います（1 始まり。-3 は 3 ページ目まで、8- は 8 ページ目から最後までを意味します）。順序は保持され、重複は削除されます。

編集 — ドキュメントの追加と修復

ツール	目的
set_metadata	Info 辞書のフィールド（title / author / subject / keywords / creator）を更新し、その他の内容は保持します。XMP を含むドキュメントでは、dc:title なども同期されます（PDF/UA および PDF/A の宣言は保持されます）。tdmReservation（0 | 1）と tdmPolicy は、W3C TDMRep の権利表示を XMP（tdm:reservation / tdm:policy、名前空間 http://www.w3.org/ns/tdmrep/）に書き込みます。XMP のないドキュメントには XMP が追加され、PDF/A ドキュメントには pdfaExtension:schemas で説明されているスキーマも追加されるため、ISO 19005-2 6.6.2.3 に関する veraPDF の検証エラーを防げます（v0.22.0）
add_bookmarks	アウトライン（ブックマーク）を設定します。children で階層化でき、既存のアウトラインは置き換えられます
add_annotation	付箋（text）、highlight、または square 注釈を追加します。タグ付き PDF では、注釈は Annot 要素内にネストされ、PDF/UA 準拠が維持されます。説明を記述するには alt を渡します
attach_file	ファイルを埋め込みます（/Names /EmbeddedFiles + カタログ /AF + /AFRelationship）。PDF/A-3 の形式です
stamp_page_numbers	ページ番号（{n} / {total}、6 つの位置、pages、startAt）を押印します。タグ付き PDF ではアーティファクトになるため、適合性が保たれます
fill_form	AcroForm フィールドに入力します。日本語の値には埋め込みフォントを使用でき、同じ処理でフラット化することもできます
flatten_form	フォームを静的コンテンツにフラット化します。デフォルトでは、タグ付き PDF（PDF/UA に違反するため）は拒否されます
tag_form_fields	PDF/UA-1 用に、タグ付き PDF 内のフォームを修復します（ウィジェットを Form 内にネストし、/Tabs S を設定し、/TU 代替名を追加します。人が読める名前を付けるには labels を渡します）。冪等です
ensure_tagged	既存の PDF を PDF/UA-1 コンテナーに格納します → タグのない PDF のスキャフォールディング
ensure_pdfa	既存の PDF を PDF/A-3b / PDF/A-4 / PDF/A-4f コンテナー（flavour）に格納します → アーカイブ用コンテナー
add_watermark	斜めの透かし（「社外秘」/「DRAFT」）を重ねます。デフォルトでは本文コンテンツの背面に配置され、タグ付き PDF ではアーティファクトになります

共通オプション：outputPath、returnBase64、allowBreakingSignatures。

重要

署名済み PDF の編集：通常の保存ではファイル全体が書き換えられるため、編集すると通常は既存の署名が無効になります。/ByteRange を含む PDF は、デフォルトで拒否されます。

• preserveSignatures: true — ISO 32000 の増分更新を追記し、すべての署名を有効なまま維持します（元のバイト列は変更されません）。ドキュメントに追加を行うすべての編集ツールでサポートされています：add_annotation、set_metadata、add_bookmarks、tag_form_fields、ensure_tagged、attach_file、stamp_page_numbers、add_watermark（タグ付き PDF では、構造ツリーの変更も同じ増分更新に含まれます）
• allowBreakingSignatures: true — 破壊的な変更を続行し、署名を無効にします
• 認定レベルで変更が許可されていない場合、認定済みドキュメント（DocMDP）は拒否されます（§12.8.2.2）

検証結果：実際に署名された PDF に増分更新を重ねても、pdf-verify-mcp の報告は VALID のままで、タグ付き PDF の増分的な構造更新も veraPDF で COMPLIANT (106/106) を維持します。

タグなしPDFの骨組み作成（ensure_tagged）

ensure_tagged は既存のPDFをPDF/UA-1コンテナーに格納します。タグ付きの入力では構造ツリーを変更せず、文書レベルで不足している要件（MarkInfo、/Lang、DisplayDocTitle、XMP）のみを修復します。構造ツリーがない文書では、最小限の骨組みを作成します。各ページのコンテンツを単一の P 要素でラップすることで、支援技術からテキストにアクセスできるようになり、veraPDFにも合格します（測定値：106/106）。

警告

これは骨組みであり、アクセシビリティ対応ではありません。 機械は意味を推測できないため、見出し、リスト、表、読み上げ順、図の代替テキストは生成されません。ツールは warnings でその旨を通知します。（コンテンツを Artifact でラップしてもveraPDFには合格しますが、スクリーンリーダーから本文が隠されます。これは適合性を装う行為であり、意図的に実装していません。）元データを管理できる場合は、tagged: true を指定した create_* で実際の構造を生成できます。ensure_tagged は、渡された文書に使用するものです。

アーカイブ用コンテナー（ensure_pdfa）

ensure_pdfa は、ensure_tagged に対応するアーカイブ用（PDF/A-3b）機能です。文書レベルの要件のみを追加します。

• トレーラーの /ID（ISO 32000-1 §14.4）
• sRGB出力インテント（GTS_PDFA1。ICCプロファイルを生成して埋め込みます）
• XMPの pdfaid 宣言（作成日はInfoの /CreationDate から引き継がれます）

警告

コンテンツストリーム、フォント、構造ツリーは変更されないため、これによってPDFが適合するようになるわけではありません。宣言を書き込んだ後、適合性を測定してください。pdf-verify-mcpの validate_conformance(flavour: "pdfa-3b") で検証できます。電子帳簿保存のサンプルで測定した結果：veraPDF 146/146 COMPLIANT、PDF/UA-1も引き続き106/106、添付ファイルも保持されました。

v0.17.0以降、主張がすでに誤りだと判明している場合、結果には declarationRisks も含まれます。現在報告されるリスクは FONT_NOT_EMBEDDED のみです。PDF/Aではすべてのフォントの埋め込みが必要ですが、ensure_pdfa はフォントを埋め込まないため、標準の14書体を使って描画された文書は、文書レベルの構造がどれだけ正しくても検証に失敗します。宣言は引き続き書き込まれ、判定はveraPDFに委ねられますが、呼び出し側は警告文を解析せずにリスクに応じた分岐ができるようになりました。

PDF/A-4（v0.16.0）

flavour: "pdfa-4" は、代わりにISO 19005-4を対象とします。PDF 2.0をベースとしているため、上記3項目に加えてヘッダーを2.0に書き換え、Info辞書を削除します。PDF/A-4では、カタログに /PieceInfo がない限りInfo辞書は許可されておらず、これはISO 32000-2 §14.3.3より厳しい要件です。PDF/A-4には適合レベルがないため、pdfaid:rev は書き込まれますが、pdfaid:conformance は書き込まれません。

文書に添付ファイルがある場合は、"pdfa-4f" を使用してください。 通常のPDF/A-4では、埋め込まれた各ファイルもPDF/Aである必要があります。そのため、電子帳簿保存の場合のようにCSVやJSONを添付すると、不適合になります。"pdfa-4f" は、まさにその場合に使用するバリアントです。

veraPDF 1.30.0で測定した結果：pdfa-4 は 109/109 COMPLIANT、同じ文書にCSVを添付した場合は pdfa-4 で108/109ですが、pdfa-4f では 109/109 です。

preserveSignatures は、入力がすでにPDF 2.0でない限り、PDF/A-4のフレーバーでは拒否されます。増分更新ではファイルのバイト0を書き換えられず、書き換えれば保持するはずの署名が壊れてしまうためです。

インストール

{
  "mcpServers": {
    "pdf-writer": {
      "command": "npx",
      "args": ["-y", "@shuji-bonji/pdf-writer-mcp@latest"],
      "env": {
        "PDF_WRITER_FONT": "/absolute/path/to/NotoSansJP-Regular.otf"
      }
    }
  }
}

PDF_WRITER_FONT を設定すると、すべてのツールで fontPath を省略してもCJKテキストを描画できます。

ヒント

@latest を使用するか、バージョンを固定してください。 バージョンを指定せずに npx -y <pkg> を実行すると、初回にキャッシュされたものがそのまま使われ続けます。-y はインストール確認を省略するだけで、更新を確認するものではありません。バージョンを指定しない指定子では、数か月前のリリースがそのまま実行されることがあります。@latest を使うと、npxは起動のたびにレジストリを確認します。再現性を確保したい場合は、代わりに @0.5.0 のようにバージョンを固定してください。古いキャッシュを削除するには、rm -rf ~/.npm/_npx を実行します。

フォント

標準の PDF フォント（Helvetica）がカバーするのは ASCII のみです。日本語やその他の非ラテン文字を描画するには、fontPath または PDF_WRITER_FONT に、埋め込み可能な単一フェイスのフォント（.ttf / .otf）を指定してください。

• 推奨される入手先：Noto Sans JP (SubsetOTF/JP) — 静的、単一フェイス、SIL OFL。

• .ttc（TrueType Collection）はサポートされていません — ファイルは検出され、拒否されます。まず単一フェイスを抽出してください。

  python3 -c "from fontTools.ttLib import TTCollection; \
    TTCollection('NotoSansCJK-Regular.ttc').fonts[0].save('NotoSansCJKjp-Regular.otf')"
  

欠落グリフ

フォントに含まれない文字（例：Noto Sans JP に含まれない ✔ U+2714）は、通常 .notdef として埋め込まれ、何も表示されない空白になります。onMissingGlyph で動作を指定します。

値	動作
error（デフォルト）	エラーにし、該当する文字を "✔" (U+2714) のように表示します
replace	〓 に置き換え、warnings で報告します
ignore	空白として描画し、warnings で報告します

結果

{
  "path": "/abs/out.pdf",     // when outputPath is given
  "base64": "JVBERi0xLj...",  // when returnBase64, or outputPath is omitted
  "pageCount": 3,
  "bytes": 91788,
  "font": "NotoSansJP-Regular.otf",
  "warnings": ["Replaced 1 unsupported character(s) with \"〓\": \"✔\" (U+2714)"]
}

編集ツールは font を含まない同じ形式を返します。split_pdf は { files: [...], count } を返します。

エラー（v0.7.0）

エラーは構造化されており、pdf-reader-mcp と同じ契約に従います。プログラム向けの安定した code に加え、LLM エージェントが実行できる next_actions を提供します。Writer 固有のガードはすべて、明示的なフラグを指定して再試行可能な形で表現されます。

{
  "error": "\"/in/signed.pdf\" appears to be digitally signed (/ByteRange found). …",
  "code": "SIGNED_PDF",
  "retryable": true,
  "next_actions": [
    {
      "action": "retry_with_allowBreakingSignatures",
      "reason": "Only if invalidating the signature is acceptable…",
      "example": { "allowBreakingSignatures": true }
    }
  ]
}

コード：INVALID_ARGUMENT、DOC_NOT_FOUND、FONT_NOT_FOUND、INVALID_PDF、ENCRYPTED_PDF、UNSUPPORTED_PDF_FEATURE（XFA）、FILE_TOO_LARGE、INTERNAL_ERROR、および Writer のガードである SIGNED_PDF（allowBreakingSignatures）、TAGGED_PDF（allowBreakingTags）、FONT_REQUIRED（fontPath）、MISSING_GLYPH（onMissingGlyph）。

決定論的な出力（v0.7.0）

SOURCE_DATE_EPOCH 環境変数（reproducible-builds.org の規約に従う UNIX 秒）を設定すると、CreationDate、ModificationDate、および XMP のタイムスタンプを固定できます。同じ入力からはバイト単位で同一の出力が生成されるため、差分確認、キャッシュ、再現可能なテストに役立ちます。無効な値は無視されず、エラーになります。

テキスト抽出

生成された PDF は、選択、コピー、検索が可能で、スクリーンリーダーにも対応しています。埋め込みサブセットフォントでも ToUnicode CMap（§9.10.3）が書き込まれます。これは回帰テスト（extract.test.ts、render.test.ts）で確認されています。

メモ

v0.13.x 以前の出力では、poppler ベースのビューアーに Mismatch between font type and embedded font file と表示されることがありました。これは実際の適合性の不具合（W-2：CFF フォントが FontFile2 経由で埋め込まれる）の症状でしたが、v0.14.0 で修正済みです。現在の出力ではこの警告は表示されません。

開発

npm install
npm run build      # emits dist/
npm test           # vitest
npm run typecheck  # tsc --noEmit

TEST_FONT_PATH に CJK フォントを指定すると、フォント依存のテストが有効になります。

TEST_FONT_PATH=/path/to/NotoSansJP-Regular.otf npm test

既知の制限事項

• インラインスタイル：太字／斜体はサイズとグリフテキストにのみ影響し、書体には影響しません。ドキュメントごとに埋め込まれるフォントは 1 つです。
• .ttc フォントでは、単一フェイスを抽出する必要があります（上記参照）。
• title と本文の最初の見出しは、どちらも H1 になります（B-19）。これは PDF/UA 7.4.2（H1 から始め、レベルを飛ばさない）を満たし、veraPDF にも合格しますが、構造ツリーを読み戻して再生成すると見出しが重複します。
• リストの /Lbl は出力されません（B-18）。箇条書きと番号は本文テキストに含まれます。ISO 32000-2 §14.8.4.8.2 では Lbl は必須ではなく「多くの場合に含まれる」とする NOTE であるため、これは規格に準拠しています。ただし、読み戻した内容から再生成するとマーカーが重複します。

解決済み：

• サブセット名のプレフィックス（ABCDEF+）は、v0.14.0（W-3）以降で適用されます。これに反する以前の制限事項は、現在は該当しません。
• snake_case のアンダースコアが削除される問題（B-17）は、2026-07-21 に修正済みです（次のリリースに含まれます）。_ による強調は、語中以外でのみ有効になり、コードスパンが先に保護されるため、日本語_変数名 のような非 ASCII の識別子も保持されます。

ロードマップ

• 編集 Tier A 第1弾 — メタデータとページ操作（v0.2.0）
• 編集 Tier A 第2弾 — ブックマークと注釈（v0.4.0）
• タグ付き PDF / PDF/UA-1 — veraPDF による検証済み（v0.5.0）
• タグ付き出力で Annot タグ内にネストされた注釈（v0.5.1）
• 編集 Tier B — ファイル添付、フォーム入力／フラット化、透かし、ページ番号のスタンプ（v0.6.0）
• コード衛生／ファミリーとの整合 — McpServer + Zod、構造化エラー、絶対パスの適用、stdout ガード、ツールのアノテーション、決定論的な出力（v0.7.0）
• tag_form_fields — タグ付き PDF のフォームに対する PDF/UA 修復。veraPDF による COMPLIANT の検証済み（v0.8.0）
• Tier C の最初のマイルストーン — add_annotation の署名を保持する増分更新。実際の CMS 署名を用いて pdf-verify-mcp による検証済み（v0.9.0）
• 増分更新を set_metadata / add_bookmarks に拡張し、トレーラー全体を引き継ぎ（§7.5.6）、XMP と Info の同期を維持（v0.10.0）
• タグ付き PDF の増分更新 — 構造ツリー全体にわたる変更追跡を一般化し、tag_form_fields に preserveSignatures を追加（v0.11.0）
• すべての編集ツールに増分更新を適用し、ensure_tagged — PDF/UA のスキャフォールドと修復を追加（v0.12.0）
• ページ操作で文書レベルの情報を報告して引き継ぐようにし、ISO 32000-2 に照らした再監査で shall 違反を3件発見（v0.13.0）
• ページ操作で構造ツリーを引き継ぐ（これにより MarkInfo、適合性を宣言する XMP、/AcroForm、複数の入力間での添付ファイルの統合も可能になります）
• Tier C の残り — edit_text（本文テキストの編集／リフロー）
• 公開パイプラインスキル（書き込み → pdf-reader で読み戻し → pdf-verify でゲート）
• 代替テキスト付き画像（Figure + /Alt）
• .ttc からの自動フェイス抽出
• 見出しと本文に別のフェイスを使用（ボールドフェイスの埋め込み）
• 画像の埋め込み、ヘッダー／フッター
• Tier C — 署名を保持する増分更新、本文テキストの編集、タグツリーの保守
• PDF/A への変換

ライセンス

MIT © shuji-bonji