跳转到内容
NextPDF

NextPDF Connect — MCP 传输

速览

标题为“速览”的章节

MCP 传输会将 bin/nextpdf-mcp 作为本地子进程运行。它通过标准输入和标准输出交换 JSON-RPC 2.0 消息。服务器实现的是以日期版本号标识的 MCP 版本 2025-06-18。

安装

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

概念总览

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

在 MCP stdio 模型中，客户端会将服务器作为子进程启动。客户端交换以换行符分隔的 JSON-RPC 消息：每行一条消息，不包含内嵌换行符，并使用 UTF-8 编码。服务器只会将有效的 MCP 消息写入标准输出，并通过标准错误输出记录日志。该实现特意将审计 logger 导向标准错误输出，因此日志行绝不会污染协议流。这种帧格式由官方 MCP 规范定义，版本为 2025-06-18。该规范不在受控标准语料库内，因此使用 URL 标明引用来源：https://modelcontextprotocol.io/specification/2025-06-18/basic/transports。

NextPDF Connect 实现的是 stdio 传输。MCP 规范还定义了一种 Streamable HTTP 传输。规范指出，客户端应尽可能支持 stdio，而服务器可以只实现 stdio。若要通过网络访问同一批工具，请改用 REST 或 gRPC 传输；详见 /transports/rest/ 与 /transports/grpc/。

API 接口

标题为“API 接口”的章节

方法

标题为“方法”的章节
方法行为
initialize返回协议版本、能力与服务器信息
notifications/initialized属于通知（没有 id）；确认接收后不返回任何响应
tools/list列出已注册的工具；可选用 params.category 过滤器
tools/call执行工具，传入 params.name 与 params.arguments

其他任何方法都会返回“找不到方法”（-32601）。不符合 JSON-RPC 2.0 的消息会返回“无效请求”（-32600）；无法解析的输入则返回“解析错误”（-32700）。重复的请求 id 会从容量为 64 条的缓冲区中返回先前缓存的响应，而不会重新执行。

initialize 的响应

标题为“initialize 的响应”的章节

initialize 的结果会报告 protocolVersion 2025-06-18、serverInfo.name: NextPDF Connect，以及一个 capabilities 对象。除标准的 tools 能力外，服务器还会添加一个 capabilities.nextpdf 块：

  • tiers——各层级当前已注册工具数（core / pro / enterprise）。
  • tool_count——已注册工具的总数，在运行期计算得出。
  • risk_model_version——服务器强制执行的风险模型版本。
  • hitl_enabled——true；确认关卡已启用。

tool_count 是 这个 部署的权威数字。它是在运行期统计的计数，而不是文档中记载的常量；详见 /connect/tool-catalog/。

代码示例——快速上手

标题为“代码示例——快速上手”的章节
Terminal window
./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"client","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
EOF

代码示例——生产环境

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

按类别过滤列表会将工具目录缩小到单一领域：

Terminal window
./vendor/bin/nextpdf-mcp --config=/etc/nextpdf/nextpdf-mcp.yaml <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"client","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{"category":"diagnostic"}}
EOF

类别值取自各工具声明的类别（例如 document、diagnostic）。

边界情况与陷阱

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

  • 没有 API 密钥。 stdio 传输没有网络监听器，也没有 bearer token。按照 MCP stdio 模型，信任边界就是操作系统的进程边界。不要将它桥接到网络上。

  • 确认质询是在带内进行的。 标记为 ApprovalRequired 的工具会返回一个成功的 JSON-RPC 响应，其内容包含质询文本与一次性令牌，而不是错误。详见 /connect/hitl-risk-tiers/。

  • 通知是静默的。 没有 id 的消息不会产生任何响应。握手流程是：先 initialize（带 id），接着是 initialized 通知，然后才是带 id 的调用。

性能

标题为“性能”的章节

MCP 服务器是单一进程，通过管道一次处理一个请求。没有网络往返；延迟主要取决于底层引擎执行的操作。

安全须知

标题为“安全须知”的章节

此传输继承启动它的客户端所拥有的信任。请确保子进程仅在本地运行。即使没有 API 密钥，高风险工具仍必须经过人工确认才能执行。详见 /connect/security-and-operations/。

一致性

标题为“一致性”的章节

stdio 帧以及 initialize/lifecycle 行为均符合官方 Model Context Protocol 规范，版本为 2025-06-18：

  • 传输：https://modelcontextprotocol.io/specification/2025-06-18/basic/transports
  • 生命周期：https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle

MCP 规范不在受控标准语料库内，因此没有 reference_id；上方的官方 URL 即为正式引用来源。

商业背景

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

只有在服务器同时安装了 nextpdf/premium 时，tools/list 才会返回 Pro 与 Enterprise 工具。无论安装了哪些层级，传输本身都完全相同。

另请参阅

标题为“另请参阅”的章节
  • /connect/quickstart/——可运行的握手流程
  • /connect/tool-catalog/——说明 tools/list 会返回什么，以及数量为什么会变化
  • /connect/hitl-risk-tiers/——确认质询的格式
  • /transports/rest/ · /transports/grpc/——可通过网络访问的替代方案
  • /connect/migrating-to-multi-transport/——将仅支持 MCP 的集成改为 REST/gRPC