Pdfnative

pdfnative-mcp

PDF 生成、PDF/A アーカイブ、PDF/X-4 印刷用データの交換、高度なタイポグラフィ、長期検証に対応した PAdES 署名、AcroForms、結合／分割、暗号化、レイアウトプレビューのための MCP サーバー — pdfnative エンジン（依存関係ゼロ、ISO 32000-1 準拠）を利用した 28 個のツールと 7 個のプロンプト。Claude Desktop、Cursor、ChatGPT、およびあらゆる Model Context Protocol クライアントに対応しています。

---

✨ 特長

pdfnative-mcp は、あらゆる MCP ホストに本番環境向けの 28 個のツールを提供します。

ツール	目的
generate_basic_pdf	13 種類のブロック（heading、paragraph、list、table、image（JPEG/PNG）、link、toc（印刷用目次）、barcode、svg、formField、chart、pageBreak、spacer）から複数ページのドキュメントを作成します。エンジンが提供するすべての DocumentBlock に対応しています。埋め込みの改行は自動的に段落に分割されます。オプションで pdfA、pdfx（v1.7.0 で追加）、print、metadata、embedFonts、watermark、outline、レイアウトオプション（pageSize、margins、headerTemplate / footerTemplate、compress、debug、encrypt）、typography（v1.7.0 で追加）、CMYK カラー（v1.7.0 で追加）を指定できます。
inspect_layout (v1.6.0 で追加)	同じ blocks（および title、footerText、pdfA、normalize、embedFonts、pageSize、margins、headerTemplate、footerTemplate、typography）を使った、読み取り専用のページネーションのドライランです。PDF を生成せずに、ページ数と各ブロックの配置先を確認できます。
add_barcode	QR Code、Code 128、EAN-13、Data Matrix、PDF417 を 1 ページの PDF に埋め込みます。
add_international_text	27 種類の Unicode 文字体系（Lao、Tai Tham、New Tai Lue、Tai Le、Cham（v1.7.0 で追加））に加え、Latin、数学記号、COLRv1 カラー絵文字（国旗／ZWJ シーケンス、肌の色の修飾子）に対応し、BiDi と OpenType シェーピングをサポートします。ドキュメント内で複数言語を使用できます。
add_table	スマートフィールド（wrap、repeatHeader、zebra、caption、minRowHeight、cellPadding）を使った表形式のレポートを作成します。
add_form	テキストフィールド、テキストエリア、チェックボックス、ラジオボタン、ドロップダウン、リストボックス（placeholder のヒントテキスト付き）を備えた新規のインタラクティブな AcroForm PDF を作成します。
read_form_fields	既存の AcroForm のフィールドツリー（名前、種類、値、ウィジェット）を読み取り専用で列挙します。
fill_form	既存の AcroForm に入力し、必要に応じてフラット化します（非破壊の増分更新）。
add_chart	ネイティブのベクターチャート v2（bar / barH / stackedBar / stackedBarH / line / area / scatter / pie / donut）、第 2 軸、対数・時間スケール、データラベルに対応します（純粋な PDF パス演算子を使用し、PDF/A に安全です）。
embed_image	JPEG または PNG 画像（base64）をタイトル付き PDF ドキュメントに埋め込みます（タグ付き出力では align、代替テキストを指定できます）。
prepare_signature_placeholder	署名ワークフローの任意のステップ 1 です。/Sig プレースホルダーを含む PDF を作成します（署名者メタデータ、subFilter、reserveTimestamp を組み込みます）。
sign_pdf	PAdES B-B / B-T CMS 署名（RSA-SHA256/384/512、ECDSA-SHA256 P-256、profile: 'pades'、timestamp、certChainDerBase64、複数署名、固定可能な signingTime）を行います。必要に応じてプレースホルダーを自動挿入します。
add_ltv (v1.6.0 で追加)	PAdES B-LT に対応します。証明書と OCSP/CRL データを含む /DSS を埋め込みます（運用者が設定したプロバイダー、または呼び出し元が提供するオフラインデータを使用します）。
timestamp_pdf (v1.6.0 で追加)	運用者が設定した TSA から RFC 3161 /DocTimeStamp を追加し、PAdES B-LTA に対応します。アーカイブチェーンを拡張するには、再実行します。
verify_pdf	すべての PAdES 署名とドキュメントタイムスタンプを検証します（整合性、署名値、任意の証明書チェーンの信頼性を確認します。/DocTimeStamp は他の署名と同様に allValid に含まれます）。ltv: true を指定すると B-B…B-LTA レベルを報告します。
validate_pdf	Tagged PDF の PDF/UA（ISO 14289-1）構造適合性を検証します。または standard: 'pdf-x-4'（v1.7.0 で追加）を指定すると、PDF/X-4（ISO 15930-7）の構造上の前提条件を検証します。読み取り専用であり、認証済みのプリフライトではありません。
add_attachment	ファイルを埋め込んだ PDF/A-3 ドキュメント（Factur-X / ZUGFeRD 請求書）を生成します。
extract_attachments	埋め込みファイルを読み取り専用で抽出します（Factur-X / ZUGFeRD XML のラウンドトリップ）。ペイロードはバイト単位で一致します。
extract_text	Unicode テキストを抽出します（/ToUnicode を解決）。オプションで位置情報付きのテキストランに対応し、password を使って暗号化された PDF を開けます。
inspect_pdf	読み取り専用の検査を行います。PDF バージョン、ページ数、暗号化（および詳細な encryptionInfo）、PDF/A の宣言、PDF/X の宣言（pdfX、v1.7.0 で追加）、署名（一覧、/DSS、ドキュメントタイムスタンプを含む）、ページボックス、/Trapped、添付ファイル、プレースホルダーの状態、annotations: true 指定時の既存ページ注釈の一覧を確認できます。
update_metadata (v1.6.0 で追加)	既存の PDF の /Info タイトル／作成者／件名／キーワード（XMP、日付を含む）を書き換え、増分更新を行います。再現可能なバイト列にするには modDate を固定します。
encrypt_pdf	PDF を AES-128 / AES-256 で再保護します（所有者／ユーザーパスワード、権限、パスワードのローテーションに対応）。
decrypt_pdf	RC4 / AES-128 / AES-256 で暗号化されたドキュメントの、暗号化されていないコピーを出力します。
merge_pdfs	pdfnative のページツリー API を使って 2～50 個の PDF を 1 つに結合します（ページボックスを保持します）。
split_pdf	1 つの PDF をページ範囲ごとに分割し、複数のドキュメントを出力します。
extract_pages	任意のページを選択して、1 つの PDF に抽出します。
annotate_pdf	マークアップ注釈（ハイライト、メモ、四角形／円、線、フリーテキスト）を視覚的なオーバーレイとして追加します。墨消しではありません。
draft_governance_issue	ガバナンス要件に準拠した GitHub イシューの下書きをローカルで作成し、人間によるレビューに回します。送信は行わず、ネットワークも使用しません。
New in v1.7.0:

• 🔤 細かなタイポグラフィ制御 — 9つのドキュメントツールと inspect_layout でオプトインできる typography オブジェクトを追加しました。splitParagraphs では orphans／widows、keepHeadingsWithNext、unitBinding、bindShortWords、punctuationSpacing（'fr'、'fr-CA'、または明示的なルール）、opticalMargins、metrics: 'exact'、fontFeatures（11個のOpenTypeタグ）、kerning、hyphenationLanguage を指定できます。段落ブロックには align（left／right／center／justify）、keepWithNext、splittable が追加され、見出しブロックには keepWithNext が追加されました。制約については正直にお伝えします。kerning、fontFeatures、'fr' の狭いノーブレークスペースには embedFonts: true が必要です（ベース14フォントのHelveticaでは、'fr' は 'fr-CA' に切り替わります）。同梱のNoto Sansでは tnum／lnum による変化はありません（診断コード TYPOGRAPHY_FEATURE_INEFFECTIVE）。ハイフネーション辞書はインストールされていないため、ここでは hyphenationLanguage の効果はありません。ソフトハイフン（U+00AD）は認識されます。詳細は docs/guides/TYPOGRAPHY.md を参照してください。

• 🎨 色を受け付けるすべての場所でCMYKに対応 — 既存の16進数／RGB形式に加えて、'c m y k' オペランド文字列（0～1）と [c, m, y, k] パーセントタプル（0～100）を使用できます。対象は、透かし、ヘッダー／フッターのテンプレート、表のセル枠線、アウトライン項目、グラフ、link ブロックと svg ブロック、annotate_pdf です。1.6.0のすべての色形式も引き続き検証されます。

