Enterprise 版本

MCP 工具

概覽

NextPDF Enterprise 在 NextPDF Connect 伺服器上新增十一項 MCP 工具。它們讓 AI 助理與 agent 框架能直接以型別化方式存取 Enterprise 引擎：合規政策檢查、PDF 鑑識、LTV 健康檢查、AI 就緒戳記、AST 感知分塊，以及 RAG 匯入與搜尋。每項工具都宣告自身的風險等級與唯讀姿態，因此你的 MCP 主機能有信心地對 agent 活動進行閘控、記錄與稽核。失敗絕不會以例外形式浮現；agent 一律收到結構化、可解析的結果。

可用性與授權

此能力隨 NextPDF Enterprise（nextpdf/enterprise）出貨，並以 Enterprise 級授權封套啟用。缺少該權限的部署不會載入此能力的類別。比較版本並取得授權。

安裝

composer require nextpdf/enterprise:^3

MCP 主機本身即 NextPDF Connect，隨 nextpdf/server 套件出貨；請見 Connect 安裝。當兩個套件都存在時，伺服器的工具登錄會自動探索 NextPDF\Enterprise\McpToolProvider 並註冊這十一項 Enterprise 工具。不需要任何接線程式碼。若 nextpdf/server 不存在，該 provider 檔會提早返回，什麼都不會載入。

批次與 RAG 工具還需要 Spectrum sidecar。透過 NextPDF\Enterprise\Mcp\SpectrumClientFactory 讀取的環境變數進行設定：SPECTRUM_URL（預設 http://127.0.0.1:7800）、SPECTRUM_TIMEOUT（預設 30.0 秒）、SPECTRUM_AUTH_TOKEN 與 SPECTRUM_APP_SECRET。

概念總覽

Model Context Protocol（MCP）是一項開放協定，讓 AI 助理與 agent 框架能呼叫伺服器所公開的型別化工具。agent 不再把 PDF 位元組貼進提示裡碰運氣，而是以名稱呼叫工具、附上通過 JSON schema 驗證的酬載，並收到確定性的結構化結果。NextPDF Connect 就是 PDF 的那個伺服器；Enterprise 套件以下方工具擴充其目錄。每項工具都是對你 PHP 程式碼直接呼叫的同一批 Enterprise API 的薄封裝，因此 agent 執行的檢查與程式碼執行的檢查會產生相同的裁決。

工具目錄

MCP 工具	類別	用途	風險	唯讀
`compliance_check`	`ComplianceCheckTool`	針對具名政策驗證單一 PDF：`pdfa4`、`pdfa4e`、`pdfa4f`、`pades-baseline`、`ltv-health`、`eidas-qualified`、`zugferd`、`fda-part11`，以及四種 `sec-17a4` 變體。	Review	yes
`batch_compliance_check`	`BatchComplianceCheckTool`	在單一 Spectrum sidecar 批次中，針對 `pdfa`、`pades` 或 `zugferd` 政策檢查多份 PDF。	Safe	yes
`forensic_analyze`	`ForensicAnalyzeTool`	報告修訂歷史、增量更新與修改事件，以偵測竄改。	Safe	yes
`batch_forensic_analyze`	`BatchForensicAnalyzeTool`	在單一 sidecar 批次中對多份 PDF 執行鑑識分析。	Safe	yes
`ltv_health_check`	`LtvHealthCheckTool`	檢查已簽署 PDF 的長期驗證素材：DSS 字典、OCSP 回應、CRL 條目、VRI 條目與憑證庫。	Safe	yes
`ai_ready_certify`	`AiReadyCertifyTool`	針對四項準則做出唯讀、產品定義的 AI 就緒裁決：鑑識完整性、簽章存在、LTV 有效性、無加密。	Review	yes
`certify_ai_ready`	`CertifyAiReadyTool`	針對三項準則做出產品定義的就緒裁決（唯讀工具四項中扣除鑑識完整性——此為刻意設計，因為此工具會改寫其所戳記的檔案），並附加一個 XMP 來源戳記；以 base64 回傳戳記後的 PDF。	Review	no
`ast_aware_chunk`	`AstAwareChunkTool`	沿標題邊界將 PDF 切成引用錨定的分塊，每塊附節點 ID、頁索引與定界框。	Review	yes
`audit_ast_mutations`	`AuditAstMutationsTool`	依 SHA-256 來源雜湊擷取文件的 AST 變異稽核軌跡。	Review	yes
`embed_documents`	`EmbedDocumentsTool`	將 PDF 匯入 RAG 集合：解析、分塊、嵌入、索引。會修改集合狀態。	Caution	no
`search_documents`	`SearchDocumentsTool`	對已匯入集合進行混合檢索（BM25 關鍵字加語意），回傳排序、計分的分塊。	Safe	yes

