NextPDF Connect の構成

概要

NextPDF Connect には 2 つの構成サーフェスがあります。MCP サーバーは YAML ファイルと NEXTPDF_MCP_* 変数を読み込みます。REST サーバーと gRPC サーバーは NEXTPDF_* 環境変数を読み込みます。サーバーの起動後、構成は変更されません。

インストール

composer require nextpdf/server

概念の概要

MCP サーバーは、固定された優先順位に従って構成を resolve（解決）します。最も優先度の高いソースが採用されます。

環境変数（NEXTPDF_MCP_*）。
YAML 構成ファイルの nextpdf_mcp セクション。
組み込みのデフォルト。

YAML ファイルは --config=PATH で渡します。指定しない場合、サーバーはデフォルトと環境変数のみを使用します。生成される McpConfig は readonly の値オブジェクトです。起動後に変更される設定はありません。

REST サーバーと gRPC サーバーは、起動時に環境から HttpConfig を読み込みます。サポートされる環境オーバーライドは、NEXTPDF_BIND、NEXTPDF_WORKER_COUNT、NEXTPDF_SESSIONS_ENABLED、および NEXTPDF_CORS_ENABLED です。その他の上限値には、安全なデフォルトが設定されています。

API サーフェス

MCP の構成（`nextpdf-mcp`）

YAML ファイルの nextpdf_mcp セクション：

nextpdf_mcp:
  enabled_tools: []          # empty/absent = all available tools allowed
  temp_directory: /tmp/nextpdf-mcp
  max_documents: 50
  document_ttl: 1800
  max_file_size_bytes: 104857600
  allow_file_output: true
  compress: true
  risk_level_overrides:
    fill_form: 3             # raise fill_form to ApprovalRequired (see below)

MCP サーバーの環境オーバーライド：

変数	構成キー	デフォルト
`NEXTPDF_MCP_ENABLED_TOOLS`	`enabled_tools`	すべてのツールを許可
`NEXTPDF_MCP_TEMP_DIR`	`temp_directory`	システムの一時ディレクトリ + `/nextpdf-mcp`
`NEXTPDF_MCP_MAX_FILE_SIZE`	`max_file_size_bytes`	`104857600`（100 MB）
`NEXTPDF_MCP_MAX_DOCUMENTS`	`max_documents`	`50`
`NEXTPDF_MCP_DOCUMENT_TTL`	`document_ttl`	`1800` 秒
`NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED`	（`parse_pdf` を制御）	未設定（無効）
`NEXTPDF_AST_TOOLS_ENABLED`	（AST ツールを制御）	有効
`NEXTPDF_MUTATION_TOOLS_ENABLED`	（AST ミューテーションツールを制御）	未設定（無効）

REST と gRPC の構成

変数	デフォルト	効果
`NEXTPDF_BIND`	`0.0.0.0:8080`	REST のリッスンアドレス
`NEXTPDF_WORKER_COUNT`	`4`	RoadRunner の PHP ワーカー数
`NEXTPDF_SESSIONS_ENABLED`	`false`	ステートフルなセッションエンドポイントを有効化
`NEXTPDF_CORS_ENABLED`	`false`	CORS レスポンスヘッダーを有効化
`NEXTPDF_API_KEYS`	未設定	インライン API キー定義
`NEXTPDF_API_KEYS_FILE`	未設定	API キーファイルへのパス
`NEXTPDF_JOB_STORE_PATH`	システムの一時ディレクトリ	SQLite ジョブストアのパス
`NEXTPDF_REDIS_HOST`	未設定	設定時に Redis ベースのストアを有効化

Redis（REST サーバーで使用。NEXTPDF_REDIS_HOST が設定され、ext-redis が読み込まれている場合）：

