MCP — 深入參考

概覽

NextPDF\Enterprise\Mcp 命名空間提供 NextPDF MCP 工具目錄的 Enterprise 層級。其公開介面為十一個工具類別、一個用戶端工廠，以及一個具型別的例外。每個工具都實作 nextpdf/server 執行環境所提供的 NextPDF\Server\Tools\ToolInterface 合約，並宣告 ToolTier::Enterprise。六個工具在行程內分析單一 PDF。四個工具透過 NextPDF\Enterprise\Mcp\SpectrumClientFactory 將批次與 RAG 工作負載委派給 Spectrum sidecar。一個工具讀取由建構子注入的 AST 變更稽核軌跡，而非 PDF 位元組。每個工具都會自我描述其 MCP 名稱、JSON Schema 輸入、用戶端註記、RiskLevel 以及類別。

可用性與授權

此功能隨 NextPDF Enterprise（nextpdf/enterprise）提供，並以 Enterprise 層級的授權封套啟用。缺少該授權資格的部署不會載入此功能的類別。比較各版本並取得授權。

公開 API 介面

符號	參數	預設行為	回傳	拋出或失敗於	備註
ForensicAnalyzeTool::execute	array $arguments, InMemoryDocumentStore $store；引數：document_id 或 source	執行鑑識分析：修訂、增量更新、簽章	ToolResult（JSON 報告）	錯誤 ToolResult；例外會被攔截，絕不重新拋出	工具 forensic_analyze；RiskLevel::Safe；唯讀、冪等；類別 document；自 2.0.0 起
BatchForensicAnalyzeTool::execute	引數：workspace_token、documents[]（各含 id + path）	透過 Spectrum sidecar 進行批次鑑識分析	ToolResult，含各文件 status、成功與失敗計數	錯誤 ToolResult（引數缺漏、sidecar 失敗）	工具 batch_forensic_analyze；RiskLevel::Safe；類別 document；自 2.1.0 起
ComplianceCheckTool::execute	引數：policy（12 值列舉）、document_id 或 source	依單一具名法遵政策評估該 PDF	ToolResult，含發現項、通過/未通過、duration_ms 與 disclaimer 欄位	錯誤 ToolResult；未知政策回傳列出支援鍵值的錯誤	工具 compliance_check；RiskLevel::Review；類別 document；自 2.0.0 起
BatchComplianceCheckTool::execute	引數：workspace_token、documents[]、policies（pdfa、pades、zugferd；預設 ["pdfa"]）	透過 Spectrum sidecar 進行批次法遵檢查	ToolResult，含合規/不合規計數	錯誤 ToolResult；每個 documents[] 元素皆驗證 id 與 path 非空	工具 batch_compliance_check；RiskLevel::Safe；類別 document；自 2.1.0 起
LtvHealthCheckTool::execute	引數：document_id 或 source	對已簽章 PDF 執行 LTV 健康度政策	ToolResult，含發現項與通過/未通過	錯誤 ToolResult	工具 ltv_health_check；RiskLevel::Safe；類別 document；自 2.0.0 起
AiReadyCertifyTool::execute	引數：document_id 或 source	對四項準則進行唯讀 AI 就緒度評估	ToolResult，含 certification_level（certified、partial、not_certified）與各準則布林值	錯誤 ToolResult	工具 ai_ready_certify；RiskLevel::Review；唯讀；類別 document；自 2.0.0 起
CertifyAiReadyTool::execute	引數：document_id 或 source、return_stamped_pdf（預設 true）	評估三項準則並附加 XMP 出處戳記	ToolResult；除非停用或 not_certified，否則包含 stamped_pdf_base64	錯誤 ToolResult	工具 certify_ai_ready；RiskLevel::Review；非唯讀；類別 document；自 3.0.0 起
AstAwareChunkTool::execute	引數：document_id 或 source、max_chunk_chars（預設 1500）、overlap_chars（預設 150）	建立 AST 並產出附引用錨點與出處的分塊	ToolResult，含 chunk_count 與各分塊的節點 ID、頁面索引、bbox、節點類型	錯誤 ToolResult	工具 ast_aware_chunk；RiskLevel::Review；類別 extraction；自 3.0.0 起
AuditAstMutationsTool::__construct	AstAuditTrailInterface $auditTrail	注入稽核軌跡後端	實例	—	建構子注入的相依項；自 3.0.0 起
AuditAstMutationsTool::execute	引數：document_source_hash（SHA-256 十六進位，必填）	回傳該文件所有已記錄的 AST 變更事件	ToolResult，含 entries[] 與 count	引數缺漏或為空時回傳錯誤 ToolResult	工具 audit_ast_mutations；RiskLevel::Review；類別 document；自 3.0.0 起
EmbedDocumentsTool::execute	引數：collection_id、workspace_token、documents[]（皆必填）	透過 Spectrum sidecar 將 PDF 匯入 RAG 集合	ToolResult，含成功/總計/失敗計數	錯誤 ToolResult	工具 embed_documents；RiskLevel::Caution；非唯讀、非冪等；類別 extraction；自 2.1.0 起
SearchDocumentsTool::execute	引數：collection_id、query（必填）、top_k（預設 10，限制 1–100）、mode（hybrid、bm25、semantic）	對已匯入的集合進行混合式擷取	ToolResult，含排名分塊與相關性分數	錯誤 ToolResult；不在允許清單內的 mode 會被拒絕	工具 search_documents；RiskLevel::Safe；類別 extraction；自 2.1.0 起
SpectrumClientFactory::create	無（讀取 SPECTRUM_URL、SPECTRUM_TIMEOUT、SPECTRUM_AUTH_TOKEN、SPECTRUM_APP_SECRET）	建立並快取一個行程層級的 sidecar 用戶端	SpectrumClient	當 SPECTRUM_URL 格式錯誤或指向被封鎖位址時拋出 InvalidArgumentException	預設端點 http://127.0.0.1:7800；逾時 30.0 秒；自 2.1.0 起
SpectrumClientFactory::reset	無	清除已快取的用戶端實例	void	—	供測試使用
SpectrumClientFactory::createRequest	string $method, $uri（string 或 UriInterface）	從 Core HTTP 類別建立 PSR-7 請求	RequestInterface	—	PSR-17 RequestFactoryInterface 實作
SpectrumClientFactory::createStream	string $content = ''	建立記憶體內 PSR-7 串流	StreamInterface	—	PSR-17 StreamFactoryInterface 實作
SpectrumClientFactory::createStreamFromFile	string $filename, string $mode = 'r'	開啟檔案並將其包裝為串流	StreamInterface	檔案無法開啟時拋出 McpStreamException	McpStreamException 繼承 RuntimeException
SpectrumClientFactory::createStreamFromResource	$resource（PHP resource）	將既有資源包裝為串流	StreamInterface	—	PSR-17 StreamFactoryInterface 實作
McpStreamException	—	具型別的串流取得失敗	—	—	final class，繼承 RuntimeException；原始碼註明 PSR-17 §1.5 相容性；原始碼將其標註為 @since 3.2.0（存在於目前以 3.1.0 為別名的開發線）

