Présentation du serveur NextPDF Connect

En un coup d’œil

NextPDF Connect, c’est le package nextpdf/server : un service longue durée qui expose le moteur PDF 2.0 de NextPDF aux agents IA et aux clients HTTP. Il s’appuie sur trois transports : Model Context Protocol (MCP) sur stdio, une API REST et gRPC. Les trois transports partagent un même registre d’outils et une même barrière de confirmation humaine dans la boucle (HITL).

Installation

composer require nextpdf/server

La contrainte Composer est nextpdf/core: ^3.0 avec php: >=8.4 <9.0. Pour la procédure complète, consulte /connect/install/. Cette page présente aussi deux extensions optionnelles : l’extension ext-redis et le package nextpdf/premium.

Vue d’ensemble conceptuelle

nextpdf/server adapte le cœur de NextPDF, indépendant de tout framework, sous forme d’interface de service. Il ne réimplémente pas la génération de PDF. À la place, il encapsule chaque capacité du moteur dans un outil nommé, doté de son propre schéma, puis expose ce catalogue via plusieurs protocoles réseau.

Toute la conception repose sur trois concepts :

Le registre d’outils. NextPDF\Server\ToolRegistry découvre et enregistre les outils au démarrage. Un ensemble de base est inclus dans le package et reste toujours disponible. Les fournisseurs Pro et Enterprise enregistrent des outils supplémentaires, mais uniquement quand les packages correspondants sont installés. Le nombre d’outils exposés est donc une propriété du déploiement à l’exécution, pas une constante figée. Voir /connect/tool-catalog/.
Les transports. Le même registre est servi de trois manières. MCP fonctionne sur stdio pour les clients IA locaux. REST s’appuie sur un pipeline de middleware PSR-15 dans un pool de workers RoadRunner, pour les clients en réseau. gRPC s’appuie sur un worker gRPC Spiral RoadRunner, pour les clients typés et en streaming. Chaque transport s’exécute dans son propre processus, avec son propre point d’entrée. Voir /transports/mcp/, /transports/rest/ et /transports/grpc/.
La barrière de confirmation. Chaque outil déclare un niveau de risque. Un outil du niveau le plus élevé exige une confirmation humaine explicite avant de s’exécuter. La barrière émet un jeton de défi à usage unique. L’agent doit transmettre ce jeton à un humain, puis appeler de nouveau l’outil avec le jeton. Voir /connect/hitl-risk-tiers/.

Le schéma ci-dessous montre comment un même registre alimente les trois transports. Il indique aussi où se situe la barrière de confirmation dans le chemin de la requête.

NextPDF Connect component architecture

Le package est sous licence Apache-2.0, ce qui correspond à nextpdf/core. La version implémentée du protocole MCP est la révision datée 2025-06-18. Un document OpenAPI 3.1 décrit l’interface REST. Le package Protocol Buffers nextpdf.connect.v1 décrit l’interface gRPC.

Surface de l’API

Les points d’entrée publics sont les trois classes de serveur. Chacune dispose d’un wrapper en ligne de commande (CLI) :

Point d’entrée	Classe	Transport
`bin/nextpdf-mcp`	`NextPDF\Server\Mcp\McpServer`	MCP sur stdio
`bin/nextpdf-server`	`NextPDF\Server\Http\HttpServer`	REST sur RoadRunner HTTP
`bin/nextpdf-grpc`	`NextPDF\Server\Grpc\GrpcServer`	gRPC sur RoadRunner gRPC
`bin/generate-skills`	`NextPDF\Server\Skills\SkillsDumper`	Export du catalogue d’outils

McpServer::create(), HttpServer::create() et GrpcServer::create() construisent chacune un serveur entièrement configuré à partir des entrées d’environnement et de configuration. Le registre, le magasin de documents, la politique de sécurité et la barrière de confirmation sont des concepts partagés par les trois serveurs.

Exemple de code — Démarrage rapide

Le serveur MCP minimal se lance avec une seule commande. Tu n’as aucun code de liaison PHP à écrire :

