NextPDF Connect — MCP トランスポート

概要

MCP トランスポートでは、bin/nextpdf-mcp をローカルのサブプロセスとして実行します。標準入力と標準出力を介して JSON-RPC 2.0 でやり取りします。サーバーは、日付付きバージョンの MCP リビジョン 2025-06-18 を実装しています。

インストール

composer require nextpdf/server

概念の概要

MCP の stdio モデルでは、クライアントがサーバーをサブプロセスとして起動します。クライアントとサーバーは、改行区切りの JSON-RPC メッセージを交換します。1 行につき 1 メッセージで、メッセージ内に改行を含まず、UTF-8 でエンコードされます。サーバーは、有効な MCP メッセージのみを標準出力に書き込み、ログには標準エラー出力を使用します。この実装では、ログ行でプロトコルストリームが壊れないよう、監査ロガーを標準エラー出力へ確実にルーティングします。このフレーミングは、公式の MCP 仕様、リビジョン 2025-06-18 で定義されています。この仕様はゲート付きの標準コーパスには含まれないため、URL で引用しています。https://modelcontextprotocol.io/specification/2025-06-18/basic/transports。

NextPDF Connect は stdio トランスポートを実装しています。MCP 仕様では、Streamable HTTP トランスポートも定義されています。仕様では、クライアントは可能な限り stdio をサポートすべきであり、サーバーは stdio のみを実装してもよいとされています。同じツールにネットワーク経由でアクセスするには、代わりに REST または gRPC トランスポートを使用してください。/transports/rest/ および /transports/grpc/. を参照してください。

API サーフェス

メソッド

メソッド	動作
`initialize`	プロトコルバージョン、ケーパビリティ、サーバー情報の返却
`notifications/initialized`	通知（`id` なし）。レスポンスなしの受理
`tools/list`	登録済みツールの一覧表示。`params.category` による任意のフィルター
`tools/call`	指定したツールの実行。対象は `params.name`、引数は `params.arguments`

その他のメソッドはすべて method-not-found（-32601）を返します。有効な JSON-RPC 2.0 ではないメッセージは invalid-request（-32600）を返します。解析できない入力は parse-error（-32700）を返します。重複するリクエスト id に対しては、再実行せずに、64 エントリのバッファにキャッシュされた以前のレスポンスを返します。

initialize レスポンス

この initialize の結果では、protocolVersion 2025-06-18、serverInfo.name: NextPDF Connect、および capabilities オブジェクトが報告されます。標準の tools ケーパビリティに加えて、サーバーは capabilities.nextpdf ブロックを追加します。

tiers — ティアごとの登録済みツール数のライブカウント（core / pro / enterprise）。
tool_count — 実行時に計算される登録済みツールの総数。
risk_model_version — サーバーが適用するリスクモデルのバージョン。
hitl_enabled — true。確認ゲートが有効です。

tool_count は、このデプロイにおける確定値です。これは実行時のカウントであり、ドキュメントに記載された定数ではありません。/connect/tool-catalog/. を参照してください。

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

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"client","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
EOF

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

カテゴリで一覧をフィルターすると、カタログを 1 つのドメインに絞り込めます。

./vendor/bin/nextpdf-mcp --config=/etc/nextpdf/nextpdf-mcp.yaml <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"client","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{"category":"diagnostic"}}
EOF

カテゴリ値は、各ツールが宣言したカテゴリに由来します（たとえば document、diagnostic）。

エッジケースと注意点

API キーは不要です。 stdio トランスポートには、ネットワークリスナーもベアラートークンもありません。MCP の stdio モデルに従い、信頼境界はオペレーティングシステムのプロセス境界です。これをネットワークへブリッジしないでください。
確認チャレンジはインバンドで行われます。 ApprovalRequired のツールは、エラーではなく、チャレンジテキストと使い捨てトークンを含む成功した JSON-RPC レスポンスを返します。/connect/hitl-risk-tiers/. を参照してください。
通知はサイレントです。 id を持たないメッセージは、レスポンスを生成しません。ハンドシェイクは、initialize（id 付き）、次に initialized 通知、その後に id 付きの呼び出しという順序です。

パフォーマンス

MCP サーバーは単一プロセスであり、パイプを介して一度に 1 つのリクエストを処理します。ネットワークのラウンドトリップはありません。レイテンシは、基盤となるエンジン処理に左右されます。

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

このトランスポートは、起動元クライアントの信頼を継承します。サブプロセスはローカルに保ってください。API キーがなくても、リスクの高いツールは引き続き人による確認でゲートされます。/connect/security-and-operations/. を参照してください。

準拠

stdio フレーミングと initialize/lifecycle の動作は、公式の Model Context Protocol 仕様、リビジョン 2025-06-18 に準拠しています。

トランスポート: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports
ライフサイクル: https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle

MCP 仕様はゲート付きの標準コーパスには含まれないため、reference_id を持ちません。上記の公式 URL が正式な引用元です。

商用に関する補足

tools/list は、nextpdf/premium がサーバーと併せてインストールされている場合にのみ、Pro および Enterprise のツールを返します。トランスポート自体は、インストールされているティアに関係なく同一です。