• 🖨️ PDF/X-4 — 6つの生成ツール（generate_basic_pdf、add_table、add_chart、add_barcode、embed_image、add_international_text）で pdfx: 'pdfx4'を指定できます。RGBに加えてCMYKまたはGrayのoutputIntent プロファイルを指定でき、print.marks.colourBars を利用できます。また、validate_pdf { standard: 'pdf-x-4' } で結果を検証できます。inspect_pdf は適合宣言を報告します（pdfX、チェック項目 'pdfx'）。プリンターのICCプロファイル（デバイスクラス prtr）が必要ですが、**同梱されていません**。適合ファイルにするには embedFonts: trueが必要です（指定しない場合はPDFX_NO_FONT_ENTRIES が返され、strict: true では拒否されます）。また、pdfAおよびencryptとは併用できません。検証は構造に基づくもので、**認定済みのプリフライトではありません**。その旨は結果のcaveats[] に記載されます。詳細は [docs/guides/PRINT.md`](docs/guides/PRINT.md) を参照してください。

• 🌏 27種類のUnicodeスクリプト — add_international_text で lo（ラオ語）、nod（タイ・タム文字）、khb（新タイ・ルー文字）、tdd（タイ・レー文字）、cjm（チャム語）を使用できます。ha、yo、ig、sw は latin の別名です（声調記号は文字に結合します）。絵文字の肌の色修飾子も描画されます。PDF/Aでは、タイ・タム文字に pdfa2u ではなく pdfa2b を使用する必要があります（上流で1つのグリフに ToUnicode エントリーがありません）。

• 🔁 どのホストでも再現可能 — すべての日付はUTCで書き込まれ、ヘッダーまたはフッターの {date} は固定された時刻に従います。また、実行者は PDFNATIVE_MCP_CREATION_DATE または SOURCE_DATE_EPOCH を設定してプロセス全体の時刻を固定できます（環境変数を参照）。設計上、対象外となるもの：signingTime、modDate、RFC 3161トークンと失効データ、暗号化、ECDSA署名。詳細は docs/guides/REPRODUCIBLE.md を参照してください。

• 🚦 strict は診断コードに応じて重大度を引き上げます — PDFA_* → PDF_A_COMPLIANCE_VIOLATION、PDFX_* → PDF_X_COMPLIANCE_VIOLATION（新規）、それ以外 → DIAGNOSTIC_ESCALATED（新規）。この2つの新しいコードは、strict: true を設定した呼び出しでのみ返されます。

• 🧩 7つ目のMCPプロンプト typography — print_ready、reproducible_output、pdfa_valid をCMYK、PDF/X-4、カラーバー、UTC／実行者による時刻固定に対応するように書き換えました。

• 🐛 修正 — 0～1のRGBトリプル（watermark.color、annotate_pdf の色）が、指定した色で描画されるようになりました（以前は [1, 0, 0] をほぼ黒で描画していました）。PDF入力を受け取るツールで予期しないエラーが発生した場合、コードなしで表面化せず、PDF_PARSE_FAILED に分類されるようになりました。

• ✅ 上流の問題を解消 — embedFonts: true で作成されたPDF/AフォームがveraPDFで検証に合格するようになりました（AcroFormのフォントが埋め込まれます）。また、inspect_layout は toc ブロックを、ビルド時のレイアウトと同じように正確に測定するようになりました。

• 🧪 単一のゲート、強化されたCI、検証済みドキュメント — npm run gate が成功の唯一の判定基準です（ビルド済みサーバーをstdio経由で実行し、stdoutにはJSON-RPCフレームのみが含まれる必要があります）。veraPDFは41ファイルの適合性コーパスに対するブロッキング検査になりました。96サンプルのバイトベースラインで出力を保護します。npm run verify:docs により、ドキュメントに記載されたすべての件数、バージョン、ツール、エラーコード、実行者向け変数が docs/assets/ecosystem.json およびソースツリーと一致することを確認します。

• 🧾 カタログ — tools/list は約306 kBになりました（タイポグラフィ用フラグメントと拡張された色スキーマは、該当する各ツールにインラインで含まれます）。npx tsx scripts/tool-shape.ts --check により、サイズは320 KiB未満、説明は8 KiB未満に保たれます。_meta.apiVersion は 1.7.0 です。

• ⬆ エンジンのアップグレード — pdfnative v1.8.0。ツールAPIに破壊的変更はありません。変更されるバイト列（埋め込みTrueTypeサブセット、print.marks、マーク位置調整を適用したシェイプ済みテキスト、UTCの日付）については、release-notes/v1.7.0.md の Upgrade を参照してください。 New in v1.6.0:

• 🧱 すべてのエンジンブロックに対応 — 13 種類 — generate_basic_pdf は pdfnative が提供するすべての DocumentBlock を受け付けます。新しい table、image、link、toc、barcode、svg、formField ブロックは、専用ツール（add_table、embed_image、add_barcode、add_form）と本文を共有するため、単独の成果物でもインラインブロックでも、同じように検証・描画されます。ルール：link が受け付けるのは http:／https:／mailto: のみ（制御文字は拒否されます）。image ブロックには上限があります（各ブロックの Base64 文字数は 12 M、1 回の呼び出しでデコードできる合計は 24 MiB。PNG は 8 ビット、非インターレース、アルファチャンネルなし、パレットなしに限り、該当しない場合は修正方法を示して拒否されます）。svg が対応するのはパス、基本図形、<text> です（transform、<g>、グラデーション、CSS はサポートされず、黙って無視されます。外部から取得することはありません）。toc は outline: 'auto' と組み合わせます。PDF/A を指定した状態で formField を使うと、PDFA_UNEMBEDDED_FORM_FONT が報告されます。barcode に alt はありません（エンジンの制約です）。

• 📐 9 つのドキュメントツールで利用できるレイアウトオプション — pageSize（デフォルトは A4、Letter、Legal、A3、Tabloid）、margins（四辺すべて、0～200 pt）、headerTemplate／footerTemplate（{page}、{pages}、{title}、{date} を使用。footerTemplate はデフォルトのフッターを置き換えるため、その場合 footerText は無視されます。1.6.0 では {date} はビルド日の実時刻でしたが、v1.7.0 以降は固定した日時に基づきます）、compress（FlateDecode ストリームを使います。ファイルは小さくなりますが、バイト列は異なります。PDF/A では XMP はプレーンのままです）、debug（ガイド用矩形、マークされていないコンテンツ。PDF/UA では使用しないでください）。デフォルトでは無効なので、デフォルト出力はバイト単位で同一のままです。

• 🔐 ビルド時の暗号化 — 7 つのドキュメントツール（generate_basic_pdf、add_table、add_form、add_international_text、embed_image、add_barcode、add_chart）で encryptを指定できます。標準セキュリティハンドラーを使用し、デフォルトは AES-128、AES-256 にも対応します。**AcroForm を保持します**（ページツリーを再構築するencrypt_pdf とは異なります）。pdfA とは併用できず（VALIDATION_ERROR）、キャッシュされることもありません。署名可能な状態を保つ必要がある prepare_signature_placeholderと、PDF/A-3 用のadd_attachment` では利用できません。

• 📏 inspect_layout — 28 番目のツールです。同じ blocks とレイアウト入力を使う、読み取り専用のページ割り付けのドライランを行い、PDF を描画せずに totalPages と各ブロックのページ、x、top、width、height を報告します。1.6.0 で確認されていたエンジンの問題（v1.7.0 で解消）：toc ブロックが 0 pt として計測されていたため、目次を印刷するドキュメントではプレビューより 1 ページ多く割り付けられることがありました。

• 🔎 inspect_pdf annotations: true — すべてのページ注釈（サブタイプ、0 始まりのページ番号、rect、200 文字で切り詰めた contents、title、colour、quadPoints、リンク URL）と annotationCount を一覧表示します。新しい check: 'annotations' にも対応します。

• 🖼️ 画像のウォーターマーク — generate_basic_pdf と add_table で watermark.image（JPEG／PNG、デフォルトの不透明度は 0.10、独自の上限は 8 MiB）を指定できます。単独でも、text（デフォルトの不透明度は 0.15）との併用でも使用できます。どちらにも position: 'background' | 'foreground' を指定できます。pdfa1b では、いずれかの不透明度が 1.0 未満の場合は拒否されます。

• 🧯 PDFNATIVE_MCP_MAX_INFLATE_BYTES — エンジンのストリームごとの展開上限 100 MiB を、オペレーターが上書きできます（1024 以上の整数。無効な値を指定すると起動を拒否します）。上限に達した添付ファイルのストリームに対して extract_attachments includeData: true を実行すると PDF_PARSE_FAILED になります。extract_text は空のページテキストを返します（エンジンがページごとのデコード失敗を握りつぶすためです）。

• 📝 フォーム — add_form と formField ブロックで listbox と placeholder が使えるようになりました。fieldType: 'textarea' はエンジンに multilineText として渡されるようになりました（以前はマッピングされずに渡され、単一行フィールドとして描画されていたため、これは入力によってバイト列が変わるバグ修正です）。embed_image に align と alt が追加されました。

• 🔏 PAdES 長期検証の段階的対応 — sign_pdf に profile: 'pades'（ETSI EN 319 142-1 ベースライン、ESS signing-certificate-v2、ETSI.CAdES.detached）、timestamp: true（B-T、RFC 3161）、RSA-SHA384／512、複数の署名に対応する certChainDerBase64、fieldName／allowMultiple が追加されました。新しい add_ltv は /DSS を埋め込みます（B-LT。オペレーターのプロバイダーを通す mode: 'online'、または呼び出し元が DER 素材を指定する mode: 'offline'）。新しい timestamp_pdf は /DocTimeStamp を追加します（B-LTA）。verify_pdf ltv: true は、プロファイル、タイムスタンプ、失効状況、ltvLevel を報告します。docs/guides/LTV.md を参照してください。

• 🌐 ネットワークの基本方針 — デフォルトでは外部へのリクエストを行いません。サーバーが外部通信できるのは、オペレーターが設定した RFC 3161／OCSP／CRL エンドポイント（PDFNATIVE_MCP_TSA_URL、PDFNATIVE_MCP_REVOCATION、PDFNATIVE_MCP_NETWORK_ALLOWED_HOSTS）のみで、SSRF ガードによって保護されています。ツール引数で URL を指定することはできません。

• 🖨️ 印刷用の制作機能 — すべてのドキュメントツールが print（TrimBox／BleedBox／ArtBox／CropBox、または bleed の省略形、crop および registration marks、/UserUnit）、metadata（/Author、/Subject、/Keywords、/Trapped）、outputIntent（PDF/A 用のカスタム RGB ICC）を受け付けます。viewerPreferences に duplex、pickTrayByPDFSize、printPageRange、numCopies が追加されました。inspect_pdf pages: true は各ボックスを報告します。結合／分割／抽出でもこれらは保持されます。docs/guides/PRINT.md を参照してください。

• ✍️ update_metadata — 既存 PDF の /Info と XMP を増分更新で書き換えます（以前のリビジョンと署名はそのまま保持されます）。

• 📊 チャート v2 — stackedBar／stackedBarH／area／scatter、右側の第 2 軸（axis2）、axis.scale: 'log'、xAxis.type: 'linear' | 'time'、dataLabels、labelStride／labelRotation に対応します。重なり合うカテゴリラベルは自動的に間引かれます。

• 📜 正確な PDF/A 対応 — embedFonts: true は Noto Sans Latin を埋め込みます（ベース 14 フォントの Helvetica は埋め込まれないため、プレーンなラテン文字テキストに対する PDF/A の指定は veraPDF によって拒否されます）。strict: true は適合しないファイルを出力する代わりに失敗し、includeDiagnostics: true はエンジンの診断情報を返します。ローカルの veraPDF スクリプト（npm run validate:pdfa）は 26 ファイルのコーパスを対象とします（24 件が検証され、そのうち 3 件は失敗を確認するカナリアです。ページツリー出力 2 件はスキップされます）。失敗時に処理を中止する VERAPDF_REQUIRED=1 モードもあります。CI ワークフローはインストーラーを SHA-256 で固定し、1.6.0 ではブロッキングなし（v1.7.0 以降はブロッキングあり。ゲートでは VERAPDF_REQUIRED=1 の代わりに --require-all を使用します）。1.6.0 で確認されていたエンジンの問題：add_form の出力は embedFonts を指定しても PDF/A-2b に適合しません（/DR /Helv が埋め込まれない問題は v1.7.0 で解消）。また、prepare_signature_placeholder の出力は署名後にのみ適合します。

• 🧰 inspect_pdf — signatures: true で署名の一覧を表示し、dss／docTimestampCount／trapped も報告します（存在する場合のみ）。check に新しい値 dss、docTimestamp、trapped が加わりました。checks には要求したキーのみが含まれ、signed は構造上の状態（署名フィールドが存在すること）を示します。署名の有効性の確認は verify_pdf の役割です。

• 🔁 再現可能な出力 — 9 つすべてのドキュメントツールで、任意の creationDate を指定して /CreationDate、XMP の日付、トレーラーの /ID を固定できます。prepare_signature_placeholder（およびタイムゾーンオフセットにも対応した sign_pdf）の signingTime で /Sig /M を固定できます。1.6.0 では同じホストのタイムゾーンであればバイト列が一致し、v1.7.0 以降は日付が UTC で書き込まれるため、すべてのホストで一致します。この機能は reproducible_output プロンプトに基づいています。

• 🛡️ 境界の強化 — 入力スキーマを厳格化しました（未知のキーや誤記されたキーは黙って無視されず、VALIDATION_ERROR になります）。data:…;base64, プレフィックスは許容され、DER 形式の代わりに PEM を指定した場合や二重エンコードされたペイロードは、正確な修正方法を示して拒否されます。ページツリーを扱うツールでページインデックスを誤ると、0 始まりであることを示すヒント付きの VALIDATION_ERROR になります。未知のツール名は JSON-RPC のプロトコルエラー（-32602、[UNKNOWN_TOOL]）になります。

• 🔑 HTTP ベアラートークン — PDFNATIVE_MCP_HTTP_TOKEN を任意で設定すると、Streamable HTTP エンドポイントへのアクセスを制御できます（未設定の場合は 401 と WWW-Authenticate が返されます）。設定しない場合、ループバックエンドポイントに認証はありません。SECURITY.md を参照してください。

• 🧾 カタログ — tools/list は約 245 kB です（1.5.0 では約 108 kB）。すべてのブロック種別、レイアウトオプション、encrypt の断片がインラインで公開されるためです。ポリシーにより $ref／$defs は使わないため、inputSchema を関数呼び出し API に転送するホストが参照に遭遇することはありません。サーバーの指示は約 6.7 kB です（12.9 kB から短縮）。構造は scripts/tool-shape.mjs（v1.7.0 以降は scripts/tool-shape.ts）と tests/catalogue-parity.test.ts によって検証され、tests/catalogue-superset.test.ts は稼働中のカタログが公開済みの 1.5.0 版を包含することを確認します。各ツールの実行可能な _meta.examples は最大 2 件で、残りは examples/ にあります。新しいレシピ用プロンプトが 4 つ追加されました：pades_ladder、print_ready、reproducible_output、pdfa_valid。

• 🐛 修正 — pdfnative 1.7 未満では、署名者のメタデータ（signerName／reason／location／contactInfo）が /Sig 辞書に反映されませんでしたが、プレースホルダーの作成時に組み込まれるようになりました。verify_pdf は、/DocTimeStamp が CMS 署名として解析されていた B-LTA ドキュメントに対して、allValid: false を報告しなくなりました。

• 🔌 MCP 2026-07-28 は MCP TypeScript SDK v2（@modelcontextprotocol/server）を使用し、2025 年当時の initialize ハンドシェイクに自動でフォールバックします。既存のホストは変更なしで引き続き動作します。MCP プロトコルへの準拠を参照してください。

• ⬆ エンジンのアップグレード — pdfnative v1.7.0（LTV、印刷用制作機能、チャート v2、ダイジェスト方式の拡張、フラグおよび ZWJ 絵文字シーケンス、UAX #9 の修正）。 v1.5.0 の新機能：

• 📊 ネイティブのベクターチャート — add_chart は、棒／横棒／折れ線／円／ドーナツチャートを純粋な PDF パス演算子として描画します（ラスタライズなし、自動代替テキスト付きで PDF/A に対応）。generate_basic_pdf では、テキストや表と組み合わせるための chart ブロックも利用できます。

• 📝 フォームへの入力とフラット化 — read_form_fields は既存の AcroForm のフィールドを一覧表示します。fill_form は非破壊的な増分更新でフォームに入力、および／またはフラット化します（add_form に対応する機能です）。

• 🔐 暗号化の相互変換 — encrypt_pdf は AES-128／AES-256 で再暗号化します（RC4 は出力されません）。decrypt_pdf は暗号化されていないコピーを作成します。読み取り専用ツールでは password 入力を指定して暗号化されたソースを開くことができ、merge_pdfs／split_pdf／extract_pages では password と encrypt を指定できます。

• 🔤 実際のテキスト抽出 — extract_text は各フォントの /ToUnicode CMap を解決するようになり（グリフインデックスが出力されることはありません）、位置情報付きの runs も返せます。

• 🔗 ネイティブの MCP リソース — サンドボックス内で生成された PDF は pdfnative://output/… リソースになります（resources/list と resources/read）。ファイルモードの結果には、呼び出しをまたいだ再参照用の resource_link が含まれます。

• 🏷️ ツールのアノテーション — すべてのツールで readOnlyHint／destructiveHint／idempotentHint／openWorldHint を公開します。

• ⬆ エンジンのアップグレード — pdfnative v1.6.0（復号／再暗号化、extractText、入力／フラット化、チャート、カラー絵文字のサブセットが 221 から 1167 グリフに拡大）。

v1.4.0 の新機能：

• 🤝 AI ガバナンス＋ヒューマン・イン・ザ・ループ — draft_governance_issue を使うと、エージェントが準拠した GitHub issue をローカルで下書きできます（下書き .md ＋機械可読な準拠レポート）。エージェントは下書き作成者であり、自律的な送信者ではありません。唯一の承認者は人間であり、サーバーは GitHub に一切書き込みません（v1.6.0 以降は、オペレーターが設定した TSA／OCSP／CRL エンドポイント以外への外部呼び出しも行いません）。governance_contract と draft_issue_workflow MCP プロンプトによって支えられています。
• ✏️ マークアップ注釈 — annotate_pdf は増分更新を使って、既存の PDF にハイライト、付箋、下線、取り消し線、波線、四角形、円、線、フリーテキストの注釈を重ねます。これは視覚的なレビュー用レイヤーであり、墨消しではありません。元のバイト列はそのまま残ります。
• 🔢 inspect_pdf のページラベル — /PageLabels の範囲（ローマ数字、10 進数、接頭辞付き）を読み取り専用で表示します。
• ∑ 数式／科学分野の文字 — add_international_text は lang: 'math' を明示的に指定すると（emoji と同様）、必要に応じて Noto Sans Math フォントを埋め込みます。
• 🧩 MCP プロンプト — サーバーが governance_contract と draft_issue_workflow を含む prompts 機能を公開するようになりました。
• ⬆ エンジンのアップグレード — pdfnative v1.5.0。

v1.3.0 の新機能：

• 🆕 3 つのページツリーツール — merge_pdfs、split_pdf、extract_pages（pdfnative v1.4.0 のページツリー API を基盤としています。暗号化されたソースは、v1.5.0 で password が追加されるまで拒否されていました）。
• 🔖 ブックマーク、ページラベル、ネストされたリスト — generate_basic_pdf に outline（'auto' または明示的なツリー）、pageLabels、複数レベルの list 項目、viewerPreferences が追加されました。
• 📐 表のセル境界線と配置 — add_table に cellBorders、cellVAlign、viewerPreferences が追加されました。add_international_text にも viewerPreferences が追加されました。
• 🔐 定時間署名 — sign_pdf は node:crypto プロバイダーを通じて RSA 鍵と EC-DER 鍵で署名します。透過的な純粋 JavaScript のフォールバックにも対応しています（生の P-256 スカラーは純粋 JavaScript で処理され、検証も純粋 JavaScript で行われます）。署名の相互運用性は維持されます。
• ⬆ エンジンのアップグレード — pdfnative v1.4.0。
• 🆕 ツール extract_attachments — PDF に埋め込まれたファイルを読み出します（Factur-X / ZUGFeRD の往復処理に対応）。バイト単位で完全に一致するペイロード、filename フィルター、メタデータのみを確認する includeData: false に対応しています。
• 💧 ウォーターマーク — generate_basic_pdf と add_table は、すべてのページに描画されるオプションの watermark（テキスト、不透明度、角度、色、位置。v1.6.0 以降は image）を受け付けます。
• 🌐 Unicode の normalize — generate_basic_pdf と add_international_text で NFC／NFD／NFKC／NFKD をオプションで指定できます。
• 🪙 トークン効率の高い読み取り — 読み取り専用ツール（inspect_pdf、verify_pdf、validate_pdf、extract_text、extract_attachments。v1.5.0 以降は read_form_fields も含む）は、オプションの verbosity: 'summary' と fields: […] 入力を受け付けます。大きな結果で応答を約 90％縮小しつつ、エージェントが分岐判断に使うフィールドは保持します。デフォルトの動作は変わりません。
• 🪙 base64 の重複を解消 — 生成された PDF（base64 モード）は、structuredContent にもコピーされることなく、埋め込みの resource コンテンツブロックとして 一度だけ 返されます。
• 🔧 MCP レジストリ公開の修正 — mcpName が正規の GitHub ログイン名の大文字・小文字（io.github.Nizoka/pdfnative-mcp）を使用するようになり、レジストリの大文字・小文字を区別する検証で npm パッケージが受け入れられるようになりました。
• ⬆ 依存関係 — zod 4 にアップグレードしました。

v1.1.0 の新機能：

• 🆕 新しいツール validate_pdf — 読み取り専用の PDF/UA（ISO 14289-1）構造適合性チェックです。
• 🆕 6 つの新しい文字体系 — テルグ文字、シンハラ文字、チベット文字、クメール文字、ミャンマー文字、エチオピア文字（合計 24 種類の文字体系）。
• 🆕 COLRv1 のカラー絵文字 — モノクロフォールバックに対応したネイティブのカラー絵文字です。
• 🆕 改行サニタイザー — 段落内に埋め込まれた \n は、自動的に別々の段落に分割されます（Safe PDF/A）。
• 🆕 add_international_text の自動 NFC 正規化。
• 🛠 エンジンのアップグレード — pdfnative v1.3.0：ユーロ記号／CP-1252 の記号が正しく抽出されるようになり、折り返された表セルには行ごとに固有の MCID が割り当てられます（PDF/UA に安全）。

v1.0.0 の新機能：

• 🆕 3 つの新しいツール： verify_pdf、add_attachment（Factur-X / ZUGFeRD）、extract_text。
• 🆕 スマートテーブルのフィールド： wrap、repeatHeader、zebra、caption、minRowHeight、cellPadding。
• 🆕 inspect_pdf が hasSignaturePlaceholder と添付ファイルごとの概要を報告するようになりました。新しい check 値として 'placeholder' と 'attachments' が追加されました。
• 🆕 署名の利便性向上： sign_pdf は ECDSA SEC1 / PKCS#8 DER キーを受け付け、存在しない場合は /Sig プレースホルダーを自動挿入します（任意の PDF に 1 回の呼び出しで署名できます）。
• 🆕 オプトインのキャッシュ（PDFNATIVE_MCP_CACHE_DIR）：SHA-256 キー、TTL 1 時間、LRU 256 MiB。
• 🆕 AI エージェントによる検出向けの _meta.apiVersion とツールごとの _meta.examples — docs/API_STABILITY.md を参照してください。
• 🆕 AI エージェントガイド： docs/AI_GUIDE.md — 判断ツリーとよくある落とし穴を解説しています。エージェント向け契約書 docs/AGENT_CONTRACT.md（カタログ、判断ツリー、レシピ、エラー表）も参照してください。コントリビューターとコーディングエージェントは AGENTS.md から始めてください。
• 🆕 PDF/A 作成ガイド： docs/guides/PDFA.md。
• 🛠 環境変数名の変更： PDFNATIVE_MCP_OUTPUT_DIR（旧名は PDFNATIVE_MPC_OUTPUT_DIR。旧名も引き続き使用でき、廃止に関する警告が 1 回だけ表示されます）。
• ✅ 提供中： merge_pdfs、split_pdf、extract_pages（v1.3.0）、annotate_pdf（v1.4.0）、add_chart／read_form_fields／fill_form／encrypt_pdf／decrypt_pdf ツール、暗号化された往復処理およびネイティブ MCP リソース（v1.5.0）、さらに add_ltv／timestamp_pdf／update_metadata、印刷用制作機能、チャート v2（v1.6.0）。redact_pdf は 延期中 です。pdfnative はページコンテンツを重ねたりフラット化したりできますが、削除 はできません。オーバーレイのみの「墨消し」は誤った安全性を生むため、意図的に提供していません（上流へのコンテンツ削除リクエストとして追跡中です）。

すべてのツールは、2 つの出力モードに対応しています：

• base64 (デフォルト) — 生成された PDF は、埋め込みの resource コンテンツブロック（data:application/pdf;base64,… URI）として一度だけ返されます。structuredContent に含まれるのは { mode, sizeBytes } のみです（includeDiagnostics: true の場合は diagnostics[] も含まれ、add_ltv では summary も含まれます）。
• file — PDF は、PDFNATIVE_MCP_OUTPUT_DIR で設定されたサンドボックス化されたディレクトリに書き込まれます。この変数が設定されていない場合、ファイル出力は無効です。絶対パス、パストラバーサル、.pdf 以外の拡張子、NUL バイトはすべて拒否されます。

v1.1.0 からのアップグレード： 動作上の変更は、base64 モードのバイト列が structuredContent.base64 に重複して格納されなくなったことだけです。代わりに、埋め込みの resource ブロックから読み取ってください。

- const base64 = response.structuredContent.base64;   // v1.1.0
+ const block = response.content.find((c) => c.type === 'resource');
+ const base64 = block.resource.blob;                  // v1.2.0

トークンを節約した読み取り（v1.2.0）。 7 つの読み取り専用ツール（inspect_pdf、verify_pdf、validate_pdf、extract_text、extract_attachments、read_form_fields、inspect_layout）は、2 つのオプション入力を受け付けます。

• verbosity: 'summary' — スカラー値のみの簡潔な判定結果を返します（大きな配列や全文を省略します）。例：verify_pdf → { signatureCount, allValid, invalid, summary }（ltv: true の場合は ltvLevel も含まれます）。inspect_pdf では、存在する場合に docTimestampCount / trapped / checksPassed が保持されます。
• fields: ['a', 'b.c'] — 構造化された結果から、指定したドットパスのフィールドを抽出します。verbosity の適用後に処理されます。一致しないパスは省略され、_meta.unmatchedFields（および _meta.availableFields）で報告されます。

「この PDF には有効な署名がありますか？」を確認する最小限のプローブ：{ "pdfBase64": "…", "verbosity": "summary", "fields": ["allValid"] }。

pdfnative を選ぶ理由

pdfnative-mcp は、基盤となるエンジンのすべての特長を継承しています。

• エンジンに実行時依存関係がありません — 純粋な JavaScript で、ネイティブバインディングはありません（このサーバーが追加するのは MCP SDK と zod のみで、実行時依存関係は合計 3 つです）。
• ISO 32000-1（PDF 1.7） 準拠の出力。
• PDF/A-1b/2b/2u/3b、AES-128/256 暗号化、AcroForm、デジタル署名。
• 27 の Unicode スクリプト（latin、emoji、math、および 4 つの latin エイリアスを含む 34 の lang コード）。BiDi の並べ替え、アラビア語の文字形状調整、タイ語／デーヴァナーガリー文字／ベンガル語／タミル語の OpenType シェーピングを内蔵しています。
• PDF/X-4 印刷データ交換、DeviceCMYK カラー、精緻なタイポグラフィ（孤立行／寡婦行の制御、両端揃え、フランス語の句読点の間隔、OpenType 機能）。
• ツリーシェイク可能な ESM ビルド。

---

🚀 インストール

# Run directly with npx (recommended for MCP clients)
npx -y pdfnative-mcp

# Or install globally
npm install -g pdfnative-mcp
pdfnative-mcp

要件：Node.js ≥ 22。

---

⚙️ 設定

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）を編集します。

{
  "mcpServers": {
    "pdfnative": {
      "command": "npx",
      "args": ["-y", "pdfnative-mcp"],
      "env": {
        "PDFNATIVE_MCP_OUTPUT_DIR": "/Users/you/Documents/mcp-pdfs"
      }
    }
  }
}

Cursor / Continue / Zed / Windsurf / Cline / Roo Code

stdio サーバーをサポートする MCP 互換クライアントであれば、どれでも使用できます。同じ command + args + env の組み合わせを使用してください。Cursor の例（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "pdfnative": {
      "command": "npx",
      "args": ["-y", "pdfnative-mcp"],
      "env": { "PDFNATIVE_MCP_OUTPUT_DIR": "/Users/you/Documents/mcp-pdfs" }
    }
  }
}

