MCP — 深度参考

概览

NextPDF\Enterprise\Mcp 命名空间提供 NextPDF MCP 工具目录的 Enterprise 层。其公共面为十一个工具类、一个 client factory 和一个类型化异常。每个工具都实现来自 nextpdf/server 运行时的 NextPDF\Server\Tools\ToolInterface 契约，并声明 ToolTier::Enterprise。六个工具在进程内分析单个 PDF。四个工具通过 NextPDF\Enterprise\Mcp\SpectrumClientFactory 将批处理和 RAG 工作负载委派给 Spectrum sidecar。一个工具读取构造函数注入的 AST 变更审计轨迹，而非 PDF 字节。每个工具都自描述其 MCP 名称、JSON Schema 输入、client annotations、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 进行批量取证分析	带每文档 status、成功与失败计数的 ToolResult	错误 ToolResult（参数缺失、sidecar 失败）	工具 batch_forensic_analyze；RiskLevel::Safe；类别 document；自 2.1.0
ComplianceCheckTool::execute	参数：policy（12 值枚举）、document_id 或 source	针对一个具名合规策略评估该 PDF	带 findings、pass/fail、duration_ms 和一个 disclaimer 字段的 ToolResult	错误 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 健康度策略	带 findings 和 pass/fail 的 ToolResult	错误 ToolResult	工具 ltv_health_check；RiskLevel::Safe；类别 document；自 2.0.0
AiReadyCertifyTool::execute	参数：document_id 或 source	基于四条准则的只读 AI 就绪评估	带 certification_level（certified、partial、not_certified）和逐准则布尔值的 ToolResult	错误 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 并发出带溯源的引用锚定分块	带 chunk_count 及每块 node ID、页索引、bbox、node type 的 ToolResult	错误 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 变更事件	带 entries[] 和 count 的 ToolResult	参数缺失或为空时返回错误 ToolResult	工具 audit_ast_mutations；RiskLevel::Review；类别 document；自 3.0.0
EmbedDocumentsTool::execute	参数：collection_id、workspace_token、documents[]（均必填）	通过 Spectrum sidecar 将 PDF 摄取进一个 RAG collection	带成功/总数/失败计数的 ToolResult	错误 ToolResult	工具 embed_documents；RiskLevel::Caution；非只读、非幂等；类别 extraction；自 2.1.0
SearchDocumentsTool::execute	参数：collection_id、query（必填）、top_k（默认 10，钳制于 1–100）、mode（hybrid、bm25、semantic）	对已摄取的 collection 进行混合检索	带排序分块和相关性分数的 ToolResult	错误 ToolResult；不在白名单内的 mode 会被拒绝	工具 search_documents；RiskLevel::Safe；类别 extraction；自 2.1.0
SpectrumClientFactory::create	无（读取 SPECTRUM_URL、SPECTRUM_TIMEOUT、SPECTRUM_AUTH_TOKEN、SPECTRUM_APP_SECRET）	构建并缓存一个进程范围内的 sidecar client	SpectrumClient	当 SPECTRUM_URL 格式错误或指向被阻止地址时抛出 InvalidArgumentException	默认端点 http://127.0.0.1:7800；超时 30.0 秒；自 2.1.0
SpectrumClientFactory::reset	无	清除已缓存的 client 实例	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）	将现有 resource 包装为流	StreamInterface	—	PSR-17 StreamFactoryInterface 实现
McpStreamException	—	类型化的流获取失败	—	—	final class，继承自 RuntimeException；源码记载 PSR-17 §1.5 兼容性；源码将其标注为 @since 3.2.0（存在于当前 3.1.0 别名的 dev 线中）

