跳到內容
NextPDF

NextPDF Connect 啟動與探索

概覽

標題為「概覽」的區段

每個傳輸都有自己的進入點與啟動流程。這些傳輸在概念上共用登錄表（registry）、組態與 gate；但它們會在彼此獨立的行程中執行，因此啟動其中一個，不會連帶啟動其他傳輸。

安裝

標題為「安裝」的區段
Terminal window
composer require nextpdf/server

概念總覽

標題為「概念總覽」的區段

MCP 啟動順序

標題為「MCP 啟動順序」的區段

McpServer::create() 會依固定順序為 MCP 伺服器接線。它會先載入組態，依據該組態建構安全性原則、建立工具登錄表，並執行層級探索。接著，它會依設定的 TTL 與容量建立記憶體內文件存放區、建立 stdio 傳輸，並組裝帶有確認 gate 與稽核記錄器的 JSON-RPC 協定處理器。完成上述步驟後，伺服器便會進入「讀取—處理—寫入」迴圈，並持續執行，直到標準輸入抵達檔案結尾為止。

REST 啟動順序

標題為「REST 啟動順序」的區段

HttpServer::create() 會從環境讀取 HttpConfig，並套用 CLI 覆寫。接著，它會依下列優先順序解析（resolve） API 金鑰存放區：先使用可熱重載的檔案存放區，再使用靜態檔案，最後才使用環境。接下來，它會解析速率限制與冪等性存放區；當 Redis 已設定且可連線時，兩者都會使用 Redis，否則會退回記憶體內儲存。接著，它會開啟共用的 SQLite 工作存放區、建構應用服務，並建立路由表。由於路由表會依偵測到的層級建立，因此會反映實際安裝的套件。最後，由 RoadRunner 驅動 worker 的請求迴圈。

gRPC 啟動順序

標題為「gRPC 啟動順序」的區段

GrpcServer::create() 會解析同一個金鑰存放區、建構同一組應用服務，並以 Spiral gRPC worker 註冊 nextpdf.connect.v1 服務。當引擎相依項不可用時，gRPC 伺服器仍會啟動，並繼續提供健康狀態與能力查詢。在這種狀態下，行程不會拒絕啟動；而是讓承載資料的 RPC 乾淨地失敗。

工具探索

標題為「工具探索」的區段

探索就是登錄表的預設註冊步驟。core 層級會最先註冊。接著，若 Pro 與 Enterprise 提供者的類別能透過 class_exists() 解析到，它們就會接續註冊。隨後，內附的 AST 與 mutation 提供者會註冊到 Pro 層級下，並受對應的環境 gate 約束。每一次註冊都會經過 enabled_tools 安全性允許清單過濾，而各層級最終的工具數量會在 MCP 的 initialize 回應中回報。請參閱 /connect/tool-catalog/.

傳輸探索

標題為「傳輸探索」的區段

並沒有任何單一組態設定能「啟用傳輸」。每個傳輸都是各自獨立的進入點。REST 與 gRPC 各自擁有獨立的 RoadRunner 設定檔。部署會依所執行的設定檔來選擇傳輸：.rr.yaml 對應 REST，.rr.grpc.yaml 對應 gRPC，而 .rr.full.yaml 則兩者皆有。這些傳輸會在彼此獨立的行程中執行。缺少 MCP 用戶端絕不會阻擋 REST 伺服器，缺少 REST 用戶端也絕不會阻擋 MCP。請參閱 /connect/deployment/.

組態解析順序

標題為「組態解析順序」的區段

MCP 伺服器會依下列優先順序解析組態：環境（NEXTPDF_MCP_*）優先於 YAML 檔的 nextpdf_mcp 區段，而後者又優先於內建預設值。REST 與 gRPC 伺服器則會讀取 HttpConfig；其來源為 NEXTPDF_* 環境變數，並帶有安全的預設值。它們不會讀取 MCP 的 YAML 檔。請參閱 /connect/configuration/.

容器繫結

標題為「容器繫結」的區段

這裡沒有需要註冊的相依注入容器或服務提供者。每個 create() 工廠都會明確且具決定性地建構自己的物件圖。這裡有兩個可注入的接縫——傳輸與 worker 工廠——但兩者都是為了測試，而非用於應用程式接線。

程式碼範例——快速上手

標題為「程式碼範例——快速上手」的區段

在不對外提供流量的情況下，檢視探索產生的結果：

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

程式碼範例——正式環境

標題為「程式碼範例——正式環境」的區段

在同一個監管行程下，啟動合併在一起的傳輸：

Terminal window
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 會為這項成本設定上限。這項成本只會在每次行程啟動時付出一次，而非每次請求都付出。

安全性注意事項

標題為「安全性注意事項」的區段

安全性原則會先於登錄表建立，因此 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 與伺服器一同安裝。

另請參閱

標題為「另請參閱」的區段
  • /connect/tool-catalog/ —— 探索註冊了哪些工具，以及工具數量為何會變動
  • /connect/configuration/ —— 解析順序的詳細說明
  • /connect/deployment/ —— 透過 RoadRunner 設定檔選擇傳輸
  • /transports/mcp/ · /transports/rest/ · /transports/grpc/ —— 各傳輸的詳細說明