Configurar NextPDF Connect

De un vistazo

NextPDF Connect tiene dos superficies de configuración. El servidor MCP lee un archivo YAML junto con las variables NEXTPDF_MCP_*. Los servidores REST y gRPC leen las variables de entorno NEXTPDF_*. La configuración queda inmutable una vez iniciado el servidor.

Instalación

composer require nextpdf/server

Resumen conceptual

El servidor MCP resuelve la configuración según un orden de prioridad fijo. Prevalece la fuente de mayor prioridad:

Variables de entorno (NEXTPDF_MCP_*).
La sección nextpdf_mcp del archivo de configuración YAML.
Valores predeterminados integrados.

El archivo YAML se pasa con --config=PATH. Si no se proporciona, el servidor usa únicamente los valores predeterminados y las variables de entorno. El McpConfig resultante es un objeto de valor readonly. Ningún ajuste cambia después del arranque.

Los servidores REST y gRPC leen HttpConfig desde el entorno durante el arranque. Las anulaciones de entorno admitidas son NEXTPDF_BIND, NEXTPDF_WORKER_COUNT, NEXTPDF_SESSIONS_ENABLED y NEXTPDF_CORS_ENABLED. Los topes restantes tienen valores predeterminados seguros.

Superficie de la API

Configuración de MCP (`nextpdf-mcp`)

Archivo YAML, sección nextpdf_mcp:

nextpdf_mcp:
  enabled_tools: []          # empty/absent = all available tools allowed
  temp_directory: /tmp/nextpdf-mcp
  max_documents: 50
  document_ttl: 1800
  max_file_size_bytes: 104857600
  allow_file_output: true
  compress: true
  risk_level_overrides:
    fill_form: 3             # raise fill_form to ApprovalRequired (see below)

Anulaciones de entorno para el servidor MCP:

Variable	Clave de configuración	Predeterminado
`NEXTPDF_MCP_ENABLED_TOOLS`	`enabled_tools`	todas las herramientas permitidas
`NEXTPDF_MCP_TEMP_DIR`	`temp_directory`	directorio temp del sistema + `/nextpdf-mcp`
`NEXTPDF_MCP_MAX_FILE_SIZE`	`max_file_size_bytes`	`104857600` (100 MB)
`NEXTPDF_MCP_MAX_DOCUMENTS`	`max_documents`	`50`
`NEXTPDF_MCP_DOCUMENT_TTL`	`document_ttl`	`1800` segundos
`NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED`	(controla `parse_pdf`)	sin definir (deshabilitado)
`NEXTPDF_AST_TOOLS_ENABLED`	(controla las herramientas AST)	habilitado
`NEXTPDF_MUTATION_TOOLS_ENABLED`	(controla las herramientas de mutación AST)	sin definir (deshabilitado)

Configuración de REST y gRPC

Variable	Predeterminado	Efecto
`NEXTPDF_BIND`	`0.0.0.0:8080`	Dirección de escucha de REST
`NEXTPDF_WORKER_COUNT`	`4`	Número de workers de PHP de RoadRunner
`NEXTPDF_SESSIONS_ENABLED`	`false`	Habilitar los endpoints de sesión con estado
`NEXTPDF_CORS_ENABLED`	`false`	Habilitar los encabezados de respuesta CORS
`NEXTPDF_API_KEYS`	sin definir	Definiciones de claves de API en línea
`NEXTPDF_API_KEYS_FILE`	sin definir	Ruta a un archivo de claves de API
`NEXTPDF_JOB_STORE_PATH`	temp del sistema	Ruta del almacén de trabajos SQLite
`NEXTPDF_REDIS_HOST`	sin definir	Habilita los almacenes respaldados por Redis cuando se define

Redis (usado por el servidor REST cuando se define NEXTPDF_REDIS_HOST y se carga ext-redis):

Variable	Predeterminado
`NEXTPDF_REDIS_PORT`	`6379`
`NEXTPDF_REDIS_PASSWORD`	vacío
`NEXTPDF_REDIS_DATABASE`	`0`
`NEXTPDF_REDIS_PREFIX`	`nextpdf:`
`NEXTPDF_REDIS_CONNECT_TIMEOUT`	`2.0` segundos
`NEXTPDF_REDIS_READ_TIMEOUT`	`2.0` segundos

