跳转到内容
NextPDF

NextPDF Connect 服务器概览

概览

标题为“概览”的章节

NextPDF Connect 即 nextpdf/server 包，是一个常驻服务，用来把 NextPDF PDF 2.0 引擎开放给 AI Agent（代理）与 HTTP 客户端使用。 它通过三种传输提供这些能力：在 stdio 之上的 Model Context Protocol（MCP）、一组 REST API，以及 gRPC。 这三种传输都位于同一个工具注册表（registry）与同一道 human-in-the-loop（HITL）确认 gate 之后。

安装

标题为“安装”的章节
Terminal window
composer require nextpdf/server

Composer 的版本约束为 nextpdf/core: ^3.0，同时要求 php: >=8.4 <9.0。 完整步骤请参阅 /connect/install/。 该页还介绍两个可选的附加组件：ext-redis 扩展，以及 nextpdf/premium 包。

概念概述

标题为“概念概述”的章节

nextpdf/server 把不依赖 Framework（框架）的 NextPDF 核心适配成一个服务接口。 它并未重新打造 PDF 生成功能，而是把引擎的每一项能力包装成带有自身结构描述（schema）的具名工具，再通过数种传输协议提供这份工具目录。

整个设计建立在三个概念之上：

  • 工具注册表。 NextPDF\Server\ToolRegistry 会在启动时发现并注册工具。 这个包自带一组核心工具，且始终可用。 Pro 与 Enterprise 提供者会注册更多工具，但只有在对应的包已安装时才会注册。 因此，对外开放的工具数量是部署在运行期决定的属性，并非固定常量。 请参阅 /connect/tool-catalog/。

  • 传输。 同一份注册表会以三种方式提供服务。 MCP 在 stdio 之上运行，供本机 AI 客户端使用。 REST 通过 RoadRunner worker 池上的一条 PSR-15 中间件（middleware）管线运行，供网络客户端使用。gRPC 则在 Spiral RoadRunner gRPC worker 之上运行，供类型化、可流式传输的客户端使用。 每种传输都有独立的进程和入口点。 请参阅 /transports/mcp/、/transports/rest/，以及 /transports/grpc/。

  • 确认 gate。 每个工具都会声明一个风险级别。 最高风险级别的工具在运行前，必须先取得明确的人工确认。 这道 gate 会签发一个单次使用的质询令牌（challenge token）。 代理（agent）必须把该令牌交给人工审核者，再携带该令牌重新调用该工具。 请参阅 /connect/hitl-risk-tiers/。

下面的图展示了一份注册表如何服务于三种传输。 它也标明了确认 gate 在请求路径中的位置。

NextPDF Connect component architectureOne tool registry is served over three transports, and high-risk tool calls pass through a single human-in-the-loop confirmation gate before reaching the engine.

stdio

HTTP

gRPC

No

Yes

class_exists probe

Local AI client

MCP server

Networked client

REST server

Typed or streaming client

gRPC server

Tool registry

High risk?

NextPDF PDF 2.0 engine

Human confirmation token

Pro and Enterprise providers

NextPDF Connect component architecture

这个包采用 Apache-2.0 许可，与 nextpdf/core 一致。 它实现的 MCP 协议版本，是以日期标记的 2025-06-18 修订版。 REST 接口由一份 OpenAPI 3.1 文档描述；gRPC 接口则由 nextpdf.connect.v1 这个 Protocol Buffers 包描述。

API 接口

标题为“API 接口”的章节

公开的入口点是这三个服务器类。 每个类都有一个命令行接口（CLI）包装器：

入口点类传输
bin/nextpdf-mcpNextPDF\Server\Mcp\McpServer在 stdio 之上的 MCP
bin/nextpdf-serverNextPDF\Server\Http\HttpServer在 RoadRunner HTTP 之上的 REST
bin/nextpdf-grpcNextPDF\Server\Grpc\GrpcServer在 RoadRunner gRPC 之上的 gRPC
bin/generate-skillsNextPDF\Server\Skills\SkillsDumper工具目录导出