每個工具也都揭露 ToolInterface 的自我描述方法：name、description、inputSchema、annotations、riskLevel、tier 與 category。其各工具的值列於上表的備註欄。

進入點簽章，逐字取自原始碼：

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function __construct(private readonly AstAuditTrailInterface $auditTrail)
public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public static function create(): SpectrumClient
public static function reset(): void
public function createRequest(string $method, $uri): RequestInterface
public function createStream(string $content = ''): StreamInterface
public function createStreamFromFile(string $filename, string $mode = 'r'): StreamInterface
public function createStreamFromResource($resource): StreamInterface

行為合約

• 每個工具都實作 NextPDF\Server\Tools\ToolInterface 並明確宣告 ToolTier::Enterprise。層級絕不會從命名空間或封裝推斷得出。
• execute 不會拋出例外。每一次失敗都會被攔截，並以攜帶失敗訊息的錯誤 ToolResult 回傳。
• 單文件工具以固定優先序解析 PDF 位元組。首先在 InMemoryDocumentStore 中查找 document_id。否則 source 會依序被解讀為 data: URI、再作為原始 base64（超過 256 個字元），最後作為檔案路徑。
• 檔案系統 source 路徑預設停用。唯有當 NEXTPDF_MCP_INPUT_DIR 環境變數指定一個受限輸入目錄時才會啟用。解析後的實際路徑必須留在該目錄之內。其餘一律以失敗封閉方式處理。
• 串流包裝器協議（phar://、php://、file://，以及任何其他協議）與檔案路徑 source 中的 null 位元組，會在任何檔案系統呼叫之前遭到拒絕。路徑穿越與符號連結逃逸會在實際路徑受限檢查中失敗。
• 使用 sidecar 的工具（embed_documents、search_documents、batch_compliance_check、batch_forensic_analyze）會從 SpectrumClientFactory::create 取得用戶端。工廠會在使用前，將非本機的 SPECTRUM_URL 對照私有與保留位址範圍進行驗證。明確指定的本機位址則允許用於本機 sidecar 模式。
• ai_ready_certify 由四項準則推導其層級：鑑識完整性、簽章存在、LTV 有效性，以及未加密。四項全部通過即得出 certified；一至三項得出 partial；零項得出 not_certified。鑑識完整性是對修訂鏈的結構性啟發式判斷，而非密碼學的位元組完整性驗證。加密檢查僅檢視 trailer 區域。
• certify_ai_ready 評估三項準則並附加 XMP 出處戳記。除非 return_stamped_pdf 為 false 或層級為 not_certified，否則已戳記的位元組會以 base64 編碼回傳。
• compliance_check 恰好接受十二個政策鍵值：pdfa4、pdfa4e、pdfa4f、pades-baseline、ltv-health、eidas-qualified、zugferd、fda-part11、sec-17a4、sec-17a4-compatible、sec-17a4-structural、sec-17a4-pre-sign。未知鍵值會回傳一個列出支援集合的錯誤結果。
• audit_ast_mutations 僅讀取注入的 AstAuditTrailInterface。它本身不記錄任何內容。

