NextPDF Connect の統合

概要

NextPDF Connect は、サーバーとして実行して統合します。ライブラリをホストアプリケーションに組み込む方式ではありません。トランスポートを選択し、そのトランスポートがネットワーク経由の場合は認証を構成します。エンジンのツールは確認ゲートの背後に配置されます。

インストール

composer require nextpdf/server

Composer の制約は nextpdf/core: ^3.0 と php: >=8.4 <9.0 です。オプションの ext-redis と nextpdf/premium については、/connect/install/. を参照してください。

概念的な概要

このパッケージはスタンドアロンのサービスです。ホストフレームワークに登録するサービスプロバイダー、バンドル、コンテナモジュールはありません。統合ポイントは、実行するプロセスです。各トランスポートには独自のエントリーポイントがあり、それぞれ独立して起動します。/connect/boot-and-discovery/. を参照してください。

API サーフェス

エントリーポイント	トランスポート	プロファイル
`bin/nextpdf-mcp`	stdio 経由の MCP	（なし — 直接サブプロセス）
`bin/nextpdf-server`	RoadRunner HTTP 経由の REST	`.rr.yaml`
`bin/nextpdf-grpc`	RoadRunner gRPC 経由の gRPC	`.rr.grpc.yaml`
両方のネットワークトランスポート	REST + gRPC	`.rr.full.yaml`

起動と自動検出

レジストリは core ティアを無条件に検出します。次に、それらのクラスが解決可能な場合は Pro プロバイダーと Enterprise プロバイダーを追加し、続いて環境ゲートの下で、バンドルされた AST プロバイダーとミューテーションプロバイダーを追加します。enabled_tools セキュリティ許可リストがこれらすべてをフィルタリングするため、公開されるカタログはデプロイメントごとに固有です。/connect/tool-catalog/ および /connect/boot-and-discovery/. を参照してください。

コンテナバインディング

ありません。各サーバーファクトリーは、独自のオブジェクトグラフを明示的に構築します。注入可能なシームは、アプリケーションの配線用ではなくテスト用です。

構成の公開

MCP サーバーは、任意の YAML ファイル（--config=PATH、nextpdf_mcp セクション）と NEXTPDF_MCP_* 環境オーバーライドを受け取ります。REST サーバーと gRPC サーバーは NEXTPDF_* 環境変数を読み取ります。詳細については、/connect/configuration/. を参照してください。

トランスポートの可用性（MCP / REST / gRPC）

3 つのトランスポートはいずれも、同じレジストリを提供します。

MCP — ローカルサブプロセス、stdio 経由の JSON-RPC 2.0、API キーなし、MCP リビジョン 2025-06-18。 /transports/mcp/. を参照してください。
REST — RoadRunner HTTP ワーカープール、OpenAPI 3.1 コントラクト、ベアラー API キー、ティアによってゲートされるルート。 /transports/rest/. を参照してください。
gRPC — RoadRunner gRPC ワーカープール、nextpdf.connect.v1 Protobuf サービス、サーバーストリーミング RPC、メタデータ内のベアラーによる認証、結合プロファイルでの相互 TLS。 /transports/grpc/. を参照してください。

トランスポートは、そのエントリーポイントまたは RoadRunner プロファイルが実行中のときに「利用可能」になります。トランスポート同士が互いを自動的に起動することはありません。

HITL リスクティア

すべてのツールは、4 つのリスクレベル（safe、caution、review、approval_required）のいずれか 1 つを宣言します。approval_required のツールは、最初の呼び出しでは実行されません。確認ゲートは、人間の承認が必要な使い捨てのチャレンジトークンを発行します。構成のオーバーライドでできるのは、ツールのリスクを引き上げることだけであり、approval_required のツールを引き下げることはできません。このモデルは、ツールを駆動するすべてのトランスポートに同じように適用されます。/connect/hitl-risk-tiers/. を参照してください。

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

ゲートのチェックは、2 つの JSON 形状のいずれか 1 つを返します。許可された場合:

{ "allowed": true }

チャレンジの場合:

{
  "allowed": false,
  "challenge": "<human-readable text naming the operation, its description, an overwrite warning when applicable, and the re-invocation instruction>",
  "token": "confirm_<nonce>"
}

トークンは、ツール名、ランダムな nonce、および 300 秒の TTL をバインドします。引数はバインドしません。続行するには、呼び出し元が _confirmation_token 引数に発行されたトークンを設定し、同じツールを再度呼び出します。チャレンジは、プレーンな指示テキストとトークンであり、暗号的に署名されたエンベロープではありません。/connect/hitl-risk-tiers/. を参照してください。

サービスのスモークテスト

./vendor/bin/generate-skills --dry-run --list-tools

これはレジストリとティア検出を起動し、トラフィックを処理せずに公開されるツールを出力します。統合が配線されていることと、このインストールでどのカタログが生成されるかを手早く確認できます。

エッジケースと注意点

フレームワークフックなし。 サービスプロバイダーやバンドルを探さないでください。統合とは、実行中のプロセスのことです。
ティアが欠落していてもエラーではありません。 core のみのインストールでも起動し、その core カタログを提供します。
ネットワークトランスポートにはキーが必要です。 /healthz と /readyz（REST）およびヘルス RPC（gRPC）のみが匿名です。

パフォーマンス

起動コストは、プロセスごとに 1 回のレジストリスキャンとティア検出です。リクエストごとのコストは、エンジン操作です。観測されたレンダリングレイテンシーに合わせて、RoadRunner ワーカープールのサイズを調整してください。/connect/production-usage/. を参照してください。

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

ネットワークトランスポートは、定数時間で検証される npk_live_ ベアラーキーで認証します。ゲートは、トランスポートに関係なく、破壊的な操作に対して人間による確認を強制します。信頼できないネットワークでは、REST の前段で TLS を終端し、gRPC には相互 TLS を使用してください。/connect/security-and-operations/. を参照してください。

適合性

プロトコルおよびセキュリティに関する引用は、/transports/mcp/、/transports/rest/、/transports/grpc/、および /connect/security-and-operations/. に固定されています。

商用コンテキスト

サーバーとあわせて nextpdf/premium をインストールすると、追加の Pro ツールと Enterprise ツールが同じ実行中のサーバーに登録されます。別プロセスは関与しません。