NextPDF Connect 工具目錄

快速一覽

一個 NextPDF Connect 部署公開的工具數量並不是固定常數。伺服器會在執行時，依據已安裝的套件、組態中的允許清單，以及一組環境 gate 計算出這個數量。本頁說明經驗證的核心集，以及總數的決定方式。

安裝

composer require nextpdf/server

概念總覽

NextPDF\Server\ToolRegistry 會在啟動時依下列順序建構目錄：

核心層。 一組固定的核心工具會無條件註冊。另外兩個工具只會在前置條件成立時註冊。
Pro 層。 Pro 工具會在 Pro 提供者類別 resolve（解析）成功時註冊；這會發生在已安裝 nextpdf/premium 的情況下。當該類別無法解析時，伺服器會靜默略過這一步。
Enterprise 層。 Enterprise 提供者遵循與 Pro 提供者相同的模式。
隨附的延伸層。 AST 與 mutation 工具提供者會隨伺服器套件一起出貨，並註冊在 Pro 層之下。每個提供者都由一個環境 gate 控制；當其底層核心支援不存在時，每個提供者都會優雅降級。
安全政策過濾。 伺服器會將每一次註冊與 enabled_tools 允許清單取交集。非空的允許清單會剔除任何不在其中的工具。層級計數器只會計入通過政策准許的工具。

MCP 的 initialize 回應會回報執行中伺服器最終的 tool_count 與各層級計數。這個值才是權威數字。請將文字敘述中的任何固定總數視為過時資訊。

API 介面

經驗證、永遠可用的核心工具

這十二個工具會無條件註冊在核心層。伺服器會從工具實作讀取各自的風險層級與 MCP 行為提示。

工具名稱	類別	說明	風險
`create_pdf`	文件	建立一份新的 PDF 文件並回傳一個 `document_id`	謹慎
`add_text`	文件	將文字內容加入 PDF 文件	謹慎
`add_image`	文件	從檔案路徑或 base64 資料加入影像	謹慎
`add_table`	文件	將 HTML 表格加入 PDF 文件	謹慎
`set_font`	文件	為後續的文字操作設定字型	謹慎
`add_page`	文件	在 PDF 文件中新增一頁	謹慎
`output_pdf`	文件	將 PDF 定稿為檔案或 base64	需要核准
`preview_layout`	文件	不進行繪製，僅回傳版面的 JSON 摘要	安全
`diagnostic.doctor`	診斷	執行健康檢查；結構化的環境診斷	安全
`diagnostic.capabilities`	診斷	列出各項能力及其層級與狀態	安全
`diagnostic.inspect`	診斷	檢視 PDF 並回傳結構中繼資料	安全
`diagnostic.verify`	診斷	驗證 PDF 完整性；可選擇進行 PDF/A 或 PDF/UA 檢查	謹慎

有條件註冊的核心工具

工具名稱	條件
`generate_barcode`	註冊條件為：核心 barcode 編碼器登錄表存在於已安裝的 `nextpdf/core`
`parse_pdf`	註冊條件為 `NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED` 為 `true` 或 `1`

output_pdf 是唯一位於 approval_required 風險層級的核心工具。寫入檔案會經過 human-in-the-loop（人為介入）gate；base64 輸出模式則不會。參見 /connect/hitl-risk-tiers/.

僅在安裝額外套件時加入的工具

伺服器會使用 class_exists() 探測提供者類別：

Pro 工具 會在已安裝 nextpdf/premium 且 Pro 提供者解析成功時註冊。
Enterprise 工具 會在已安裝 nextpdf/premium 且 Enterprise 提供者解析成功時註冊。隱私工具（編修、去識別化、區塊編修）封裝了 Enterprise 類別。只有在這些類別可被自動載入時，它們才會註冊在 Enterprise 層之下。
AST 與 mutation 工具 會隨伺服器一起出貨，並註冊在 Pro 層之下。 NEXTPDF_AST_TOOLS_ENABLED 與 NEXTPDF_MUTATION_TOOLS_ENABLED 這兩個 gate 控制它們，且兩個 gate 預設皆為啟用。

確切的 Pro 與 Enterprise 工具清單由 Premium 套件定義，而不是由伺服器定義，且這些清單由該套件的隨附說明文件提供。伺服器的契約是這套註冊機制，而不是一份固定的 Premium 清單。

程式碼範例 — 快速上手

不啟動伺服器，直接列印這個安裝所公開的工具：

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

程式碼範例 — 正式環境

透過 MCP 向執行中的伺服器查詢權威數量：

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

伺服器會為執行中的行程計算 initialize 結果中的 capabilities.nextpdf.tool_count 與 tiers。透過 REST，GET /api/v1/capabilities 會回傳等效的內省資訊。

邊界情況與陷阱

沒有固定的「33 個工具」——也沒有任何固定的總數。 舊資料引用單一數字，但那並不是契約。這個數量會隨已安裝的套件、enabled_tools 允許清單，以及 parse_pdf、AST 與 mutation 的環境 gate 而變動。請一律從執行中的伺服器讀取它。
允許清單只做減法，永不增加。 把某個 Pro 工具列入 enabled_tools，但缺少 nextpdf/premium 時，並不會註冊它。
缺少某個層級是靜默且預期的行為。 純開源安裝只提供核心集，並回報零個 Pro 工具與零個 Enterprise 工具。這代表系統正確運作，並非故障。
目錄中的層級是一個宣告式不變量。 每個工具都在程式碼中宣告自己的層級與風險。登錄表絕不會從 namespace 或封裝方式推斷層級。

效能

登錄表掃描與層級偵測只會在啟動時執行一次。 performance_budget 頁面會界定它們的上限。每個工具的成本來自底層的引擎操作，而非目錄查詢；目錄查詢以工具名稱為鍵，是 O(1)。

安全性說明

請把 enabled_tools 視為最小權限控制：只公開某個整合真正需要的工具。目錄絕不會納入被安全政策拒絕的工具，而層級計數器只反映被准許的工具。不論是否列於目錄中，高風險工具都仍受人為確認所把關。參見 /connect/security-and-operations/.

一致性

本頁說明登錄表機制。 tools/list 與 initialize 介面的協定引用釘選於 /transports/mcp/。風險模型則規範於 /connect/hitl-risk-tiers/。

商業脈絡

核心目錄對於建立、檢視與診斷而言已相當完整。簽章、編修、合規與鑑識工具只會在 nextpdf/premium 與伺服器一同安裝時出現。這是一條封裝邊界，會在 composer require 時套用，絕非執行時提示。

另請參閱

/connect/hitl-risk-tiers/ —— 風險欄位的意義，以及執行方式
/connect/boot-and-discovery/ —— 完整的啟動與探索流程
/connect/configuration/ —— enabled_tools 與環境 gate
/transports/mcp/ —— tools/list 與 initialize 的線路格式
/connect/overview/ —— 為何此目錄在設計上即依執行時而定