NextPDF Connect の起動とディスカバリー

概要

各トランスポートには、独自のエントリーポイントと起動シーケンスがあります。これらのトランスポートは、レジストリ、構成、ゲートを概念として共有します。独立したプロセスとして実行されるため、いずれか 1 つを起動しても他のトランスポートは起動しません。

インストール

composer require nextpdf/server

概念的な概要

MCP の起動シーケンス

McpServer::create() は、MCP サーバーを決まった順序で組み立てます。まず構成を読み込み、その構成からセキュリティポリシーを構築し、ツールレジストリを構成して、ティアディスカバリーを実行します。次に、構成された TTL と容量からインメモリのドキュメントストアを構築し、stdio トランスポートを作成して、確認ゲートと監査ロガーを備えた JSON-RPC プロトコルハンドラーを組み立てます。これらが整うと、サーバーは読み取り・処理・書き込みのループに入り、標準入力がファイルの終端に達するまで実行を続けます。

REST の起動シーケンス

HttpServer::create() は、環境から HttpConfig を読み取り、CLI のオーバーライドを適用します。次に、API キーストアを次の優先順位で解決します。最初にホットリロード対応のファイルストア、次に静的ファイル、最後に環境です。続いて、レート制限ストアと冪等性ストアを解決します。これらは、Redis が構成され到達可能な場合は Redis を使用し、そうでない場合はインメモリストレージにフォールバックします。その後、共有 SQLite ジョブストアを開き、アプリケーションサービスを構築して、ルートテーブルを構成します。ルートテーブルは検出されたティアから構築されるため、インストールされているパッケージが反映されます。その後、RoadRunner がワーカーのリクエストループを駆動します。

gRPC の起動シーケンス

GrpcServer::create() は、同じキーストアを解決し、同じアプリケーションサービスを構築して、nextpdf.connect.v1 サービスを Spiral gRPC ワーカーに登録します。エンジンの依存関係を利用できない場合でも、gRPC サーバーは起動し、ヘルスチェックとケイパビリティのクエリには応答します。その状態でも、プロセスは起動を拒否しません。代わりに、データを伴う RPC がクリーンに失敗します。

ツールのディスカバリー

ディスカバリーは、レジストリのデフォルト登録ステップです。最初に core ティアが登録されます。次に、Pro プロバイダーと Enterprise プロバイダーが、それぞれのクラスを class_exists() で解決できる場合に登録されます。その後、バンドルされた AST プロバイダーとミューテーションプロバイダーが、それぞれの環境ゲートに従って Pro ティアの下に登録されます。すべての登録は enabled_tools セキュリティ許可リストを通じてフィルタリングされ、その結果として得られたティアごとの件数が MCP の initialize レスポンスで報告されます。/connect/tool-catalog/ を参照してください。

トランスポートのディスカバリー

「トランスポートを有効化する」という単一の構成設定はありません。各トランスポートは、それぞれ独立したエントリーポイントです。REST と gRPC には、それぞれ別個の RoadRunner プロファイルがあります。デプロイメントは、実行するプロファイルによってトランスポートを選択します。REST には .rr.yaml、gRPC には .rr.grpc.yaml、両方には .rr.full.yaml を使用します。これらのトランスポートは、独立したプロセスとして実行されます。MCP クライアントが存在しなくても REST サーバーがブロックされることは決してなく、REST クライアントが存在しなくても MCP がブロックされることは決してありません。/connect/deployment/ を参照してください。

構成の解決順序

MCP サーバーは、次の優先順位で構成を解決します。環境（NEXTPDF_MCP_*）が YAML ファイルの nextpdf_mcp セクションよりも優先され、そのセクションが組み込みのデフォルト値よりも優先されます。REST サーバーと gRPC サーバーは、HttpConfig を NEXTPDF_* 環境変数から読み取り、安全なデフォルト値を適用します。これらは MCP の YAML ファイルを読み取りません。/connect/configuration/ を参照してください。

コンテナのバインディング

登録すべき依存性注入コンテナやサービスプロバイダーはありません。各 create() ファクトリーは、独自のオブジェクトグラフを明示的かつ決定論的に構築します。注入可能な接合点（シーム）はトランスポートとワーカーファクトリーの 2 つで、どちらもテスト用であり、アプリケーションの組み立て用ではありません。

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

トラフィックを処理せずに、ディスカバリーが生成した内容を確認します。

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

コードサンプル — 本番環境

統合されたトランスポートを 1 つのスーパーバイザーの下で起動します。

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
./vendor/bin/rr serve -c .rr.full.yaml

エッジケースと注意点

ティアが存在しなくても起動は失敗しません。 ティアディスカバリーは、存在しない Pro パッケージや Enterprise パッケージをサイレントにスキップします。サーバーは core カタログで起動します。
ダウングレードのオーバーライドは起動を失敗させます。 risk_level_overrides エントリーのうち、approval_required ツールを弱めるものは、構成の読み込み時に例外をスローし、サーバーは起動を拒否します。これは意図的な動作です。
Redis の障害は機能を縮退させるだけで、クラッシュは引き起こしません。 Redis が構成されていても起動時に到達不能な場合、REST サーバーはインメモリストアにフォールバックします。Redis が使用されていると決め付けず、Redis のヘルス状態を確認してください。

パフォーマンス

起動コストは、構成のパースに加えて、レジストリのスキャンとティアの検出にかかるコストです。ページの performance_budget が、このコストの上限を定めます。このコストは、リクエストごとではなく、プロセスの起動ごとに 1 回だけ発生します。

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

セキュリティポリシーはレジストリよりも先に構築されるため、enabled_tools 許可リストは最初の登録からディスカバリーを制約します。API キーが MCP の YAML ファイルから読み取られることは決してありません。ネットワーク経由のトランスポートは、シークレットファイルまたは環境からキーを解決します。/connect/security-and-operations/ を参照してください。

適合性

このページでは、起動の仕組みについて説明します。プロトコルとセキュリティの引用は、/transports/mcp/、/transports/rest/、/transports/grpc/、および /connect/security-and-operations/ に固定されています。

商用コンテキスト

起動時のティア検出は、nextpdf/premium が自身の Pro ツールと Enterprise ツールをカタログに追加する唯一のポイントであり、これは nextpdf/premium がサーバーと並んでインストールされている場合に行われます。