NextPDF Connect の環境診断を実行する

概要

実際の作業に入る前に、NextPDF Connect サーバーが健全で、ワークフローに必要な機能を備えていることを確認します。これは、あらゆるエージェント型パイプラインで推奨される最初のステップです。サーバーのツールレジストリで再確認されているツールは、diagnostic.doctor、diagnostic.capabilities、diagnostic.verify です。レジストリはこれらをドット区切りのプロトコル名で公開しており、関連する diagnostic.inspect も存在します。いずれも Core です。

インストール

composer require nextpdf/server

トランスポートをバインドします。veraPDF は、任意で行う準拠性検証ステップにのみ必要です。構造検証には外部ツールは不要です。

概念の概要

diagnostic.doctor は、基本的な健全性レポートを返します。内容は、PHP のバージョン、ロード済みの拡張機能、サーバーのバージョン、アクティブなティア、および各種警告です。status をゲートとして扱います。ok なら続行し、warning なら warnings を読み、error なら停止します。
diagnostic.capabilities は、登録済みの機能を、対応するティアとランタイムステータス（available、unavailable、degraded）とともに一覧表示します。機能の数は ランタイムとティアに依存 するため、合計をハードコードしないでください。ワークフローが依存する各機能を、一つずつ確認してください。
diagnostic.verify は構造的な整合性を検査します。対象は、PDF ヘッダー、EOF マーカー、およびクロスリファレンステーブルです。これは、ページツリーを通じて到達する文書構造です（ISO 32000-2 §7.5）。compliance_flavour を指定すると、veraPDF も呼び出します。

診断結果は、どのトランスポートでも通常のレスポンスとして返ります（PSR-18 §p2）。

API サーフェス

ツール	役割	リスクティア
`diagnostic.doctor`	環境の健全性レポート	Safe
`diagnostic.capabilities`	ステータス付き機能インベントリ	Safe
`diagnostic.verify`	構造検証/準拠性検証	Safe
`create_pdf`、`add_text`、`output_pdf`	文書のスモークテスト	別途記載のとおり

これらの名前は、レジストリのプロトコル名です。ツールカタログが正式なカタログです。どのツールや機能が存在するかはインストールされたティアに依存するため、ツールや機能の数を固定値として断定しないでください。

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

diagnostic.doctor（引数なし）→ status を読みます。
diagnostic.capabilities（引数なし）→ 必要な各機能が available であることを確認します。
create_pdf に続けて add_text → 最小限のスモーク文書を作成します。
diagnostic.verify に document_id を渡す → 構造検査を実行します。
任意で、diagnostic.verify に compliance_flavour: "4" を指定する → veraPDF を実行します。
output_pdf（base64）→ スモークセッションを破棄します。

コードサンプル — プロダクション

パイプラインを diagnostic.doctorstatus でゲートします。各ワークフローの依存関係を特定の機能 id にマッピングし、依存するステップを実行する前に available であることをアサートします。degraded は、スポットチェックを要する品質リスクとして扱います。構造的な diagnostic.verify は常に実行します。準拠性バリアントは、適合性が重要な場合にのみ実行し、veraPDF が存在しない場合は、サーバーの欠陥ではなく明確な not-found 結果が返るものとして受け入れてください。

エッジケースと注意点

veraPDF が存在しない場合。 準拠性の呼び出しは、明示的な not-found 結果を返します。構造検査は引き続き機能します。準拠性検証が必要な場合は、veraPDF をインストールし、サーバープロセスの PATH に追加してください。
veraPDF のタイムアウト。 大きな文書では、検証のタイムアウトに達することがあります。文書のサイズを減らすか、サーバー設定でタイムアウトを引き上げてください。
degraded の機能。 依存関係が部分的にしか利用できないため、出力品質が低下することがあります。使用中のフォールバックについては、サーバーのログを確認してください。
Doctor の error。 重要な要件が満たされていません。続行しないでください。

パフォーマンス

構造検証は高速です。準拠性パスは veraPDF を起動し、検証のタイムアウトによって上限が定められます。大きめの予算は、そのサブプロセスを反映したものです。

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

診断出力は、PHP のバージョン、拡張機能、ティアといった環境の詳細を明らかにします。これはオペレーター専用として扱い、信頼できない呼び出し元には公開しないでください。

準拠性

記述	仕様	条項	reference_id
診断結果は、通常のトランスポートレスポンスです。	PSR-18	§p2
構造的整合性の対象は、ページツリーに固定された構造です。	ISO 32000-2	§7.5

準拠性バリアントは veraPDF を実行し、その判定を報告します。NextPDF 自体は準拠性を主張しません。判定はバリデーターが行います。

商用上の位置づけ

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

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

トランスポート	提供	備考
MCP（stdio）	はい	診断結果はツール結果です。
REST	はい	ヘルスエンドポイントは、これらのツールにマッピングされます。
gRPC	はい	ユーナリ。結果は同じステータスフィールドを維持します。

HITL リスクティア

3 つの診断ツールはいずれも Safe です。読み取り専用で、副作用はありません。これらが確認ゲートをトリガーすることはありません。スモークテストの output_pdf は base64 モードです（Review、ゲートなし）。

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

診断によってゲートされることはありません。

{ "allowed": true }