Pro 版本

MCP Tools — 深度参考

可用性与授权

此能力随 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，再将 source 作为一个 data: URI、文件系统路径或原始 base64。缺失输入会返回一个校验错误，而不是处理一个空文档。
sign_pdf 仅生成一个 PAdES B-B 基线签名——没有时间戳，没有长期验证。受支持的算法以及 AES-GCM 密钥传输信封详见下文；解密失败即关闭，且该工具绝不会将密文用作密钥材料。
完整的发现、风险、来源解析、逐工具与签名细节见下文各节。本页仅描述外部可观察的行为与已发布的工具契约。

范围

本页是这八个 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 —— 产生可能被滥用的输出。自动执行，但 agent skill 指令会对其加以标记，以便 agent 向用户发出警告。
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 会失败并附一个明确的错误，指示调用方先创建该文档。
source 作为一个 data: URI —— 工具解码逗号之后的 base64 主体。
source 作为一个文件系统路径 —— 当路径解析到一个文件时，工具从磁盘读取。
source 作为一个原始 base64 字符串 —— 工具仅接受并解码足够长、呈 base64 形态的输入。

compare_pdfs 会对 source_a 与 source_b 各自独立地应用同一套解析，并额外地接受任一来源槽中的一个 document_id 值。如果既未提供 document_id 也未提供 source，工具会返回一个校验错误，而不是处理一个空文档。

逐工具参考

工具	风险	输入	结果字段	行为边界
`extract_text`	safe	PDF；可选的 1 起索引 `page_start` / `page_end`	文本、总页数	仅文本层；范围被钳制到真实页数；无 OCR
`segment_document`	safe	PDF	分段计数、分段列表	由布局推导出的分段；不是带标签 PDF 的结构树
`compare_pdfs`	safe	两个 PDF	identical 标志、总变更数、逐文档页数、区域（类型、文本、页索引、行索引、可选的对应方文本）	文本内容比对；不是可视或二进制比对
`redact_pii`	review	PDF；可选的 `types`（`email`、`phone`、`ssn`、`credit_card`）	has-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 认证标签。

解密失败即关闭：认证标签不匹配或有效载荷格式错误会返回一个解密错误，且工具绝不会将密文用作密钥材料。工具会在任何密码学工作之前拒绝错误的密钥或 nonce 尺寸。

边界情形与 FIPS 模式

extract_text：工具会钳制超出文档的页面范围末端，而不是拒绝它，并把低于第一页的起始位置归一化到第一页。
compare_pdfs：缺失 source_a 或 source_b 会返回一个校验错误；相同的文档会返回一个明确的 identical 结果，变更数为零。
extract_form_data：没有嵌入 XFDF 流的 PDF 会返回一个零字段结果并附一条说明，而不是一个错误。
redact_pii：types 中未识别的条目会被忽略；一个全部未识别的列表会产生一次空扫描，而不是一次失败。
sign_pdf：缺失证书或私钥会在任何签名工作之前失败；工具会在签名时检查算法要求（SHA-3 的 OpenSSL 支持、Ed25519 的 libsodium），并将其作为明确的错误呈现。
FIPS 模式：算法可用性遵循宿主的 OpenSSL/libsodium 构建。在受 FIPS 约束的构建中，未获批准的算法会在密码学边界处失败并附一个明确的错误，而不是静默降级。MCP 层不会添加或放松密码学策略——它呈现的是宿主密码学提供者的决定。

运营方 runbook 注记

让 sign_pdf 保持 approval-required。确认没有任何运营方覆盖无意中提高了 safe 工具上的风险——覆盖只会收紧，因此一个意外的覆盖会降低可用性，而非安全性。
审计留存：服务器会对每一次在 review 等级及以上的执行进行审计日志记录。请按 redact_pii、fill_form 与 sign_pdf 调用的量级来规划你的日志留存。
传输选择：当运行在一个并非端到端机密的传输通道上时，请为 sign_pdf 要求使用 AES-GCM 密钥传输信封，并在你的 agent 工具调用日志策略中将私钥材料视为机密。
层级计数：使用服务器的逐层级计数，在部署时断言 Pro 层级注册了八个工具；计数为零表明 Pro 包未解析成功。

版本边界

Pro 层级恰好贡献八个 MCP 工具。Enterprise 版本附带一个独立的 MCP 层级，带有自己的工具——合规、取证、长期验证健康、AI-ready 认证，以及文档搜索/嵌入。Enterprise 工具的输入、输出与内部实现不在此处范围内，并随 Enterprise 版本一同记录。服务器独立地发现各层级；缺失的某个层级绝不会禁用另一个。

发布边界

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