Inicio rápido con NextPDF Connect

De un vistazo

Esta página recorre el mínimo intercambio útil con ambos transportes: MCP y REST. Cada petición usa el formato exacto que implementa el servidor en el cable. No interviene ningún SDK.

Instalación

composer require nextpdf/server

Resumen conceptual

El transporte MCP usa JSON-RPC 2.0 por entrada y salida estándar. La secuencia es obligatoria y se ejecuta en orden. Primero se envía initialize. Luego se envía el acuse de recibo notifications/initialized. Después se envían tools/list y tools/call. El servidor lee un mensaje JSON por línea, cada una terminada con un salto de línea, y escribe una respuesta por línea.

El transporte REST expone como operaciones HTTP las mismas capacidades del motor. Un renderizado único y sin estado consiste en un POST /api/v1/render con un arreglo de operaciones ordenado. El cuerpo de la respuesta es el PDF.

Ejemplo de código — Inicio rápido (MCP sobre stdio)

Iniciar el servidor y canalizarle el handshake. Las tres peticiones siguientes usan los nombres de método verificados que enruta el manejador del protocolo:

./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

La respuesta de initialize informa la versión del protocolo 2025-06-18, el nombre del servidor NextPDF Connect y un bloque capabilities.nextpdf. Ese bloque incluye los conteos de niveles en vivo, el tool_count en tiempo de ejecución, la versión del modelo de riesgo y hitl_enabled: true. La respuesta de tools/list enumera exactamente las herramientas registradas por esta instalación. La línea de notificación no produce ninguna respuesta, por diseño.

A continuación, llamar a una herramienta segura. La herramienta diagnostic.doctor ejecuta una comprobación de solo lectura del entorno. No necesita ningún documento ni confirmación:

./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

Ejemplo de código — Inicio rápido (REST)

Iniciar el servidor REST y luego renderizar un PDF de una línea. El servidor exige una clave de API en cada endpoint que no sea de salud, por lo que primero hay que definir una:

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

En otra shell, enviar una petición de renderizado. El cuerpo es un RenderRequest. La petición contiene un arreglo operations ordenado de operaciones tipadas.

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

El cuerpo de una respuesta 200 es el PDF (Content-Type: application/pdf), escrito en hello.pdf. Las sondas de salud no requieren clave:

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

Casos límite y consejos

• El orden del handshake importa. El manejador del protocolo trata un mensaje sin id como una notificación y no devuelve respuesta. Enviar initialize con un id, luego la notificación initialized y después las peticiones que lleven id.

• Un id de petición repetido se deduplica. El manejador almacena en caché las respuestas recientes en un búfer circular de 64 entradas. Ante un id duplicado, devuelve la respuesta en caché sin volver a ejecutar la herramienta. Usar identificadores nuevos.

• Una herramienta de alto riesgo devuelve un desafío, no un resultado. Llamar a output_pdf con un file_path devuelve un desafío de confirmación en lugar de ejecutarse. Volver a invocarla con el _confirmation_token emitido. El modo de salida base64 (sin file_path) no requiere confirmación. Consultar /connect/hitl-risk-tiers/.

• Una petición REST no autorizada recibe 401. Un encabezado Authorization: Bearer ausente o con formato incorrecto devuelve un cuerpo de problem-details con un encabezado WWW-Authenticate: Bearer. Las sondas /healthz y /readyz son los únicos endpoints anónimos.

Rendimiento

Ambas rutas del inicio rápido requieren una sola petición. La ruta REST también incurre en el costo de arranque en frío del grupo de workers de RoadRunner en la primera petición después de rr serve. Las peticiones posteriores reutilizan workers en caliente.

Notas de seguridad

La clave npk_live_ anterior es un valor de demostración desechable. Generar claves reales con suficiente entropía, guardarlas fuera del control de versiones y preferir el almacén de claves basado en archivos para la rotación. El transporte MCP por stdio no tiene clave de API porque se ejecuta como un subproceso local en el que confía el cliente que lo lanza, de acuerdo con el modelo de transporte de MCP. Consultar /connect/security-and-operations/.

Conformidad

Los formatos en el cable que se muestran coinciden con la revisión de MCP implementada 2025-06-18 y con el contrato REST de OpenAPI 3.1. Las citas normativas de protocolo y autenticación están definidas en /transports/mcp/, /transports/rest/ y /connect/security-and-operations/.

Consulta también

• /transports/mcp/ — la referencia completa del transporte MCP
• /transports/rest/ — la referencia completa del transporte REST y el renderizado de OpenAPI
• /connect/tool-catalog/ — qué herramientas devuelve tools/list y por qué
• /connect/hitl-risk-tiers/ — cómo se ve un desafío de confirmación
• /connect/configuration/ — cómo restringir el catálogo y ajustar el servidor