NextPDF Connect 工具目录

快速概览

一个 NextPDF Connect 部署公开的工具数量并不是固定常数。服务器会在运行时，根据已安装的包、配置的允许清单以及一组环境 gate 计算出这个数量。本页说明经验证的核心工具集，以及决定工具总数的方法。

安装

composer require nextpdf/server

概念总览

NextPDF\Server\ToolRegistry 会在启动时按以下顺序构建目录：

核心层。 一组固定的核心工具会无条件注册。另外两个工具只会在前置条件成立时注册。
Pro 层。 Pro 工具会在 Pro 提供者类 resolve（解析）成功时注册，这发生在已安装 nextpdf/premium 时。当该类无法解析时，服务器会静默跳过这一步。
Enterprise 层。 Enterprise 提供者遵循与 Pro 提供者相同的模式。
随附的扩展层。 AST 与 mutation 工具提供者随服务器包一起提供，并注册在 Pro 层之下。每个提供者都由一个环境 gate 控制；当底层核心支持不存在时，也都会优雅降级。
安全策略过滤。 服务器会将每一次注册与 enabled_tools 允许清单取交集。非空允许清单会剔除所有不在其中的工具。层级计数器只统计策略允许的工具。

MCP 的 initialize 响应会报告运行中服务器最终的 tool_count 与各层级计数。该值才是权威数字。请将文字叙述中的任何固定总数都视为过时信息。

API 接口

经验证且始终可用的核心工具

这十二个工具会无条件注册到核心层。服务器会从工具实现中读取各自的风险层级与 MCP 行为提示。

工具名称	类别	说明	风险
`create_pdf`	文档	创建一份新的 PDF 文档并返回一个 `document_id`	谨慎
`add_text`	文档	向 PDF 文档添加文字内容	谨慎
`add_image`	文档	从文件路径或 base64 数据添加图像	谨慎
`add_table`	文档	向 PDF 文档添加 HTML 表格	谨慎
`set_font`	文档	为后续文字操作设置字体	谨慎
`add_page`	文档	在 PDF 文档中添加一页	谨慎
`output_pdf`	文档	将 PDF 最终输出为文件或 base64	需要核准
`preview_layout`	文档	不执行渲染，仅返回版面的 JSON 摘要	安全
`diagnostic.doctor`	诊断	执行健康检查；返回结构化的环境诊断	安全
`diagnostic.capabilities`	诊断	列出各项能力及其层级与状态	安全
`diagnostic.inspect`	诊断	检查 PDF 并返回结构元数据	安全
`diagnostic.verify`	诊断	验证 PDF 完整性；可选执行 PDF/A 或 PDF/UA 检查	谨慎

有条件注册的核心工具

工具名称	条件
`generate_barcode`	注册条件：已安装的 `nextpdf/core` 中存在核心 barcode 编码器注册表
`parse_pdf`	注册条件：`NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED` 为 `true` 或 `1`

output_pdf 是唯一一个处于 approval_required 风险层级的核心工具。写入文件会经过 human-in-the-loop（人工干预）gate；base64 输出模式则不会。参见 /connect/hitl-risk-tiers/.

仅在安装额外包时加入的工具

服务器会用 class_exists() 探测提供者类：

Pro 工具 会在已安装 nextpdf/premium 且 Pro 提供者解析成功时注册。
Enterprise 工具 会在已安装 nextpdf/premium 且 Enterprise 提供者解析成功时注册。隐私工具（编修、去标识化、区域涂黑）封装了 Enterprise 类。它们只在这些类可自动加载时，才注册在 Enterprise 层之下。
AST 与 mutation 工具 随服务器一起提供，并注册在 Pro 层之下。NEXTPDF_AST_TOOLS_ENABLED 与 NEXTPDF_MUTATION_TOOLS_ENABLED 这两个 gate 控制它们，且两个 gate 默认均为启用。

确切的 Pro 与 Enterprise 工具清单由 Premium 包定义，而不是服务器定义；这些清单随该包的说明文档提供。服务器的契约是这套注册机制，而不是一份固定的 Premium 清单。

代码示例 — 快速上手

无需启动服务器，直接打印这个安装所公开的工具：

./vendor/bin/generate-skills --dry-run --list-tools

代码示例 — 正式环境

通过 MCP 向运行中的服务器查询权威数量：

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"c","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
EOF

服务器会为运行中的进程计算 initialize 结果中的 capabilities.nextpdf.tool_count 与 tiers。通过 REST，GET /api/v1/capabilities 会返回等效的内省信息。

边界情况与陷阱

没有固定的「33 个工具」——也没有任何固定的总数。 旧数据引用过单一数字，但那并不是契约。这个数量会随已安装的包、enabled_tools 允许清单，以及 parse_pdf、AST 与 mutation 的环境 gate 而变动。请一律从运行中的服务器读取它。
允许清单只做减法，永不增加。 即使把某个 Pro 工具列入 enabled_tools，只要缺少 nextpdf/premium，也不会注册它。
缺少某个层级是静默且预期的行为。 纯开源安装只提供核心集，并报告零个 Pro 工具与零个 Enterprise 工具。这个结果表示系统正常运行，并非故障。
目录中的层级是一项声明式不变量。 每个工具都在代码中声明自己的层级与风险。注册表绝不会根据 namespace 或封装方式推断层级。

性能

注册表扫描与层级检测只会在启动时执行一次。performance_budget 页面会限定它们的上限。每个工具的成本来自底层引擎操作，而不是目录查询；目录查询以工具名称为键，复杂度为 O(1)。

安全性说明

把 enabled_tools 当成最小权限控制：只公开某个集成真正需要的工具。目录绝不会纳入被安全策略拒绝的工具，层级计数器也只反映被允许的工具。无论是否列于目录中，高风险工具仍然受人工确认把关。参见 /connect/security-and-operations/.

一致性

本页说明注册表机制。tools/list 与 initialize 接口的协议引用以 /transports/mcp/ 为准。风险模型则由 /connect/hitl-risk-tiers/ 规范。

商业背景

核心目录已经足以支持创建、检查与诊断。签章、编修、合规与取证工具只会在 nextpdf/premium 与服务器一同安装时出现。这是一条封装边界，会在 composer require 时应用，绝不是运行时提示。

另请参阅

/connect/hitl-risk-tiers/ —— 风险字段的含义及其执行方式
/connect/boot-and-discovery/ —— 完整的启动与探索流程
/connect/configuration/ —— enabled_tools 与环境 gate
/transports/mcp/ —— tools/list 与 initialize 的传输格式
/connect/overview/ —— 为什么此目录在设计上就取决于运行时