Windsurf / Cline / Roo Code では、それぞれの MCP 設定ファイル内で同じ形式を使用します。

🌐 対応する AI エコシステムとクライアント

pdfnative-mcp は MCP ネイティブ環境向けに設計されており、stdio または Streamable HTTP 経由の MCP をサポートするクライアントで動作します。

コミュニティで互換性が確認されているもの：

• Ontheia — セルフホスト可能なオープンソースの AI エージェントプラットフォーム（プライバシーを最優先）。issue #41 で、すぐに動作すると報告されており、Ontheia の互換性のある MCP サーバーのページにも掲載されています。

🔌 MCP プロトコルへの準拠

v1.6.0 以降、サーバーは MCP TypeScript SDK v2（@modelcontextprotocol/server）を基盤とし、MCP 2026-07-28 に対応しています。

• ステートレスなサービング — server/discover がセッションハンドシェイクに代わり、すべての結果に resultType と _meta の serverInfo エンベロープが含まれます。HTTP では、2026-07-28 対応クライアントは各 POST /mcp に Mcp-Method / Mcp-Name ヘッダーを付けて送信します。
• キャッシュヒント — tools/list と prompts/list は ttlMs が 24 時間の public、server/discover は 1 時間の public、resources/list / resources/templates/list / resources/read は ttlMs: 0 の private です（生成された PDF はホストごとのユーザーデータです）。
• リソースエラー — 不明なリソース URI は、2026-07-28 の仕様要件に従い、JSON-RPC -32602（Invalid params）として報告されます。
• レガシーへの自動フォールバック — initialize（2025-11-25、2025-06-18、または 2025-03-26）で接続するクライアントは、stdio と HTTP の両方で SDK のレガシーパスを通じて処理されます。既存のホストに変更はありません。
• HTTP — GET / DELETE /mcp は 405 を返します（SSE の再開には非対応。サーバーはステートレスです）。ループバックへのバインドと Host / Origin ガードは変更されていません。また、Origin のポートはサーバーのポートと一致する必要があります（SDK のチェックだけではポートを考慮しません）。PDFNATIVE_MCP_HTTP_TOKEN を設定すると、任意でベアラートークンによるゲートが有効になります（設定されていない場合は 401 + WWW-Authenticate）。JSON-RPC バッチ配列（2025-03-26）は HTTP 経由で受け付けられます。キープアライブ接続でソケットリスナーが蓄積されなくなりました。
• stdio — これまでのすべての SDK リリースと同様、initialize より前に送信されたリクエストは返信なしで破棄され、JSON-RPC バッチ配列は stdio では受け付けられません（1.5.0 から変更なし。主要なホストでバッチ送信はありません）。
• プロトコルエラー — 不明なツール名を指定した tools/call は、仕様でそのように分類されているため、isError の結果ではなく JSON-RPC エラー（-32602、[UNKNOWN_TOOL] Unknown tool: …）になります。isError: true は実行失敗に限られます。
• 出力スキーマ — すべての structuredContent は、そのツールの outputSchema（2026-07-28 で必須）に対して検証されます。これには verbosity: 'summary' と fields による射影も含まれます。7 つの読み取りツールでは射影可能なスキーマを宣言しており（すべてのプロパティは省略可能で、additionalProperties: false は維持されています）、ポリシーにより入力スキーマには $schema キーワードがありません（MCP ≥ 2025-11-25 では JSON Schema 2020-12 がデフォルトです。一部のホストは、未知のキーワードを拒否する関数呼び出し API に inputSchema を転送します）。serverInfo には websiteUrl が含まれ、リソーステンプレートは pdfnative://output/{+path} です。

