Configurer NextPDF Connect

En bref

NextPDF Connect expose deux surfaces de configuration. Le serveur MCP lit un fichier YAML et les variables NEXTPDF_MCP_*. Les serveurs REST et gRPC lisent les variables d’environnement NEXTPDF_*. La configuration devient immuable dès le démarrage du serveur.

Installation

composer require nextpdf/server

Vue d’ensemble conceptuelle

Le serveur MCP résout la configuration selon un ordre de priorité fixe. La source la plus prioritaire l’emporte :

Les variables d’environnement (NEXTPDF_MCP_*).
La section nextpdf_mcp du fichier de configuration YAML.
Les valeurs par défaut intégrées.

Passe le fichier YAML avec --config=PATH. À défaut, le serveur s’appuie uniquement sur les valeurs par défaut et les variables d’environnement. Le McpConfig obtenu est un objet valeur readonly. Aucun paramètre ne change après le démarrage.

Les serveurs REST et gRPC lisent HttpConfig dans l’environnement au démarrage. Les surcharges par variable d’environnement prises en charge sont NEXTPDF_BIND, NEXTPDF_WORKER_COUNT, NEXTPDF_SESSIONS_ENABLED et NEXTPDF_CORS_ENABLED. Les autres plafonds conservent des valeurs par défaut sûres.

Surface de l’API

Configuration MCP (`nextpdf-mcp`)

Fichier YAML, section 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)

Surcharges par variables d’environnement pour le serveur MCP :

Variable	Clé de configuration	Valeur par défaut
`NEXTPDF_MCP_ENABLED_TOOLS`	`enabled_tools`	tous les outils autorisés
`NEXTPDF_MCP_TEMP_DIR`	`temp_directory`	répertoire temporaire système + `/nextpdf-mcp`
`NEXTPDF_MCP_MAX_FILE_SIZE`	`max_file_size_bytes`	`104857600` (100 Mo)
`NEXTPDF_MCP_MAX_DOCUMENTS`	`max_documents`	`50`
`NEXTPDF_MCP_DOCUMENT_TTL`	`document_ttl`	`1800` secondes
`NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED`	(contrôle `parse_pdf`)	non défini (désactivé)
`NEXTPDF_AST_TOOLS_ENABLED`	(contrôle les outils AST)	activé
`NEXTPDF_MUTATION_TOOLS_ENABLED`	(contrôle les outils de mutation AST)	non défini (désactivé)

Configuration REST et gRPC

Variable	Valeur par défaut	Effet
`NEXTPDF_BIND`	`0.0.0.0:8080`	Adresse d’écoute REST
`NEXTPDF_WORKER_COUNT`	`4`	Nombre de workers PHP RoadRunner
`NEXTPDF_SESSIONS_ENABLED`	`false`	Active les endpoints de session avec état
`NEXTPDF_CORS_ENABLED`	`false`	Active les en-têtes de réponse CORS
`NEXTPDF_API_KEYS`	non défini	Définitions de clés d’API en ligne
`NEXTPDF_API_KEYS_FILE`	non défini	Chemin vers un fichier de clés d’API
`NEXTPDF_JOB_STORE_PATH`	répertoire temporaire système	Chemin du magasin de tâches SQLite
`NEXTPDF_REDIS_HOST`	non défini	Active les magasins Redis lorsqu’elle est définie

Redis (utilisé par le serveur REST lorsque NEXTPDF_REDIS_HOST est défini et que ext-redis est chargé) :

Variable	Valeur par défaut
`NEXTPDF_REDIS_PORT`	`6379`
`NEXTPDF_REDIS_PASSWORD`	vide
`NEXTPDF_REDIS_DATABASE`	`0`
`NEXTPDF_REDIS_PREFIX`	`nextpdf:`
`NEXTPDF_REDIS_CONNECT_TIMEOUT`	`2.0` secondes
`NEXTPDF_REDIS_READ_TIMEOUT`	`2.0` secondes

Exemple de code — Démarrage rapide

Exécute le serveur MCP avec un fichier de configuration explicite :

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

Exemple de code — Production

Restreins le catalogue MCP à une allowlist explicite et relève le niveau de risque d’un outil :

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

Avec un enabled_tools non vide, la politique de sécurité n’autorise que les noms d’outils listés. Tout autre outil est retiré silencieusement du registre. Une liste vide ou absente autorise tous les outils disponibles.

Cas limites et pièges

Les deux outils critiques ne peuvent pas être rétrogradés. output_pdf et sign_pdf sont soumis à approbation par conception : une entrée risk_level_overrides qui abaisse l’un ou l’autre en dessous de ApprovalRequired déclenche une InvalidArgumentException au chargement et le serveur refuse de démarrer. Le niveau de risque de tout autre outil peut être relevé ou abaissé ; examine donc chaque rétrogradation en fonction de ton propre modèle de menace. Voir /connect/hitl-risk-tiers/.
enabled_tools filtre, il n’ajoute pas. Indiquer le nom d’un outil Pro alors que nextpdf/premium est absent ne le fait pas apparaître. L’allowlist est intersectée avec les outils que le registre a réellement découverts.
L’environnement l’emporte sur le YAML pour le serveur MCP. Une variable NEXTPDF_MCP_* remplace la clé correspondante dans le fichier YAML. Les serveurs REST et gRPC ne lisent pas du tout le fichier YAML du MCP.
parse_pdf est en opt-in. L’outil parse_pdf n’est enregistré que lorsque NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED vaut true ou 1. Il est absent par défaut, même dans le catalogue principal.

Performances

La configuration est analysée une seule fois au démarrage. Les paramètres max_documents et document_ttl bornent le magasin de documents en mémoire. Les réduire diminue le pic mémoire, au prix de durées de vie de document plus courtes. Le nombre de workers et les plafonds de charge utile par niveau sont des leviers de réglage du déploiement, traités dans /connect/deployment/.

Notes de sécurité

Traite enabled_tools comme un contrôle « refus par défaut » pour les déploiements au moindre privilège : ne liste que les outils dont une intégration donnée a besoin.
Ne stocke jamais les clés d’API dans le fichier YAML. Utilise NEXTPDF_API_KEYS_FILE avec un fichier monté comme secret Docker ou Kubernetes. Le serveur privilégie un magasin de fichiers à rechargement à chaud, ce qui permet la rotation des clés sans redémarrage. Voir /connect/security-and-operations/.
Le temp_directory est le répertoire de base imposé pour la sortie de fichiers. Le serveur résout canoniquement les chemins de sortie et rejette tout chemin qui pointe en dehors de ce répertoire.

Conformité

Cette page décrit les mécanismes de configuration. Les citations de conformité relatives à l’authentification et à la sécurité du transport se trouvent dans /connect/security-and-operations/.

Contexte commercial

Les plafonds de charge utile et de délai d’expiration par niveau (corePayloadLimit, proPayloadLimit, enterprisePayloadLimit et les délais d’expiration correspondants) s’appliquent au transport REST selon le niveau de la clé d’API authentifiée. Ils ne prennent effet que lorsque des outils Pro ou Enterprise sont installés et que la clé y donne accès.

Voir aussi

/connect/install/ — installation et packages optionnels
/connect/boot-and-discovery/ — comment la configuration alimente la séquence de démarrage
/connect/hitl-risk-tiers/ — le modèle de risque et la surcharge réservée à l’augmentation
/connect/security-and-operations/ — configuration des clés d’API et sécurité du transport
/connect/deployment/ — nombre de workers, Redis et plafonds de niveau en production