NextPDF Connect
NextPDF Connect
NextPDF Connect 是 nextpdf/server 包：一个长期运行的服务，将 NextPDF PDF 2.0 引擎提供给 AI Agent（代理）与 HTTP 客户端使用。同一份工具注册表通过三种方式开放：基于标准输入与输出的模型上下文协议（Model Context Protocol，MCP）、由一份 OpenAPI 3.1 文件描述的 REST API，以及由 nextpdf.connect.v1 Protocol Buffers 包定义的 gRPC。每个工具都会声明风险等级。最高等级的工具在运行前会先经过一道人工介入（HITL）确认 gate。
当你需要运维或集成此服务器时，请使用本节内容。先阅读概览了解整体架构，接着选择一种传输方式，然后阅读 API 参考查阅具体的工具与服务符号。
章节地图
标题为“章节地图”的章节这些页面涵盖了服务器的概念、配置与运维。
| 页面 | 用途 |
|---|---|
| 概览 | 包边界、三种传输方式，以及为什么工具数量是运行时属性。 |
| 快速上手 | 一次可实际运行的初始 MCP 握手，以及对应的 REST 渲染请求。 |
| 配置 | MCP 的 YAML 文件、NEXTPDF_* 环境变量，以及仅可升级的风险覆盖。 |
| 启动与发现 | 每种传输方式如何接入对应服务器，并在启动时发现工具与层级。 |
| 工具目录 | 经过验证、始终可用的核心工具集，以及总数如何在运行时计算。 |
| HITL 风险层级 | 四级风险模型，以及需要批准的工具对应的确认挑战。 |
| 部署 | RoadRunner worker 配置文件、Docker、以 Redis 为后端的存储区，以及 gRPC 的双向 TLS。 |
| 安全性与运维 | 验证模型、传输安全、威胁模型，以及数据驻留（data residency）的处理。 |
这三种传输方式各有专属参考页。
| 传输页面 | 用途 |
|---|---|
| MCP 传输 | 以 stdio 承载的 JSON-RPC 2.0 消息框架，以及 initialize / tools/list / tools/call 方法。 |
| REST 传输 | RoadRunner 的 PSR-15 管线、OpenAPI 3.1 合约、bearer 验证，以及按层级把关的路由。 |
| gRPC 传输 | 提供 nextpdf.connect.v1.NextPDFConnect 服务、服务器流式 RPC 与元数据验证。 |
主要 API
标题为“主要 API”的章节这两个页面是开发者要针对此服务器进行开发时的入口。
| 页面 | 角色 |
|---|---|
| API 参考 | 按名称与类别列出每个已注册的工具、gRPC 服务与消息符号、错误模型，以及速率限制。 |
| 开发者指南 | 架构边界、运行时生命周期、层级 resolve（解析）、确认 gate、扩展点，以及测试检查清单。 |