Pro 版本

MCP 工具 — 深入參考

可用性與授權

此功能隨 NextPDF Pro（nextpdf/pro）出貨，並以 Pro 層級授權封套啟用。未持有該權利的部署不會載入此功能的類別。比較版本並取得授權。

沒有任何單功能授權旗標。程式碼隨 Pro 版本出貨；當 Pro 套件在啟動時與 nextpdf/server 一同解析時，這八個工具會註冊在 pro 層級下。

行為合約

NextPDF Server 會在啟動時透過探測 Pro 工具提供者類別來探索各層級；若它能解析，伺服器就會將這八個工具註冊在 pro 層級下。Pro 套件並非伺服器的硬相依，因此 Pro 工具嚴格採取「需共同安裝才啟用」的方式。層級註冊彼此獨立：某個缺少或被政策排除的層級絕不會阻擋其他層級。
每一個工具都會宣告四種風險等級之一（safe、caution、review、approval-required）。一個選用的操作者覆寫只能提高工具的等級，絕不能降低；伺服器會對任何在 caution 以上等級的執行進行稽核記錄。sign_pdf 屬於 approval-required。
PDF 輸入會以固定順序解析：先是來自記憶體內儲存區的 document_id，接著是作為 data: URI、檔案系統路徑或原始 base64 的 source。缺少輸入時會回傳一個驗證錯誤，而非處理一份空白文件。
sign_pdf 只會產生一個 PAdES B-B 基準簽章——沒有時間戳記，也沒有長期驗證。支援的演算法與 AES-GCM 金鑰傳輸封套詳述於下；解密採取失敗即關閉（fail closed），且該工具絕不會把密文當作金鑰材料使用。
完整的探索、風險、來源解析、各工具與簽署細節請參閱下方各節。本頁僅描述外部可觀察的行為與已發布的工具合約。

範圍

本頁是這八個 Pro MCP 工具的操作者與整合者參考。它涵蓋探索模型、伺服器所套用的風險/HITL 語意、來源解析規則、簽署金鑰傳輸封套，以及各工具的失敗行為。它僅描述外部可觀察的行為與已發布的工具合約。面向使用者的目錄請參閱公開 MCP 頁面。

探索與註冊模型

NextPDF Server 會在啟動時探索層級提供者。它透過探測 Pro 工具提供者類別來偵測 Pro 層級；若該類別能解析，伺服器就會實例化該提供者，並將它回傳的每一個工具註冊在 pro 層級下。Pro 套件刻意不是伺服器的硬相依——這讓開源伺服器在沒有專有套件的情況下仍可安裝，並使 Pro 工具嚴格採取「需共同安裝才啟用」的方式。

伺服器會以每個層級為單位隔離註冊。若 Pro 套件不存在，Core 工具仍會註冊；某個存在的層級提供者不會阻擋其他層級。工具註冊同時也受伺服器安全政策允許清單的約束：被政策排除的工具會被無聲地略過註冊，且不會被計入層級摘要。伺服器會對外暴露每個層級的計數（core/pro/enterprise），以供診斷與記錄使用。

提供者會以固定順序回傳這八個工具：文字擷取、分段、比對、PII 遮罩、表單填寫、表單讀回、無障礙分析、簽署。順序是穩定的，但呼叫端不得倚賴它——請以工具的 MCP 協定名稱來解析工具。

風險模型與 HITL 語意

每一個工具都會宣告四種風險等級之一。伺服器會以所宣告的等級進行人為介入（human-in-the-loop）的強制：

Safe — 唯讀、無副作用。自動執行。
Caution — 建立或修改記憶體內狀態。自動執行，並附一筆稽核記錄項目。
Review — 產生可能被誤用的輸出。會自動執行，但代理人技能指示會標記它，使代理人對使用者提出警告。
Approval-required — 具破壞性、法律性或對隱私至關重要。伺服器會在執行前要求明確的人為確認。

Pro 工具分類：五個擷取/分析工具（extract_text、segment_document、compare_pdfs、extract_form_data、check_accessibility）為 safe；redact_pii 與 fill_form 為 review；sign_pdf 為 approval-required。

風險等級恰好來自兩個來源：工具自身的宣告，以及一個選用的執行階段操作者覆寫。該覆寫只能提高工具的風險等級（收緊強制）；它絕不能降低。伺服器會對任何在 caution 等級以上的執行進行稽核記錄。風險模型帶有一個版本；伺服器會在其初始化回應中公告該版本，讓用戶端能偵測不相容的變更。

來源解析順序

每一個接受 PDF 的工具，都會透過三種輸入形態之一接受它，並依此順序解析：

document_id — 伺服器從其記憶體內文件儲存區取回位元組。未知的 id 會以一個明確錯誤失敗，指示呼叫端先建立文件。
作為 data: URI 的 source — 工具會解碼逗號之後的 base64 主體。
作為檔案系統路徑的 source — 當路徑解析到一個檔案時，工具會從磁碟讀取。
作為原始 base64 字串的 source — 工具只會接受並解碼足夠長、且形態符合 base64 的輸入。

compare_pdfs 會對 source_a 與 source_b 各自獨立套用相同的解析，並額外接受在任一 source 槽位中的 document_id 值。若既未提供 document_id 也未提供 source，工具會回傳一個驗證錯誤，而非處理一份空白文件。

各工具參考