「certify」類工具會發出產品定義的就緒裁決（certified、partial 或 not_certified）。該裁決是一項技術檢查結果，而非任何認證機構的認證。

核准閘控與稽核姿態

每項工具都從四級 Connect 模型中宣告一個風險等級。Safe 工具會自動執行。Caution 工具會自動執行並附一筆稽核日誌條目。Review 工具會在呼叫 agent 的指示中帶一則警告。ApprovalRequired 工具要求人工確認；目前沒有任何 Enterprise MCP 工具宣告此等級，因為沒有一項具破壞性。執行期設定只能提高工具的風險等級，絕不能降低。工具也會發布 MCP 行為註記（readOnlyHint、idempotentHint），因此符合規範的用戶端可在其上套用自己的閘控。完整模型請見 HITL 風險層級。

為何這樣設計

承載全局的決策是：工具是薄的、確定性的封裝，並自我宣告治理——每項工具將自身的風險等級與層級陳述為一項領域不變量，絕不從命名空間或封裝推斷。這讓閘控決策能在主機端可稽核，而不必信任傳輸層。工具本身不含任何文件智慧；它們委派給你程式碼呼叫的同一批 Enterprise API，因此只有一種行為要測試、只有一個裁決要信任。錯誤會回到 MCP 錯誤通道，而不是以例外逸出，因為 agent 無法捕捉 PHP 例外，卻永遠能依 isError 分支。任何可能觸及檔案系統的輸入預設皆採 fail-closed，因為 MCP 引數依定義即為攻擊者可達。

設計背景：一個拒絕猜測的 API。

API 介面

這十一項工具全都實作 nextpdf/server 的 NextPDF\Server\Tools\ToolInterface 合約，並共用相同的公開介面。以下簽章以代表性的 NextPDF\Enterprise\Mcp\ComplianceCheckTool 展示一次：

public function name(): string
public function description(): string
public function inputSchema(): array
public function annotations(): array
public function riskLevel(): RiskLevel
public function tier(): ToolTier
public function category(): string
public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

拋出或失敗於：execute() 絕不拋出。它會在內部捕捉 Throwable 並回傳 ToolResult::error()，其 isError = true。無效引數（缺少 workspace_token、documents 條目格式錯誤、未知 document_id、不安全的 source）會以 InvalidArgumentException 訊息浮現於該錯誤通道。

稽核軌跡工具以建構子注入方式接收其儲存後端：

public function __construct(private readonly AstAuditTrailInterface $auditTrail)

註冊目錄的 provider：

public function getTier(): string
public function getTools(): array

getTier() 回傳 'enterprise'。getTools() 回傳十一個工具實例；audit_ast_mutations 預設以 NextPDF\Enterprise\Ast\InMemoryAstAuditTrail 接線。

Spectrum sidecar 用戶端工廠，同時也是 PSR-17 request 與 stream 工廠：

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

拋出或失敗於：當 SPECTRUM_URL 格式錯誤，或設定的端點指向已知的私有或保留位址（localhost 除外）時，create() 會拋出 InvalidArgumentException。這是一項設定期的閘門，而非網路層的控制：仍須在主機環境中落實出口政策、重導向處理與 DNS 釘選。當檔案無法開啟時，createStreamFromFile() 會拋出 NextPDF\Enterprise\Mcp\McpStreamException（依 PSR-17 合約，為 RuntimeException 的子類別）。

程式碼範例 — 快速開始

完全比照 agent 的做法，使用記憶體內 data: URI 通道執行一次 PDF/A-4 合規檢查：

<?php

declare(strict_types=1);

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