Ejemplo de código — Inicio rápido

Ejecutar el servidor MCP con un archivo de configuración explícito:

./vendor/bin/nextpdf-mcp --config=/etc/nextpdf/nextpdf-mcp.yaml

Ejemplo de código — Producción

Restringir el catálogo de MCP a una lista de permitidos explícita y elevar el riesgo de una herramienta:

nextpdf_mcp:
  enabled_tools:
    - create_pdf
    - add_text
    - output_pdf
    - diagnostic.doctor
  temp_directory: /var/lib/nextpdf/tmp
  max_file_size_bytes: 26214400
  risk_level_overrides:
    add_text: 2          # upgrade add_text from caution to review

Con un enabled_tools no vacío, la política de seguridad permite solo los nombres de herramienta listados. Cualquier otra herramienta se descarta silenciosamente del registro. Una lista vacía o ausente permite todas las herramientas disponibles.

Casos límite y trampas

Las dos herramientas críticas no se pueden degradar. output_pdf y sign_pdf están sujetas a aprobación por diseño: una entrada de risk_level_overrides que rebaje cualquiera de las dos por debajo de ApprovalRequired lanza una InvalidArgumentException en el momento de la carga y el servidor se niega a arrancar. El nivel de riesgo de cualquier otra herramienta se puede elevar o rebajar, por lo que conviene revisar cualquier degradación frente al propio modelo de amenazas. Más detalles en /connect/hitl-risk-tiers/.
enabled_tools filtra, no añade. Listar el nombre de una herramienta Pro cuando nextpdf/premium está ausente no hace que aparezca. La lista de permitidos se calcula por intersección con las herramientas que el registro realmente descubrió.
El entorno prevalece sobre el YAML para el servidor MCP. Una variable NEXTPDF_MCP_* anula la misma clave en el archivo YAML. Los servidores REST y gRPC no leen en absoluto el archivo YAML de MCP.
parse_pdf es opcional (opt-in). La herramienta parse_pdf se registra solo cuando NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED es true o 1. Está ausente de forma predeterminada, incluso en el catálogo del núcleo.

Rendimiento

La configuración se analiza una sola vez durante el arranque. Los ajustes max_documents y document_ttl acotan el almacén de documentos en memoria. Reducirlos disminuye el pico de memoria a costa de tiempos de vida más cortos para los documentos. El número de workers y los topes de carga útil por nivel son parámetros de ajuste del despliegue que se tratan en /connect/deployment/.

Notas de seguridad

Tratar enabled_tools como una superficie de control con denegación predeterminada para despliegues de mínimo privilegio: listar solo las herramientas que necesita una integración dada.
Nunca almacenar claves de API en el archivo YAML. Usar NEXTPDF_API_KEYS_FILE con un archivo montado como secreto de Docker o Kubernetes. El servidor prefiere un almacén de archivos con recarga en caliente para que las claves roten sin reiniciar. Más detalles en /connect/security-and-operations/.
El temp_directory es el directorio base obligatorio para la salida de archivos. El servidor canoniza las rutas de salida y rechaza cualquiera que se resuelva fuera de él.

Conformidad

Esta página describe el funcionamiento de la configuración. Las referencias de conformidad sobre autenticación y seguridad del transporte se mantienen en /connect/security-and-operations/.

Contexto comercial

Los topes de carga útil y de tiempo de espera por nivel (corePayloadLimit, proPayloadLimit, enterprisePayloadLimit y los tiempos de espera correspondientes) se aplican en el transporte REST según el nivel de la clave de API autenticada. Surten efecto solo cuando hay herramientas Pro o Enterprise instaladas y la clave está autorizada para usarlas.

Véase también

/connect/install/ — instalación y paquetes opcionales
/connect/boot-and-discovery/ — cómo la configuración alimenta la secuencia de arranque
/connect/hitl-risk-tiers/ — el modelo de riesgo y la anulación solo-hacia-arriba
/connect/security-and-operations/ — configuración de claves de API y seguridad del transporte
/connect/deployment/ — número de workers, Redis y topes de nivel en producción