./vendor/bin/nextpdf-mcp

Le serveur lit les requêtes JSON-RPC depuis l’entrée standard et écrit les réponses sur la sortie standard. Pour un échange initialize et tools/list exécutable, ainsi que pour la requête REST correspondante, voir /connect/quickstart/.

Cas limites et pièges

Le nombre d’outils n’est pas 33, ni aucun autre nombre figé. Le serveur compte les outils à l’exécution via count(ToolRegistry::all()), après le filtrage par la politique et la détection du niveau. Toute documentation qui cite un total figé est périmée. Pour obtenir le décompte qui fait autorité, interroge le serveur en cours d’exécution. Utilise la réponse initialize de MCP, ou le point de terminaison REST /api/v1/capabilities.

Le nombre d’outils exposés dépend des packages installés et de la politique active. Lis-le depuis le serveur en cours d’exécution, à l’exécution. Un nombre figé recopié dans ton propre code ou ta documentation finira par être obsolète.
L’absence d’un package Pro ou Enterprise n’est pas une erreur. Le registre vérifie la présence des classes de fournisseur avec class_exists(), puis ignore silencieusement tout niveau absent. Un déploiement uniquement open source démarre et sert son catalogue de base normalement.
Les trois transports ne partagent pas de processus. Lancer le serveur MCP ne démarre ni le serveur REST ni le serveur gRPC. L’inverse est également vrai. Un déploiement combiné fait tourner le superviseur RoadRunner avec une configuration qui démarre les deux pools de workers : le pool HTTP et le pool gRPC. Voir /connect/deployment/.

Performance

Chaque transport repose sur des workers. Un worker traite une requête à la fois. Les serveurs REST et gRPC s’exécutent dans des pools de workers RoadRunner, et la configuration définit la taille du pool. La valeur par défaut est de quatre workers HTTP. Le superviseur RoadRunner plafonne la mémoire de chaque worker. Le performance_budget du frontmatter de cette page décrit une enveloppe de démarrage à froid et de découverte. Ce n’est pas un objectif par requête. L’opération sous-jacente du moteur représente l’essentiel du coût de chaque requête.

Notes de sécurité

Tous les transports en réseau s’authentifient au moyen d’un jeton porteur de type clé d’API. Le transport MCP sur stdio est un sous-processus local auquel le client qui le lance fait confiance, conformément au modèle de transport MCP. Les outils à haut risque restent verrouillés derrière une confirmation humaine sur chaque transport. Pour le modèle de menace complet, le modèle d’authentification et la configuration de sécurité des transports, voir /connect/security-and-operations/.

Conformité

Cette page ne formule que des affirmations architecturales. Les citations normatives de protocole et de sécurité sont épinglées sur les pages qui spécifient le comportement : /connect/security-and-operations/, /transports/mcp/, /transports/rest/ et /transports/grpc/. La référence du cycle de vie MCP est la spécification officielle sur modelcontextprotocol.io (révision 2025-06-18). Les pages de transport consignent cette référence avec son URL, car la spécification MCP ne fait pas partie du corpus de normes contrôlées.

Contexte commercial

Le catalogue de base est complet pour la création, l’inspection et le diagnostic de documents. Les outils de signature, de caviardage, de certification de conformité et d’analyse forensique n’apparaissent que lorsque nextpdf/premium est installé aux côtés du serveur. C’est une frontière de packaging, pas une incitation à l’achat au moment de l’exécution. Le serveur n’émet jamais de contenu marketing.

Voir aussi

/connect/install/ — installation et packages optionnels
/connect/quickstart/ — premier échange MCP et REST exécutable
/connect/tool-catalog/ — l’ensemble d’outils de base vérifié et la façon dont le décompte dépend de l’exécution
/connect/hitl-risk-tiers/ — la barrière de confirmation et le modèle de risque
/transports/mcp/, /transports/rest/, /transports/grpc/ — configuration par transport
/connect/security-and-operations/ — authentification, sécurité des transports, modèle de menace
/connect/deployment/ — déploiement RoadRunner, Docker et transport combiné