邊界案例與失敗模式

• 未提供 document_id 也未提供 source：回傳錯誤結果，指示呼叫方提供其中之一。
• 未知的 document_id：回傳錯誤結果，指名該 ID 並指向 create_pdf。
• 未設定 NEXTPDF_MCP_INPUT_DIR 時使用檔案系統 source：以指名支援管道的訊息拒絕。
• source 路徑解析後落在所設定輸入目錄之外，包含透過符號連結者：拒絕。比較是在目錄分隔符邊界上進行，因此共用相同名稱前綴的同層目錄無法通過。
• data: URI 缺少逗號分隔符，或 base64 酬載無效：回傳錯誤結果。
• search_documents 的 top_k 落在 1–100 之外：限制範圍，而非拒絕。非整數的 top_k 會退回至所設定的管線預設值。
• search_documents 的 mode 落在 hybrid、bm25、semantic 之外：由管線允許清單回傳錯誤結果。
• batch_compliance_check 的 documents[] 元素缺少 id 或 path，或攜帶空字串：回傳指名違規索引的錯誤結果。batch_forensic_analyze 僅驗證外層陣列形狀；元素缺陷會從批次層浮現。
• SpectrumClientFactory::create 遇到格式錯誤的 SPECTRUM_URL，或指向私有、連結本機或中繼資料位址者：拋出 InvalidArgumentException。在工具 execute 之內，這會以錯誤結果浮現。
• SpectrumClientFactory::createStreamFromFile 遇到無法讀取的路徑：拋出 McpStreamException。
• 空的環境變數視同未設定，並退回至預設值。

一致性

NextPDF 未持有任何認證，亦不授予任何認證。MCP 工具回報的是能力層級的評估；支援不等於一致性，一致性也不等於認證。ai_ready_certify 與 certify_ai_ready 所回傳的 certification_level 值，是這些工具本身回報的詞彙。它們不構成第三方認證。基於同一理由，compliance_check 回應包含由底層報告產生的 disclaimer 欄位。政策條款參照（例如產品原始碼所述 LTV 政策依據為 ISO 32000-2:2020 §12.8.4.3）承載於工具描述與各發現項的 clause 欄位中；本頁不新增獨立的標準主張。受檢文件是否滿足某項法規，屬於操作者及其評估人員的判定。

開發注記

• SpectrumClientFactory::create 每個行程快取一個用戶端。在測試設定中呼叫 SpectrumClientFactory::reset 以強制取得全新用戶端。
• 環境讀取會依序查詢 $_ENV、$_SERVER、getenv，並將空字串視同不存在。
• RiskLevel 驅動 server 執行環境中主機端的處理方式：Safe 自動執行，Caution 及以上會記入稽核日誌，ApprovalRequired 則要求人工確認。沒有任何 Enterprise MCP 工具宣告 ApprovalRequired。操作者覆寫可提升已宣告的層級，但絕不能降低。
• annotations 值（readOnlyHint、idempotentHint）是 MCP 用戶端提示，而非強制措施。無論提示為何，限制與驗證皆在 server 端進行。
• 工具回報 category 值 document 或 extraction，供 tools/list 篩選使用。
• AuditAstMutationsTool 是唯一需要建構子注入的工具；請以具體的 AstAuditTrailInterface 實作註冊它。

另請參閱

• MCP（功能頁）
• Accelerator — 深入參考 — Spectrum sidecar 用戶端介面。
• Forensics — 深入參考 — forensic_analyze 背後的分析器。
• Compliance — 深入參考 — compliance_check 背後的政策。
• AST — 深入參考 — 分塊與變更稽核軌跡。
• Validation — 深入參考

出版範圍界線

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