跳到內容
NextPDF

NextPDF Connect — MCP 傳輸

快速概覽

標題為「快速概覽」的區段

MCP 傳輸會將 bin/nextpdf-mcp 作為本機子行程執行。它透過標準輸入與標準輸出傳遞 JSON-RPC 2.0 訊息。伺服器實作以日期版號標示的 MCP 版本 2025-06-18。

安裝

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

概念總覽

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

在 MCP stdio 模型中，用戶端會把伺服器啟動為子行程。雙方交換以換行分隔的 JSON-RPC 訊息：每行一則訊息、不含內嵌換行、採 UTF-8 編碼。伺服器只會把有效的 MCP 訊息寫到標準輸出，並以標準錯誤輸出記錄日誌。實作刻意將稽核 logger 導向標準錯誤輸出，因此日誌行絕不會污染協定串流。此 Framework（框架）由官方 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 介面

標題為「API 介面」的區段

方法

標題為「方法」的區段
方法行為
initialize回傳協定版本、能力與伺服器資訊
notifications/initialized屬於通知（沒有 id）；收到後不回傳任何回應
tools/list列出已註冊的工具；可使用選用的 params.category 篩選器
tools/call執行工具，傳入 params.name 與 params.arguments

任何其他方法都會回傳「找不到方法」（-32601）。不是有效 JSON-RPC 2.0 的訊息會回傳「無效請求」（-32600）；無法剖析的輸入則回傳「剖析錯誤」（-32700）。重複的請求 id 會從容量為 64 筆的緩衝區回傳先前快取的回應，而不會重新執行。

initialize 的回應

標題為「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/。

程式碼範例——快速上手

標題為「程式碼範例——快速上手」的區段
Terminal window
./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

程式碼範例——正式環境

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

使用類別篩選時，列表會把工具目錄縮小到單一領域：

Terminal window
./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 傳輸沒有網路監聽器，也沒有 bearer token。依 MCP stdio 模型，信任邊界就是作業系統的行程界線。不要把它橋接到網路上。

  • 確認挑戰是在頻道內進行的。 標記為 ApprovalRequired 的工具會回傳成功的 JSON-RPC 回應，其內容是挑戰文字與一次性權杖，而不是錯誤。詳見 /connect/hitl-risk-tiers/。

  • 通知是靜默的。 沒有 id 的訊息不會產生任何回應。握手流程是先 initialize（帶 id），接著是 initialized 通知，然後才是帶 id 的呼叫。

效能

標題為「效能」的區段

MCP 伺服器以單一行程運作，透過管線一次處理一個請求。它沒有網路來回往返；延遲主要取決於底層引擎的操作。

安全須知

標題為「安全須知」的區段

此傳輸會繼承啟動它的用戶端所擁有的信任。請讓子行程保持在本機。即使沒有 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 工具。不論安裝了哪些層級，傳輸本身都完全相同。

另請參閱

標題為「另請參閱」的區段
  • /connect/quickstart/——可實際執行的握手流程
  • /connect/tool-catalog/——說明 tools/list 的回傳內容，以及數量為何會變動
  • /connect/hitl-risk-tiers/——確認挑戰的格式
  • /transports/rest/ · /transports/grpc/——可透過網路存取的替代方案
  • /connect/migrating-to-multi-transport/——將僅支援 MCP 的整合改為 REST/gRPC