Pro 版本

MCP 工具

速览

NextPDF Pro 增加了八个模型上下文协议（MCP）工具，让 AI 代理能够通过 NextPDF Server 运行高级 PDF 操作。当 nextpdf/pro 和 nextpdf/server 都已安装时，这些工具会自动浮现 —— 无需单独的注册步骤。

可用性与授权

此能力随 NextPDF Pro（nextpdf/pro）发行，并通过一份 Pro 层级授权封套激活。没有该授权的部署不会加载此能力的类。比较各版本并获取授权。

基础 MCP 接口面 —— 文档创建、文本、表格、诊断 —— 随开源的 NextPDF Server 发行，无需授权。本页面上的这八个工具需要一份 Pro 授权，且仅在 nextpdf/pro 包于启动时解析成功时才注册。pro 工具层级为整套工具把关：每个工具都显式声明其层级，没有逐工具标记 —— 将 nextpdf/pro 与 nextpdf/server 一同安装即可启用整套工具。

行为契约

当 nextpdf/pro 和 nextpdf/server 在启动时都解析成功，这八个 Pro MCP 工具会在 pro 层级下，通过标准的 MCP tools/list 与 tools/call 流程自动注册。没有逐工具标记，消费端应用程序也无需任何代码改动。
每个工具接受一个 PDF：来自更早 create_pdf 调用的 document_id、一个内联的 source（文件路径、base64 或 data: URI），或者 —— 对于 compare_pdfs —— 两个这样的来源。工具返回结构化 JSON。
每个工具都声明一个由服务器强制执行的 HITL 风险等级：safe（自动执行、只读）、review（可能被滥用的输出）以及 approval-required。sign_pdf 是 approval-required，会被一直挂起，直到有人确认。运营方只能收紧一个工具的风险等级，绝不能放松。
sign_pdf 仅产出一个 PAdES B-B（基线）签名 —— 没有受信任时间戳，也没有长期验证材料。长期（B-LT/B-LTA）的 profile、硬件密钥保管，以及审计追踪签名属于 Enterprise 层级，这些工具并不提供；B-T（带时间戳的签名）在配置了时间戳提供方时可由 Core 引擎提供。
redact_pii 执行的是文本层级的模式检测与遮罩，而非视觉遮蔽；check_accessibility 是一个结构性启发式，而非 PDF/UA 或 WCAG 符合性判定。权威的输入/输出 schema 是服务器实时的 tools/list 响应，而非本页面。

概念概述

NextPDF Server 是 NextPDF 的确定性 MCP 执行层。它在启动时使用一次类存在性探测来发现工具提供方，因此 Pro 包不需要被列入服务器的依赖中。当 Pro 包存在时，服务器会在 pro 层级下注册其八个工具，并在你所配置的任意传输之上，通过标准的 MCP tools/list 与 tools/call 流程暴露它们。

每个 Pro 工具从三种来源之一接受一个 PDF：由更早 create_pdf 调用返回的 document_id、一个内联的 source（文件路径、base64 字符串或 data: URI），或者 —— 对于比较工具 —— 两个这样的来源。工具返回结构化的 JSON 结果：提取出的文本、diff 区域、被遮罩的文本、片段树、无障碍发现项，或一个已签名的 PDF。

每个 Pro 工具都携带一个风险分类，服务器用它进行人在环（HITL）强制执行。只读分析工具被评定为 safe 并自动执行。生成调用方可能滥用之输出的工具被评定为 review。签名工具被评定为 approval-required，因此服务器会将其挂起，直到有人确认。工具本身声明此分类；运营方在运行时只能收紧它 —— 绝不能放松。

MCP 工具接口面有意与 Pro PDF 引擎分离。这些工具是薄适配器：它们校验输入、解析 PDF、委派给某个 Pro 引擎组件，并序列化结果。它们不是引擎的第二套 API，也不是 Pro 公共 PHP API 的一部分 —— 受支持的集成点是 NextPDF Server 所暴露的 MCP 协议。

工具目录（八个 Pro 工具）

