Descripción general del servidor NextPDF Connect

De un vistazo

NextPDF Connect es el paquete nextpdf/server: un servicio de larga duración que expone el motor PDF 2.0 de NextPDF a agentes de IA y clientes HTTP. Lo hace mediante tres transportes: Model Context Protocol (MCP) sobre stdio, una API REST y gRPC. Los tres transportes se basan en un único registro de herramientas y comparten una única compuerta de confirmación humana en el flujo (human-in-the-loop, HITL).

Instalación

composer require nextpdf/server

La restricción de Composer declara nextpdf/core: ^3.0 con php: >=8.4 <9.0. Para ver el procedimiento completo, consultar /connect/install/. Esa página también cubre dos complementos opcionales: la extensión ext-redis y el paquete nextpdf/premium.

Descripción general conceptual

nextpdf/server adapta el núcleo de NextPDF, independiente del framework, para exponerlo como una superficie de servicio. No vuelve a implementar la generación de PDF. En su lugar, encapsula cada capacidad del motor como una herramienta con nombre, con su propio esquema, y luego sirve ese catálogo a través de varios protocolos de transporte.

El diseño se sostiene sobre tres conceptos:

• El registro de herramientas. NextPDF\Server\ToolRegistry detecta y registra las herramientas durante el arranque. El paquete incluye un conjunto básico, y ese conjunto básico está siempre disponible. Los proveedores Pro y Enterprise registran más herramientas, pero solo cuando los paquetes correspondientes están instalados. Por tanto, el número de herramientas expuestas es una propiedad del despliegue en tiempo de ejecución, no una constante fija. Consultar /connect/tool-catalog/.

• Los transportes. El mismo registro se sirve de tres maneras. MCP funciona sobre stdio para clientes de IA locales. REST funciona sobre una canalización de middleware PSR-15 en un grupo de workers de RoadRunner para clientes en red. gRPC funciona sobre un worker gRPC de Spiral RoadRunner para clientes tipados y de streaming. Cada transporte se ejecuta en su propio proceso, con su propio punto de entrada. Consultar /transports/mcp/, /transports/rest/ y /transports/grpc/.

• La compuerta de confirmación. Cada herramienta declara un nivel de riesgo. Una herramienta del nivel más alto requiere una confirmación humana explícita antes de ejecutarse. La compuerta emite un token de desafío de un solo uso. El agente debe entregar ese token a una persona y, luego, volver a invocar la herramienta con el token. Consultar /connect/hitl-risk-tiers/.

El diagrama siguiente muestra cómo un único registro llega a tres transportes. También muestra dónde se ubica la compuerta de confirmación en la ruta de la solicitud.

NextPDF Connect component architecture

El paquete se publica con licencia Apache-2.0, que coincide con la de nextpdf/core. La versión del protocolo MCP implementada es la revisión con fecha 2025-06-18. Un documento OpenAPI 3.1 describe la superficie REST. El paquete de Protocol Buffers nextpdf.connect.v1 describe la superficie gRPC.

Superficie de la API

Los puntos de entrada públicos son las tres clases de servidor. Cada una tiene un envoltorio de interfaz de línea de comandos (CLI):

Punto de entrada	Clase	Transporte
bin/nextpdf-mcp	NextPDF\Server\Mcp\McpServer	MCP sobre stdio
bin/nextpdf-server	NextPDF\Server\Http\HttpServer	REST sobre RoadRunner HTTP
bin/nextpdf-grpc	NextPDF\Server\Grpc\GrpcServer	gRPC sobre RoadRunner gRPC
bin/generate-skills	NextPDF\Server\Skills\SkillsDumper	Exportación del catálogo de herramientas

McpServer::create(), HttpServer::create() y GrpcServer::create() construyen, cada uno, un servidor totalmente configurado a partir de entradas de entorno y configuración. El registro, el almacén de documentos, la política de seguridad y la compuerta de confirmación son conceptos compartidos por los tres servidores.

Ejemplo de código: inicio rápido

El servidor MCP mínimo requiere un solo comando. No hace falta escribir código PHP de pegamento:

./vendor/bin/nextpdf-mcp

El servidor lee solicitudes JSON-RPC desde la entrada estándar y escribe las respuestas en la salida estándar. Para ver un intercambio ejecutable de initialize y tools/list, así como la solicitud REST correspondiente, consultar /connect/quickstart/.

