Pro 版本

MCP 工具

速覽

NextPDF Pro 加入八個 Model Context Protocol（MCP）工具，讓 AI 代理能透過 NextPDF Server 執行進階 PDF 作業。當 nextpdf/pro 與 nextpdf/server 都已安裝時，這些工具會自動呈現——無須個別的註冊步驟。

供應與授權

此能力隨 NextPDF Pro（nextpdf/pro）一併提供，並以 Pro 層級授權封套啟用。缺少該權利的部署不會載入此能力的類別。比較各版本並取得授權。

基礎 MCP 介面——文件建立、文字、表格、診斷——隨開源 NextPDF Server 一併提供，且不需要授權。本頁的八個工具需要 Pro 授權，且只在 nextpdf/pro 套件於開機時解析成功時才註冊。pro 工具層級閘控整組工具：每個工具都明確宣告其層級，且沒有逐工具旗標——將 nextpdf/pro 與 nextpdf/server 並列安裝即可啟用整組工具。

行為合約

這八個 Pro MCP 工具會在 nextpdf/pro 與 nextpdf/server 都於開機時解析成功時，於 pro 層級下，透過標準的 MCP tools/list 與 tools/call 流程自動註冊。沒有逐工具旗標，使用方應用程式也無須變更程式碼。
每個工具都接受 PDF：透過先前一次 create_pdf 呼叫所得的 document_id、一個內嵌 source（檔案路徑、base64 或 data: URI），或——對 compare_pdfs 而言——兩個這樣的來源。工具會回傳結構化 JSON。
每個工具都宣告一個伺服器會強制執行的 HITL 風險類別：safe（自動執行、唯讀）、review（可能被濫用的輸出），以及 approval-required。sign_pdf 屬於 approval-required，會被保留直到有人確認。操作者只能收緊一個工具的風險類別，絕不能放寬。
sign_pdf 只產生 PAdES B-B（基準）簽章——沒有受信任的時間戳記，也沒有長期驗證資料。長期（B-LT / B-LTA）設定檔、硬體金鑰保管，以及稽核軌跡簽署皆屬於 Enterprise 層級，這些工具並不提供；當已設定時間戳記提供者時，B-T（帶時間戳記的簽章）可由 Core 引擎提供。
redact_pii 執行的是文字層樣式偵測與遮蔽，而非視覺遮蔽；check_accessibility 是一個結構性啟發式分析，而非 PDF/UA 或 WCAG 一致性判定。權威的輸入/輸出綱要是伺服器即時的 tools/list 回應，而非本頁。

概念總覽

NextPDF Server 是 NextPDF 確定性的 MCP 執行層。它在開機時以類別存在性探測來探索工具供應者，因此 Pro 套件不需要被列在伺服器的依賴中。當 Pro 套件存在時，伺服器會在 pro 層級下註冊其八個工具，並透過標準的 MCP tools/list 與 tools/call 流程，在你所設定的任一傳輸通道上揭露它們。

每個 Pro 工具都接受來自三種來源之一的 PDF：先前一次 create_pdf 呼叫回傳的 document_id、一個內嵌 source（檔案路徑、base64 字串或 data: URI），或——對比對工具而言——兩個這樣的來源。工具會回傳結構化的 JSON 結果：擷取的文字、差異區域、遮蔽後的文字、區段樹、無障礙發現項，或一份已簽署的 PDF。

每個 Pro 工具都帶有一個風險分類，伺服器會用它來進行 human-in-the-loop（HITL）強制。唯讀分析工具被列為 safe 並自動執行。會產生呼叫端可能濫用之輸出的工具被列為 review。簽署工具被列為 approval-required，因此伺服器會保留它直到有人確認。工具本身宣告此分類；操作者在執行階段只能收緊它——絕不能放寬。

MCP 工具介面刻意與 Pro PDF 引擎分離。這些工具是薄轉接器：它們驗證輸入、解析 PDF、委派給某個 Pro 引擎元件，並序列化結果。它們不是引擎的第二套 API，也不屬於 Pro 公開 PHP API——受支援的整合點是 NextPDF Server 揭露的 MCP 協定。

工具目錄（八個 Pro 工具）

依 MCP 協定名稱列出的八個 Pro MCP 工具。風險層級遵循伺服器的 HITL 模型：safe（自動執行、唯讀）、review（產生可能被濫用的輸出；於代理指示中提出警告），以及 approval-required（必須由人類確認）。

