NextPDF Connect クイックスタート

概要

このページでは、MCP と REST の両方のトランスポートで、実用に必要な最小限のやり取りを実行します。各リクエストは、サーバー実装どおりのワイヤーフォーマットです。ソフトウェア開発キット（SDK）は使用しません。

インストール

composer require nextpdf/server

概念の概要

MCP トランスポートは、標準入力と標準出力を介して JSON-RPC 2.0 を使用します。この順序は必須で、記載どおりに実行されます。まず initialize を送信します。次に notifications/initialized の確認応答を送信します。続いて tools/list と tools/call を送信します。サーバーは 1 行につき 1 つの JSON メッセージを読み取り、各行は改行で終わります。その後、1 行につき 1 つのレスポンスを書き込みます。

REST トランスポートは、同じエンジンの機能を HTTP オペレーションとして公開します。ステートレスな単一のレンダリングは、順序付きの operations 配列を伴う 1 回の POST /api/v1/render です。レスポンスボディは PDF です。

コードサンプル — クイックスタート（stdio 上の MCP）

サーバーを起動し、ハンドシェイクをパイプで入力します。以下の 3 つのリクエストでは、プロトコルハンドラーがルーティングする検証済みのメソッド名を使用します。

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"quickstart","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
EOF

この initialize へのレスポンスは、プロトコルバージョン 2025-06-18、サーバー名 NextPDF Connect、および capabilities.nextpdf ブロックを返します。このブロックには、ライブのティア別件数、実行時の tool_count、リスクモデルのバージョン、および hitl_enabled: true が含まれます。tools/list のレスポンスは、このインストールで登録されたツールを過不足なく列挙します。通知行には、仕様上レスポンスは返されません。

次に、安全なツールを呼び出します。diagnostic.doctor ツールは、読み取り専用の環境チェックを実行します。ドキュメントも確認も不要です。

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"quickstart","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"diagnostic.doctor","arguments":{}}}
EOF

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

REST サーバーを起動し、1 行だけの PDF をレンダリングします。サーバーはヘルス以外のすべてのエンドポイントで API キーを要求するため、まずキーを定義します。

export NEXTPDF_API_KEYS='npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef:demo:core:default'
./vendor/bin/rr serve -c .rr.yaml

別のシェルで、レンダリングリクエストを送信します。ボディは RenderRequest です。このリクエストには、型付きオペレーションの順序付き operations 配列が含まれます。

curl -sS -X POST http://localhost:8080/api/v1/render \
  -H 'Authorization: Bearer npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef' \
  -H 'Content-Type: application/json' \
  -d '{
        "page_size": "A4",
        "orientation": "portrait",
        "operations": [
          { "type": "add_text", "text": "Hello from NextPDF Connect" }
        ]
      }' \
  --output hello.pdf

この 200 レスポンスのボディは PDF（Content-Type: application/pdf）で、hello.pdf に書き込まれます。ヘルスプローブにはキーが不要です。

curl -sS http://localhost:8080/healthz

エッジケースと注意点

ハンドシェイクの順序が重要です。 プロトコルハンドラーは、id を持たないメッセージを通知として扱い、何も返しません。initialize を id 付きで送信し、続けて initialized 通知を送信してから、id を持つリクエストを送信します。
繰り返されたリクエスト id は重複排除されます。 ハンドラーは、直近のレスポンスを 64 エントリのリングバッファにキャッシュします。id が重複した場合は、ツールを再実行せずにキャッシュされたレスポンスを返します。毎回新しい id を使用してください。
高リスクのツールは、結果ではなくチャレンジを返します。 output_pdf を呼び出す際に file_path を指定すると、実行結果ではなく確認チャレンジが返されます。発行された _confirmation_token を指定して再度呼び出します。base64 出力モード（file_path なし）では、確認は必要ありません。/connect/hitl-risk-tiers/. を参照してください。
認可されていない REST リクエストは 401 を受け取ります。 Authorization: Bearer ヘッダーが欠落しているか不正な場合は、WWW-Authenticate: Bearer ヘッダーを伴う problem-details ボディが返されます。/healthz と /readyz のプローブが、匿名でアクセスできる唯一のエンドポイントです。

パフォーマンス

どちらのクイックスタートパスも単一リクエストです。REST パスでは、rr serve の後の最初のリクエストで、RoadRunner ワーカープールのコールドスタートコストも発生します。以降のリクエストは、ウォーム状態のワーカーを再利用します。

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

上記の npk_live_ キーは、使い捨てのデモ用の値です。実際のキーは十分なエントロピーを持たせて生成し、ソース管理の外部に保存し、ローテーションにはファイルベースのキーストアを優先してください。MCP stdio トランスポートで API キーを使わないのは、MCP トランスポートモデルに従い、起動元のクライアントから信頼されるローカルのサブプロセスだからです。/connect/security-and-operations/. を参照してください。

適合性

示されているワイヤーフォーマットは、実装されている MCP リビジョン 2025-06-18 および OpenAPI 3.1 の REST コントラクトに一致します。規範的なプロトコルと認証の出典は、/transports/mcp/、/transports/rest/、および /connect/security-and-operations/. に固定されています。