这八个 Pro MCP 工具，按 MCP 协议名称列出。风险等级遵循服务器的 HITL 模型：safe（自动执行、只读）、review（生成可能被滥用的输出；会在代理指令中给出警告），以及 approval-required（必须由人确认）。

`extract_text`

用途： 文本提取。提取一个 PDF 的文本层，可选地限定到一个从 1 起算的页码范围。
输入： 一个 PDF（document_id 或 source）；可选的 page_start 与 page_end。
输出： 提取出的文本以及总页数。
风险： Safe。只读且幂等。
边界： 提取现有的文本层。它不会对扫描页或纯图像页执行 OCR。

`segment_document`

用途： 结构化分段。将一个 PDF 切分为逻辑章节 —— 标题、各级标题、正文、表格、图。
输入： 一个 PDF（document_id 或 source）。
输出： 一个片段计数以及一个结构化的片段列表。
风险： Safe。只读且幂等。
边界： 基于版面分析的结构化分段；它不是语义大纲，也不是 tagged-PDF 结构树。

`compare_pdfs`

用途： 结构化 diff。比较两个 PDF 并返回其文本内容的结构化 diff。
输入： 两个 PDF（source_a 与 source_b，每个可以是路径、base64、data URI 或 document_id）。
输出： 一个 identical 标记、总变更计数、各文档的页数，以及一个带页码与行索引的变更区域列表。
风险： Safe。只读且幂等。
边界： 文本内容 diff。它不会对视觉渲染、内嵌字体或二进制结构做 diff。

`redact_pii`

用途： PII 检测与遮罩。检测一个 PDF 文本层中的个人可识别信息，并返回该文本的遮罩视图。
输入： 一个 PDF（document_id 或 source）；可选的 types 过滤器（email、phone、ssn、credit_card）。
输出： 一个 has-PII 标记、检测到的数量、被遮罩的文本，以及所扫描的类型列表。
风险： Review。若把被遮罩的输出当作一份已净化的文档，它可能被滥用。
边界： 这是文本层级的模式检测与遮罩，而非视觉遮蔽。它不会移除或覆盖已渲染 PDF 中的字形，且模式匹配并不保证敏感数据的每一处实例都被找到。请勿将其输出视为 PII 已完全移除的保证。若需要销毁底层内容的文档级遮蔽，请使用开源服务器工具或 Enterprise 版本中专门的遮蔽接口。

`fill_form`

用途： AcroForm 填充数据。生成 XFDF（ISO 19444-1）数据，从一个字段名到值的映射来填充 PDF AcroForm 字段。
输入： 一个字段名到字符串值的 fields 映射；可选的 pdf_filename，会作为 XFDF 引用内嵌。
输出： 生成的 XFDF 文档以及字段计数。
风险： Review。它产出旨在应用到文档上的表单数据。
边界： 它产出符合标准的 XFDF；它本身并不会把这些值写回 PDF。请用任何符合标准的阅读器或处理工具来应用该 XFDF。

`extract_form_data`

用途： AcroForm 回读。从一个 PDF 中内嵌的 XFDF 提取 AcroForm 字段名与值。
输入： 一个 PDF（document_id 或 source）。
输出： 一个字段计数以及一个字段名到值的映射；当不存在内嵌表单数据时附带一条明确说明。
风险： Safe。只读且幂等。
边界： 读取内嵌的 XFDF（ISO 19444-1）流。一个仅在 AcroForm 对象中而无内嵌 XFDF 持有表单值的 PDF 会返回一个空结果。

`check_accessibility`

用途： 结构性无障碍分析。分析一个 PDF 的结构性无障碍 —— 各级标题、段落、表格与图像 —— 并报告可能的问题及 WCAG 引用。
输入： 一个 PDF（document_id 或 source）。
输出： 一个结构性评分（0–100）、一个问题列表，以及一个片段摘要。
风险： Safe。只读且幂等。
边界： 这是一个结构性启发式，而非一项符合性判定。完整的 PDF/UA 与 WCAG 符合性测试 —— 标签树、阅读顺序、色彩对比度 —— 需要一个专门的无障碍引擎。高分并不是一份关于 PDF/UA 符合性的声明。

`sign_pdf`