McpServer::create()、HttpServer::create() 与 GrpcServer::create() 都会基于环境变量与配置输入，构建出一个完整配置好的服务器。 注册表、文档存储区、安全策略以及确认 gate，都是三个服务器共享的概念。

代码示例 — 快速上手

标题为“代码示例 — 快速上手”的章节

启动最精简的 MCP 服务器只需一条命令。 你不必编写任何 PHP 胶水代码：

Terminal window
./vendor/bin/nextpdf-mcp

服务器会从标准输入读取 JSON-RPC 请求，并把响应写到标准输出。 若想查看可实际运行的 initialize 与 tools/list 往返交换，以及对应的 REST 请求，请参阅 /connect/quickstart/。

边界情况与陷阱

标题为“边界情况与陷阱”的章节

  • 工具数量不是 33，也不是任何其他固定数字。 服务器会在运行期，在策略筛选与层级检测之后，以 count(ToolRegistry::all()) 计算工具数量。 凡是引用固定总数的文档都已过时。 要获取权威数量，请查询运行中的服务器。 请使用 MCP 的 initialize 响应，或 REST 的 /api/v1/capabilities 端点。

  • 缺少 Pro 或 Enterprise 包并不是错误。 注册表会用 class_exists() 检查提供者类，然后静默跳过任何不存在的层级。 纯开源部署会照常启动，并提供其核心目录。

  • 这三种传输不共用同一个进程。 运行 MCP 服务器并不会启动 REST 服务器或 gRPC 服务器。 反过来也是如此。 合并式部署会使用一份同时启动两个 worker 池（HTTP 池与 gRPC 池）的配置，来运行 RoadRunner 监督进程。 请参阅 /connect/deployment/。

性能

标题为“性能”的章节

每种传输都基于 worker。 一个 worker 一次处理一条请求。 REST 与 gRPC 服务器在 RoadRunner worker 池上运行，池大小由配置设定。 默认值为四个 HTTP worker。 RoadRunner 监督进程会限制每个 worker 的内存上限。 本页前置元数据中的 performance_budget 描述的是冷启动并完成发现过程的预算范围。 它并非单条请求的目标值。 每条请求的成本大多由底层的引擎运算主导。

安全说明

标题为“安全说明”的章节

所有网络传输都使用应用程序编程接口（API）密钥形式的 bearer token 进行身份验证。 根据 MCP 的传输模型，MCP stdio 传输是一个本机子进程，受启动它的客户端信任。 无论使用哪种传输，高风险工具仍受人工确认把守。 完整的威胁模型、身份验证模型以及传输安全配置，请参阅 /connect/security-and-operations/。

一致性

标题为“一致性”的章节

本页只陈述架构层面的主张。 规范性的协议与安全引用，已固定在分别规定相关行为的页面上：/connect/security-and-operations/、/transports/mcp/、/transports/rest/，以及 /transports/grpc/。 MCP 生命周期的参考依据，是 modelcontextprotocol.io 上的官方规范（2025-06-18 修订版）。 由于 MCP 规范并不属于受管控的标准语料库，各传输页面会将该参考依据连同其网址一并记录。

商业背景

标题为“商业背景”的章节

对于文档创建、检查与诊断，核心目录已经完整。 用于签名、涂黑（redaction）、合规认证以及取证分析的工具，只有在 nextpdf/premium 与服务器一同安装时才会出现。 这是包层面的边界，而非运行期的追加销售提示。 服务器永远不会发出营销内容。

另请参阅

标题为“另请参阅”的章节
  • /connect/install/ — 安装与可选包
  • /connect/quickstart/ — 第一个可实际运行的 MCP 与 REST 往返交互
  • /connect/tool-catalog/ — 经过验证的核心工具集，以及数量为何取决于运行期
  • /connect/hitl-risk-tiers/ — 确认 gate 与风险模型
  • /transports/mcp/、/transports/rest/、/transports/grpc/ — 各传输的设置
  • /connect/security-and-operations/ — 身份验证、传输安全、威胁模型
  • /connect/deployment/ — RoadRunner、Docker 与合并式传输部署