use NextPDF\Enterprise\Mcp\ComplianceCheckTool;
use NextPDF\Enterprise\Mcp\McpStreamException;
use NextPDF\Enterprise\Mcp\SpectrumClientFactory;
use NextPDF\Server\Document\InMemoryDocumentStore;

$streams = new SpectrumClientFactory(); // PSR-17 stream factory from this module

try {
    $pdfBytes = (string) $streams->createStreamFromFile(__DIR__ . '/invoice.pdf');
} catch (McpStreamException $e) {
    fwrite(STDERR, 'Cannot read PDF: ' . $e->getMessage() . PHP_EOL);
    exit(1);
}

$tool   = new ComplianceCheckTool();
$result = $tool->execute(
    [
        'source' => 'data:application/pdf;base64,' . base64_encode($pdfBytes),
        'policy' => 'pdfa4',
    ],
    new InMemoryDocumentStore(),
);

// Tool failures arrive on the MCP error channel, never as exceptions.
if ($result->isError) {
    fwrite(STDERR, $result->content[0]['text'] . PHP_EOL);
    exit(1);
}

echo $result->content[0]['text'] . PHP_EOL;

符合規範的檔案之預期輸出（發現項數量依文件而異）：

Compliance check (PDF/A-4): PASS — 0 finding(s)

完整的機器可讀報告——包含每項發現的嚴重度、規則 ID、條款與建議——可於 $result->structured 取得。

程式碼範例 — 正式環境

先預檢 sidecar、落實宣告的風險姿態，再執行批次合規檢查：

<?php

declare(strict_types=1);

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

use NextPDF\Enterprise\Mcp\BatchComplianceCheckTool;
use NextPDF\Enterprise\Mcp\SpectrumClientFactory;
use NextPDF\Server\Document\InMemoryDocumentStore;

// 1. Fail fast on sidecar misconfiguration before accepting agent traffic.
//    The factory validates SPECTRUM_URL and rejects private/reserved targets.
try {
    SpectrumClientFactory::create();
} catch (InvalidArgumentException $e) {
    fwrite(STDERR, 'Spectrum sidecar rejected: ' . $e->getMessage() . PHP_EOL);
    exit(1);
}

$tool = new BatchComplianceCheckTool();
$risk = $tool->riskLevel();

// 2. Enforce the declared risk posture before execution.
if ($risk->requiresHumanConfirmation()) {
    // Route to your approval queue instead of executing.
    exit(0);
}

if ($risk->requiresAuditLog()) {
    error_log(sprintf('[mcp-audit] tool=%s risk=%s', $tool->name(), $risk->label()));
}

// 3. Execute the batch.
$result = $tool->execute(
    [
        'workspace_token' => (string) getenv('SPECTRUM_WORKSPACE_TOKEN'),
        'documents'       => [
            ['id' => 'contract-001', 'path' => '/var/pdf-inbox/contract-001.pdf'],
            ['id' => 'contract-002', 'path' => '/var/pdf-inbox/contract-002.pdf'],
        ],
        'policies'        => ['pdfa', 'pades'],
    ],
    new InMemoryDocumentStore(),
);

echo $result->content[0]['text'] . PHP_EOL;

預期輸出（數量反映你的文件）：

Batch compliance check complete: 1 compliant, 1 non-compliant

邊界情況與陷阱

檔案系統 source 路徑預設停用。 若未設定 NEXTPDF_MCP_INPUT_DIR 環境變數，路徑形狀的 source 會被拒並回傳錯誤結果。改用 document_id、data: URI 或原始 base64。
原始 base64 僅在超過 256 個字元時才被辨識。 較短的 base64 區塊會被當作檔案路徑而遭拒。請將小型酬載包進 data:application/pdf;base64, URI。
未知的 document_id 值會伴隨指引而失敗。 錯誤文字為 Unknown document_id: ... Call create_pdf first.。記憶體內儲存中的文件也會依儲存的 TTL 到期，因此陳舊的 ID 會以相同方式失敗。
compliance_check 會拒絕未知的政策鍵，並在錯誤訊息中列出支援的集合。
批次與 RAG 工具需要 sidecar。 batch_compliance_check、batch_forensic_analyze、embed_documents 與 search_documents 需要可連線的 Spectrum 端點與 workspace_token。工廠每個行程快取一個用戶端；測試中請呼叫 SpectrumClientFactory::reset()。
search_documents 會將 top_k 夾限在 1–100；非整數值會退回伺服器預設值 10。
ast_aware_chunk 的預設值為每塊 1500 個字元、重疊 150 個字元。
certify_ai_ready 會略去戳記後的位元組，當 return_stamped_pdf 為 false 或裁決為 not_certified 時。若有回傳，base64 酬載約比 PDF 本身大三分之一。
預設的 AST 稽核軌跡為記憶體內。 透過內建 provider 接線所記錄的條目不會跨行程持久化；請注入持久化的 AstAuditTrailInterface 實作以取得耐久的稽核軌跡。