tools/call のペイロード（content、structuredContent、isError）は、2026-07-28 のパスとレガシーパスで同一です。tests/http-modern.test.ts でこれを検証し、tests/schema-conformance.test.ts では SDK の JSON Schema 2020-12 バリデーターを使って structuredContent を検証します。

クライアント	トランスポート	ネゴシエートされるプロトコル
Claude Desktop、Cursor、Continue、Zed、Windsurf、Cline	stdio	レガシー initialize（2025-xx）— 変更なし
ChatGPT およびその他の Streamable HTTP ホスト	HTTP POST /mcp	レガシーのステートレスな Streamable HTTP — 変更なし
MCP 2026-07-28 対応クライアント（SDK v2 Client、最新の MCP Inspector）	stdio / HTTP	server/discover、キャッシュヒント、_meta エンベロープ
Ontheia	stdio	レガシー initialize（コミュニティによる検証済み、#41）

環境変数

変数	用途
PDFNATIVE_MCP_OUTPUT_DIR	サンドボックスディレクトリの絶対パスです。outputMode: 'file'を有効にするには必須です。
PDFNATIVE_MCP_CACHE_DIR	SHA-256 キーを使用した永続的な結果キャッシュ（TTL 1 時間、LRU 256 MiB。キーはツール API、パッケージバージョン、固定された作成時刻で名前空間が分かれます）を有効にするための絶対パスです。未設定の場合、キャッシュは無効です。encrypt_pdf／decrypt_pdf／sign_pdf／add_ltv／timestamp_pdf／update_metadataおよびファイルモードの呼び出しはキャッシュされません。キャッシュヒット時は_meta.cached: trueが付与され、以前の呼び出しのバイト列が返されます。
PDFNATIVE_MCP_PORT	有効なポート（1～65535）が設定されている場合、stdio の代わりにhttp://127.0.0.1:<port>/mcpで HTTP サーバーを起動します。ループバックインターフェイスのみにバインドし、DNS リバインディング保護を有効にします（外部のHost／Originは403になります）。PDFNATIVE_MCP_HTTP_TOKENが設定されていない限り、認証は行われません。ほかのローカルプロセスからエンドポイントにアクセスできます。
PDFNATIVE_MCP_HTTP_TOKEN	(v1.6.0、シークレット) HTTP トランスポート用のオプトイン方式のベアラートークンです（16 文字以上で空白なし。条件を満たさない値では起動が中止されます）。設定すると、すべての/mcpリクエストにAuthorization: Bearer <token>を含める必要があります。含まれていない場合は401とWWW-Authenticate: Bearer realm="pdfnative-mcp"が返されます（認証情報が送信された場合に限りerror="invalid_token"が付きます — RFC 6750 §3.1）。定数時間で比較され、ログには記録されません。
PDFNATIVE_MCP_MAX_INFLATE_BYTES	(v1.6.0) エンジンのストリームごとの解凍上限 100 MiB（ZIP 爆弾対策）を上書きします。1024 以上の正の整数バイト数を指定します。起動時に一度だけ読み取られ、無効な値の場合は起動できません。共有ホストでは値を小さくし、信頼できる大容量スキャンのアーカイブでは値を大きくしてください。上限に達した添付ファイルストリームではextract_attachments includeData: trueがPDF_PARSE_FAILEDで失敗します。上限に達したコンテンツストリームではextract_textはページテキストを空にして処理を続行します（エンジンの動作であり、エラーは通知されません）。
PDFNATIVE_MCP_TSA_URL	(v1.6.0) sign_pdf timestamp: trueおよびtimestamp_pdfで使用する、RFC 3161 タイムスタンプ局の絶対http(s) URLです。未設定の場合はTSA_NOT_CONFIGUREDとなり、リクエストは送信されません。
PDFNATIVE_MCP_TSA_AUTH	(v1.6.0、シークレット) TSA に送信する任意のAuthorizationヘッダー値です。ログに記録されたり、応答に含まれたりすることはありません。
PDFNATIVE_MCP_REVOCATION	(v1.6.0) ocsp、crl、またはocsp,crlを指定すると、add_ltv mode: 'online'のオンライン失効情報収集が有効になります。未設定の場合はREVOCATION_NOT_CONFIGUREDとなります。
PDFNATIVE_MCP_NETWORK_ALLOWED_HOSTS	(v1.6.0) OCSP／CRL レスポンダー用のカンマ区切りの許可リスト（host、host:port、*.suffix）です。PDFNATIVE_MCP_REVOCATIONを設定する場合は必須です。レスポンダー URL は信頼できない証明書から取得されるためです。
PDFNATIVE_MCP_NETWORK_TIMEOUT_MS	(v1.6.0) TSA／OCSP／CRL 呼び出しのリクエストごとのタイムアウトです。1000～120000 ミリ秒（デフォルトは 10000）です。
PDFNATIVE_MCP_CREATION_DATE	(v1.7.0) プロセスが作成するすべてのドキュメントの作成時刻を固定する、タイムゾーン付きの ISO 8601 時刻です（例：2026-01-01T00:00:00Z）。/CreationDate、XMP の日付、トレーラーの/ID、および{date}ヘッダー／フッターのプレースホルダーに適用されます。起動時に一度だけ読み取られ、無効な値の場合は起動できません。固定値の取得元は stderr に記録されます。
SOURCE_DATE_EPOCH	(v1.7.0) reproducible-builds.orgの規約に従った、Unix エポックからの経過秒数を表す整数です。PDFNATIVE_MCP_CREATION_DATEが未設定の場合に使用されます。無効な値の場合は起動できません。多くのビルド環境ではすでにこの変数がエクスポートされています。このリリースから、これによりすべてのドキュメントの作成日が固定されます。固定したくない場合は、サーバープロセスでこの変数の設定を解除してください。
作成日時の優先順位（高い順）：呼び出しごとの creationDate → PDFNATIVE_MCP_CREATION_DATE → SOURCE_DATE_EPOCH → システム時刻。日付は常に UTC で記録されるため、固定した出力は、どのホストでもどのタイムゾーンでもバイト単位で同一になります。設計上、固定の対象外となるもの：signingTime（sign_pdf、prepare_signature_placeholder）、modDate（update_metadata）、インクリメンタルライターの再生成される 2 つ目の /ID（annotate_pdf、fill_form）、RFC 3161 タイムスタンプトークンとオンラインの失効データ、暗号化（新しいファイルキー、ソルト、IV）、および ECDSA 署名（設計上ランダム化されます）。docs/guides/REPRODUCIBLE.md を参照してください。

