NextPDF Connect 伺服器總覽

概觀

NextPDF Connect 是 nextpdf/server 套件提供的長駐服務，會將 NextPDF PDF 2.0 引擎開放給 AI Agent（代理）與 HTTP 用戶端使用。它透過三種傳輸達成這件事：stdio 之上的 Model Context Protocol（MCP）、一組 REST API，以及 gRPC。這三種傳輸都位於同一個工具註冊表（registry）與同一道 human-in-the-loop（HITL）確認 gate 之後。

安裝

composer require nextpdf/server

Composer 的版本限制為 nextpdf/core: ^3.0，並搭配 php: >=8.4 <9.0。完整步驟請參閱 /connect/install/。該頁也說明兩個選用附加元件：ext-redis 擴充功能，以及 nextpdf/premium 套件。

概念總覽

nextpdf/server 會將與 Framework（框架）無關的 NextPDF 核心轉接成服務介面。它並未重新打造 PDF 產生功能；相反地，它會把引擎的每一項能力包裝成帶有自身結構描述（schema）的具名工具，再透過數種傳輸協定提供這份工具型錄。

整體設計建立在三個概念之上：

工具註冊表。 NextPDF\Server\ToolRegistry 會在啟動時探索並註冊工具。套件本身附帶一組核心工具，且這組核心工具永遠可用。Pro 與 Enterprise 提供者會註冊更多工具，但只有在對應套件已安裝時才會註冊。因此，對外開放的工具數量是該部署的執行期屬性，而不是固定常數。請參閱 /connect/tool-catalog/。
傳輸。 同一份註冊表會以三種方式提供服務。MCP 在 stdio 之上執行，供本機 AI 用戶端使用。REST 在 RoadRunner worker 集區之上的 PSR-15 中介軟體（middleware）管線中執行，供網路用戶端使用。gRPC 則在 Spiral RoadRunner gRPC worker 之上執行，供具型別且可串流的用戶端使用。每一種傳輸都是獨立程序，並有各自的進入點。請參閱 /transports/mcp/、/transports/rest/，以及 /transports/grpc/。
確認 gate。 每個工具都會宣告自己的風險等級。最高風險等級的工具，執行前必須先取得明確的人工確認。這道 gate 會發出一個單次使用的挑戰權杖（challenge token）。代理（agent）必須把該權杖交給人工審核者，再帶著權杖重新呼叫該工具。請參閱 /connect/hitl-risk-tiers/。

下圖顯示一份註冊表如何連接三種傳輸，也標示確認 gate 在請求路徑中的位置。

NextPDF Connect component architecture

此套件採用 Apache-2.0 授權，與 nextpdf/core 一致。它實作的 MCP 協定版本，是以日期標示版本的 2025-06-18 修訂版。REST 介面由一份 OpenAPI 3.1 文件描述。gRPC 介面則由 nextpdf.connect.v1 這個 Protocol Buffers 套件描述。

API 介面

公開的進入點是這三個伺服器類別。每一個都有對應的命令列介面（CLI）包裝器：

進入點	類別	傳輸
`bin/nextpdf-mcp`	`NextPDF\Server\Mcp\McpServer`	在 stdio 之上的 MCP
`bin/nextpdf-server`	`NextPDF\Server\Http\HttpServer`	在 RoadRunner HTTP 之上的 REST
`bin/nextpdf-grpc`	`NextPDF\Server\Grpc\GrpcServer`	在 RoadRunner gRPC 之上的 gRPC
`bin/generate-skills`	`NextPDF\Server\Skills\SkillsDumper`	工具型錄匯出

McpServer::create()、HttpServer::create() 與 GrpcServer::create() 會各自從環境變數與組態輸入，建構出完整設定好的伺服器。註冊表、文件儲存區、安全性原則以及確認 gate，都是三個伺服器共用的概念。

程式碼範例 — 快速上手

最精簡的 MCP 伺服器只需要一道指令。你不必撰寫任何 PHP 黏合程式碼：

./vendor/bin/nextpdf-mcp

伺服器會從標準輸入讀取 JSON-RPC 請求，並將回應寫到標準輸出。若要查看可實際執行的 initialize 與 tools/list 往返交換，以及對應的 REST 請求，請參閱 /connect/quickstart/。

邊界情況與陷阱

工具數量不是 33，也不是任何其他固定數字。 伺服器會在執行期，於原則篩選與層級偵測之後，以 count(ToolRegistry::all()) 計算工具數量。凡是引用固定總數的文件都已過時。若要取得權威數量，請查詢執行中的伺服器：使用 MCP 的 initialize 回應，或 REST 的 /api/v1/capabilities 端點。

對外開放的工具數量取決於已安裝的套件，以及目前生效的原則。請在執行期從執行中的伺服器讀取。把固定數字複製到你自己的程式碼或文件裡，遲早會過時。
缺少 Pro 或 Enterprise 套件並不是錯誤。 註冊表會使用 class_exists() 檢查提供者類別，並靜默略過任何不存在的層級。純開放原始碼部署仍會照常啟動，並提供其核心型錄。
這三種傳輸不共用同一個程序。 執行 MCP 伺服器並不會啟動 REST 伺服器或 gRPC 伺服器；反過來也是如此。合併式部署會以一份同時啟動兩個 worker 集區（HTTP 集區與 gRPC 集區）的組態來執行 RoadRunner 監督程序。請參閱 /connect/deployment/。

效能

每一種傳輸都以 worker 為基礎。一個 worker 一次處理一筆請求。REST 與 gRPC 伺服器在 RoadRunner worker 集區上執行，集區大小由組態設定。預設值為四個 HTTP worker。RoadRunner 監督程序會限制每個 worker 的記憶體上限。本頁前置設定中的 performance_budget 描述的是冷啟動並完成探索時的範圍，而不是單筆請求的目標值。每筆請求的成本大多由底層引擎運算主導。

安全性說明

所有網路傳輸都使用應用程式介面（API）金鑰的 bearer token 進行驗證。依照 MCP 的傳輸模型，MCP stdio 傳輸是由啟動它的用戶端所信任的本機子程序。在每一種傳輸上，高風險工具仍都受人工確認把關。完整的威脅模型、驗證模型以及傳輸安全性設定，請參閱 /connect/security-and-operations/。

符合性

本頁只提出架構層面的主張。規範性的協定與安全性引用，已釘選在各自規定該行為的頁面上：/connect/security-and-operations/、/transports/mcp/、/transports/rest/，以及 /transports/grpc/。MCP 生命週期的參考依據，是 modelcontextprotocol.io 上的官方規格（2025-06-18 修訂版）。由於 MCP 規格並不屬於受管控的標準語料庫，因此各傳輸頁面會連同其網址一併記錄該參考依據。

商業脈絡

就文件建立、檢視與診斷而言，核心型錄已經完整。用於簽署、塗銷（redaction）、合規認證以及鑑識分析的工具，只有在 nextpdf/premium 與伺服器一同安裝時才會出現。這是打包邊界，而不是執行期的加購提示。伺服器永遠不會發出行銷內容。

另請參閱

/connect/install/ — 安裝與選用套件
/connect/quickstart/ — 第一個可實際執行的 MCP 與 REST 往返交換
/connect/tool-catalog/ — 經過驗證的核心工具集，以及數量為何取決於執行期
/connect/hitl-risk-tiers/ — 確認 gate 與風險模型
/transports/mcp/、/transports/rest/、/transports/grpc/ — 各傳輸的設定
/connect/security-and-operations/ — 驗證、傳輸安全性、威脅模型
/connect/deployment/ — RoadRunner、Docker 與合併式傳輸部署