NextPDF Connect API リファレンス

概要

このページは、NextPDF Connect サーバー（nextpdf/server）のシンボルレベルのリファレンスです。各ツールを登録済みツール名と実装クラスで一覧化し、リモートプロシージャコール（RPC）メソッド、およびリクエスト/レスポンスメッセージを備えた gRPC サービス NextPDFConnect について説明します。すべてのトランスポートに共通する、認証、エラー、レート制限の契約も示します。

サーバーは、3 つのトランスポート（標準入出力上の Model Context Protocol（MCP）、Representational State Transfer（REST）Application Programming Interface（API）、および gRPC）にわたって 1 つのツールレジストリを公開します。各トランスポートのワイヤーレベルの詳細は、それぞれ専用ページの MCP トランスポート、REST トランスポート、gRPC トランスポートを参照してください。このページは、それらのトランスポートで扱われるシンボルのカタログです。

以下のツール名、クラス、リスクティアは、src/Tools/ にあるツール実装から読み取られます。実際のデプロイで公開されるツール数はランタイムのプロパティです。ツールカタログを参照してください。ティアの resolve（解決）については、ブートとディスカバリーで説明します。

トランスポートの可用性

ツールには、デプロイが実行しているトランスポートを通じてアクセスできます。各トランスポートは独立したプロセスです。一方を実行しても、もう一方は起動しません。

トランスポート	エントリーポイント	ワイヤーフォーマット	認証
MCP	`bin/nextpdf-mcp`	標準入出力（stdio）上の JavaScript Object Notation Remote Procedure Call（JSON-RPC）2.0	オペレーティングシステムのプロセス境界（API キーなし）
REST	`bin/nextpdf-server`	HTTP、OpenAPI 3.1	ベアラー API キー（`Authorization` ヘッダー内）
gRPC	`bin/nextpdf-grpc`	Protocol Buffers、パッケージ `nextpdf.connect.v1`	ベアラートークン（`authorization` コールメタデータ内）

MCP では、登録済みツール名を指定して tools/call でツールを呼び出します。REST と gRPC では、同じエンジン機能にレンダー、オペレーション、ケイパビリティの各サーフェスからアクセスします。REST トランスポートのルートテーブルと gRPC トランスポートの RPC テーブルを参照してください。

認証とリスクティア

API キー認証

REST と gRPC のトランスポートでは、認証不要のヘルスプローブを除くすべてのリクエストでベアラー API キーが必要です。キーは npk_live_{kid}_{secret} という形式です。kid はレコード参照用の 8 文字の識別子で、シークレットがエントロピーを担います。サーバーはキーの SHA-256 ダイジェストのみを保存し、提示されたトークンを定数時間比較で照合するため、誤ったキーからタイミング経由で情報が漏れることはありません。REST はトークンを Authorization: Bearer … ヘッダーから読み取り、gRPC は同じトークンを authorization コールメタデータから読み取ります。MCP の stdio トランスポートは、起動元のクライアントから信頼されるローカルサブプロセスであるため、API キーを持ちません。認証モデルの詳細は、セキュリティと運用に記載しています。

4 つのリスクティア

すべてのツールは、RiskLevel（src/Config/RiskLevel.php）で定義される、順序を持つ 4 つのリスクレベルのいずれか 1 つを宣言します。

ティア	Enum ケース	値	効果
Safe	`RiskLevel::Safe`	0	読み取り専用、副作用なし。自動実行されます。
Caution	`RiskLevel::Caution`	1	メモリ内の状態を作成または変更します。自動実行され、監査ログに記録されます。
Review	`RiskLevel::Review`	2	悪用されるおそれのある出力を生成します。自動実行され、監査ログに記録されます。
ApprovalRequired	`RiskLevel::ApprovalRequired`	3	破壊的、法的、またはプライバシーに関わる重大な操作。人間による確認が必要です。