用途： PAdES B-B 数字签名。使用一个本地 X.509 证书与私钥，对一个 PDF 应用一个 PAdES B-B（基线）数字签名。
输入： 一个 PDF（document_id 或 source）；一个 PEM 证书与一个 PKCS#8 私钥；一个可选算法（默认 RSA-SHA256、RSA + SHA-3 256/384/512，或 Ed25519）；可选的签名者名称与原因；一个围绕私钥载荷的可选 AES-GCM 传输封套。
输出： 已签名的 PDF、签名计数、完成标记，以及所用的算法、OID 与摘要。
风险： Approval-required。签名是一项具有法律意义的破坏性操作；服务器在其运行之前要求明确的人工确认。
边界： 此工具产出一个 PAdES B-B（基线）签名 —— 它不会嵌入受信任时间戳或长期验证材料。长期（B-LT/B-LTA）的 profile、硬件支撑的密钥保管，以及审计追踪签名是 Enterprise 版本的一部分；B-T（带时间戳的签名）在配置了时间戳提供方时可由 Core 引擎提供。关于 Pro 包更广的签名能力，请参阅 Pro 签名接口面，关于 B-LT/B-LTA 请参阅 Enterprise 版本。

工具如何浮现

composer require nextpdf/pro
composer require nextpdf/server

两个包都安装后，用你选定的传输启动 NextPDF Server。服务器在启动时发现 Pro 层级，这八个工具便会与开源的 Core 工具一起，出现在 MCP tools/list 响应的 pro 层级下。你的应用程序无需任何代码改动 —— 发现是自动运行的，且某个缺失的层级绝不会阻止其他层级加载。

每个工具权威的输入与输出 schema，是服务器在其 tools/list 响应中发布的 schema。请将该响应 —— 而非本页面 —— 视为契约：本目录描述意图与边界；实时 schema 描述确切的字段名与类型。

代码示例 —— 快速上手

这些 Pro 工具通过 MCP 协议消费，而非通过某个 Pro PHP API。宿主端的集成就是启动 NextPDF Server。当 nextpdf/pro 存在时，这八个工具通过运行时发现注册 —— 无需逐工具接线 —— 宿主随后将它们提供给代理。

<?php

declare(strict_types=1);

use NextPDF\Server\Mcp\McpServer;

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

// Runtime discovery registers the Pro tier when nextpdf/pro is installed
// alongside nextpdf/server. The consuming application changes no code.
$server = McpServer::create();

// A Pro tool name resolves only when the Pro package is present.
$signTool = $server->getToolRegistry()->get('sign_pdf');

\fwrite(\STDERR, $signTool !== null
    ? "Pro MCP tools active.\n"
    : "Pro MCP tools unavailable; install nextpdf/pro.\n");

// Serve the MCP protocol over stdio (Claude Desktop, Cursor, local agents).
$server->run();

代码示例 —— 生产环境

加固启动路径。加载一份显式的策略文件，在遇到无效的风险等级覆写时拒绝启动，并在提供服务之前确认 Pro 层级已浮现。当 risk_level_overrides 块试图削弱一个如 sign_pdf 这样的 approval-required 工具时，McpServer::create() 中的接线会抛出 InvalidArgumentException，因此一份配置错误的策略会在服务循环之前失败即关闭。

<?php

declare(strict_types=1);

use NextPDF\Server\Mcp\McpServer;
use NextPDF\Server\Tools\ToolInterface;

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

// A downgrade of an approval-required tool's HITL gate is rejected at boot,
// never silently applied — the server refuses to start on such a policy.
try {
    $server = McpServer::create(__DIR__ . '/nextpdf-mcp.yaml');
} catch (\InvalidArgumentException $e) {
    \fwrite(\STDERR, 'Refusing to start: invalid MCP policy. ' . $e->getMessage() . "\n");
    exit(1);
}

// Confirm the Pro tier surfaced before advertising it to agents.
$signTool = $server->getToolRegistry()->get('sign_pdf');

if (!$signTool instanceof ToolInterface) {
    \fwrite(\STDERR, "nextpdf/pro is not resolving; Pro MCP tools are unavailable.\n");
    exit(1);
}

