跳转到内容
NextPDF

从仅支持 MCP 迁移到多重传输（multi-transport）

概览

标题为“概览”的章节

将集成从 MCP stdio 传输迁移到 REST 或 gRPC 传输。引擎行为不会改变。工具目录、风险模型和确认 gate（闸门）都保持完全一致。会改变的只有三件事：wire 协议、身份验证方式和并发模型。

安装

标题为“安装”的章节
Terminal window
composer require nextpdf/server
./vendor/bin/rr get-binary

概念总览

标题为“概念总览”的章节

本软件包早期文档只描述一种传输：基于 stdio 的 MCP。现在，本软件包会通过三种传输提供同一份工具注册表（tool registry）。迁移包含两个步骤：先选择一种网络传输，再将 MCP 调用映射到该传输上。它不会重写你的文档逻辑。

根据你的部署形态选择合适的传输：

  • 维持使用 MCP：适用于单一本机 AI Agent（代理）、要求最低延迟（没有网络跳转），或使用 MCP 原生客户端（例如本机 IDE 助手）的场景。
  • 改用 REST：适用于需要多客户端访问、为每个客户端配置 API key、容器或 Kubernetes 部署、按客户端限流、异步作业（async job），或使用任意语言编写客户端的场景。
  • 改用 gRPC：适用于需要类型化契约、通过服务器流式（server-streaming）传输大型 PDF，以及采用双向 TLS（mutual-TLS）的服务到服务部署的场景。

API 接口

标题为“API 接口”的章节

哪些保持不变

标题为“哪些保持不变”的章节
  • 工具注册表，以及取决于运行时环境的工具目录（详见 /connect/tool-catalog/）。
  • 四级风险模型和确认 gate（详见 /connect/hitl-risk-tiers/）。
  • 文档模型与引擎语义。

哪些会改变

标题为“哪些会改变”的章节
方面MCP（stdio 标准输入输出）RESTgRPC
Wire 格式基于 stdio 的 JSON-RPC 2.0通过 HTTP 的 JSON通过 gRPC 的 Protobuf
身份验证无（本机子进程）Authorization: Bearer API key（API 密钥）在调用元数据（call metadata）中携带 bearer
并发单一进程，一次处理一个调用RoadRunner worker 池RoadRunner gRPC 池
异步不适用作业 endpoint（端点）作业 RPC
流式不适用同步响应体服务器流式 RPC

概念映射

标题为“概念映射”的章节

典型的 MCP 序列是先调用 create_pdf，再调用内容工具，最后调用 output_pdf。在 REST 上，这会收敛为一个无状态的 POST /api/v1/render，并携带一个有序的 operations 数组。需要逐步累积状态时，请改用可选的 session endpoint。在 gRPC 上，对应的是 Render RPC，或使用 RenderStream 分块传递。若要进行有状态构建，请使用 CreateSession、SessionOperation 与 SessionRender 这些 RPC。

MCP 工具序列RESTgRPC
create_pdf + 内容工具 + output_pdfPOST /api/v1/renderRender / RenderStream
跨多次调用的有状态构建POST /api/v1/sessions（加上 session 操作）CreateSession（加上 SessionOperation）
长时间渲染POST /api/v1/jobs 再轮询结果SubmitJob 然后 GetJobResult
受分级管控（tier-gated）的操作POST /api/v1/<operation>ExecuteCapability

代码示例 — 快速上手

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

MCP 调用：

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"add_text","arguments":{"text":"Hello"}}}

会变成这个 REST 请求：

Terminal window
curl -sS -X POST http://localhost:8080/api/v1/render \
  -H "Authorization: Bearer $NEXTPDF_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"type":"add_text","text":"Hello"}]}' \
  --output hello.pdf

代码示例 — 生产环境

标题为“代码示例 — 生产环境”的章节

分阶段迁移期间，可以同时运行两种传输。合并后的 RoadRunner 配置文件（profile）会让同一个 supervisor 同时提供 REST 与 gRPC。旧的 MCP 集成仍可在适合的地方继续以本机方式运行：

Terminal window
export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
./vendor/bin/rr serve -c .rr.full.yaml

没有需要迁移的共享状态。这些传输是在同一个引擎之上的独立进程。逐步将客户端切换过去即可。

边界情况与陷阱

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

  • 加上身份验证。 MCP 传输原本不需要身份验证，因为它是本机子进程。网络传输要求每个非健康检查（health）请求都携带有效的 API key。请在切换前先配置好 key。请见 /connect/security-and-operations/.

  • 确认 gate 仍会触发。 标记为 approval_required 的工具在 REST 与 gRPC 上发出的确认请求，与它在 MCP 上的行为完全相同。请把确认流程接入新的集成。不要以为这个 gate 只会在 MCP 上触发。请见 /connect/hitl-risk-tiers/.

  • 分级管控保持不变。 Pro 或 Enterprise 操作在新传输上同样需要已安装 nextpdf/premium，并持有具备相应权限的 key；这与对应工具在 MCP 上需要该软件包一致。

  • 幂等性（idempotency）是新增且实用的功能。 REST 增加了 stdio 传输从未提供过的幂等性控制。用它可以让作业提交安全重试。请见 /connect/production-usage/.

性能

标题为“性能”的章节

MCP 是单一进程，对于单一本机代理延迟最低。网络传输会额外引入一个 worker 池和一次网络跳转。作为交换，它们可以扩展到大量并发客户端。请将长时间渲染改走新传输上的异步作业路径，避免 worker 被长期占用。

安全性注意事项

标题为“安全性注意事项”的章节

从 stdio 迁移出去，意味着你需要开始承担网络暴露风险。请在 REST 前端终结 TLS，在不受信任的网络上对 gRPC 采用双向 TLS，为每个客户端限制 key 的作用范围，并将 enabled_tools 保持在最小范围。MCP 传输不需要凭证的模型之所以安全，只是因为它是本机子进程。不要在网络上重现这种暴露风险。请见 /connect/security-and-operations/.

合规性

标题为“合规性”的章节

本页是迁移指引。协议与身份验证的引用来源分别固定在 /transports/mcp/、/transports/rest/、/transports/grpc/ 与 /connect/security-and-operations/.

商业背景

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

受分级管控的操作无论在哪一种传输上，都需要 nextpdf/premium。迁移不会改变哪些属于 core、哪些属于 Premium。它只会改变访问工具目录的方式。

另请参阅

标题为“另请参阅”的章节
  • /transports/mcp/ — 你要从中迁出的传输
  • /transports/rest/ · /transports/grpc/ — 你要迁入的传输
  • /connect/tool-catalog/ — 工具目录，在各传输之间保持一致
  • /connect/hitl-risk-tiers/ — 这个 gate，在各传输之间保持一致
  • /connect/security-and-operations/ — 你必须添加的身份验证