ツールの実効リスクは、厳密に 2 つの要素で決まります。ツール自身の riskLevel() 宣言と、リスクの引き上げのみが可能な任意のオペレーター設定オーバーライドです。このオーバーライドで ApprovalRequired ツールを引き下げることはできません。HITL リスクティアと設定を参照してください。

承認トークンのフロー

有効なトークンなしで ApprovalRequired ツールが呼び出されると、ConfirmationGate（src/Mcp/ConfirmationGate.php）はツールを実行せず、1 回限り使用できるチャレンジトークンを返します。エージェントはチャレンジを人間に中継し、その後、発行されたトークンを _confirmation_token 引数に指定して同じツールを再度呼び出します。トークンは、ツール名、ランダムな nonce、および 300 秒の有効期間（TTL）をバインドします。トークンは引数をバインドせず、認証資格情報でもありません。REST では、ベアラー API キーが引き続きリクエストを認証し、同じゲートがゲート対象の操作の前に共通のツールエグゼキューターで実行されます。gRPC では、同じゲートがディスパッチされる操作の前に実行されます。チャレンジとトークンの仕組みは、すべてのトランスポートで同一です。

ツールとエンドポイント

この表では、各ツールを登録済みツール名（Symbol 列）で示し、その実装クラスを記載します。ツールはティアとカテゴリでグループ化されています。すべての AST クラスとミューテーションクラスは src/Tools/Ast と src/Tools/Ast/Mutation の下にあります。抽出クラスは src/Tools/Extraction の下にあり、残りのクラスは src/Tools/Core の下にあります。

コアドキュメントツール

シンボル	パラメーター	デフォルトの動作	戻り値	スローまたは失敗の条件	備考
`create_pdf`	`page_size`（デフォルト `A4`）、`orientation`（`portrait`/`landscape`）、`title`、`author`。いずれも必須ではありません。	メモリ内ドキュメントと 1 ページを作成し、指定がある場合はメタデータを設定します。	`document_id`、`page_count`、`page_size`、`orientation` を含む JSON。	失敗時はエンジンのメッセージを含むエラー結果を返します。	クラス `CreatePdfTool`。リスク `RiskLevel::Caution`。ティア core。返される `document_id` は、後続のすべての操作に渡されます。
`add_page`	`document_id`（必須）、任意のページサイズと向き。	ドキュメントにページを追加します。	新しいページ数を含む JSON。	指定した `document_id` が不明な場合はエラー結果。	クラス `AddPageTool`。リスク `RiskLevel::Caution`。ティア core。
`add_text`	`document_id`（必須）、`text`（必須）、任意の位置とスタイル。	ドキュメントにテキストを追加します。	JSON 形式のドキュメント状態サマリー。	指定した `document_id` が不明な場合はエラー結果。	クラス `AddTextTool`。リスク `RiskLevel::Caution`。ティア core。
`add_image`	`document_id`（必須）、`source`（必須: ファイルパスまたは base64）、任意の配置。	パスまたは base64 データから画像を追加します。	JSON 形式のドキュメント状態サマリー。	ソースを読み取れない場合、または `document_id` が不明な場合はエラー結果。	クラス `AddImageTool`。リスク `RiskLevel::Caution`。ティア core。
`add_table`	`document_id`（必須）、`html`（必須）。	Hypertext Markup Language（HTML）テーブルをドキュメントにレンダリングします。	JSON 形式のドキュメント状態サマリー。	マークアップが無効な場合、または `document_id` が不明な場合はエラー結果。	クラス `AddTableTool`。リスク `RiskLevel::Caution`。ティア core。
`set_font`	`document_id`（必須）、`family`（必須）、任意のサイズとスタイル。	後続のテキスト操作で使用するフォントを設定します。	アクティブなフォントを確認する JSON。	フォントが不明な場合、または `document_id` が不明な場合はエラー結果。	クラス `SetFontTool`。リスク `RiskLevel::Caution`。ティア core。
`output_pdf`	`document_id`（必須）、`file_path`（任意）、`destroy`（デフォルト `true`）。	ドキュメントを確定します。`file_path` に書き込むか、省略時は base64 を返します。デフォルトでドキュメントを破棄します。	`file_path` と `file_size`、または `base64` と `file_size` を含む JSON。	指定した `document_id` が不明な場合はエラー結果。ベースディレクトリの外に書き込む場合はパス封じ込めの失敗。	クラス `OutputPdfTool`。リスク `RiskLevel::ApprovalRequired`。ティア core。ファイルへの書き込みは確認ゲートを通過します。base64 モードは通過しません。
`preview_layout`	`document_id`（必須）。	最終的な PDF をレンダリングせずに、レイアウトのサマリーを返します。	JSON 形式のレイアウトサマリー。	指定した `document_id` が不明な場合はエラー結果。	クラス `PreviewLayoutTool`。リスク `RiskLevel::Safe`。ティア core。
`parse_pdf`	`document_id`（必須）。	構造メタデータ（ページ数、フォント、画像、暗号化、Info Dictionary）を検査します。	JSON 形式の構造メタデータ。	ドキュメントの形式が不正な場合はエラー結果。	クラス `ParsePdfTool`。リスク `RiskLevel::Safe`。ティア core。`NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED` が `true` または `1` の場合にのみ登録されます。