Tool	Risk	Inputs	Result fields	Behavioral boundary
`extract_text`	safe	PDF；選用的 1 起算 `page_start` / `page_end`	文字、總頁數	僅限文字圖層；範圍夾制至實際頁數；無 OCR
`segment_document`	safe	PDF	分段數、分段清單	由版面推導的分段；不是已標記 PDF 的結構樹
`compare_pdfs`	safe	兩份 PDF	相同旗標、總變更數、各文件頁數、區域（類型、文字、頁面索引、行索引、選用的對應方文字）	文字內容 diff；非視覺或二進位
`redact_pii`	review	PDF；選用的 `types`（`email`、`phone`、`ssn`、`credit_card`）	是否含 PII 旗標、偵測數量、遮罩後文字、掃描的類型	文字圖層偵測/遮罩；非視覺遮罩；以樣式為基礎，非窮盡
`fill_form`	review	`fields` 對映；選用的 `pdf_filename`	XFDF 文件、欄位數	產生 XFDF（ISO 19444-1）；不會把值寫入 PDF
`extract_form_data`	safe	PDF	欄位數、欄位對映、無欄位時的明確註記	僅讀取嵌入的 XFDF
`check_accessibility`	safe	PDF	結構分數（0–100）、問題、分段摘要	帶 WCAG 參考的結構性啟發式；非一致性裁決
`sign_pdf`	approval-required	PDF；PEM 憑證 + PKCS#8 金鑰；選用的演算法、簽署者名稱、原因、傳輸封套	已簽署 PDF、簽章數、完成旗標、演算法、OID、摘要	僅 PAdES B-B 基準；無時間戳記、無 LTV

簽署：演算法與金鑰傳輸

sign_pdf 會產生一個 PAdES B-B 基準簽章。支援的演算法，底線與連字號兩種拼法皆可接受：

RSA with SHA-256（預設）。
RSA with SHA-3 256 / 384 / 512 — 需要一個支援 SHA-3 的 OpenSSL 建置。
Ed25519 — 需要 libsodium 擴充；金鑰必須是一個包裝 Ed25519 私鑰的 PKCS#8 PEM。

工具會拒絕不支援的識別碼，並回傳可接受值的清單。

選用的傳輸加密封套讓呼叫端能透過一個並非端對端機密的傳輸通道隧道傳送私鑰。該封套僅限 AES-GCM：

對稱金鑰：16、24 或 32 位元組（AES-128/192/256），以 base64 編碼。
Nonce：恰為 12 位元組，以 base64 編碼。
選用的附加驗證資料，以 base64 編碼。
private_key 酬載是 base64 密文，並在尾端附上一個 16 位元組的 GCM 驗證標籤。

解密採取失敗即關閉（fail closed）：驗證標籤不符或酬載格式不正確時，會回傳一個解密錯誤，且工具絕不會把密文當作金鑰材料使用。工具會在進行任何密碼學工作之前，先拒絕錯誤的金鑰或 nonce 大小。

邊界案例與 FIPS 模式

extract_text：當頁面範圍的結尾超過文件時，工具會夾制它而非拒絕它，並會把低於第一頁的起點正規化為第一頁。
compare_pdfs：缺少 source_a 或 source_b 會回傳一個驗證錯誤；相同的文件會回傳一個明確的「相同」結果，變更數為零。
extract_form_data：不含嵌入 XFDF 串流的 PDF 會回傳一個零欄位結果並附上說明註記，而非錯誤。
redact_pii：types 中無法辨識的項目會被忽略；一個全部無法辨識的清單會產生一個空白掃描，而非失敗。
sign_pdf：缺少憑證或私鑰會在任何簽署工作之前先失敗；工具會在簽署時檢查演算法需求（SHA-3 的 OpenSSL 支援、Ed25519 的 libsodium），並以明確錯誤呈現它們。
FIPS 模式：演算法的可用性取決於主機的 OpenSSL/libsodium 建置。在受 FIPS 約束的建置中，未獲核准的演算法會在密碼學邊界以明確錯誤失敗，而非無聲降級。MCP 層不會新增或放寬密碼學政策——它只是呈現主機密碼學提供者的決定。

操作者執行手冊註記

維持 sign_pdf 為 approval-required。請確認沒有操作者覆寫意外提高了 safe 工具的風險——覆寫只會收緊，因此一個意外的覆寫會降低可用性，而非安全性。
稽核留存：每一個在 review 等級以上的執行都會被伺服器稽核記錄。請依 redact_pii、fill_form 與 sign_pdf 呼叫的量，規劃你的記錄留存大小。
傳輸選擇：當在一個並非端對端機密的傳輸通道上執行時，請為 sign_pdf 要求使用 AES-GCM 金鑰傳輸封套，並在你代理人的工具呼叫記錄政策中，把私鑰材料視為機密。
層級計數：請使用伺服器的各層級計數，在部署時斷言 Pro 層級已註冊八個工具；計數為零表示 Pro 套件未能解析。

版本邊界

Pro 層級恰好貢獻八個 MCP 工具。Enterprise 版本會出貨一個獨立的 MCP 層級，帶有其自身的工具——合規、鑑識、長期驗證健康度、AI-ready 認證，以及文件搜尋/嵌入。Enterprise 工具的輸入、輸出與內部實作不在此處範圍內，而是與 Enterprise 版本一同記載。伺服器會獨立探索各層級；某個層級缺少絕不會停用另一個層級。

發布邊界

本頁僅記載外部可觀察的行為與受支援的公開 API 介面。內部命名空間路徑、輔助類別、機制表格、執行手冊檔名與工單前綴皆不在範圍內。