NextPDF Connect 快速入門

概覽

本頁會針對 MCP 與 REST 兩種傳輸（transport），各跑一輪最小但實用的交換流程。每個請求都是伺服器實際實作的 wire 格式。整個過程不需要任何軟體開發套件（SDK）。

安裝

composer require nextpdf/server

概念說明

MCP 傳輸透過標準輸入與輸出，以 JSON-RPC 2.0 溝通。這個流程順序是必要條件，而且必須依序執行。先送出 initialize。接著送出 notifications/initialized 確認訊息。再送出 tools/list 與 tools/call。伺服器會逐行讀取 JSON 訊息，每行訊息都以換行字元結尾；回應也會逐行寫出。

REST 傳輸透過 HTTP 操作，對外開放與 MCP 相同的引擎能力。一次無狀態（stateless）算繪就是一個 POST /api/v1/render，內含一個有順序的 operations 陣列。回應主體就是 PDF。

程式碼範例 — 快速入門（透過 stdio 走 MCP）

啟動伺服器，並透過管線傳入交握流程。下面三個請求使用協定處理器（protocol handler）實際路由的已驗證方法名稱：

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

這個 initialize 回應會回報協定版本 2025-06-18、伺服器名稱 NextPDF Connect，以及一個 capabilities.nextpdf 區塊。該區塊帶有即時的分級數量、執行階段的 tool_count、風險模型版本，以及 hitl_enabled: true。tools/list 回應會精確列出這次安裝所註冊的工具。依設計，通知行不會產生任何回應。

現在來呼叫一個安全工具。diagnostic.doctor 工具會執行一次唯讀的環境檢查。它不需要文件，也不需要任何確認：

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

程式碼範例 — 快速入門（REST）

啟動 REST 伺服器，接著算繪一份單行 PDF。伺服器在每個非健康檢查的端點（endpoint）上都要求 API 金鑰，所以先定義一個：

export NEXTPDF_API_KEYS='npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef:demo:core:default'
./vendor/bin/rr serve -c .rr.yaml

在第二個 shell 中，送出一個算繪請求。請求主體是一個 RenderRequest。該請求帶有一個有順序的 operations 陣列，內含具型別的操作。

curl -sS -X POST http://localhost:8080/api/v1/render \
  -H 'Authorization: Bearer npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef' \
  -H 'Content-Type: application/json' \
  -d '{
        "page_size": "A4",
        "orientation": "portrait",
        "operations": [
          { "type": "add_text", "text": "Hello from NextPDF Connect" }
        ]
      }' \
  --output hello.pdf

一個 200 回應的主體就是 PDF（Content-Type: application/pdf），並會寫入 hello.pdf。健康檢查探針不需要金鑰：

curl -sS http://localhost:8080/healthz

邊界情況與陷阱

交握順序很重要。 協定處理器會把沒有 id 的訊息視為通知，不回傳任何內容。請先送出帶 initialize 與 id 的訊息，接著送出 initialized 通知，再送出你帶有 id 的請求。
重複的請求 id 會被去重複。 處理器會用一個 64 筆的環形緩衝區快取最近的回應。遇到重複的 id 時，它會回傳快取的回應，不會再次執行該工具。請使用全新的 id。
高風險工具回的是挑戰，而非結果。 呼叫 output_pdf 並帶上 file_path 時，會回傳一個確認挑戰，而不是直接執行。請帶著核發的 _confirmation_token 重新呼叫。base64 輸出模式（不帶 file_path）則不需要確認。請參閱 /connect/hitl-risk-tiers/.
未授權的 REST 請求會得到 401。 缺少或格式錯誤的 Authorization: Bearer 標頭時，會回傳一個帶 WWW-Authenticate: Bearer 標頭的 problem-details 主體。/healthz 與 /readyz 探針是僅有的匿名端點。

效能

兩條快速入門路徑都是單一請求。REST 路徑在 rr serve 之後的首個請求，還會付出 RoadRunner worker 池的冷啟動成本。後續請求則會重用已暖機的 worker。

安全性須知

上面那把 npk_live_ 金鑰只是用過即丟的示範值。請產生具備足夠熵的真實金鑰，將其存放在版本控制之外，並優先採用以檔案為基礎的金鑰儲存區以利輪替。MCP 的 stdio 傳輸沒有 API 金鑰，因為依 MCP 傳輸模型，它是由啟動用戶端所信任的本機子行程。請參閱 /connect/security-and-operations/.

符合性

此處呈現的 wire 格式，對應實作的 MCP 修訂版本 2025-06-18 與 OpenAPI 3.1 的 REST 合約。規範性的協定與認證引用，釘選在 /transports/mcp/、/transports/rest/ 與 /connect/security-and-operations/.

另請參閱

/transports/mcp/ — 完整的 MCP 傳輸參考
/transports/rest/ — 完整的 REST 傳輸參考與 OpenAPI 算繪
/connect/tool-catalog/ — tools/list 會回傳哪些工具以及背後原因
/connect/hitl-risk-tiers/ — 確認挑戰的樣貌
/connect/configuration/ — 如何限縮工具目錄並調校伺服器