Intégration de NextPDF Connect

En un coup d’œil

Intègre NextPDF Connect en l’exécutant comme un serveur. Tu ne câbles pas une bibliothèque à une application hôte. Choisis un transport, puis configure l’authentification lorsque ce transport passe par le réseau. Les outils du moteur restent derrière la barrière de confirmation.

Installation

composer require nextpdf/server

La contrainte Composer est nextpdf/core: ^3.0 avec php: >=8.4 <9.0. Pour ext-redis et nextpdf/premium, optionnels, consulte /connect/install/.

Vue d’ensemble conceptuelle

Le package est un service autonome. Il n’y a ni service provider ni bundle ni module de conteneur à enregistrer dans un framework hôte. Le point d’intégration est le processus que tu lances. Chaque transport a son propre point d’entrée et démarre indépendamment. Consulte /connect/boot-and-discovery/.

Surface de l’API

Point d’entrée	Transport	Profil
bin/nextpdf-mcp	MCP sur stdio	(aucun — sous-processus direct)
bin/nextpdf-server	REST sur RoadRunner HTTP	.rr.yaml
bin/nextpdf-grpc	gRPC sur RoadRunner gRPC	.rr.grpc.yaml
les deux transports réseau	REST + gRPC	.rr.full.yaml

Démarrage et auto-découverte

Le registre détecte toujours le niveau core. Il ajoute ensuite les providers Pro et Enterprise lorsque leurs classes peuvent être résolues, puis les providers AST et de mutation fournis, selon les variables d’environnement. La liste d’autorisation de sécurité enabled_tools filtre l’ensemble de ces outils, si bien que le catalogue exposé est propre à ce déploiement. Consulte /connect/tool-catalog/ et /connect/boot-and-discovery/.

Liaisons du conteneur

Aucune. Chaque fabrique de serveur construit explicitement son propre graphe d’objets. Les points d’injection sont destinés aux tests, pas au câblage applicatif.

Publier la configuration

Le serveur MCP accepte un fichier YAML optionnel (--config=PATH, section nextpdf_mcp) et des surcharges d’environnement NEXTPDF_MCP_*. Les serveurs REST et gRPC lisent les variables d’environnement NEXTPDF_*. Pour le détail, consulte /connect/configuration/.

Disponibilité des transports (MCP / REST / gRPC)

Les trois transports servent le même registre :

• MCP — sous-processus local, JSON-RPC 2.0 sur stdio, sans clé API, révision MCP 2025-06-18. Consulte /transports/mcp/.
• REST — pool de workers RoadRunner HTTP, contrat OpenAPI 3.1, clé API bearer, routes contrôlées par niveau. Consulte /transports/rest/.
• gRPC — pool de workers RoadRunner gRPC, service Protobuf nextpdf.connect.v1, RPC en streaming serveur, authentification bearer dans les métadonnées, TLS mutuel dans le profil combiné. Consulte /transports/grpc/.

Un transport est « disponible » lorsque son point d’entrée ou son profil RoadRunner tourne. Les transports ne se lancent pas mutuellement automatiquement.

Niveau de risque HITL

Chaque outil déclare l’un des quatre niveaux de risque — safe, caution, review, approval_required. Les outils en approval_required ne s’exécutent pas dès le premier appel. La barrière de confirmation émet un jeton de défi à usage unique qu’un humain doit autoriser. Une surcharge de configuration ne peut qu’élever le risque d’un outil, jamais abaisser le niveau d’un outil en approval_required. Le modèle s’applique à l’identique sur chaque transport qui pilote des outils. Consulte /connect/hitl-risk-tiers/.

Enveloppe JSON de la barrière de confirmation

La vérification de la barrière renvoie l’une des deux formes JSON. Autorisé :

{ "allowed": true }

Défi :

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

Le jeton lie le nom de l’outil, un nonce aléatoire et un TTL de 300 secondes — pas les arguments. Pour continuer, l’appelant réinvoque le même outil avec un argument _confirmation_token défini sur le jeton émis. Le défi est un simple texte d’instruction accompagné du jeton ; ce n’est pas une enveloppe signée cryptographiquement. Consulte /connect/hitl-risk-tiers/.

Smoke test du service

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

Cette commande démarre le registre et la détection de niveau, puis affiche les outils exposés sans traiter de trafic. C’est un moyen rapide de confirmer que l’intégration est câblée et de vérifier quel catalogue cette installation produit.

Cas limites et pièges

• Aucun hook de framework. Ne cherche pas de service provider ni de bundle. L’intégration, c’est le processus qui tourne.
• Un niveau manquant n’est pas une erreur. L’installation core-only démarre et expose son catalogue core.
• Les transports réseau exigent une clé. Seuls /healthz et /readyz (REST) et les RPC de santé (gRPC) sont anonymes.

Performance

Le coût de démarrage correspond au scan du registre et à la détection de niveau, une fois par processus. Le coût par requête correspond à l’opération du moteur. Dimensionne les pools de workers RoadRunner en fonction de la latence de rendu observée. Consulte /connect/production-usage/.

Notes de sécurité

Les transports réseau s’authentifient avec une clé bearer npk_live_ validée en temps constant ; la barrière impose la confirmation humaine pour les opérations destructrices, quel que soit le transport. Termine TLS en amont de REST et utilise le TLS mutuel pour gRPC sur les réseaux non fiables. Consulte /connect/security-and-operations/.

Conformité

Les citations relatives aux protocoles et à la sécurité sont maintenues dans /transports/mcp/, /transports/rest/, /transports/grpc/, et /connect/security-and-operations/.

Contexte commercial

Installer nextpdf/premium avec le serveur enregistre les outils Pro et Enterprise supplémentaires dans le même serveur en cours d’exécution. Aucun processus séparé n’est en jeu.

Voir aussi

• /connect/overview/ — l’architecture
• /connect/quickstart/ — le premier échange à exécuter
• /transports/mcp/ · /transports/rest/ · /transports/grpc/ — références par transport
• /connect/hitl-risk-tiers/ — la barrière de confirmation en détail
• /connect/tool-catalog/ — le catalogue dépendant de l’exécution
• /connect/security-and-operations/ — authentification et modèle de menace