---

🛠 ツールリファレンス

generate_basic_pdf

{
  "title": "Q1 2026 Report",
  "blocks": [
    { "type": "heading", "text": "Executive summary", "level": 1 },
    { "type": "paragraph", "text": "Revenue grew 24% year over year." },
    { "type": "list", "style": "bullet", "items": ["Strong APAC", "Stable EU", "Soft NA"] },
    { "type": "pageBreak" },
    { "type": "heading", "text": "Details", "level": 2 }
  ],
  "footerText": "Confidential — Internal use only",
  "outputMode": "base64"
}

13 種類のブロック：heading、paragraph、list、table、image、link、toc、barcode、svg、formField、chart、pageBreak、spacer。複合レポートの例：

{
  "title": "Quarterly report",
  "blocks": [
    { "type": "toc" },
    { "type": "heading", "text": "Sales", "level": 1 },
    { "type": "table", "headers": ["Region", "Revenue"], "rows": [["EMEA", "1.2 M"], ["APAC", "0.9 M"]], "zebra": true },
    { "type": "image", "imageBase64": "<base64 JPEG>", "mimeType": "image/jpeg", "width": 300, "alt": "Revenue chart" },
    { "type": "svg", "data": "M10 10 H 90 V 90 H 10 Z", "viewBox": [0, 0, 100, 100], "fill": "#0a7e8c" },
    { "type": "barcode", "format": "qr", "data": "https://example.com/q1", "align": "center" },
    { "type": "link", "text": "Full dataset", "url": "https://example.com/data" },
    { "type": "formField", "fieldType": "text", "name": "reviewer", "label": "Reviewed by" }
  ],
  "outline": "auto",
  "pageSize": "Letter",
  "headerTemplate": { "right": "{title} — page {page}/{pages}" },
  "embedFonts": true
}

ブロックのルール：table、barcode、formField、chart は、それぞれ add_table／add_barcode／add_form／add_chart と同じ本文を受け取ります。link の URL は http:、https:、mailto: のいずれかである必要があります。image ブロックは、1 つにつき 12 M 個の Base64 文字、1 回の呼び出しにつきデコード後 24 MiB までです（PNG は 8 ビットのグレースケール／RGB、非インターレース、アルファなし、パレットなし。それ以外は修正方法を示す VALIDATION_ERROR になります）。svg は <path>、<rect>、<circle>、<ellipse>、<line>、<polyline>、<polygon>、<text>／<tspan> をサポートし、transform、<g>、<use>、<image>、グラデーション、不透明度、CSS は無視します（外部参照が取得されることはありません）。toc は見出しブロックから生成され、outline: 'auto' と組み合わせて使用します。pdfA で formField を使用する場合は、フィールドのフォントも埋め込むため embedFonts: true が必要です（そうでない場合は PDFA_UNEMBEDDED_FORM_FONT が発生し、strict: true では失敗します）。barcode に alt はありません。レンダリング前にページ割りをプレビューするには、同じ入力で inspect_layout を使用してください。

タイポグラフィ（v1.7.0）。 typography は、9 つのドキュメントツールと inspect_layout で使用できる、オプトインのオブジェクト 1 つです（キーは 12 個で、すべてデフォルトではオフです。省略するとバイト列は変更されません）。

{
  "title": "Annual report",
  "embedFonts": true,
  "typography": {
    "splitParagraphs": true, "orphans": 3, "widows": 3,
    "keepHeadingsWithNext": { "minLines": 3 },
    "opticalMargins": true, "kerning": true, "fontFeatures": ["onum", "smcp"],
    "unitBinding": true, "bindShortWords": true, "punctuationSpacing": "fr"
  },
  "blocks": [
    { "type": "heading", "text": "Outlook", "level": 2, "keepWithNext": true },
    { "type": "paragraph", "text": "A long justified paragraph…", "align": "justify" },
    { "type": "paragraph", "text": "Figures by region:", "keepWithNext": true, "splittable": false }
  ]
}

• キー：splitParagraphs、orphans／widows（1～10、デフォルトは 2、splitParagraphs が必要）、keepHeadingsWithNext（true または { minLines }）、unitBinding（true または { units }）、bindShortWords（true または { maxLength, words }）、punctuationSpacing（'fr'、'fr-CA'、または { char, side, space } ルールの配列）、opticalMargins、metrics（デフォルトの 'approximate'／'exact'）、fontFeatures（tnum、pnum、lnum、onum、zero、ordn、sups、subs、smcp、c2sc、case）、kerning、hyphenationLanguage。
• ブロック入力：paragraph は align（デフォルトの left／right／center／justify）、keepWithNext、splittable を受け取ります（このブロックでは typography.splitParagraphs を上書きします）。heading は keepWithNext を受け取ります（このブロックでは typography.keepHeadingsWithNext を上書きします）。
• 制限：kerning、fontFeatures、および 'fr' の狭い改行なしスペースには、埋め込みフォント（embedFonts: true）が必要です（ベース 14 フォントの Helvetica では、'fr' は 'fr-CA' にフォールバックします）。metrics: 'exact' はベース 14 のテキストにのみ適用されます。バンドルされている Noto Sans では tnum／lnum による変更はありません（診断 TYPOGRAPHY_FEATURE_INEFFECTIVE）。ハイフネーション辞書はインストールされていないため、このサーバーでは hyphenationLanguage の効果はありません。テキスト内のソフトハイフン（U+00AD）は有効です。docs/guides/TYPOGRAPHY.md と typography プロンプトを参照してください。 CMYK カラー（v1.7.0）。 すべてのカラー入力は、従来どおりの形式（チャート、テンプレート、link ブロック、svg ブロックでは hex、ウォーターマークと annotate_pdf では 0～1 の RGB 3要素、アウトライン項目と表のセル境界線では任意の文字列）を維持し、これに加えて DeviceCMYK を指定できます。成分が 0～1 のオペランド文字列 'c m y k'（"1 0.6 0 0.1"）と、成分が 0～100 のパーセントタプル [c, m, y, k]（[100, 60, 0, 10]）を使用します。デフォルトの sRGB インテントに対する PDF/A 適合を指定した場合、CMYK カラーは PDFA_DEVICE_CMYK_CONTENT として報告されます。その場合はカラーを RGB にするか、CMYK の outputIntent を指定してください。

PDF/X-4（v1.7.0）。 generate_basic_pdf、add_table、add_chart、add_barcode、embed_image、add_international_text で pdfx: 'pdfx4' を指定すると、PDF/X-4（ISO 15930-7）ファイルを書き出します。内容は、%PDF-1.6 ヘッダー、PDF/X-4 の XMP 識別情報、/GTS_PDFX 出力インテント、各ページの TrimBox、/Trapped です。

{
  "title": "Spring catalogue",
  "pdfx": "pdfx4",
  "embedFonts": true,
  "outputIntent": { "iccProfileBase64": "<the printer's CMYK ICC profile, base64>", "outputConditionIdentifier": "FOGRA39" },
  "metadata": { "trapped": "False" },
  "print": { "bleed": 14.17, "marks": { "colourBars": true } },
  "blocks": [{ "type": "paragraph", "text": "Four-colour job exchanged as PDF/X-4." }]
}

• 適合するファイルには、印刷条件の ICC プロファイルを指定した outputIntent が必須です（デバイスクラス prtr、CMYK または Gray — 印刷用プロファイルは同梱されていません。印刷会社にお問い合わせください）。適合ファイルにするには embedFonts: true が必要です（それ以外の場合は PDFX_NO_FONT_ENTRIES が報告され、strict: true では拒否されます）。pdfA および encrypt とは併用できません。metadata.trapped は 'True' または 'False' である必要があります。各ページには TrimBox または ArtBox のいずれか一方を指定し、両方は指定できません。整合性のない要求は、処理開始前に VALIDATION_ERROR で拒否されます。リンクとフォームフィールドは報告されます（PDFX_ANNOTATIONS）。strict: true の場合、PDFX_* 診断があると、呼び出しは PDF_X_COMPLIANCE_VIOLATION で失敗します。
• outputIntent は RGB、CMYK、Gray のプロファイルを受け付けます（pdfA または pdfx の場合、最大 8 MiB）。プロファイルは実際の ICC ファイルである必要があります（acsp シグネチャと整合性のあるサイズフィールドが必要です）。手作りのスタブは拒否されます。
• print.marks は true またはオブジェクトを受け付けます。marks.colourBars（true または { tints, size }。size は 4～72 pt、デフォルトは 12）は、塗り足し領域に C M Y K のベタと各色の 50 % 濃度を追加します。デフォルトでは無効です。約 5 mm（14.17 pt）の塗り足しが必要で、帯が収まらない場合はスキップされます。
• validate_pdf { standard: 'pdf-x-4' } で結果を確認できます。これは構造チェックであり、認定済みのプリフライトではありません。docs/guides/PRINT.md と print_ready プロンプトを参照してください。