コア診断ツール

シンボル	パラメーター	デフォルトの動作	戻り値	スローまたは失敗の条件	備考
`diagnostic.doctor`	なし。	ヘルスチェックを実行し、構造化された環境診断を返します。	JSON 形式の環境レポート。	内部チェックに失敗した場合はエラー結果。	クラス `DiagnosticDoctorTool`。リスク `RiskLevel::Safe`。ティア core。ドキュメントも確認も不要です。
`diagnostic.capabilities`	なし。	ティアとステータス情報を含む機能一覧を表示します。	JSON 形式の機能一覧。	内部エラーの場合はエラー結果。	クラス `DiagnosticCapabilitiesTool`。リスク `RiskLevel::Safe`。ティア core。
`diagnostic.inspect`	`document_id`（必須）。	PDF を検査し、構造メタデータを返します。	JSON 形式の構造メタデータ。	指定した `document_id` が不明な場合はエラー結果。	クラス `DiagnosticInspectTool`。リスク `RiskLevel::Safe`。ティア core。
`diagnostic.verify`	`document_id`（必須）、任意の PDF/A または PDF/UA プロファイル。	構造の整合性を検証し、任意で VeraPDF サブプロセスを起動して PDF/A または PDF/UA を検証します。	JSON 形式の検証レポート。	サブプロセスの失敗、タイムアウト、またはサイズ超過の入力の場合はエラー結果。	クラス `DiagnosticVerifyTool`。リスク `RiskLevel::Caution`。ティア core。入力は 50 メビバイト（MiB）に制限されています。

コアバーコードツール

シンボル	パラメーター	デフォルトの動作	戻り値	スローまたは失敗の条件	備考
`generate_barcode`	`payload`（必須）、`format`（例: QR コード、DataMatrix など）。	ペイロードの二次元バーコードモジュールマトリックスを生成します。	JSON 形式のモジュールマトリックス。	`format` がサポート対象外の場合、またはペイロードが無効な場合はエラー結果。	クラス `BarcodeTool`。リスク `RiskLevel::Caution`。ティア core。`BarcodeTool` は、コアの `barcode` エンコーダーレジストリがインストール済みの `nextpdf/core` に存在する場合にのみ登録されます。登録されるツール名は `generate_barcode` です。

Enterprise プライバシーツール

これらのツールは Enterprise プライバシークラスをラップし、それらのクラスがオートロード可能な場合にのみ Enterprise ティアの下に登録されます。操作対象はプレーンテキストのコンテンツです。