// sign_pdf is approval-required; the server holds it for human confirmation.
$risk = $signTool->riskLevel()->label();
\fwrite(\STDERR, "Pro MCP tools ready. sign_pdf risk: {$risk}.\n");

$server->run();

生产环境指引

HITL 把关。 让 sign_pdf 处于人工确认之后。服务器会依据该工具声明的风险等级强制执行这一点；不要把你的代理配置成绕过它。运营方只能收紧一个工具的风险等级，绝不能放松。
来源处理。 对于已在会话中的文档，优先使用 document_id。对于内联数据，这些工具接受 base64 与 data: URI；非常大的内联载荷比一个被引用的文档运行得更慢。
PII 预期。 显式地设定调用方预期：redact_pii 是一个检测与遮罩辅助手段，而非一项净化保证。若需要不可逆移除，请路由到一个专门的遮蔽接口。
签名密钥。 当传输并非端到端机密时，通过传输加密封套提供密钥。在你代理的工具调用日志策略中，把私钥材料当作机密处理。
审计日志。 高于 safe 等级的工具会被服务器审计记录。请确保你的部署按你的合规要求留存这些日志。

边界情况

extract_text 的页码范围从 1 起算，并被夹紧到文档真实的页数；一个超出范围的结尾不会报错。
compare_pdfs 需要两个来源；只传一个会返回一个清晰的校验错误，而非一个部分 diff。
对于没有内嵌 XFDF 的 PDF，extract_form_data 会返回一个已填充、明确的“无内嵌表单数据”结果，而非一个错误。
sign_pdf 会拒绝不支持的算法标识符并附上受支持值的列表；Ed25519 需要 libsodium 扩展，SHA-3 变体需要一个支持 SHA-3 的 OpenSSL 构建。
check_accessibility 在设计上会给纯图像 PDF 打低分 —— 它标记的是缺少可读文本层，而非失败。

安全说明

签名工具是唯一一个 approval-required 的工具；服务器不会自动执行它。
围绕私钥的可选 AES-GCM 封套对载荷进行身份验证；标签不匹配会失败即关闭并报一个解密错误，绝不会回退到使用密文。
redact_pii 不会更改源 PDF；它返回一个被遮罩的文本表示。它不能替代内容销毁。
该工具在任何引擎工作之前校验输入；它会以明确的错误拒绝格式不正确的来源、data URI 与 base64 载荷。

一致性

表单工具按 ISO 19444-1:2019（XML Forms Data Format）产出与消费 XFDF。
sign_pdf 产出一个与 ETSI EN 319 142 PAdES 家族对齐的 PAdES 基线（B-B）签名；长期的 profile 是一项 Enterprise 能力，而 B-T 在配置了时间戳提供方时可由 Core 引擎提供。
check_accessibility 以 WCAG 成功准则引用（例如 1.1.1、1.3.1、2.4.6）报告发现项，作为启发式指引，而非一份符合性证明。

版本边界

NextPDF Pro 恰好贡献八个 MCP 工具，全部在 pro 层级。Enterprise 版本在 enterprise 层级发行其自己的、独立的 MCP 工具集 —— 涵盖符合性检查、取证分析、长期验证健康度、AI 就绪认证，以及文档搜索与嵌入。那些工具、它们的输入及其内部细节不在本页面范围内；请参阅 Enterprise MCP 工具。服务器自身的文档涵盖随它发行的 Core（开源）工具。服务器独立发现这三个层级，且某个缺失的层级绝不会停用其他层级。

Enterprise 边界说明

Pro 恰好在 pro 层级贡献八个 MCP 工具。Enterprise 版本在 enterprise 层级发行一套独立的 MCP 工具集（符合性检查、取证分析、长期验证健康度、AI 就绪认证、文档搜索与嵌入）以及带时间戳/长期的签名 profile；这些都不由 Pro 层级提供。完整的层级拆分请参阅上文的版本边界一节。

Core 回退/替代方案

开源的 NextPDF Server 为任何 AI 代理提供一套确定性的 Core PDF 工具集（文档创建、文本、表格、诊断），无需授权。本页面上的八个高级工具是 Pro 新增能力。参阅 /connect/tools/。

发布边界

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