add_barcode

{
  "format": "qr",
  "data": "https://pdfnative.dev",
  "caption": "Scan to learn more",
  "ecLevel": "H",
  "outputMode": "file",
  "outputPath": "tickets/event-42.pdf"
}

対応フォーマット：qr、code128、ean13、datamatrix、pdf417。

add_international_text

{
  "title": "مرحبا بالعالم",
  "lang": "ar",
  "paragraphs": [
    "هذا اختبار للنص العربي مع تشكيل OpenType ومحارف ثنائية الاتجاه.",
    "Mixed content: العربية + English ✓"
  ]
}

対応する lang コード：Unicode の 27 種類の文字体系 — ar、he、th、ja、zh、ko、el、hi、bn、ta、ru、ka、hy、tr、pl、vi、te、si、bo、km、my、am、および v1.7.0 から追加された lo（ラオ語）、nod（タイ・タム文字）、khb（新タイ・ルー文字）、tdd（タイ・レ文字）、cjm（チャム文字） — に加え、ユーティリティ用フォントの latin、emoji、math です。v1.7.0 から ha（ハウサ語）、yo（ヨルバ語）、ig（イボ語）、sw（スワヒリ語）は latin のエイリアスです。同梱の Noto Sans が声調記号に対応しており、追加のフォントは埋め込まれません。フォントは常に埋め込まれます（embedFonts 入力なし）。バイト単位で同一の出力にするには、creationDate を固定してください。このツールは typography と pdfx も受け付けます（generate_basic_pdf を参照）。

PDF/A でのタイ・タム文字： lang: 'nod' の場合は pdfa2u ではなく、pdfA: 'pdfa2b' を使用してください。エンジン内の一部のグリフに ToUnicode エントリーがなく、PDF/A-2u では veraPDF によって拒否されます（上流で追跡中）。

複数の文字体系を含む文書 — 配列またはカンマ区切りのリストを渡します：

{
  "title": "Mixed Script",
  "lang": ["ar", "emoji"],
  "paragraphs": ["العربية مع رموز 🎉🚀"],
  "pdfA": "pdfa2u"
}

sign_pdf

v1.0.0 以降、sign_pdf は存在しない場合に /Sig プレースホルダーを自動挿入するため、あらゆる PDF に対して 1 回の呼び出しで署名できます。

{
  "pdfBase64": "<any base64 PDF>",
  "algorithm": "rsa-sha256",
  "certDerBase64": "<base64 X.509 cert in DER>",
  "rsaKeyPkcs1DerBase64": "<base64 PKCS#1 RSAPrivateKey DER>",
  "signerName": "Alice",
  "reason": "Approval",
  "location": "Paris, FR",
  "signingTime": "2026-01-15T10:30:00Z"
}

ECDSA P-256 の場合は、algorithm: "ecdsa-sha256" を指定し、ecPrivateKeyDerBase64（SEC1 または PKCS#8 DER）または ecPrivateScalarHex（64 桁の 16 進数）のいずれかを渡してください。

PEM → DER の変換：

openssl x509 -in cert.pem -outform DER | openssl base64 -A                 # cert
openssl rsa  -in key.pem  -outform DER -traditional | openssl base64 -A    # RSA PKCS#1
openssl pkey -in key.pem  -outform DER | openssl base64 -A                 # ECDSA

プレースホルダーをカスタマイズする必要がある場合（例：4096 ビットを超える RSA キー用に placeholderBytes を大きくする、subFilter: 'ETSI.CAdES.detached' を指定する、reserveTimestamp: true を設定する場合）に限り、prepare_signature_placeholder を使用してください。それ以外の場合は、sign_pdf を直接呼び出してください。

PAdES の段階（v1.6.0）。 sign_pdf に profile: "pades" を指定すると B-B 署名が生成されます。B-T にするには timestamp: true を追加してください（PDFNATIVE_MCP_TSA_URL が必要です）。続いて add_ltv で B-LT に、timestamp_pdf で B-LTA にできます。

// 1. sign_pdf  { ..., "profile": "pades", "timestamp": true, "certChainDerBase64": ["<intermediate DER>"] }
// 2. add_ltv   { "pdfBase64": "<signed>", "mode": "online" }            // or "offline" + certificatesDerBase64 / ocspResponsesDerBase64 / crlsDerBase64
// 3. timestamp_pdf { "pdfBase64": "<ltv>" }                              // re-run before the TSA certificate expires
// 4. verify_pdf { "pdfBase64": "<final>", "ltv": true }                  // -> ltvLevel: "B-LTA"

署名者のメタデータ（signerName、reason、location、contactInfo）はプレースホルダーに組み込まれます。fieldName は複数ある未署名プレースホルダーから 1 つを選択し（それ以外の場合は PLACEHOLDER_AMBIGUOUS）、allowMultiple: true を指定すると追加の署名が可能になります。docs/guides/LTV.md を参照してください。

---

add_table

{
  "title": "Monthly Sales",
  "headers": ["Region", "Units", "Revenue"],
  "rows": [
    ["APAC", "1200", "$240,000"],
    ["EMEA", "800", "$160,000"]
  ],
  "infoItems": [{ "label": "Period", "value": "January 2025" }],
  "footerText": "Internal use only",
  "outputMode": "base64"
}

add_form

{
  "title": "Employee Onboarding",
  "fields": [
    { "fieldType": "text", "name": "fullName", "label": "Full Name", "required": true },
    { "fieldType": "dropdown", "name": "dept", "label": "Department", "options": ["Engineering", "Sales", "HR"] },
    { "fieldType": "checkbox", "name": "agree", "label": "I agree to the terms", "checked": false },
    { "fieldType": "listbox", "name": "skills", "label": "Skills", "options": ["TypeScript", "PDF", "MCP"] },
    { "fieldType": "textarea", "name": "notes", "label": "Notes", "placeholder": "Anything we should know?" }
  ],
  "outputMode": "base64"
}

フィールドの種類：text、textarea（複数行、/Ff 4096）、checkbox、radio、dropdown、listbox。placeholder は、フィールドが空のときにヒントテキストを表示します。encrypt を追加すると、AcroForm を保持したままパスワード保護されたフォームを作成できます。PDF/A の適合を示す場合は embedFonts: true を渡して、フィールドのフォントも埋め込んでください（v1.7.0 以降、このフォームは veraPDF で検証できます）。指定しない場合、呼び出しは PDFA_UNEMBEDDED_FORM_FONT を報告し（strict: true の場合は失敗します）。

embed_image

{
  "title": "Product Photo",
  "imageBase64": "<base64-encoded JPEG bytes>",
  "mimeType": "image/jpeg",
  "caption": "Front view of Model X",
  "width": 400,
  "align": "center",
  "alt": "Front view of the Model X chassis",
  "outputMode": "base64"
}

注： エンジンの PNG デコーダーが受け付けるのは、8 ビットの非インターレースのグレースケール／RGB 画像のみです。アルファチャンネル（カラータイプ 4／6）、パレット（タイプ 3）、16 ビット、インターレースの PNG は、対処方法（フラット化または再エクスポート）とともに、入力時に VALIDATION_ERROR で拒否されます。このルールは image ブロックと画像ウォーターマークにも適用されます。embed_image.imageBase64 は 1.5.0 の仕様どおり、長さの上限はありません。12 M 文字の上限が適用されるのは、インラインの image ブロックとウォーターマーク画像のみです。

prepare_signature_placeholder

{
  "title": "Service Agreement",
  "signerName": "Alice Dupont",
  "reason": "Approved",
  "location": "Paris, FR",
  "blocks": [
    { "type": "paragraph", "text": "By signing below, I accept the terms and conditions." }
  ],
  "outputMode": "base64"
}

署名ワークフローを完了するには、返された PDF バイト列を sign_pdf に渡してください。

inspect_pdf

読み取り専用の構造・セキュリティ検査です。後続の検証、CI のアサーション、または操作前に PDF を把握する必要がある AI エージェントに役立ちます。

{
  "pdfBase64": "<base64 PDF>",
  "pages": true,
  "check": ["pdfa", "signed", "attachments"]
}

戻り値：

{
  "version": "1.7",
  "pageCount": 3,
  "encryption": "none",          // 'none' | 'aes-128' | 'aes-256' | 'rc4' | 'unknown'
  "pdfA": "3B",                  // null when no PDF/A claim is present
  "signatureCount": 1,
  "hasSignaturePlaceholder": false,
  "attachments": [{ "filename": "factur-x.xml", "mimeType": "application/xml", "sizeBytes": 1234, "relationship": "Source" }],
  "info": { "Producer": "pdfnative", "Title": "Invoice INV-2025-001" },
  "perPage": [{ "index": 0, "width": 595, "height": 842 }],
  "checks": { "pdfa": true, "signed": true, "attachments": true },
  "checksPassed": true
}

check[] では 'pdfa'、'signed'、'encrypted'、'placeholder'、'attachments'、'dss'、'docTimestamp'、'trapped'、'annotations'（後半 4 項目は v1.6.0 以降）、および 'pdfx'（v1.7.0 以降。XMP が PDF/X を適合として示しているかを確認します。適合性そのものではなく、適合の表明を確認します。適合性の検証には validate_pdf standard: 'pdf-x-4' を使用してください）を指定できます。pdfX は XMP が PDF/X を適合として示している場合にのみ結果に含まれます（verbosity: 'summary' でも保持されます）。checksPassed は、要求されたすべてのチェックの AND です。signatures: true を指定すると、フィールドごとの一覧（subFilter、isDocTimestamp、isPlaceholder、byteRange、vriKey）が追加されます。annotations: true を指定すると、annotations[]（すべての /Annots エントリー。0 始まりの page、subtype、rect と、存在する場合は 200 文字で切り詰められた contents、title、color、quadPoints、リンクの url）および annotationCount が追加されます。dss、docTimestampCount、trapped は存在する場合にのみ表示されます。pages: true を指定すると、設定されている場合に各 perPage エントリーに trimBox／bleedBox／artBox／cropBox／userUnit も含まれます。

inspect_layout

読み取り専用のページネーションのドライランです。generate_basic_pdf と同じ blocks に加え、ブロックの位置に影響するすべての入力（title、footerText、pdfA、normalize、embedFonts、pageSize、margins、headerTemplate、footerTemplate、および v1.7.0 以降の typography）を指定します。PDF は生成されません。generate_basic_pdf に渡す内容とまったく同じものを渡すと、totalPages が一致します。

{ "title": "Memo", "blocks": [{ "type": "paragraph", "text": "Short note." }], "pageSize": "Letter", "verbosity": "summary", "fields": ["totalPages"] }

完全な結果には、pageWidth、pageHeight、margins、totalPages、および pages[].blocks[]（type、page、x、top、width、height。単位はポイントで、小数点以下2桁に丸められます）が含まれます。v1.7.0 以降、ドライランとビルドでは同じページネーションプランナーを使用するため、toc を含むすべてのブロック種別が、実際のレイアウトどおりに正確に測定されます（1.6.0 では toc ブロックは 0 pt として測定されていました）。

validate_pdf

読み取り専用の構造適合性チェックです。standard でルールセットを選択します。'pdf-ua-1'（デフォルト。タグ付き PDF 用の PDF/UA、ISO 14289-1）または、v1.7.0 以降の 'pdf-x-4'（PDF/X-4、ISO 15930-7）を指定します。任意のツールで pdfA（例：pdfA: 'pdfa2u'）を使用してアクセシブルな文書を生成し、その結果を検証します。

