Integración con NextPDF Connect

De un vistazo

Integrar NextPDF Connect consiste en ejecutarlo como servidor. No se conecta una biblioteca a una aplicación anfitriona. Hay que elegir un transporte y, después, configurar la autenticación cuando ese transporte opere en red. Las herramientas del motor quedan detrás de la compuerta de confirmación.

Instalación

composer require nextpdf/server

La restricción de Composer es nextpdf/core: ^3.0 con php: >=8.4 <9.0. Para los elementos opcionales ext-redis y nextpdf/premium, consulta /connect/install/.

Panorama conceptual

El paquete funciona como un servicio independiente. No hay que registrar ningún proveedor de servicios, bundle ni módulo de contenedor en un framework anfitrión. El punto de integración es el proceso que se ejecuta. Cada transporte tiene su propio punto de entrada y arranca de forma independiente. Consulta /connect/boot-and-discovery/.

Superficie de la API

Punto de entrada	Transporte	Perfil
`bin/nextpdf-mcp`	MCP sobre stdio	(ninguno: subproceso directo)
`bin/nextpdf-server`	REST sobre HTTP de RoadRunner	`.rr.yaml`
`bin/nextpdf-grpc`	gRPC sobre gRPC de RoadRunner	`.rr.grpc.yaml`
ambos transportes en red	REST + gRPC	`.rr.full.yaml`

Arranque y autodescubrimiento

El registro descubre siempre el nivel core. Luego añade los proveedores Pro y Enterprise cuando sus clases se resuelven, seguidos de los proveedores AST y de mutación incluidos bajo controles de entorno. La lista de permitidos de seguridad enabled_tools filtra todos estos elementos, por lo que el catálogo expuesto es una propiedad de este despliegue. Consulta /connect/tool-catalog/ y /connect/boot-and-discovery/.

Vinculaciones del contenedor

Ninguna. Cada fábrica de servidor construye explícitamente su propio grafo de objetos. Los puntos de inyección sirven para pruebas, no para el cableado de la aplicación.

Publicar la configuración

El servidor MCP acepta un archivo YAML opcional (--config=PATH, sección nextpdf_mcp) y anulaciones mediante variables de entorno NEXTPDF_MCP_*. Los servidores REST y gRPC leen las variables de entorno NEXTPDF_*. Para más detalles, consulta /connect/configuration/.

Disponibilidad de transportes (MCP / REST / gRPC)

Los tres transportes exponen el mismo registro:

MCP: subproceso local, JSON-RPC 2.0 sobre stdio, sin clave de API, revisión de MCP 2025-06-18. Consulta /transports/mcp/.
REST: grupo de workers HTTP de RoadRunner, contrato OpenAPI 3.1, clave de API bearer, rutas controladas por nivel. Consulta /transports/rest/.
gRPC: grupo de workers gRPC de RoadRunner, servicio Protobuf nextpdf.connect.v1, RPC con streaming desde el servidor, autenticación bearer en los metadatos y TLS mutuo en el perfil combinado. Consulta /transports/grpc/.

Un transporte está «disponible» cuando su punto de entrada o su perfil de RoadRunner está en ejecución. Los transportes no se inician unos a otros de forma automática.

Nivel de riesgo HITL

Cada herramienta declara uno de estos cuatro niveles de riesgo: safe, caution, review, approval_required. Las herramientas en approval_required no se ejecutan en la primera llamada. La compuerta de confirmación emite un token de desafío de un solo uso que una persona debe autorizar. Una anulación de configuración solo puede elevar el riesgo de una herramienta; nunca rebajar una herramienta approval_required. El modelo se aplica de forma idéntica en cada transporte que opera con herramientas. Consulta /connect/hitl-risk-tiers/.

JSON de la compuerta de confirmación

La comprobación de la compuerta devuelve una de dos formas JSON. Caso permitido:

{ "allowed": true }

Desafío:

{
  "allowed": false,
  "challenge": "<human-readable text naming the operation, its description, an overwrite warning when applicable, and the re-invocation instruction>",
  "token": "confirm_<nonce>"
}

El token vincula el nombre de la herramienta, un nonce aleatorio y un TTL de 300 segundos, no los argumentos. Para continuar, el llamador vuelve a invocar la misma herramienta con un argumento _confirmation_token establecido en el token emitido. El desafío es texto instructivo sencillo junto con el token; no es un sobre firmado criptográficamente. Consulta /connect/hitl-risk-tiers/.

Prueba de humo del servicio

./vendor/bin/generate-skills --dry-run --list-tools

Esto arranca el registro y la detección de niveles y, luego, imprime las herramientas expuestas sin servir tráfico. Es una forma rápida de confirmar que la integración está cableada y de comprobar qué catálogo produce esta instalación.

Casos límite y trampas

Sin hooks de framework. No hay que buscar un proveedor de servicios ni un bundle. La integración es el proceso en ejecución.
Un nivel ausente no es un error. La instalación solo con core arranca y sirve su catálogo core.
Los transportes en red requieren una clave. Solo /healthz y /readyz (REST) y los RPC de salud (gRPC) son anónimos.

Rendimiento

El costo de arranque corresponde al escaneo del registro y a la detección de niveles, una vez por proceso. El costo por solicitud corresponde a la operación del motor. Los grupos de workers de RoadRunner deben dimensionarse según la latencia de renderizado observada. Consulta /connect/production-usage/.

Notas de seguridad

Los transportes en red se autentican con una clave bearer npk_live_ validada en tiempo constante; la compuerta exige confirmación humana para las operaciones destructivas independientemente del transporte. TLS debe terminarse delante de REST y debe usarse TLS mutuo para gRPC en redes no confiables. Consulta /connect/security-and-operations/.

Conformidad

Las citas de protocolo y seguridad están definidas en /transports/mcp/, /transports/rest/, /transports/grpc/ y /connect/security-and-operations/.

Contexto comercial

Instalar nextpdf/premium junto con el servidor registra las herramientas Pro y Enterprise adicionales en el mismo servidor en ejecución. No interviene ningún proceso separado.

Véase también

/connect/overview/: la arquitectura
/connect/quickstart/: el primer intercambio ejecutable
/transports/mcp/ · /transports/rest/ · /transports/grpc/: referencia por transporte
/connect/hitl-risk-tiers/: la compuerta de confirmación en detalle
/connect/tool-catalog/: el catálogo dependiente del tiempo de ejecución
/connect/security-and-operations/: autenticación y modelo de amenazas