`extract_text`

用途： 文字擷取。擷取一份 PDF 的文字層，可選擇限定於以 1 為起始索引的頁面範圍。
輸入： 一份 PDF（document_id 或 source）；可選的 page_start 與 page_end。
輸出： 擷取的文字與總頁數。
風險： Safe。唯讀且具冪等性。
邊界： 擷取既有的文字層。它不會對掃描或純影像頁面執行 OCR。

`segment_document`

用途： 結構性分段。將一份 PDF 切分為邏輯區段——標題、各級標題、本文、表格、圖。
輸入： 一份 PDF（document_id 或 source）。
輸出： 一個區段數量與一份結構化的區段清單。
風險： Safe。唯讀且具冪等性。
邊界： 基於版面分析的結構性分段；它不是語意大綱，也不是 tagged-PDF 的結構樹。

`compare_pdfs`

用途： 結構性差異。比對兩份 PDF，並回傳其文字內容的結構化差異。
輸入： 兩份 PDF（source_a 與 source_b，各為路徑、base64、data URI 或 document_id）。
輸出： 一個 identical 旗標、變更總數、各文件頁數，以及一份帶有頁與行索引的變更區域清單。
風險： Safe。唯讀且具冪等性。
邊界： 文字內容差異。它不會比對視覺彩現、嵌入字型或二進位結構。

`redact_pii`

用途： PII 偵測與遮蔽。偵測一份 PDF 文字層中的個人可識別資訊，並回傳該文字的遮蔽檢視。
輸入： 一份 PDF（document_id 或 source）；可選的 types 篩選（email、phone、ssn、credit_card）。
輸出： 一個 has-PII 旗標、偵測到的數量、遮蔽後的文字，以及所掃描類型的清單。
風險： Review。若把遮蔽後的輸出當成已清理的文件看待，可能會被濫用。
邊界： 這是文字層樣式偵測與遮蔽，而非視覺遮蔽。它不會移除或覆寫彩現後 PDF 中的字符，且樣式比對並不保證找到敏感資料的每一個出現處。請勿將其輸出視為完整移除 PII 的保證。若需要摧毀底層內容的文件層級遮蔽，請使用開源伺服器工具中的專用遮蔽介面，或使用 Enterprise 版本。

`fill_form`

用途： AcroForm 填寫資料。從欄位名稱到值的對應表，產生可填入 PDF AcroForm 欄位的 XFDF（ISO 19444-1）資料。
輸入： 一個從欄位名稱到字串值的 fields 對應表；可選的 pdf_filename，會作為 XFDF 參照嵌入。
輸出： 所產生的 XFDF 文件與欄位數量。
風險： Review。它產生意圖套用至文件的表單資料。
邊界： 它產生符合標準的 XFDF；它本身不會將值寫回 PDF。請以任何相容的閱讀器或處理工具套用該 XFDF。

`extract_form_data`

用途： AcroForm 回讀。從嵌入於 PDF 中的 XFDF 擷取 AcroForm 欄位名稱與值。
輸入： 一份 PDF（document_id 或 source）。
輸出： 一個欄位數量與一份從欄位名稱到值的對應表；當沒有嵌入的表單資料時，會附上明確註記。
風險： Safe。唯讀且具冪等性。
邊界： 讀取嵌入的 XFDF（ISO 19444-1）串流。一份只在 AcroForm 物件中、未嵌入 XFDF 的方式保存表單值的 PDF，會回傳空結果。

`check_accessibility`

用途： 結構性無障礙分析。分析一份 PDF 的結構性無障礙——各級標題、段落、表格與影像——並回報可能的問題，附上 WCAG 參照。
輸入： 一份 PDF（document_id 或 source）。
輸出： 一個結構分數（0–100）、一份問題清單，以及一份區段摘要。
風險： Safe。唯讀且具冪等性。
邊界： 這是一個結構性啟發式分析，而非一致性判定。完整的 PDF/UA 與 WCAG 一致性測試——標籤樹、閱讀順序、色彩對比——需要專用的無障礙引擎。高分並不是 PDF/UA 一致性的陳述。

`sign_pdf`