{ "pdfBase64": "<tagged-pdf-base64>" }

戻り値：

{
  "standard": "pdf-ua-1",
  "valid": true,
  "errors": [],          // blocking structural violations (empty when valid)
  "warnings": [],        // non-blocking best-practice recommendations
  "summary": "PDF/UA structural prerequisites hold."
}

カタログの /MarkInfo /Marked true、/StructTreeRoot（および /ParentTree）、/Metadata（XMP）、/Lang、ページごとの MCID の一意性を検証します。これは開発時に使う高速なゲートであり、フォント、色、レンダリングも追加でチェックする完全なリファレンスバリデーター（veraPDF）の代わりにはなりません。

PDF/X-4（v1.7.0）。 { "pdfBase64": "<pdf>", "standard": "pdf-x-4" } では、ISO 15930-7 の構造上の前提条件をチェックします。PDF 1.6 ヘッダー、暗号化なし、トレーラーの /ID、PDF/X-4 の XMP 識別情報、埋め込み prtr ICC プロファイルを含む /GTS_PDFX 出力インテント、各ページの BleedBox および MediaBox 内にネストされた TrimBox または ArtBox、すべてのフォントの埋め込み、印刷領域上に注釈がないこと、JavaScript がないこと、埋め込みファイルがないこと、出力インテントと整合するデバイスカラーを確認します。結果は同じ形式で、さらに caveats[] が追加されます。これは valid: true の判定で保証されない内容を示します。これは認定済みのプリフライトではなく、veraPDF は PDF/X を対象としていません。印刷ジョブは callas pdfToolbox または Acrobat Preflight で確認してください。デフォルト（pdf-ua-1）のレスポンスは変更されず、caveats は含まれません。

annotate_pdf

既存の PDF に増分更新で注釈マークアップを重ねます。これは視覚的なレビュー用レイヤーであり、墨消しではありません。元のコンテンツは変更されません。

{
  "pdfBase64": "<base64 PDF>",
  "annotations": [
    { "type": "highlight", "page": 0, "rect": [72, 700, 520, 715], "color": [1, 1, 0], "contents": "Check this figure" },
    { "type": "text", "page": 0, "rect": [540, 700, 560, 720], "contents": "Reviewer note" }
  ]
}

種類：text、highlight、underline、strikeout、squiggly、square、circle、line、freetext。ページインデックスは 0 始まりです。color / interiorColor には、16 進数またはオペランド文字列（CMYK オペランド文字列を含む）、0～1 の RGB 3 要素配列（[1, 1, 0]）、または v1.7.0 以降の CMYK パーセント値のタプル（[0, 0, 100, 0]）を指定できます。v1.7.0 では、ほぼ黒くレンダリングされていた 0～1 の 3 要素配列も修正されています。暗号化されたソースは拒否されます（ENCRYPTED_SOURCE）。まず decrypt_pdf を実行し（署名 / AcroForm が削除されます）、注釈を追加してから、再度 encrypt_pdf を実行してください。

draft_governance_issue