安全性須知

Fail-closed 的來源解析。 MCP 呼叫端完全掌控工具引數，因此解析器將其視為敵意。串流包裝器（phar://、php://、file:// 及任何 scheme）與 null 位元組會在任何檔案系統呼叫之前被拒。路徑穿越會被拒。原始檔案路徑僅在設定 NEXTPDF_MCP_INPUT_DIR 時才有效，且經 realpath 正規化的目標必須嚴格解析在該目錄內，並以分隔符邊界比對以阻擋前綴混淆逃逸。
對 sidecar 端點的 SSRF 防護。 SpectrumClientFactory 允許 localhost 用於本機 sidecar 模式，並針對私有、保留、link-local 與 cloud-metadata 範圍驗證其他每個 SPECTRUM_URL，遇到被封鎖的位址即拋出 InvalidArgumentException。這是對所設定端點的設定期閘門，而非網路層控制——出口政策、重導向處理與 DNS 釘選仍應留在主機環境中。
祕密留在環境中。 sidecar bearer token（SPECTRUM_AUTH_TOKEN）與 HMAC 簽署祕密（SPECTRUM_APP_SECRET）從環境變數讀取，絕不出現在工具酬載或結果中。
非反射式錯誤。 路徑拒絕訊息刻意通用（Source path is not permitted.），因此探測性的呼叫端無從得知主機檔案系統的任何資訊。
風險覆寫只能向上。 操作者設定可提高工具宣告的風險等級，但絕不能將其降到工具自身宣告之下。

符合性

支援不等於符合性，符合性不等於認證。NextPDF 不持有任何認證，也不授予任何認證。合規工具依具名政策設定檔檢查文件結構並報告帶條款參照的發現項；compliance_check 報告另附引擎自身的免責聲明，表明它是供參考的技術結構檢查，而非法律意見或合規背書。ai_ready_certify 與 certify_ai_ready 裁決為產品定義的就緒等級，而非任何標準機構的證明。MCP 是由其廠商管理者發布的開放協定，而非 SDO 標準；本頁記錄 NextPDF 的實作行為，不作任何獨立的協定符合性或認證主張。

行為合約

工具失敗以錯誤結果回傳（isError = true 並附訊息）；例外絕不跨越 MCP 邊界。
成功結果攜帶一行人類可讀摘要，加上一份結構化 JSON 酬載，每項工具皆有穩定、已記錄的欄位集。
每項工具都回報 tier() = ToolTier::Enterprise 與一個宣告的 RiskLevel；風險無法在執行期降低。
唯讀工具宣告 readOnlyHint: true，且不修改文件儲存、來源 PDF 或任何集合。
certify_ai_ready 絕不就地變更輸入文件；戳記套用於回傳的副本。
合規與 LTV 報告包含驗證時間戳與依嚴重度分類的發現項數量；compliance_check 酬載另包含引擎的法律免責聲明字串。

Core 後備方案

MCP 主機本身不需要 Enterprise。NextPDF Connect（nextpdf/server，Apache-2.0）可搭配開放的 Core 引擎執行，並提供其 core 級工具目錄：文件建立、文字與內容操作，以及擷取。請見工具目錄。單靠 Core 不提供合規政策檢查、鑑識分析、LTV 健康檢查、AI 就緒戳記、AST 感知分塊、變異稽核軌跡，或批次與 RAG 工具；那十一項工具僅在安裝並授權 nextpdf/enterprise 時才會註冊。

發布邊界

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