シンボル	パラメーター	デフォルトの動作	戻り値	スローまたは失敗の条件	備考
`redact_pdf`	`content`（必須）、任意の検出オプション。	Enterprise の墨消しエンジンを使用して、プレーンテキストコンテンツ内の個人を特定できる情報（PII）を破壊的に墨消しします。	墨消し後のコンテンツと SHA-256 ハッシュを含む JSON。	Enterprise クラスが存在しない場合、または検出に失敗した場合はエラー結果。	クラス `RedactPdfTool`。リスク `RiskLevel::Review`。ティア enterprise。
`deidentify_pdf`	`content`（必須）、`strategy`（redact または suppress）。	Enterprise の非識別化機能を使用して、プレーンテキストコンテンツに体系的な非識別化戦略を適用します。	非識別化後のコンテンツを含む JSON。	Enterprise クラスが存在しない場合はエラー結果。	クラス `DeIdentifyPdfTool`。リスク `RiskLevel::Review`。ティア enterprise。
`zone_redact_pdf`	`content`（必須）、`zones`（ページと正規化された矩形のリスト）。	Enterprise の墨消しエンジンを使用して、座標ベースのゾーン墨消しを適用します。	墨消し後のコンテンツを含む JSON。	ゾーンが無効な場合、または Enterprise クラスが存在しない場合はエラー結果。	クラス `ZoneRedactionTool`。リスク `RiskLevel::Review`。ティア enterprise。

抽象構文木（AST）読み取りツール

これらのツールはサーバーに同梱され、Pro ティアの下に登録され、NEXTPDF_AST_TOOLS_ENABLED（デフォルトで有効）によってゲートされます。いずれも読み取り専用です。

シンボル	パラメーター	デフォルトの動作	戻り値	スローまたは失敗の条件	備考
`get_document_ast`	`pdf_data`（必須）。	セマンティック AST（すべての構造要素に対する引用アンカーを備えた完全なノードツリー）を構築します。	JSON 形式のノードツリーと、並行性制御用の ETag。	ドキュメントの形式が不正な場合はエラー結果。	クラス `GetDocumentAstTool`。リスク `RiskLevel::Safe`。ティア pro。
`get_ast_node`	`pdf_data`（必須）、`node_id`（必須）。	単一の AST ノードとそのすべての子を取得します。	子を含むノードの JSON。	`node_id` が不明な場合はエラー結果。	クラス `GetAstNodeTool`。リスク `RiskLevel::Safe`。ティア pro。
`get_ast_diff`	`original_pdf_data`（必須）、`modified_pdf_data`（必須）。	2 つのドキュメントのセマンティック AST を比較し、構造的な差分を取得します。	追加、削除、変更されたノードの JSON。	入力ドキュメントの形式が不正な場合はエラー結果。	クラス `GetAstDiffTool`。リスク `RiskLevel::Safe`。ティア pro。
`search_ast_nodes`	`pdf_data`（必須）、任意のタイプ、ページインデックス、テキストフィルター。	タイプ、ページインデックス、またはテキストコンテンツで AST ノードを検索します。	浅い子を含む、一致ノードのフラットなリストの JSON。	ドキュメントの形式が不正な場合はエラー結果。	クラス `SearchAstNodesTool`。リスク `RiskLevel::Safe`。ティア pro。
`extract_cited_text`	`pdf_data`（必須）、任意の `headings_only`。	引用アンカー（ページ、バウンディングボックス、信頼度）付きのテキストブロックを抽出します。	JSON 形式の引用テキストブロック。	ドキュメントの形式が不正な場合はエラー結果。	クラス `ExtractCitedTextTool`。リスク `RiskLevel::Safe`。ティア pro。カテゴリ `ast`。
`extract_cited_tables`	`pdf_data`（必須）。	引用アンカー付きのテーブルブロックを抽出します。Table ノードごとに、セルの行優先マトリックスを返します。	アンカー付きテーブルマトリックスの JSON。	ドキュメントの形式が不正な場合はエラー結果。	クラス `ExtractCitedTablesTool`。リスク `RiskLevel::Safe`。ティア pro。カテゴリ `extraction`。

