Enterprise 版本

MCP 工具

概览

NextPDF Enterprise 为 NextPDF Connect 服务器新增十一个 MCP 工具。它们让 AI 助手与 agent 框架以类型化方式直接访问 Enterprise 引擎：合规策略检查、PDF 取证、LTV 健康检查、AI-readiness 盖章、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（审查）	是
`batch_compliance_check`	`BatchComplianceCheckTool`	在一次 Spectrum sidecar 批处理中根据 `pdfa`、`pades` 或 `zugferd` 策略检查多个 PDF。	Safe（安全）	是
`forensic_analyze`	`ForensicAnalyzeTool`	报告修订历史、增量更新与修改事件，用于篡改检测。	Safe（安全）	是
`batch_forensic_analyze`	`BatchForensicAnalyzeTool`	在一次 sidecar 批处理中对多个 PDF 运行取证分析。	Safe（安全）	是
`ltv_health_check`	`LtvHealthCheckTool`	检查已签名 PDF 的长期验证材料：DSS 字典、OCSP 响应、CRL 条目、VRI 条目与证书存储。	Safe（安全）	是
`ai_ready_certify`	`AiReadyCertifyTool`	只读的、产品定义的 AI-readiness 判定，基于四项标准：取证完整性、签名存在、LTV 有效性、无加密。	Review（审查）	是
`certify_ai_ready`	`CertifyAiReadyTool`	产品定义的就绪判定，基于三项标准（即只读工具四项中去掉取证完整性——这是设计使然，因为该工具会重写它所盖章的文件），并追加一个 XMP 溯源盖章；以 base64 返回已盖章的 PDF。	Review（审查）	否
`ast_aware_chunk`	`AstAwareChunkTool`	沿标题边界将 PDF 拆分为带引用锚点的分块，每个分块附带节点 ID、页索引与边界框。	Review（审查）	是
`audit_ast_mutations`	`AuditAstMutationsTool`	按 SHA-256 源哈希检索文档的 AST 变更审计轨迹。	Review（审查）	是
`embed_documents`	`EmbedDocumentsTool`	将 PDF 摄取到 RAG 集合中：解析、分块、嵌入、索引。会修改集合状态。	Caution（谨慎）	否
`search_documents`	`SearchDocumentsTool`	对已摄取的集合进行混合检索（BM25 关键词加语义），返回已排名、带评分的分块。	Safe（安全）	是

“certify”工具会给出一个产品定义的就绪判定（certified、partial 或 not_certified）。该判定是一项技术检查结果，而非任何认证机构的认证。

审批门控与审计态势

每个工具都从 Connect 的四级模型中声明一个风险级别。Safe 工具自动执行。Caution 工具自动执行并写入一条审计日志。Review 工具会为调用方 agent 的指令附带一条警告。ApprovalRequired 工具要求人工确认；目前没有任何 Enterprise MCP 工具声明此级别，因为没有一个是破坏性的。运行时配置只能提高工具的风险级别，绝不能降低。工具还发布 MCP 行为注解（readOnlyHint、idempotentHint），因此合规的客户端可以在其之上施加自己的门控。完整模型参见 HITL 风险层级。

为什么这样设计

承重的设计决定是：工具是薄的、确定性的封装，并自我声明治理——每个工具将自身的风险级别与层级作为领域不变量陈述，绝不从命名空间或打包方式推断。这让门控决策在主机端可审计，而无需信任传输层。工具本身不含任何文档智能；它们委托给你的代码调用的同一批 Enterprise API，因此只有一种行为要测试、一个判定值得信任。错误在 MCP 错误通道上返回，而非以异常逃逸，因为 agent 无法捕获 PHP 异常，却始终可以基于 isError 分支。可能触及文件系统的输入默认按失败关闭处理，因为 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 并返回 isError = true 的 ToolResult::error()。无效参数（缺少 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 请求与流工厂：

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 实现以获得持久的审计轨迹。

安全说明

失败关闭的 source 解析。 MCP 调用方完全控制工具参数，因此解析器将其视为敌意输入。流包装器（phar://、php://、file:// 及任何 scheme）与空字节会在任何文件系统调用之前被拒绝。路径遍历会被拒绝。原始文件路径仅在设置了 NEXTPDF_MCP_INPUT_DIR 时可用，且经 realpath 规范化的目标必须严格解析到该目录之内，并在分隔符边界上比较，以阻止前缀混淆逃逸。
sidecar 端点的 SSRF 防护。 SpectrumClientFactory 在本地 sidecar 模式下允许 localhost，并对其他每个 SPECTRUM_URL 校验私有、保留、链路本地与云元数据地址段，在被阻止的地址上抛出 InvalidArgumentException。这是对所配置端点的配置期门控，而非网络层控制——请在主机环境中保留出站策略、重定向处理与 DNS 固定。
密钥留在环境中。 sidecar 承载令牌（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-readiness 盖章、AST 感知分块、变更审计轨迹或批量与 RAG 工具；那十一个工具只有在安装并授权 nextpdf/enterprise 后才会注册。

发布边界

本页仅记录外部可观察的行为与受支持的公共 API 表面。内部命名空间路径、辅助类、机制表、runbook 文件名与工单前缀不在范围内。