NextPDF Connect 疑難排解

快速概覽

大多數故障都屬於五大類之一：JSON-RPC 交握格式錯誤、缺少 API 金鑰、此分級未安裝對應工具、尚未回應的確認挑戰，或是儲存狀態未在 worker（工作行程）之間共用。每一類都有明確的徵象。

安裝

composer require nextpdf/server

概念總覽

MCP 傳輸會回傳帶有標準錯誤碼的 JSON-RPC 2.0 錯誤物件。REST 傳輸則回傳 RFC 7807 問題詳情文件。每一筆都帶有 type URL，用來識別該狀況。排查環境問題時，先從診斷工具著手（diagnostic.doctor、diagnostic.capabilities）。這些工具一律包含在核心目錄中。

API 介面

MCP JSON-RPC 錯誤碼

錯誤碼	名稱	成因
`-32700`	剖析錯誤	該行不是有效的 JSON
`-32600`	無效的請求	不是 JSON-RPC 2.0 訊息（缺少 `jsonrpc`/`method`）
`-32601`	找不到方法	方法不是下列任一項：`initialize`、`tools/list`、`tools/call`
`-32602`	無效的參數	`tools/call` 方法中缺少 `params.name`
`-32603`	內部錯誤	工具在執行期間擲出例外

工具若以正常流程回報失敗，不會使用這些錯誤碼。它會改為回傳成功的 JSON-RPC 回應，其 result 帶有 isError: true 與一段文字說明，例如未知工具、被政策停用或引數無效。

REST 問題詳情類型

HTTP	`type` 識別碼	成因
`401`	`unauthorized`	API 金鑰遺失、無效、停用或已過期
`403`	`capability-denied`	金鑰的分級無權執行此操作
`413`	`payload-too-large` / `tier-payload-exceeded`	內文超出全域或分級上限
`422`	`validation-failed`	請求內文未通過結構描述驗證
`429`	`ip-rate-exceeded` / `client-rate-exceeded`	觸及速率限制
`404`	`not-found`	未知路由，或 job/session id
`504`	（請求逾時）	操作超過該分級的逾時上限

程式碼範例 —— 快速開始

執行環境健康檢查；它不需要文件，也不需要確認：

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

程式碼範例 —— 正式環境

除錯「缺少工具」之前，先確認這個部署實際對外開放哪些工具：

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

或者，針對執行中的 REST 伺服器：

curl -sS http://localhost:8080/api/v1/capabilities \
  -H "Authorization: Bearer $NEXTPDF_KEY"

邊界情況與陷阱

Pro/Enterprise 工具出現「Unknown tool」。 該工具的套件尚未安裝。註冊表會探查 provider 類別，並在不發出警告的情況下略過未安裝的分級。這是預期行為，並非 bug。請在伺服器端一併安裝 nextpdf/premium，或改用核心工具。錯誤訊息中會包含安裝路徑。
我在 enabled_tools 中設定的工具沒有出現。 此允許清單會與探查到的工具取交集，無法加入註冊表沒有找到的工具。請檢查分級的安裝狀態以及任何環境 gate。舉例來說，parse_pdf 需透過 NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED 主動啟用。
tools/call 回傳了要求權杖的文字。 那是確認挑戰，不是錯誤。請在 300 秒內，將 _confirmation_token 設為核發的權杖，然後再次呼叫該工具。請參閱 /connect/hitl-risk-tiers/。
通知這一行沒有產生輸出。 這是預期行為。沒有 id 的 JSON-RPC 訊息屬於通知，處理常式不會回傳任何內容。若要取得回應，請改送帶有 id 的請求。
重複的請求 id 回傳了過時的回應。 處理常式會依請求 id，在 64 筆緩衝區內去除重複。請為每個邏輯請求使用全新的 id。
速率限制在多個 worker 之間行為異常。 記憶體內儲存是各 worker 獨立的。若要共用計數，請設定 NEXTPDF_REDIS_HOST 並安裝 ext-redis。請參閱 /connect/deployment/。
文件在不同請求之間消失了。 記憶體內的文件儲存是各 worker 獨立的，並受存活時間限制（document_ttl，預設 1800 秒）。若要讓文件在多個 worker 之間保留，請使用 Redis 後端儲存、session 端點，或將整組操作維持在同一次同步繪製中完成。
儘管已設定 Redis，伺服器仍退回記憶體內模式。 若 Redis 連線在啟動時失敗，REST 伺服器會自動退回記憶體內模式。請檢查 Redis 是否可連線，並確認執行中的映像檔內含 ext-redis。不要在未經驗證的情況下假設 Redis 正在使用中。
伺服器因組態錯誤而拒絕啟動。 某個 risk_level_overrides 項目試圖將一個 ApprovalRequired 工具降級。載入器依設計會拒絕此舉。請移除該降級；覆寫只能調高風險等級。

效能

如果在負載下繪製變慢，請確認 worker 集區並未達到飽和。請檢查 RoadRunner 的 metrics 端點。接著將長時間繪製移到非同步 job 路徑，以免占用 worker。請參閱 /connect/production-usage/。

安全性注意事項

不要為了規避 401，就把未經驗證的 MCP 傳輸暴露到網路上；那等於完全移除了驗證。請改為修正 API 金鑰。不要為了檢視工具引數而在共用環境中調高記錄詳盡度；引數內容可能含敏感資料。請參閱 /connect/security-and-operations/。

符合性

本頁屬於操作指引。協定與安全性的引用固定收錄在 /transports/mcp/、/transports/rest/ 與 /connect/security-and-operations/。

另請參閱

/connect/tool-catalog/ —— 核心目錄包含的內容，以及數量為何會變動
/connect/hitl-risk-tiers/ —— 確認挑戰的細節
/connect/deployment/ —— Redis、worker 集區與儲存共用
/connect/security-and-operations/ —— 驗證失敗與安全態勢