NextPDF Connect で複数ページのドキュメントを作成する

概要

NextPDF Connect で複数ページのドキュメントを作成します。 add_page は、ドキュメントのデフォルトのジオメトリを継承するページ、または向きを上書きするページを追加します。各 add_page の後、カーソルは新しいページの左上マージンにリセットされます。使用するツールは 4 つで、いずれも Core です。create_pdf、add_text、add_page、および output_pdf です。

インストール

composer require nextpdf/server

トランスポートをバインドします。MCP stdio、REST、または gRPC のいずれかを使用します。ライセンスティアは不要です。

概念の概要

ドキュメントはページツリーとして構成されます。各ページは、そのツリーを通じて到達されるノードです（ISO 32000-2 §7.7.3）。ページは、可視領域を定義するメディアボックスを含め、独自のジオメトリ属性を持ちます（ISO 32000-2 §7.7.3.3）。 create_pdf は最初のページを自動的に作成し、add_page は以降のページを追加します。ドキュメントのデフォルトを継承するには、page_size/orientation を省略します。 A4 ページを 297×210 mm に回転させるには、orientation: "landscape" を設定します。

API サーフェス

ツール	役割	リスクティア
`create_pdf`	セッションを開き、最初のページを作成	Safe
`add_text`	カーソル位置へのテキスト書き込み	Caution
`add_page`	ページを追加（継承または上書き）	Caution
`output_pdf`	PDF のレンダリングと返却	Approval Required / Review（base64）

ツール名はレジストリ上のプロトコル名です。ツールカタログが正式なカタログです。利用できるツールは、インストールされているティアによって異なります。

コードサンプル — クイックスタート

手順を文章で示すと、以下のとおりです。

create_pdf（A4 縦向き、タイトル、作成者）→ document_id。
add_text（タイトル、大きいフォント、中央揃え）、続いて add_text（導入の段落、本文フォント）。
document_id のみを指定した add_page → A4 縦向きを継承します。新しい page_number が返され、カーソルはリセットされます。
2 ページ目のセクション見出しと本文に対して add_text。
orientation: "landscape" を指定した add_page → 横長の A4 ページ。
横長のコンテンツに対して add_text。
output_pdf → base64。

コードサンプル — 本番環境

各レスポンスを検証します。 add_page の後は、コンテンツが新しいページの先頭から始まるものとして扱います。カーソルのリセットは意図された動作であり、不具合ではありません。コンテンツが後続ページに送られたタイミングを検出するには、add_text のレスポンスから position.page を追跡します。 output_pdf はちょうど 1 回だけ呼び出し、その後 document_id を破棄します。

エッジケースと注意点

カーソルのリセット。 add_page の後、カーソルは新しいページの左上マージンに移動します。前のページからそのまま続くと想定することが、最もよくある誤りです。
document_id は必須。 create_pdf を除くすべてのツールは document_id を必要とします。省略するとエラーになります。
無効な向き。 有効なのは "portrait" と "landscape" のみです。
出力後の編集。 destroy: true を指定した output_pdf の後にコンテンツを追加しようとすると、セッションが失われているため失敗します。

パフォーマンス

複数ページのテキストドキュメントはページ予算内に収まり、出力は数 KB です。プロファイルは structural です。トレーラーの /ID とタイムスタンプは、実行間で安定しません。

セキュリティに関する注意

base64 モードには副作用がありません。ファイル出力はゲートされています（HITL セクション）。 document_id は不透明なハンドルです。並行して実行されるリクエスト間で共有しないでください。

準拠

記述	仕様	箇条	reference_id
ページはページツリーを通じて到達される。	ISO 32000-2	§7.7.3
ページオブジェクトは独自のジオメトリ属性を定義する。	ISO 32000-2	§7.7.3.3

商用コンテキスト

該当なし — すべてのツールは Core です。

トランスポートの提供状況

トランスポート	提供状況	備考
MCP (stdio)	あり	ツールごとに `tools/call`。
REST	あり	ツールごとに 1 つの操作。
gRPC	あり	ツールごとに unary。

HITL リスクティア

create_pdf は Safe、add_text と add_page は Caution、output_pdf は Approval Required で、base64 モードでは Review にダウングレードされます。ファイル出力では Approval Required のままです。 output-approval および HITL リスクティアを参照してください。

確認ゲートの JSON エンベロープ

base64 出力は次のとおりです。

{ "allowed": true }

チャレンジフォームは output-approval に示されています。