Arranque y descubrimiento en NextPDF Connect

De un vistazo

Cada transporte cuenta con su propio punto de entrada y su propia secuencia de arranque. Comparten el registro, la configuración y el gate como conceptos. Se ejecutan como procesos independientes; por lo tanto, iniciar uno no inicia los demás.

Instalación

composer require nextpdf/server

Panorama conceptual

Secuencia de arranque de MCP

McpServer::create() inicializa el servidor MCP en un orden fijo. Primero carga la configuración, construye la política de seguridad a partir de esa configuración, crea el registro de herramientas y ejecuta el descubrimiento de niveles. A continuación, construye el almacén de documentos en memoria a partir del TTL y la capacidad configurados, crea el transporte stdio y ensambla el manejador del protocolo JSON-RPC con el gate de confirmación y el registrador de auditoría. Una vez hecho esto, el servidor entra en su bucle de lectura, manejo y escritura, y se ejecuta hasta que la entrada estándar llega al final del archivo.

Secuencia de arranque de REST

HttpServer::create() lee HttpConfig desde el entorno y aplica las anulaciones de la CLI. Luego resuelve el almacén de claves de API en este orden de preferencia: primero el almacén de archivos con recarga en caliente, después el archivo estático y, por último, el entorno. A continuación, resuelve los almacenes de límite de tasa e idempotencia, que usan Redis cuando Redis está configurado y accesible, y recurren al almacenamiento en memoria en caso contrario. Desde ese punto, abre el almacén de trabajos SQLite compartido, construye los servicios de la aplicación y crea la tabla de rutas. Como la tabla de rutas se construye a partir de los niveles detectados, refleja los paquetes instalados. Luego RoadRunner impulsa el bucle de peticiones de los workers.

Secuencia de arranque de gRPC

GrpcServer::create() resuelve el mismo almacén de claves, construye los mismos servicios de la aplicación y registra el servicio nextpdf.connect.v1 con el worker gRPC de Spiral. Cuando la dependencia del motor no está disponible, el servidor gRPC aun así arranca y atiende consultas de estado y capacidades. En ese estado, el proceso no rechaza el arranque; en cambio, las RPC que transportan datos fallan limpiamente.

Descubrimiento de herramientas

El descubrimiento es el paso predeterminado para poblar el registro. El nivel core se registra primero. Los proveedores Pro y Enterprise se registran a continuación si sus clases se resuelven mediante class_exists(). Los proveedores de AST y de mutación incluidos se registran después bajo el nivel Pro, sujetos a sus gates de entorno. Cada registro se filtra a través de la lista de permitidos de seguridad enabled_tools, y los recuentos resultantes por nivel se informan en la respuesta initialize de MCP. Consultar /connect/tool-catalog/.

Descubrimiento de transportes

Ningún ajuste de configuración, por sí solo, «habilita los transportes». Cada transporte es un punto de entrada separado. REST y gRPC tienen cada uno un perfil de RoadRunner independiente. Un despliegue elige los transportes según el perfil que ejecuta: .rr.yaml para REST, .rr.grpc.yaml para gRPC, o .rr.full.yaml para ambos. Los transportes se ejecutan como procesos independientes. Un cliente MCP ausente nunca bloquea el servidor REST, y un cliente REST ausente nunca bloquea MCP. Consultar /connect/deployment/.

Orden de resolución de la configuración

El servidor MCP resuelve la configuración en este orden de prioridad: el entorno (NEXTPDF_MCP_*) tiene prioridad sobre la sección nextpdf_mcp del archivo YAML, que a su vez tiene prioridad sobre los valores predeterminados integrados. Los servidores REST y gRPC leen HttpConfig desde variables de entorno NEXTPDF_* con valores predeterminados seguros. No leen el archivo YAML de MCP. Consultar /connect/configuration/.

Enlaces del contenedor

No hay ningún contenedor de inyección de dependencias ni proveedor de servicios que registrar. Cada fábrica create() construye su propio grafo de objetos de forma explícita y determinista. Existen dos puntos de inyección — el transporte y la fábrica de workers —, y ambos son para pruebas, no para el cableado de la aplicación.

Ejemplo de código — Inicio rápido

Inspeccionar lo que produjo el descubrimiento, sin atender tráfico:

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

Ejemplo de código — Producción

Arrancar los transportes combinados bajo un único supervisor:

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
./vendor/bin/rr serve -c .rr.full.yaml

Casos límite y trampas

• Un nivel ausente no hace fallar el arranque. El descubrimiento de niveles omite silenciosamente un paquete Pro o Enterprise ausente. El servidor arranca con el catálogo core.

• Una anulación que degrada hace fallar el arranque. Una entrada de risk_level_overrides que debilita una herramienta approval_required lanza un error al cargar la configuración; el servidor rechaza el inicio. Es intencional.

• Un fallo de Redis degrada, no provoca una caída. Si Redis está configurado pero inaccesible en el arranque, el servidor REST recurre a los almacenes en memoria. Verificar el estado de Redis en lugar de suponer que Redis está en uso.

Rendimiento

El costo del arranque corresponde al análisis de la configuración más el escaneo del registro y la detección de niveles. La página performance_budget acota este costo. El costo se paga una vez por arranque de proceso, no por petición.

Notas de seguridad

La política de seguridad se construye antes que el registro, así que la lista de permitidos enabled_tools restringe el descubrimiento desde la primera alta en el registro. Las claves de API nunca se leen del archivo YAML de MCP; los transportes en red resuelven las claves a partir de un archivo de secretos o del entorno. Consultar /connect/security-and-operations/.

Conformidad

Esta página describe la mecánica del arranque. Las citas de protocolo y seguridad están fijadas en /transports/mcp/, /transports/rest/, /transports/grpc/ y /connect/security-and-operations/.

Contexto comercial

La detección de niveles en el arranque es el único punto en el que nextpdf/premium aporta sus herramientas Pro y Enterprise al catálogo, cuando nextpdf/premium está instalado junto con el servidor.

Consulta también

• /connect/tool-catalog/ — qué registra el descubrimiento y por qué varía el recuento
• /connect/configuration/ — el orden de resolución en detalle
• /connect/deployment/ — elegir transportes mediante perfiles de RoadRunner
• /transports/mcp/ · /transports/rest/ · /transports/grpc/ — detalle por transporte