Casos límite y errores frecuentes

• El número de herramientas no es 33, ni ningún otro número fijo. El servidor cuenta las herramientas en tiempo de ejecución con count(ToolRegistry::all()), después de aplicar el filtrado por política y la detección de nivel. La documentación que cite un total fijo está desactualizada. Para obtener el recuento autoritativo, consultar el servidor en ejecución. Usar la respuesta de initialize de MCP o el endpoint REST /api/v1/capabilities.

  No codifiques de forma rígida el número de herramientas

  El número de herramientas expuestas depende de los paquetes instalados y de la política activa. Debe leerse desde el servidor en ejecución, en tiempo de ejecución. Un número fijo copiado en código o documentación propios quedará desactualizado.

• La ausencia de un paquete Pro o Enterprise no es un error. El registro comprueba las clases de proveedor con class_exists() y, luego, omite en silencio cualquier nivel que esté ausente. Un despliegue exclusivamente de código abierto se inicia y sirve su catálogo básico con normalidad.

• Los tres transportes no comparten un proceso. Ejecutar el servidor MCP no inicia el servidor REST ni el servidor gRPC. Lo inverso también es cierto. Un despliegue combinado ejecuta el supervisor de RoadRunner con una configuración que inicia ambos grupos de workers, el grupo HTTP y el grupo gRPC. Consultar /connect/deployment/.

Rendimiento

Cada transporte se basa en workers. Un worker atiende una solicitud a la vez. Los servidores REST y gRPC se ejecutan en grupos de workers de RoadRunner, y la configuración define el tamaño del grupo. El valor predeterminado es de cuatro workers HTTP. El supervisor de RoadRunner limita la memoria de cada worker. El performance_budget del front-matter de esta página describe un margen de arranque en frío y descubrimiento. No es un objetivo por solicitud. La operación subyacente del motor representa la mayor parte del coste de cada solicitud.

Notas de seguridad

Todos los transportes en red se autentican con un token bearer basado en una clave de interfaz de programación de aplicaciones (API). El transporte stdio de MCP es un subproceso local en el que confía el cliente que lo lanza, según el modelo de transporte de MCP. Las herramientas de alto riesgo permanecen bajo control de confirmación humana en todos los transportes. Para ver el modelo de amenazas completo, el modelo de autenticación y la configuración de seguridad del transporte, consultar /connect/security-and-operations/.

El transporte stdio de MCP se apoya en la confianza local

El transporte stdio de MCP no lleva ningún token bearer. Se ejecuta como un subproceso local, y el cliente que lo lanza controla ese límite de confianza. Aplicar el modelo de autenticación en red solo a los transportes REST y gRPC.

Conformidad

Esta página solo hace afirmaciones arquitectónicas. Las citas normativas de protocolo y seguridad están fijadas en las páginas que especifican el comportamiento: /connect/security-and-operations/, /transports/mcp/, /transports/rest/ y /transports/grpc/. La referencia del ciclo de vida de MCP es la especificación oficial en modelcontextprotocol.io (revisión 2025-06-18). Las páginas de transporte registran esa referencia con su URL, porque la especificación de MCP no forma parte del corpus controlado de normas.

Contexto comercial

El catálogo básico está completo para la creación, la inspección y el diagnóstico de documentos. Las herramientas de firma, redacción, certificación de conformidad y análisis forense aparecen solo cuando nextpdf/premium está instalado junto con el servidor. Esto marca un límite de empaquetado, no un mensaje de venta en tiempo de ejecución. El servidor nunca emite contenido de marketing.

Véase también

• /connect/install/ — instalación y paquetes opcionales
• /connect/quickstart/ — primer intercambio ejecutable de MCP y REST
• /connect/tool-catalog/ — el conjunto básico verificado de herramientas y cómo el recuento depende del tiempo de ejecución
• /connect/hitl-risk-tiers/ — la compuerta de confirmación y el modelo de riesgo
• /transports/mcp/, /transports/rest/, /transports/grpc/ — configuración por transporte
• /connect/security-and-operations/ — autenticación, seguridad de transporte, modelo de amenazas
• /connect/deployment/ — RoadRunner, Docker y despliegue con transporte combinado