変数	デフォルト
`NEXTPDF_REDIS_PORT`	`6379`
`NEXTPDF_REDIS_PASSWORD`	空
`NEXTPDF_REDIS_DATABASE`	`0`
`NEXTPDF_REDIS_PREFIX`	`nextpdf:`
`NEXTPDF_REDIS_CONNECT_TIMEOUT`	`2.0` 秒
`NEXTPDF_REDIS_READ_TIMEOUT`	`2.0` 秒

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

明示的な構成ファイルを指定して MCP サーバーを実行します：

./vendor/bin/nextpdf-mcp --config=/etc/nextpdf/nextpdf-mcp.yaml

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

MCP カタログを明示的な許可リストに制限し、ツールのリスクを引き上げます：

nextpdf_mcp:
  enabled_tools:
    - create_pdf
    - add_text
    - output_pdf
    - diagnostic.doctor
  temp_directory: /var/lib/nextpdf/tmp
  max_file_size_bytes: 26214400
  risk_level_overrides:
    add_text: 2          # upgrade add_text from caution to review

空でない enabled_tools を指定すると、セキュリティポリシーは列挙されたツール名だけを許可します。それ以外のツールは、すべてレジストリから暗黙的に除外されます。リストが空、または存在しない場合は、利用可能なすべてのツールが許可されます。

エッジケースと注意点

2 つの重要なツールはダウングレードできません。 output_pdf と sign_pdf は設計上、承認ゲートの対象です。risk_level_overrides エントリでこれらのいずれかを ApprovalRequired より低くすると、読み込み時に InvalidArgumentException をスローし、サーバーは起動を拒否します。その他のすべてのツールでは、リスクレベルを引き上げることも引き下げることもできるため、ダウングレードは必ず自身の脅威モデルに照らして検討してください。/connect/hitl-risk-tiers/. を参照してください。
enabled_tools はフィルタリングするものであり、追加するものではありません。 nextpdf/premium が存在しない状態で Pro ツール名を列挙しても、そのツールは表示されません。許可リストは、レジストリが実際に検出したツールとの積集合になります。
MCP サーバーでは環境変数が YAML より優先されます。 NEXTPDF_MCP_* 変数は、YAML ファイル内の同じキーをオーバーライドします。REST サーバーと gRPC サーバーは、MCP の YAML ファイルをまったく読み込みません。
parse_pdf はオプトインです。 parse_pdf ツールは、NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED が true または 1 のときにのみ登録されます。デフォルトでは、コアカタログにも含まれません。

パフォーマンス

構成は起動時に一度だけ解析されます。max_documents と document_ttl の設定は、メモリ内ドキュメントストアの上限を定めます。これらを下げると、ドキュメントの有効期間が短くなる代わりにピークメモリが削減されます。ワーカー数と各ティアのペイロード上限はデプロイ時の調整項目であり、/connect/deployment/. で説明します。

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

最小権限のデプロイでは、enabled_tools をデフォルト拒否の制御サーフェスとして扱ってください。つまり、各統合に必要なツールのみを列挙します。
API キーを YAML ファイルに保存しないでください。Docker または Kubernetes のシークレットとしてマウントしたファイルを使い、NEXTPDF_API_KEYS_FILE を指定してください。サーバーはホットリロード対応のファイルストアを優先するため、再起動なしで鍵をローテーションできます。/connect/security-and-operations/. を参照してください。
なお、temp_directory は、ファイル出力で強制されるベースディレクトリです。サーバーは出力パスを正規化し、その外部に解決されるものはすべて拒否します。

準拠

このページでは構成の仕組みについて説明します。認証とトランスポートセキュリティに関する準拠の引用は、/connect/security-and-operations/. に固定されています。

商用に関する補足

ティアごとのペイロード上限とタイムアウト上限（corePayloadLimit、proPayloadLimit、enterprisePayloadLimit、および対応するタイムアウト）は、認証された API キーのティアに応じて REST トランスポートに適用されます。これらは、Pro または Enterprise のツールがインストールされ、かつその鍵にそれらの利用権限がある場合にのみ有効になります。