人間がレビューして送信するための、ガバナンスに準拠した GitHub Issue のドラフトをローカルで作成します。サーバーが GitHub に接続することはありません（外部への通信が発生する可能性があるのは、オペレーターが設定した TSA / OCSP / CRL エンドポイントのみです。［ネットワークと外部通信］(#network--egress)を参照）。ドラフトの Markdown と機械可読形式のコンプライアンスレポートを返します。

{
  "title": "add_table drops the caption on the second page",
  "issueType": "bug",
  "summary": "The table caption is only rendered on page 1 when repeatHeader is true.",
  "reproduction": { "command": "add_table with caption + repeatHeader over 2 pages (examples/bordered-table.json, then inspect_pdf)", "result": "Page 2 has no caption row." },
  "expectedBehavior": "The caption repeats with the header on every page.",
  "duplicateSearchPerformed": true
}

ランタイム依存関係を提案する、再現手順を省略する、または duplicateSearchPerformed: false を設定するドラフトは、GOVERNANCE_VIOLATION で拒否されます。人間が介在するプロセスの詳細については、docs/guides/AI_GOVERNANCE.md を参照してください。

verify_pdf、add_attachment、extract_text

docs/AI_GUIDE.md の専用セクションと、docs/KNOWLEDGE_BASE.md のリファレンスを参照してください。すぐに実行できる例は examples/ にあります。

---

🔐 セキュリティモデル

pdfnative-mcp はホストプロセス内で実行され、stdio MCP サーバー（またはループバック専用 HTTP エンドポイント）を公開します。設定されたサンドボックスの外部では、いかなる I/O も行いません。

• ファイルへの書き込みは PDFNATIVE_MCP_OUTPUT_DIR によって制限されます。設定されていない場合、file 出力モードは SecurityError とともに拒否されます。
• パス解決では、絶対パス、パストラバーサルシーケンス（..）、NUL バイト、.pdf 以外の拡張子が拒否されます。
• 出力サイズは、1 回の呼び出しにつき 50 MB に制限されます。
• 入力は、各ツールの境界で厳格な JSON スキーマと Zod の実行時チェックに照らして検証されます。不明なキーやスペルミスのあるキー（トップレベルまたはネストされたもの）は VALIDATION_ERROR とともに拒否されます。また、パーサーの実行前に base64 / DER ペイロードの妥当性がチェックされます（data: プレフィックスは許容されますが、PEM または二重エンコードされた入力は、対処方法とともに拒否されます）。
• HTTP トランスポート（PDFNATIVE_MCP_PORT）はループバックのみにバインドされます。PDFNATIVE_MCP_HTTP_TOKEN が設定されていない場合、認証は行われません（有効なベアラートークンがない場合は 401）。

ネットワークと外部通信

サーバーは、デフォルトでは外部へのネットワーク呼び出しを行いません。外部通信が発生する可能性があるのは、PAdES の長期検証用にオペレーターが環境変数で設定した RFC 3161 / OCSP / CRL エンドポイント（PDFNATIVE_MCP_TSA_URL、PDFNATIVE_MCP_REVOCATION、PDFNATIVE_MCP_NETWORK_ALLOWED_HOSTS）のみです。ツール引数で指定された URL、GitHub、テレメトリーへの通信は一切行いません。この設定がない場合、sign_pdf timestamp: true、timestamp_pdf、add_ltv mode: 'online' は、ドキュメントに触れる前に TSA_NOT_CONFIGURED / REVOCATION_NOT_CONFIGURED で即座に失敗します。add_ltv mode: 'offline' は、呼び出し元から提供された素材をネットワークに一切アクセスせずに埋め込みます。

OCSP / CRL の URL は、PDF 内の信頼されていない証明書に含まれる AIA / CRL 配布ポイント拡張から取得されるため、すべての取得に SSRF ガードが適用されます。

• ホストはオペレーターの許可リスト（host、host:port、または *.suffix）に一致する必要があります（ワイルドカードのみの指定は拒否されます）。エントリーには URL ではなくホスト名を指定します。host:port エントリーは、明示的なポートを含む URL にのみ一致します（URL パーサーはデフォルトの :80 / :443 を削除するため、それらの場合はポートを付けずにホストを指定してください）。ワイルドカードエントリーにポートは指定できません。IDN ホスト名は punycode（xn--…）で指定する必要があります。IPv6 リテラルは角括弧で囲みます（[2001:db8::1]）。
• 使用できるのは http: / https: のみです。埋め込み認証情報は許可されず、リダイレクトは一切追跡されません。
• ループバック、リンクローカル、プライベート、ユニークローカル、CGNAT、未指定、マルチキャストのアドレスリテラル（10 進数 / 8 進数 / 16 進数表記や IPv4 マップ IPv6 を含む）は、そのリテラルが許可リストにそのまま登録されていない限り拒否されます。このガードがチェックするのはリテラルのみです。内部アドレスに解決される許可済みホスト名（DNS リバインディング）は検出されません。依存関係を追加せずにリゾルバーを使用する方法がないためです。許可リストには、自分が管理するホストのみ登録してください。
• リクエストごとのタイムアウト（PDFNATIVE_MCP_NETWORK_TIMEOUT_MS）とレスポンスサイズ上限（TSA は 256 KiB、OCSP は 1 MiB、CRL は 16 MiB）は、ストリーミング中に適用されます。そのため、サイズ超過のレスポンスはバッファリングされずに中断されます。
• レスポンダーから返される OCSP レスポンスと CRL は、add_ltv が埋め込む前にパース検証されます。
• TSA URL はオペレーターが信頼するものです（チェックするのはスキームと認証情報のみ）。PDFNATIVE_MCP_TSA_AUTH シークレットがログに記録されたり、エラーメッセージに出力されたりすることはありません。

プロバイダーは呼び出しごとに構築され、pdfnative の呼び出しごとのオプションを通じて渡されます。プロセス全体に適用されるプロバイダー設定関数は使用されないため、同時リクエスト間で共有されるものはありません。server/discover の説明には、現在の外部通信ポリシー（エンドポイントの種類のみ。シークレットは含まれません）が報告されます。

責任ある脆弱性開示の手順については SECURITY.md を、オペレーター向けの設定については docs/guides/LTV.md を参照してください。

---

🧪 ローカル開発

git clone https://github.com/Nizoka/pdfnative-mcp.git
cd pdfnative-mcp
npm ci                    # .npmrc sets ignore-scripts=true: nothing builds on install
npm run gate:fast         # before every commit: typecheck:all, lint, test, server-json, verify:docs
npm run gate              # the CI profile: build, dist checks, stdio smoke test, tool shape, samples, coverage, docs, corpus, validate:pdfx
npx tsx scripts/gate.ts --publish --require-all   # release branches: everything incl. validate:pdfa (veraPDF); a skipped step fails

npm run gate (scripts/gate.ts) は、テスト 1631 件、vitest.config.ts のカバレッジしきい値、および標準入出力経由で実行するビルド済みサーバー（標準出力には JSON-RPC フレームのみを出力する必要があります）を含む、すべてのチェックが成功した状態の唯一の定義です。ステップごとに 1 行を出力し、ログを test-output/.gate/<step>.log に書き込みます。--only <step> で 1 つのステップだけを実行でき、--json で機械処理用の出力を取得できます（フラグを渡すにはスクリプトを直接呼び出してください：npx tsx scripts/gate.ts --fast）。個々のステップは通常の npm スクリプトです。

npm run build && npm run test:generate   # drive the built server under TZ=UTC, operator variables scrubbed -> test-output/samples/
npm run verify:samples    # hold the 96 samples to tests/_fixtures/samples.sha256.json (93 by bytes, 3 by a semantic projection)
npm run corpus:pdfa       # write the 41-file conformance corpus (33 claim PDF/A, 6 claim PDF/X-4, 2 page-tree outputs claim nothing)
npm run validate:pdfx     # in-process structural PDF/X-4 check of the corpus; never skips
npm run validate:pdfa     # veraPDF over the PDF/A files (VERAPDF_HOME, JAVACMD); exit 0 ok / 1 conformance / 2 infrastructure
npm run verify:docs       # every count, version, tool, error code, operator variable, link and anchor in the docs vs docs/assets/ecosystem.json and src/
npx tsx scripts/tool-shape.ts --write   # only after a deliberate tools/list schema change (npm run verify:tool-shape checks the fixture)

意図した出力の変更は、npx tsx scripts/verify-samples.ts --update でベースラインを更新し、リリースノートに記載します。予期しない変更を黙らせるために使ってはいけません。veraPDF 1.30.2 では、コーパスの結果は PASS が 27 件、予想される失敗が 6 件です（拒否され続ける必要があるネガティブカナリア）。各スクリプト、そのフラグ、終了コードはすべて scripts/README.md に記載されています。

標準入出力経由でサーバーをスモークテストします。

node dist/cli.js
# In another terminal, send a JSON-RPC initialize request via stdin (e.g. with mcp-inspector).

コントリビューターの皆さんへ： AGENTS.md（すべてのコーディングエージェントとコントリビューターが共有するリポジトリのルール）から始めてください。完全なローカル検証ワークフローについては、docs/guides/LOCAL_TESTING.md を参照してください。品質ゲート、テストとしてのサンプル、生成された PDF の構造的な正しさの検証（assertValidPdf、inspect_pdf、validate_pdf、verify_pdf）、ビューアーでの出力の表示、veraPDF による外部 PDF/A チェック、MCP Inspector が含まれます。

📣 リリース手順

pdfnative-mcp は pdfnative と同じリリース方式に従います。

• タグごとに release-notes/vX.Y.Z.md にリリースノートファイルを 1 つ作成します
• 各リリースの箇条書きを CHANGELOG.md に反映します
• GitHub Release の本文には release-notes/vX.Y.Z.md の内容をコピーします
• npx tsx scripts/release-prepare.ts --version X.Y.Z でバージョン更新の機械的な処理を行います（コミット、タグ付け、公開は行いません）。バージョンは package.json、src/version.ts、server.json、docs/assets/ecosystem.json の間で常に一致させます
• リリースブランチでは npx tsx scripts/gate.ts --publish --require-all に合格する必要があります。veraPDF を含むすべてのステップが対象で、スキップはできません
• npm への公開は、保護された環境から、NPM_TOKEN を使わず GitHub Actions Trusted Publishing（OIDC）で行います。このワークフローでは、タグがパッケージのバージョンと一致することを確認し、公開ゲートを実行して、--provenance を指定して公開します。2 つ目のジョブでは、CycloneDX SBOM とともに tarball を証明（ビルドの来歴）し、両方を GitHub Release に添付します
• Linux と Windows の各ジョブは step-security/harden-runner から開始します（このアクションは macOS をサポートしていないため、macOS ジョブは文書化された例外です）。persist-credentials: false を指定してチェックアウトし、npm ci --ignore-scripts でインストールして、最小権限の permissions で実行します。アクションはコミット SHA で固定されます。veraPDF ジョブは必須です
• 人間が関与する手順：コーディングエージェントが準備と検証を行い、メンテナーがプッシュ、プルリクエストの作成、タグ付け、公開を行います（.github/AGENT_RULES.md）

標準的な構成と公開チェックリストについては release-notes/TEMPLATE.md を、リリース手順については CONTRIBUTING.md を参照してください。

---

📚 プロジェクト構成

src/
├── cli.ts                      # entrypoint: stdio (default) or Streamable HTTP (PDFNATIVE_MCP_PORT)
├── http.ts                     # Node http <-> Web Request/Response bridge + Host/Origin loopback guard
├── auth.ts                     # opt-in HTTP bearer token (PDFNATIVE_MCP_HTTP_TOKEN)
├── base64.ts                   # base64 / DER boundary decoding with agent-facing diagnostics
├── index.ts                    # public library exports
├── server.ts                   # Server factory, tool registry, cache hints, SERVER_INSTRUCTIONS
├── network.ts                  # operator-configured TSA / OCSP / CRL egress + SSRF guard
├── print.ts                    # print-production schema (boxes, bleed, marks + colour bars, userUnit, RGB / CMYK / Gray outputIntent, metadata, creationDate)
├── pdfx.ts                     # pdfx: 'pdfx4' conformance target + the static conflicts refused before the build
├── color.ts                    # shared colour fragment: CMYK operand string / percent tuple beside each historical form, toEngineColor()
├── typography.ts               # the typography fragment (12 opt-in keys) + TypographyOptions mapper
├── reproducible.ts             # operator-pinned creation instant (PDFNATIVE_MCP_CREATION_DATE, SOURCE_DATE_EPOCH)
├── diagnostics.ts              # engine diagnostics sink (PDFA_* / PDFX_* / TYPOGRAPHY_*), strict escalation by code, includeDiagnostics, embedFonts
├── chart.ts                    # charts v2 schema + ChartBlock mapper
├── blocks.ts                   # the 7 extended document blocks (table, image, link, toc, barcode, svg, formField)
├── layout.ts                   # pageSize / margins / header & footer templates / compress / debug / encrypt / typography (PdfLayoutOptions)
├── table.ts, barcode.ts, form.ts, image.ts   # bodies shared by a dedicated tool and its inline block
├── watermark.ts                # text and/or image watermark + position, PDF/A-1b transparency guard
├── encryption.ts               # password + encrypt schema (Standard Security Handler), decrypt error mapping
├── inflate-cap.ts              # PDFNATIVE_MCP_MAX_INFLATE_BYTES (engine decompression cap) + PDF_PARSE_FAILED mapping
├── output.ts                   # sandboxed file writer / base64 emitter (single + multi)
├── text.ts                     # newline sanitizer (Safe PDF/A)
├── doc-features.ts             # nested lists, outline, page labels, viewer prefs (+ print-dialog defaults)
├── pagetree.ts                 # page-tree error mapping (merge/split/extract)
├── crypto-provider.ts          # node:crypto signing provider for DER keys (SHA-256/384/512); verification stays pure JS
├── projection.ts               # verbosity / fields projection for the seven read tools
├── errors.ts                   # ToolError, SecurityError, GovernanceError
└── tools/
    ├── generate-basic-pdf.ts
    ├── inspect-layout.ts
    ├── add-barcode.ts
    ├── sign-pdf.ts
    ├── add-ltv.ts
    ├── timestamp-pdf.ts
    ├── update-metadata.ts
    ├── add-international-text.ts
    ├── add-table.ts
    ├── add-form.ts
    ├── read-form-fields.ts
    ├── fill-form.ts
    ├── add-chart.ts
    ├── embed-image.ts
    ├── inspect-pdf.ts
    ├── verify-pdf.ts
    ├── validate-pdf.ts
    ├── add-attachment.ts
    ├── extract-attachments.ts
    ├── extract-text.ts
    ├── merge-pdfs.ts
    ├── split-pdf.ts
    ├── extract-pages.ts
    ├── annotate-pdf.ts
    ├── encrypt-pdf.ts
    ├── decrypt-pdf.ts
    ├── draft-governance-issue.ts
    └── prepare-signature-placeholder.ts
scripts/                        # TypeScript run by tsx — the full table is in scripts/README.md
├── gate.ts                     # THE quality gate (npm run gate / gate:fast; --publish --require-all on release branches)
├── generate-samples.ts         # npm run test:generate — the built server under TZ=UTC -> test-output/samples/
├── verify-samples.ts           # npm run verify:samples — the byte baseline (tests/_fixtures/samples.sha256.json)
├── generate-pdfa-corpus.ts     # npm run corpus:pdfa — the 41-file PDF/A + PDF/X-4 conformance corpus
├── validate-pdfa.ts            # npm run validate:pdfa — veraPDF (PASS/FAIL/XFAIL/XPASS; exit 0 / 1 / 2)
├── validate-pdfx.ts            # npm run validate:pdfx — in-process structural PDF/X-4 check, never skips
├── tool-shape.ts               # structural tools/list fingerprint (--write refreshes tests/_fixtures/tool-shape.json)
├── verify-docs.ts              # npm run verify:docs — the docs held to docs/assets/ecosystem.json and the source tree
├── release-prepare.ts          # mechanical version bump (never commits, tags or publishes)
├── build-claude-rules.ts       # npm run agents:rules — .github/instructions/ -> .claude/rules/
└── verify-issue.mjs            # governance draft checker (npm run verify:issue)
docs/
├── AGENT_CONTRACT.md           # the consumer contract for agents that USE the server (catalogue, decision tree, recipes, error codes)
├── AI_GUIDE.md, KNOWLEDGE_BASE.md, API_STABILITY.md
├── guides/                     # PDFA, PRINT, TYPOGRAPHY, REPRODUCIBLE, CHARTS, FORMS, ENCRYPTION, LTV, AI_GOVERNANCE, LOCAL_TESTING
└── assets/ecosystem.json       # the single source of every count and version quoted in the docs
examples/                       # 43 executable tools/call sequences (npm run examples:check)
AGENTS.md, CLAUDE.md            # repository rules for coding agents; .github/instructions/ holds the per-area rules
.claude/                        # shared agent settings, the fail-closed guard hook, generated rules, the release-audit skill
.github/workflows/              # ci (Node 22 / 24 on Linux, plus Windows and macOS, all running the gate, all required), publish, sample-regression, verapdf (blocking),
                                #   docs, codeql, scorecard, dependency-review, audit
.github/rulesets/               # branch and tag rulesets to import
tests/                          # vitest suites (one per tool / module), _fixtures/ (tool shape, sample baseline, engine-surface matrix,
                                #   the frozen 1.5.0 catalogue), tools/ (repository tooling)

---

🗺 ロードマップ

v1.7.0 がリリースされました（高度なタイポグラフィ、CMYK カラー、PDF/X-4、27 の Unicode スクリプト、すべてのホストで再現可能な出力、pdfnative 1.8）。その基盤となった v1.6.0 では、エンジン全体をカバーし（13 種類のブロック、レイアウトオプション、inspect_layout）、PAdES LTV の段階的対応、印刷用制作、チャート v2、update_metadata、MCP 2026-07-28 を実現しました。リリース済みのマイルストーン、進行中の作業、長期的な方針を含む全計画は、ROADMAP.md をご覧ください。

引き続き延期中の項目：

• redact_pdf — pdfnative にはコンテンツを削除する API がありません。オーバーレイだけの「墨消し」では、セキュリティが確保されたという誤解を招きます。
• カスタムフォント（オペレーター側のフォントディレクトリ）と annotate_pdf の link アノテーション — ロードマップには含まれていますが、v1.7.0 には含まれていません。
• ネイティブ ECDSA 検証 — pdfnative は ecdsaVerifyHash をエクスポートしていないため、verify_pdf は P-256 に対して純粋な JavaScript の処理経路を維持します。
• HTTP ページストリーミング — MCP 2026-07-28 では依然として部分的な structuredContent に対応していないため、大きな結果も一括で返されます。

機能のアイデアがあれば、issue または PR を作成してください。

---

⭐ プロジェクトにスターを付ける

pdfnative-mcp が役に立った場合は、このリポジトリに ⭐ を付けてください。また、基盤となるエンジン Nizoka/pdfnative にもスターを付けていただけると幸いです。スターは、より多くの人にプロジェクトを知ってもらい、継続的な開発の励みになります。

---

🤝 コントリビューション

コントリビューションを歓迎します。CONTRIBUTING.md を読み、未解決の issue を確認のうえ、行動規範に従ってください。

---

📄 ライセンス

MIT © 2026 Nizoka。サードパーティの素材については、THIRD-PARTY-NOTICES.md をご覧ください。

pdfnative-mcp は、pdfnative と Model Context Protocol TypeScript SDK を基盤として構築されています。