每个工具还暴露 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 中的空字节，都会在任何文件系统调用之前被拒绝。目录穿越和符号链接逃逸会在真实路径限制检查下失败。
• Sidecar 支撑的工具（embed_documents、search_documents、batch_compliance_check、batch_forensic_analyze）从 SpectrumClientFactory::create 获取其 client。工厂在使用前会针对私有和保留地址范围校验非本地的 SPECTRUM_URL。显式的 localhost 被允许，用于本地 sidecar 模式。
• ai_ready_certify 从四条准则推导其级别：取证完整性、签名存在性、LTV 有效性和无加密。四条全部通过得出 certified；一到三条得出 partial；零条得出 not_certified。取证完整性是对修订链的结构性启发式判断，而非加密字节完整性验证。加密检查仅检视 trailer 区域。
• certify_ai_ready 评估三条准则并追加一枚 XMP 溯源戳记。戳记后的字节以 base64 编码返回，除非 return_stamped_pdf 为 false 或级别为 not_certified。
• 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。
• 文件系统 source 但 NEXTPDF_MCP_INPUT_DIR 未设置：被拒绝，附带一条指明受支持通道的消息。
• source 路径解析到配置的输入目录之外，包括经由符号链接：被拒绝。比较发生在目录分隔符边界上，因此共享名称前缀的同级目录无法通过。
• data: URI 缺少逗号分隔符，或 base64 载荷无效：返回错误结果。
• search_documents 的 top_k 超出 1–100：钳制而非拒绝。非整数 top_k 回退到配置的 pipeline 默认值。
• search_documents 的 mode 超出 hybrid、bm25、semantic：来自 pipeline 白名单的错误结果。
• batch_compliance_check 的 documents[] 元素缺少 id 或 path，或携带空字符串：返回错误结果，指出出错的索引。batch_forensic_analyze 仅校验外层数组形状；元素缺陷从批处理层浮现。
• SpectrumClientFactory::create 遇到格式错误的 SPECTRUM_URL，或指向私有、链路本地或元数据地址的 URL：抛出 InvalidArgumentException。在工具 execute 内部这会浮现为一个错误结果。
• SpectrumClientFactory::createStreamFromFile 遇到不可读路径：抛出 McpStreamException。
• 空的环境变量被视为未设置并回退到默认值。

符合性

NextPDF 不持有任何认证，也不授予任何认证。MCP 工具报告的是能力级评估；支持不等于符合，符合不等于认证。ai_ready_certify 和 certify_ai_ready 返回的 certification_level 值是这些工具自有的报告词汇。它们不构成第三方证明。compliance_check 响应包含一个 disclaimer 字段，出于同样原因由底层报告生成。策略条款引用——例如产品源码声明为 ISO 32000-2:2020 §12.8.4.3 的 LTV 策略依据——承载于工具描述和逐 finding 的 clause 字段中；本页不添加任何独立的标准主张。被检查的文档是否满足某项法规，由运营方及其评估者裁定。

开发说明

• SpectrumClientFactory::create 按进程缓存一个 client。在测试 setup 中调用 SpectrumClientFactory::reset 以强制获取新的 client。
• 环境读取依次查询 $_ENV、$_SERVER、getenv，并将空字符串视为缺失。
• RiskLevel 驱动 server 运行时中的主机侧处理：Safe 自动执行，Caution 及以上被审计记录，ApprovalRequired 要求人工确认。没有任何 Enterprise MCP 工具声明 ApprovalRequired。运营方覆盖可以提升已声明的级别，但绝不能降低。
• annotations 值（readOnlyHint、idempotentHint）是 MCP client 提示，而非强制。无论提示如何，限制和校验都在 server 侧发生。
• 工具报告 category 值 document 或 extraction，供 tools/list 过滤。
• AuditAstMutationsTool 是唯一需要构造函数注入的工具；请以一个具体的 AstAuditTrailInterface 实现来注册它。

另请参阅

• MCP（能力页）
• Accelerator — 深度参考 — Spectrum sidecar client 接口面。
• Forensics — 深度参考 — forensic_analyze 背后的分析器。
• Compliance — 深度参考 — compliance_check 背后的策略。
• AST — 深度参考 — 分块与变更审计轨迹。
• Validation — 深度参考

发布边界

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