AST ミューテーションツール

これらのツールはサーバーに同梱され、Pro ティアの下に登録され、NEXTPDF_MUTATION_TOOLS_ENABLED（デフォルトで有効）によってゲートされます。4 つすべてが ApprovalRequired であり、ETag を介した楽観的並行性制御（OCC）を使用します。

シンボル	パラメーター	デフォルトの動作	戻り値	スローまたは失敗の条件	備考
`apply_ast_mutations`	`pdf_data`、`etag`、`idempotency_key`、`mutations`（すべて必須）。	ミューテーションのバッチをアトミックに適用します。`idempotency_key` が繰り返された場合は、キャッシュ済みの結果を再生します。	ミューテーション後の PDF と新しい ETag を含む JSON。	ETag が古い場合は OCC 競合。ミューテーションの形式が不正な場合は検証エラー。	クラス `ApplyAstMutationsTool`。リスク `RiskLevel::ApprovalRequired`。ティア pro。
`delete_ast_node`	`pdf_data`、`node_id`、`etag`（すべて必須）。	オーバーレイモードでノードを削除します（元のコンテンツは物理的には削除されず、覆い隠されます）。	変更後の PDF と新しい ETag を含む JSON。	ETag が古い場合は OCC 競合。`node_id` が不明な場合はエラー。	クラス `DeleteAstNodeTool`。リスク `RiskLevel::ApprovalRequired`。ティア pro。
`insert_ast_node`	`pdf_data`、`parent_node_id`、`position`、`etag`、`node`（すべて必須）。	親の指定位置に、新しいノードを子として挿入します。	変更後の PDF と新しい ETag を含む JSON。	ETag が古い場合は OCC 競合。ノードの形式が不正な場合は検証エラー。	クラス `InsertAstNodeTool`。リスク `RiskLevel::ApprovalRequired`。ティア pro。
`update_ast_node`	`pdf_data`、`node_id`、`etag`、`updates`（すべて必須）。	ノードのテキストコンテンツを更新します。	変更後の PDF と新しい ETag を含む JSON。	ETag が古い場合は OCC 競合。`node_id` が不明な場合はエラー。	クラス `UpdateAstNodeTool`。リスク `RiskLevel::ApprovalRequired`。ティア pro。

リクエストとレスポンスのスキーマ

