Generar el primer PDF con NextPDF Connect

De un vistazo

Esta receta muestra el camino más corto desde una sesión vacía hasta un PDF generado con NextPDF Connect. Se crea un documento A4 de una sola página, se escriben un título y un subtítulo y, a continuación, se devuelve el archivo como base64. Tres herramientas de Core se encargan de todo el trabajo: create_pdf, add_text y output_pdf. No se necesitan fuentes, imágenes ni ningún nivel con licencia.

Un transporte de Connect envía cada llamada de herramienta como solicitud y devuelve el resultado de la herramienta como respuesta. La capa de transporte es independiente del resultado informado por la herramienta (PSR-18 §p2).

Instalación

Instalar NextPDF Server y vincular un transporte:

composer require nextpdf/server

Ejecutar el servidor en el transporte que espere el host: Model Context Protocol sobre stdio, REST o gRPC. Consultar Disponibilidad de transportes más abajo. Las herramientas de esta receta son herramientas de Core. Están incluidas con el servidor, por lo que no se necesita ningún paquete Pro ni Enterprise.

Resumen conceptual

Una sesión de Connect es un almacén de documentos del lado del servidor, indexado por un document_id. create_pdf abre una sesión y devuelve el id. Cada llamada de herramienta posterior hace referencia a ese id. El documento comienza con una página en blanco. El árbol de páginas es la estructura a través de la cual un lector alcanza cada página (ISO 32000-2 §7.7.3). output_pdf genera un PDF a partir de la sesión. De forma predeterminada, después destruye la sesión para liberar memoria.

Al llamar a add_text sin un x ni un y explícito, el texto fluye hasta su posición: empieza en el cursor actual y el cursor avanza después de cada llamada.

Superficie de la API

Al arrancar el servidor, el registro de herramientas resuelve las siguientes herramientas. Los nombres corresponden a los nombres de protocolo del registro. La referencia completa está en el catálogo de herramientas combinado. Las herramientas disponibles dependen del nivel instalado, pero estas tres siempre están presentes en Core.

Herramienta	Función	Nivel de riesgo
`create_pdf`	Abrir una sesión de documento	Safe
`add_text`	Escribir texto en el documento	Caution
`output_pdf`	Representar y devolver el PDF	Approval Required (modo de archivo) / Review (base64)

Ejemplo de código — Inicio rápido

El host realiza tres llamadas de herramienta. En palabras, son las siguientes:

Llamar a create_pdf con page_size: "A4", orientation: "portrait" y el título y el autor del documento. El servidor devuelve un document_id.
Llamar a add_text con ese document_id, el texto del título, un font_size grande, width: 0 (el ancho de contenido completo) y alignment: "center".
Llamar a output_pdf con el document_id. Sin un file_path, el servidor devuelve el PDF como base64 y destruye la sesión.

A continuación, un objeto de argumentos create_pdf mínimo:

{
  "page_size": "A4",
  "orientation": "portrait",
  "title": "Hello World",
  "author": "NextPDF Cookbook"
}

La respuesta incluye el document_id, el número de páginas y la geometría de la página. Tratar el id como un valor opaco y no interpretar ningún significado en él.

Ejemplo de código — Producción

En producción, el llamador comprueba cada respuesta antes de la siguiente llamada. Nunca reutilizar un document_id después de que output_pdf haya destruido la sesión.

create_pdf: confirmar que la respuesta contiene un document_id. Si el servidor devuelve el error de límite de sesiones, liberar las sesiones no usadas e intentarlo de nuevo.
add_text (título): confirmar que la respuesta devuelve un position.
add_text (subtítulo): usar un font_size más pequeño; el cursor continúa debajo del título.
output_pdf: leer el campo base64 y decodificarlo en bytes. El indicador destroyed confirma que la sesión ya no existe.

El archivo se devuelve en línea (modo base64), por lo que no hay ningún efecto secundario en el sistema de archivos ni ninguna puerta de aprobación humana; consultar Nivel de riesgo HITL.

Casos límite y trampas

Sesión destruida. Después de ejecutar output_pdf con el valor predeterminado destroy: true, el document_id deja de ser válido. Cualquier llamada posterior que lo use devuelve un error de documento desconocido. Crear una nueva sesión en su lugar.
Tamaño de página desconocido. El servidor rechaza un page_size que no reconoce y devuelve un error claro. Usar un tamaño documentado (A3, A4, A5, A6, Letter, Legal, Tabloid).
Texto vacío. Un text vacío genera una entrada de ancho cero, no un error. Comprobar la entrada antes de la llamada.
Límite de sesiones. El almacén en memoria limita la cantidad de sesiones simultáneas. Liberar las sesiones con prontitud con output_pdf.

Rendimiento

Una sola página de solo texto se genera con holgura dentro del presupuesto de página, y la salida suele ser de 1–3 KB. Para esta receta, el perfil de reproducibilidad de doble representación es structural. El PDF incluye un /ID de tráiler y marcas de tiempo que cambian de una ejecución a otra, por lo que una comparación estructural (normalizada) es la más fiel.

Notas de seguridad

La vía base64 no tiene ningún efecto secundario en el sistema de archivos. La vía de salida a archivo sí lo tiene, y está protegida; consultar la sección HITL. Tratar el base64 devuelto como contenido del documento, no como un canal de confianza. Son exactamente los bytes que produjeron las herramientas.

Conformidad

Afirmación	Especificación	Cláusula	reference_id
Un transporte envía una solicitud y recibe una respuesta con independencia del resultado.	PSR-18	§p2
Las páginas se alcanzan a través del árbol de páginas del documento.	ISO 32000-2	§7.7.3

Esta receta describe cómo el servidor produce la salida. No declara conformidad con ningún perfil.

Contexto comercial

No aplicable: las tres herramientas son de Core.

Disponibilidad de transportes

Transporte	Disponible	Notas
MCP (stdio)	Sí	Las llamadas de herramienta se asignan a `tools/call` de MCP.
REST	Sí	Cada herramienta es una operación REST; el resultado es el cuerpo de la respuesta.
gRPC	Sí	Cada herramienta es una llamada unaria.

El resultado de la herramienta es el mismo en todos los transportes; solo cambia el encuadre. Un resultado no exitoso sigue siendo una respuesta normal, no un fallo de transporte (PSR-18 §p2).

Nivel de riesgo HITL

El servidor sitúa cada llamada de herramienta en una escala de riesgo «humano en el bucle» (HITL): Safe (0) → Caution (1) → Review (2) → Approval Required (3). create_pdf es Safe y add_text es Caution. output_pdf es Approval Required, pero en modo base64 (sin file_path) baja a Review y se ejecuta sin confirmación humana. Escribir en un archivo lo mantiene en Approval Required; consultar output-approval y la referencia de niveles de riesgo HITL.

Envoltorio JSON de la puerta de confirmación

Esta receta permanece en modo base64, por lo que la puerta de confirmación devuelve el envoltorio de permiso:

{ "allowed": true }

El envoltorio de desafío (allowed: false, con una cadena challenge y un token de un solo uso) está documentado en output-approval.