NextPDF Connect 快速入门

概览

本页分别通过 MCP 和 REST 两种传输（transport）运行一轮最小但实用的交换流程。每个请求都采用服务器实际实现的 wire 格式。整个过程不需要任何软件开发工具包（SDK）。

安装

composer require nextpdf/server

概念说明

MCP 传输通过标准输入和输出，以 JSON-RPC 2.0 通信。这个顺序是必需的，而且必须严格按序执行。先发送 initialize。接着发送 notifications/initialized 确认消息。再发送 tools/list 和 tools/call。服务器按行读取 JSON 消息，每行消息以换行符结尾；它也按行写出响应。

REST 传输通过 HTTP 操作对外提供与 MCP 相同的引擎能力。一次无状态（stateless）渲染就是一个 POST /api/v1/render，其中包含一个按顺序排列的 operations 数组。响应主体就是 PDF。

代码示例 — 快速入门（通过 stdio 走 MCP）

启动服务器，并通过管道传入握手流程。下面三个请求使用的是协议处理器（protocol handler）实际路由的已验证方法名称：

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

这个 initialize 响应会报告协议版本 2025-06-18、服务器名称 NextPDF Connect，以及一个 capabilities.nextpdf 块。该块包含实时的分级数量、运行时的 tool_count、风险模型版本，以及 hitl_enabled: true。tools/list 响应会精确列出当前安装所注册的工具。按照设计，通知行不会产生任何响应。

现在调用一个安全工具。diagnostic.doctor 工具会执行一次只读环境检查。它不需要文档，也不需要任何确认：

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

代码示例 — 快速入门（REST）

启动 REST 服务器，然后渲染一份单行 PDF。服务器对每个非健康检查端点（endpoint）都要求 API 密钥，所以先定义一个：

export NEXTPDF_API_KEYS='npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef:demo:core:default'
./vendor/bin/rr serve -c .rr.yaml

在第二个 shell 中发送一个渲染请求。请求主体是一个 RenderRequest。该请求包含一个按顺序排列的 operations 数组，数组内是带类型的操作。

curl -sS -X POST http://localhost:8080/api/v1/render \
  -H 'Authorization: Bearer npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef' \
  -H 'Content-Type: application/json' \
  -d '{
        "page_size": "A4",
        "orientation": "portrait",
        "operations": [
          { "type": "add_text", "text": "Hello from NextPDF Connect" }
        ]
      }' \
  --output hello.pdf

一个 200 响应的主体就是 PDF（Content-Type: application/pdf），并写入 hello.pdf。健康检查探针不需要密钥：

curl -sS http://localhost:8080/healthz

边界情况与陷阱

握手顺序很重要。 协议处理器会把没有 id 的消息视为通知，不返回任何内容。先发送包含 initialize 和 id 的消息，接着发送 initialized 通知，再发送带有 id 的请求。
重复的请求 id 会被去重。 处理器会使用一个 64 条的环形缓冲区缓存最近的响应。遇到重复的 id 时，它会返回已缓存的响应，不会再次执行该工具。请使用全新的 id。
高风险工具返回的是挑战，而不是结果。 调用 output_pdf 并传入 file_path 时，会返回确认挑战，而不是直接执行。请携带签发的 _confirmation_token 重新调用。base64 输出模式（不带 file_path）则不需要确认。请参阅 /connect/hitl-risk-tiers/.
未授权的 REST 请求会返回 401。 缺少或格式错误的 Authorization: Bearer 标头，会返回一个带 WWW-Authenticate: Bearer 标头的 problem-details 主体。/healthz 和 /readyz 探针是仅有的匿名端点。

性能

两条快速入门路径都是单一请求。REST 路径还会在 rr serve 之后的首个请求上，承担 RoadRunner worker 池的冷启动成本。后续请求则会复用已预热的 worker。

安全须知

上面的 npk_live_ 密钥只是一次性示例值。请生成具有足够熵的真实密钥，将其存放在版本控制之外，并优先采用基于文件的密钥存储区以便轮换。MCP 的 stdio 传输没有 API 密钥，因为按照 MCP 传输模型，它是由启动它的客户端信任的本机子进程。请参阅 /connect/security-and-operations/.

符合性

此处呈现的 wire 格式对应已实现的 MCP 修订版本 2025-06-18 与 OpenAPI 3.1 的 REST 合约。规范性的协议和认证引用固定在 /transports/mcp/、/transports/rest/ 与 /connect/security-and-operations/.

另请参阅

/transports/mcp/ — 完整的 MCP 传输参考
/transports/rest/ — 完整的 REST 传输参考和 OpenAPI 渲染
/connect/tool-catalog/ — tools/list 会返回哪些工具及其原因
/connect/hitl-risk-tiers/ — 确认挑战的形式
/connect/configuration/ — 如何缩小工具目录范围并调优服务器