gRPC トランスポートは、サーバーの型付きスキーマを Protocol Buffers パッケージ nextpdf.connect.v1（proto/nextpdf/connect/v1/*.proto 内）で定義します。サービスとそのメッセージが、正規のスキーマシンボルです。

サービス `NextPDFConnect`

サービス NextPDFConnect は、ユナリー RPC とサーバーストリーミング RPC を公開します。スキーマシンボルは、RPC メソッド名と、それらが運ぶリクエストおよびレスポンスのメッセージです。

RPC	リクエストメッセージ	レスポンスメッセージ	形態
`Render`	`RenderRequest`	`RenderResponse`	ユナリー。同期のステートレスレンダー。
`RenderStream`	`RenderRequest`	`RenderChunk`（ストリーム）	サーバーストリーミング。順序付きチャンクとして配信されるレンダー。
`SubmitJob`	`SubmitJobRequest`	`JobResponse`	ユナリー。非同期レンダージョブの送信。
`GetJobStatus`	`GetJobStatusRequest`	`JobResponse`	ユナリー。ジョブステータスのポーリング。
`GetJobResult`	`GetJobResultRequest`	`RenderResponse`	ユナリー。完了済み結果のダウンロード。
`GetJobResultStream`	`GetJobResultRequest`	`RenderChunk`（ストリーム）	サーバーストリーミング。完了済み結果のチャンク単位でのダウンロード。
`CancelJob`	`CancelJobRequest`	`JobResponse`	ユナリー。ジョブのキャンセルまたは削除。
`CreateSession`	`CreateSessionRequest`	`SessionResponse`	ユナリー。ドキュメント構築セッションの作成。
`GetSession`	`GetSessionRequest`	`SessionResponse`	ユナリー。セッションメタデータの取得。
`DestroySession`	`DestroySessionRequest`	`DestroySessionResponse`	ユナリー。セッションとそのドキュメントの破棄。
`SessionOperation`	`SessionOperationRequest`	`SessionResponse`	ユナリー。セッションドキュメントに対する操作の実行。
`SessionRender`	`SessionRenderRequest`	`RenderResponse`	ユナリー。セッションドキュメントの PDF レンダリング。
`SessionRenderStream`	`SessionRenderRequest`	`RenderChunk`（ストリーム）	サーバーストリーミング。セッションドキュメントのチャンク単位でのレンダリング。
`ExecuteCapability`	`CapabilityRequest`	`CapabilityResponse`	ユナリー。ティアでゲートされたケイパビリティ操作の実行。
`GetCapabilities`	`GetCapabilitiesRequest`	`GetCapabilitiesResponse`	ユナリー。認証済みクライアントの機能一覧。
`HealthCheck`	`HealthCheckRequest`	`HealthCheckResponse`	ユナリー。ライブネスプローブ。
`ReadinessCheck`	`ReadinessCheckRequest`	`ReadinessCheckResponse`	ユナリー。レディネスプローブ。

メッセージシンボル

リクエストとレスポンスのメッセージは、スキーマの構造シンボルです。レンダーメッセージ（RenderRequest、RenderResponse、およびストリーミングの RenderChunk）は、ページサイズ、向き、順序付き操作、および結果として得られる PDF バイトを運びます。ジョブメッセージ（SubmitJobRequest、GetJobStatusRequest、GetJobResultRequest、CancelJobRequest、および JobResponse）は、非同期ジョブのライフサイクルをモデル化し、ジョブのメタデータは JobData メッセージに保持されます。セッションメッセージ（CreateSessionRequest、SessionResponse、GetSessionRequest、DestroySessionRequest、DestroySessionResponse、SessionOperationRequest、および SessionRenderRequest）は、ステートフルなセッションのライフサイクルをモデル化し、セッションのメタデータは SessionData メッセージに保持されます。ケイパビリティメッセージ（CapabilityRequest、CapabilityResponse、GetCapabilitiesRequest、および GetCapabilitiesResponse）は、ティアでゲートされた操作のディスパッチとイントロスペクションを運びます。システムメッセージ（HealthCheckRequest、HealthCheckResponse、ReadinessCheckRequest、および ReadinessCheckResponse）は、ライブネスとレディネスのステータスを運びます。

同梱される .proto ファイルが、ワイヤー契約の正本です。gRPC トランスポートのリファレンスは gRPC トランスポートにあります。

エラーモデル

サーバーは、各トランスポート固有のエラーメカニズムで失敗を報告します。各トランスポートは同じ論理条件を維持し、エンコーディングのみが異なります。

MCP

MCP のエラーは JSON-RPC 2.0 のエラーオブジェクトです。不明なメソッドは method-not-found（-32601）を返し、有効な JSON-RPC でないメッセージは invalid-request（-32600）を返し、解析できない入力は parse-error（-32700）を返します。失敗したツールは、トランスポートレベルのエラーではなく、コンテンツ内にエラーを示す成功した JSON-RPC レスポンスを返すため、エージェントはメッセージを読み取れます。ApprovalRequired ツールの確認チャレンジも、エラーではなく成功したレスポンスです。

REST

REST は、RFC 9110 で定義されたセマンティクスに従って Hypertext Transfer Protocol（HTTP）ステータスコードを使用します。200 は結果を運びます。400 はリクエストフィールドの形式検証が失敗した場合に返されます。401 は有効な API キーが提示されない場合に返され、WWW-Authenticate: Bearer チャレンジヘッダーを伴います。403 は有効なキーのティアに操作の権限がない場合に返されます。404 は、ティアでゲートされたルートがパッケージの不在により登録されていない場合に返されます。機械可読なエラーボディは RFC 9457 に準拠した Problem Details ドキュメントで、application/problem+json メディアタイプと、条件ごとに安定した type Uniform Resource Identifier（URI）とともに提供されます。フィールドレベルの検証失敗はボディに列挙されます。パストラバーサル対策の強化策として、document_id がパターン doc_[a-f0-9]{24} に一致しない場合、ツールの実行前に 400 で拒否されます。REST のミドルウェアパイプラインとルートテーブルは、REST トランスポートに記載しています。

gRPC

gRPC は、標準の gRPC ステータスコードを使用します。欠落、不正な形式、不明、無効化、または期限切れのトークンは、HTTP ステータスではなく UNAUTHENTICATED でコールを失敗させます。リッチなエラー詳細は REST の Problem Details の形態を反映し、gRPC のステータス詳細で運ばれるため、エラーの type URI はトランスポート間で一貫します。

参照: ステータスコードのセマンティクスについては RFC 9110（HTTP Semantics）を、エラーボディの形式については RFC 9457（Problem Details for HTTP APIs）を参照してください。

RFC 9110（HTTP セマンティクス）: https://www.rfc-editor.org/rfc/rfc9110
RFC 9457（HTTP API の Problem Details）: https://www.rfc-editor.org/rfc/rfc9457

レート制限とクォータ

REST トランスポートは、ミドルウェアパイプラインで Internet Protocol アドレスごと（IP ごと）およびクライアントごとのレート制限を適用し、さらにボディサイズ、ティアごとのペイロード制限、リクエストごとのタイムアウトを適用します。関連する上限は、ハードコードされた定数ではなく設定値です。

ティアごとのペイロード上限（corePayloadLimit、proPayloadLimit、enterprisePayloadLimit）と対応するタイムアウトは、認証済みキーのティアに応じて REST に適用されます。設定を参照してください。
メモリ内のドキュメントストアは、max_documents（デフォルト 50）と document_ttl（デフォルト 1800 秒）によって上限が設けられます。
レート制限と冪等性の状態は、共有ストア用に NEXTPDF_REDIS_HOST が設定されていない限り、ワーカーごとです。デプロイを参照してください。

レート制限と冪等性のストアが共有されている場合、同一の非同期ジョブ送信が繰り返されると idempotency_key によって重複排除されます。MCP トランスポートはパイプ上で一度に 1 つのリクエストを処理し、ネットワークのレート制限を適用する代わりに、64 エントリのバッファで繰り返されたリクエスト id を重複排除します。

開発上の注意

ツール名、クラス、リスクティアは、src/Tools/ の下のソースから読み取ってください。固定の合計数を前提にしないでください。ツールカタログに示すように、正確な数については実行中のサーバーに問い合わせてください。
gRPC クライアントスタブは、同梱される proto/nextpdf/connect/v1/*.proto ファイルから再生成してください。パッケージと名前空間は nextpdf.connect.v1 です。生成されたメッセージクラスを手動で編集しないでください。
対象の ApprovalRequired ツールは、最初の呼び出しで確認チャレンジを返します。リトライ経路（チャレンジを中継し、その後 _confirmation_token を指定して再度呼び出す）を構築してから、output_pdf や任意のミューテーションツールを駆動する統合を出荷してください。
インストールされていない、ティアでゲートされたルートやケイパビリティは、認証の失敗ではありません。REST は不在のルートに対して 404 を返し、gRPC の ExecuteCapability は操作を利用不可として報告します。不在の Pro または Enterprise ティアは、障害ではなく想定どおりの動作として扱ってください。
API キーをソース管理の外に保管してください。シークレットファイルからマウントし、ローテーション時に再起動が不要となるよう、ホットリロード対応のファイルキーストアを優先してください。セキュリティと運用を参照してください。