NextPDF Connect で最初の PDF を生成する

概要

このレシピでは、空のセッションから NextPDF Connect でレンダリング済み PDF を取得するまでの最短手順を説明します。1 ページの A4 文書を作成し、見出しと副題を書き込み、そのファイルを base64 として返します。これらの処理はすべて、3 つの Core ツール（create_pdf、add_text、output_pdf）で行います。フォント、画像、ライセンス付きティアはいずれも必要ありません。

Connect のトランスポートは、各ツール呼び出しをリクエストとして運び、ツールの結果をレスポンスとして返します。トランスポート層は、ツールが返す結果の内容に依存しません（PSR-18 §p2）。

インストール

NextPDF Server をインストールし、トランスポートをバインドします。

composer require nextpdf/server

ホストが想定するトランスポート（stdio 上の Model Context Protocol、REST、または gRPC）でサーバーを実行します。下記のトランスポートの利用可否を参照してください。このレシピで使うツールは Core ツールです。サーバーに同梱されているため、Pro パッケージや Enterprise パッケージは必要ありません。

概念の概要

Connect のセッションは、document_id をキーにしたサーバー側の文書ストアです。create_pdf はセッションを開き、その id を返します。以降のツール呼び出しはすべて、その id を参照します。文書は 1 枚の空白ページから始まります。ページツリーは、読み手が各ページに到達するための構造です（ISO 32000-2 §7.7.3）。output_pdf はセッションを PDF としてレンダリングします。デフォルトでは、その後メモリを解放するためにセッションを破棄します。

明示的に x や y を指定せずに add_text を呼び出すと、テキストは現在のカーソル位置から自動的に配置され、各呼び出しのあとにカーソルが先へ進みます。

API サーフェス

サーバー起動時に、ツールレジストリが以下のツールを解決します。これらの名前はレジストリ上のプロトコル名です。正式な一覧は、統合版のツールカタログです。利用できるツールはインストールされたティアによって異なりますが、この 3 つは Core に常に含まれます。

ツール	役割	リスクティア
`create_pdf`	文書セッションの開始	Safe
`add_text`	文書へのテキスト書き込み	Caution
`output_pdf`	PDF のレンダリングと返却	Approval Required（ファイルモード）/ Review（base64）

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

ホストは 3 回ツールを呼び出します。流れは次のとおりです。

create_pdf を呼び出し、page_size: "A4"、orientation: "portrait"、文書のタイトル、作成者を指定します。サーバーは document_id を返します。
その document_id、見出しテキスト、大きめの font_size、width: 0（コンテンツ幅いっぱい）、alignment: "center" を指定して add_text を呼び出します。
document_id を指定して output_pdf を呼び出します。file_path を指定しない場合、サーバーは PDF を base64 として返し、セッションを破棄します。

最小限の create_pdf 引数オブジェクトは次の例です。

{
  "page_size": "A4",
  "orientation": "portrait",
  "title": "Hello World",
  "author": "NextPDF Cookbook"
}

レスポンスには document_id、ページ数、ページのジオメトリが含まれます。この id は不透明な値として扱い、その内容から意味を読み取ろうとしないでください。

コードサンプル — 本番

本番の呼び出し側では、次の呼び出しへ進む前にすべてのレスポンスを確認します。output_pdf がセッションを破棄したあとは、その document_id を再利用してはいけません。

create_pdf — レスポンスに document_id が含まれていることを確認します。サーバーがセッション上限のエラーを返した場合は、使用していないセッションを解放してから再試行します。
add_text（見出し） — レスポンスが position を返すことを確認します。
add_text（副題） — より小さい font_size を使用します。カーソルは見出しの下から続きます。
output_pdf — base64 フィールドを読み取り、バイト列へデコードします。destroyed フラグは、セッションが破棄されたことを確認するものです。

ファイルはインラインで返されるため（base64 モード）、ファイルシステムへの副作用はなく、人間による承認ゲートもありません。HITL リスクティアを参照してください。

エッジケースと落とし穴

破棄されたセッション。 デフォルトの destroy: true で output_pdf を実行したあとは、その document_id は無効になります。その document_id に対するそれ以降の呼び出しは、不明な文書エラーを返します。代わりに新しいセッションを作成してください。
不明なページサイズ。 サーバーは認識できない page_size を拒否し、明確なエラーを返します。ドキュメントに記載されたサイズ（A3、A4、A5、A6、Letter、Legal、Tabloid）を使用してください。
空のテキスト。 空の text は、エラーではなく幅ゼロのエントリーを生成します。呼び出し前に入力を確認してください。
セッション上限。 インメモリストアには、同時に保持できるセッション数の上限があります。output_pdf でセッションを速やかに解放してください。

パフォーマンス

テキストのみの 1 ページは、パフォーマンス予算に十分収まる速度でレンダリングされ、出力は通常 1〜3 KB です。このレシピのダブルレンダー再現性プロファイルは structural です。PDF にはトレーラーの /ID と、実行ごとに変化するタイムスタンプが含まれるため、構造的（正規化）比較が適切です。

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

base64 パスにはファイルシステムへの副作用がありません。ファイル出力パスには副作用が 1 つあり、ゲートの対象です。HITL セクションを参照してください。返された base64 は、信頼できるチャネルとしてではなく、文書コンテンツとして扱ってください。これはツールが生成したバイト列そのものです。

コンフォーマンス

記述	仕様	条項	reference_id
結果とは独立した、トランスポートによるリクエスト送信とレスポンス受信	PSR-18	§p2
文書のページツリーを通じたページへの到達	ISO 32000-2	§7.7.3

このレシピは、サーバーが出力を生成する方法を記述したものです。いかなるプロファイルへの準拠も主張するものではありません。

コマーシャルコンテキスト

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

トランスポートの利用可否

トランスポート	利用可否	備考
MCP（stdio）	はい	MCP の `tools/call` に対応
REST	はい	各ツールは REST 操作、結果はレスポンスボディ
gRPC	はい	各ツールはユーナリー呼び出し

ツールの結果はトランスポートを問わず同じで、異なるのはフレーミングだけです。成功でない結果も、トランスポートの失敗ではなく通常のレスポンスです（PSR-18 §p2）。

HITL リスクティア

サーバーは各ツール呼び出しを、人間参加型（HITL）のリスクティアに分類します。Safe (0) → Caution (1) → Review (2) → Approval Required (3)。create_pdf は Safe、add_text は Caution です。output_pdf は Approval Required ですが、base64 モード（file_path なし）では Review に下がり、人間による確認なしで実行されます。ファイルに書き込む場合は Approval Required のままです。output-approval と HITL リスクティアのリファレンスを参照してください。

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

このレシピは base64 モードのままであるため、確認ゲートは許可エンベロープを返します。

{ "allowed": true }

チャレンジエンベロープ（allowed: false、challenge 文字列、1 回限り使用できる token を含む）は、output-approvalに記載されています。