用途： PAdES B-B 數位簽章。使用本機 X.509 憑證與私鑰，對一份 PDF 套用 PAdES B-B（基準）數位簽章。
輸入： 一份 PDF（document_id 或 source）；一個 PEM 憑證與 PKCS#8 私鑰；一個可選的演算法（預設 RSA-SHA256、RSA + SHA-3 256/384/512 或 Ed25519）；可選的簽署者名稱與原因；以及一個圍繞私鑰承載的可選 AES-GCM 傳輸封套。
輸出： 已簽署的 PDF、簽章數量、完成旗標，以及所使用的演算法、OID 與摘要。
風險： Approval-required。簽署是一項具法律意義的破壞性作業；伺服器在執行前要求明確的人類確認。
邊界： 此工具產生一個 PAdES B-B（基準）簽章——它不嵌入受信任的時間戳記或長期驗證資料。長期（B-LT / B-LTA）設定檔、硬體支撐的金鑰保管，以及稽核軌跡簽署都屬於 Enterprise 版本；當已設定時間戳記提供者時，B-T（帶時間戳記的簽章）可由 Core 引擎提供。關於 Pro 套件更廣泛的簽署能力，以及 Enterprise 版本的 B-LT/B-LTA，請參閱 Pro 簽章介面。

工具如何呈現

composer require nextpdf/pro
composer require nextpdf/server

兩個套件都安裝後，以你選定的傳輸通道啟動 NextPDF Server。伺服器會在開機時探索 Pro 層級，這八個工具就會與開源 Core 工具一同出現在 MCP tools/list 回應的 pro 層級下。你的應用程式無須變更程式碼——探索會自動執行，而缺少某個層級絕不會阻擋其他層級載入。

每個工具權威的輸入與輸出綱要，是伺服器在其 tools/list 回應中發布的綱要。請將該回應——而非本頁——視為合約：本目錄描述意圖與邊界；即時綱要才描述確切的欄位名稱與型別。

程式碼範例——快速開始

Pro 工具是透過 MCP 協定消費，而非透過 Pro PHP API。主機端的整合就是啟動 NextPDF Server。當 nextpdf/pro 存在時，這八個工具會透過執行階段探索註冊——無須逐工具接線——主機接著便會將它們提供給代理。

<?php

declare(strict_types=1);

use NextPDF\Server\Mcp\McpServer;

require __DIR__ . '/vendor/autoload.php';

// Runtime discovery registers the Pro tier when nextpdf/pro is installed
// alongside nextpdf/server. The consuming application changes no code.
$server = McpServer::create();

// A Pro tool name resolves only when the Pro package is present.
$signTool = $server->getToolRegistry()->get('sign_pdf');

\fwrite(\STDERR, $signTool !== null
    ? "Pro MCP tools active.\n"
    : "Pro MCP tools unavailable; install nextpdf/pro.\n");

// Serve the MCP protocol over stdio (Claude Desktop, Cursor, local agents).
$server->run();

程式碼範例——正式環境

強化開機路徑。載入一個明確的政策檔案、在遇到無效的風險層級覆寫時拒絕啟動，並在提供服務前確認 Pro 層級已呈現。McpServer::create() 中的接線在某個 risk_level_overrides 區塊試圖削弱像 sign_pdf 這種 approval-required 工具時，會擲出 InvalidArgumentException，因此一個組態錯誤的政策會在服務迴圈之前 fail closed。

<?php

declare(strict_types=1);

use NextPDF\Server\Mcp\McpServer;
use NextPDF\Server\Tools\ToolInterface;

require __DIR__ . '/vendor/autoload.php';

// A downgrade of an approval-required tool's HITL gate is rejected at boot,
// never silently applied — the server refuses to start on such a policy.
try {
    $server = McpServer::create(__DIR__ . '/nextpdf-mcp.yaml');
} catch (\InvalidArgumentException $e) {
    \fwrite(\STDERR, 'Refusing to start: invalid MCP policy. ' . $e->getMessage() . "\n");
    exit(1);
}

// Confirm the Pro tier surfaced before advertising it to agents.
$signTool = $server->getToolRegistry()->get('sign_pdf');

if (!$signTool instanceof ToolInterface) {
    \fwrite(\STDERR, "nextpdf/pro is not resolving; Pro MCP tools are unavailable.\n");
    exit(1);
}

// sign_pdf is approval-required; the server holds it for human confirmation.
$risk = $signTool->riskLevel()->label();
\fwrite(\STDERR, "Pro MCP tools ready. sign_pdf risk: {$risk}.\n");

$server->run();

正式環境指引

HITL 閘控。 讓 sign_pdf 維持在人類確認之後。伺服器會依工具所宣告的風險層級強制執行此點；請勿將你的代理設定為繞過它。操作者只能收緊一個工具的風險層級，絕不能放寬。
來源處理。 對已在工作階段中的文件，優先使用 document_id。對於內嵌資料，這些工具接受 base64 與 data: URI；非常大的內嵌承載會比參照式文件執行得更慢。
PII 預期。 請明確設定呼叫端的預期：redact_pii 是一個偵測與遮蔽輔助，而非清理保證。若需要不可逆的移除，請改用專用的遮蔽介面。
簽署金鑰。 當傳輸通道並非端對端機密時，請透過傳輸加密封套提供金鑰。在你代理的工具呼叫日誌政策中，請將私鑰素材視為祕密。
稽核日誌。 safe 層級以上的工具會由伺服器進行稽核日誌記錄。請確保你的部署依你的合規要求留存那些日誌。

邊界案例

extract_text 的頁面範圍以 1 為起始索引，並夾限至文件的實際頁數；超出範圍的結束值不會出錯。
compare_pdfs 需要兩個來源；只傳入一個會回傳清楚的驗證錯誤，而非部分差異。
extract_form_data 對於未嵌入 XFDF 的 PDF，會回傳一個已填妥、明確的「無嵌入表單資料」結果，而非錯誤。
sign_pdf 會拒絕不支援的演算法識別碼，並附上支援值的清單；Ed25519 需要 libsodium 擴充，而 SHA-3 變體需要一個支援 SHA-3 的 OpenSSL 建置。
check_accessibility 依設計會給純影像 PDF 較低分數——它會標示缺少可讀文字層的情況，而非失敗。

安全注意事項

簽署工具是唯一一個 approval-required 工具；伺服器不會自動執行它。
圍繞私鑰的可選 AES-GCM 封套會驗證承載；標籤不符會 fail closed 並回傳解密錯誤，且絕不會回退為使用密文。
redact_pii 不會更動來源 PDF；它回傳的是一個遮蔽後的文字表示。它不能替代內容摧毀。
工具在任何引擎作業之前驗證輸入；它會以明確錯誤拒絕格式錯誤的來源、data URI 與 base64 承載。

一致性

表單工具依 ISO 19444-1:2019（XML Forms Data Format）產生與消費 XFDF。
sign_pdf 產生一個與 ETSI EN 319 142 PAdES 家族對齊的 PAdES 基準（B-B）簽章；長期設定檔屬於 Enterprise 能力，而當已設定時間戳記提供者時，B-T 可由 Core 引擎提供。
check_accessibility 以 WCAG 成功準則參照（例如 1.1.1、1.3.1、2.4.6）回報發現項，作為啟發式指引，而非一致性證明。

版本邊界

NextPDF Pro 恰好貢獻八個 MCP 工具，全部位於 pro 層級。Enterprise 版本在 enterprise 層級隨附其自有、獨立的 MCP 工具集——涵蓋合規檢查、鑑識分析、長期驗證健康、AI-ready 認證，以及文件搜尋與嵌入。那些工具、它們的輸入與其內部實作皆超出本頁範圍；請參閱 Enterprise MCP 工具。伺服器本身的文件涵蓋隨它一併提供的 Core（開源）工具。伺服器會獨立探索這三個層級，且缺少某個層級絕不會停用其他層級。

Enterprise 邊界註記

Pro 恰好在 pro 層級貢獻八個 MCP 工具。Enterprise 版本在 enterprise 層級隨附一套獨立的 MCP 工具集（合規檢查、鑑識分析、長期驗證健康、AI-ready 認證、文件搜尋與嵌入），以及帶時間戳記/長期簽章設定檔；那些並非由 Pro 層級提供。完整的層級拆解，請參閱上方的版本邊界一節。

Core 回退/替代方案

開源 NextPDF Server 為任何 AI 代理提供一套確定性的 Core PDF 工具集（文件建立、文字、表格、診斷），且不需要授權。本頁的八個進階工具是 Pro 新增的。請參閱 /connect/tools/。

發布邊界

本頁僅描述外部可觀察的行為，以及受支援的公開 API 介面。內部命名空間路徑、輔助類別、機制表格、runbook 檔案名稱與工單前綴皆超出範圍。