Génère ton premier PDF avec NextPDF Connect

En bref

Cette recette te guide au plus direct, d’une session vide à un PDF généré avec NextPDF Connect. Tu crées un document A4 d’une seule page, tu écris un titre et un sous-titre, puis tu renvoies le fichier en base64. Trois outils Core font tout le travail : create_pdf, add_text et output_pdf. Tu n’as besoin ni de police, ni d’image, ni d’édition sous licence.

Un transport Connect achemine chaque appel d’outil comme une requête et renvoie le résultat de l’outil comme une réponse. La couche de transport ne dépend pas du résultat renvoyé par l’outil (PSR-18 §p2).

Installer

Installe NextPDF Server et associe un transport :

composer require nextpdf/server

Démarre le serveur avec le transport attendu par ton hôte : Model Context Protocol via stdio, REST ou gRPC. Consulte Disponibilité des transports ci-dessous. Les outils de cette recette sont des outils Core. Ils sont livrés avec le serveur ; tu n’as donc besoin d’aucun paquet Pro ou Enterprise.

Vue d’ensemble conceptuelle

Une session Connect est un magasin de documents côté serveur, indexé par un document_id. create_pdf ouvre une session et renvoie l’id. Chaque appel d’outil ultérieur fait référence à cet id. Le document démarre avec une page vierge. L’arbre des pages est la structure qui permet à un lecteur d’atteindre chaque page (ISO 32000-2 §7.7.3). output_pdf transforme la session en PDF. Par défaut, il détruit ensuite la session pour libérer la mémoire.

Quand tu appelles add_text sans x ou y explicite, le texte se place automatiquement : il commence au curseur courant, puis le curseur avance après chaque appel.

Surface d’API

Le registre d’outils résout les outils ci-dessous au démarrage du serveur. Ces noms sont les noms de protocole du registre. Le catalogue de référence est le catalogue d’outils fusionné. La disponibilité des outils dépend de l’édition installée, mais ces trois-là sont toujours présents dans Core.

Outil	Rôle	Niveau de risque
create_pdf	Ouvrir une session de document	Sûr
add_text	Écrire du texte dans le document	Prudence
output_pdf	Rendre et renvoyer le PDF	Approbation requise (mode fichier) / Revue (base64)

Exemple de code — Démarrage rapide

L’hôte effectue trois appels d’outil. Les voici en toutes lettres :

1. Appelle create_pdf avec page_size: "A4", orientation: "portrait", ainsi que le titre et l’auteur du document. Le serveur renvoie un document_id.
2. Appelle add_text avec ce document_id, le texte du titre, une grande font_size, width: 0 (toute la largeur du contenu) et alignment: "center".
3. Appelle output_pdf avec le document_id. Sans file_path, le serveur renvoie le PDF en base64 et détruit la session.

Voici un objet d’arguments create_pdf minimal :

{
  "page_size": "A4",
  "orientation": "portrait",
  "title": "Hello World",
  "author": "NextPDF Cookbook"
}

La réponse contient le document_id, le nombre de pages et la géométrie de la page. Traite l’id comme une valeur opaque et n’y cherche aucune signification.

Exemple de code — Production

En production, l’appelant vérifie chaque réponse avant l’appel suivant. Il ne réutilise jamais un document_id après que output_pdf a détruit la session.

1. create_pdf — confirme que la réponse contient un document_id. Si le serveur renvoie l’erreur de limite de sessions, libère les sessions inutilisées et réessaie.
2. add_text (titre) — confirme que la réponse contient une position.
3. add_text (sous-titre) — utilise une font_size plus petite ; le curseur continue sous le titre.
4. output_pdf — lis le champ base64 et décode-le en octets. Le drapeau destroyed confirme que la session a disparu.

Le fichier est renvoyé en ligne (mode base64), donc il n’y a aucun effet de bord sur le système de fichiers ni aucune barrière d’approbation humaine — voir Niveau de risque HITL.

Cas limites & pièges

• Session détruite. Une fois output_pdf exécuté avec la valeur par défaut destroy: true, le document_id n’est plus valide. Tout appel ultérieur avec cet identifiant renvoie une erreur de document inconnu. Crée plutôt une nouvelle session.
• Taille de page inconnue. Le serveur rejette une page_size qu’il ne reconnaît pas et renvoie une erreur claire. Utilise une taille documentée (A3, A4, A5, A6, Letter, Legal, Tabloid).
• Texte vide. Un text vide produit une entrée de largeur nulle, pas une erreur. Vérifie ta saisie avant l’appel.
• Limite de sessions. Le magasin en mémoire plafonne le nombre de sessions actives simultanément. Libère les sessions sans tarder avec output_pdf.

Performance

Une page unique constituée uniquement de texte reste largement dans le budget de page au rendu, et la sortie fait généralement 1–3 Ko. Le profil de reproductibilité en double rendu pour cette recette est structural. Le PDF porte un /ID de trailer et des horodatages qui changent d’une exécution à l’autre, donc une comparaison structurelle (normalisée) est la comparaison pertinente.

Notes de sécurité

Le mode base64 n’a aucun effet de bord sur le système de fichiers. La sortie vers un fichier en a un, et elle est protégée — voir la section HITL. Traite le base64 renvoyé comme du contenu de document, pas comme un canal de confiance. Ce sont exactement les octets que les outils ont produits.

Conformité

Énoncé	Spécification	Clause	reference_id
Un transport envoie une requête et reçoit une réponse indépendamment du résultat.	PSR-18	§p2
Les pages sont atteintes via l’arbre des pages du document.	ISO 32000-2	§7.7.3

Cette recette décrit comment le serveur produit sa sortie. Elle ne revendique aucune conformité à un profil.

Contexte commercial

Sans objet — les trois outils sont Core.

Disponibilité des transports

Transport	Disponible	Notes
MCP (stdio)	Oui	Les appels d’outil correspondent à tools/call en MCP.
REST	Oui	Chaque outil est une opération REST ; le résultat est le corps de la réponse.
gRPC	Oui	Chaque outil est un appel unaire.

Le résultat de l’outil est identique d’un transport à l’autre ; seule l’enveloppe diffère. Un résultat d’outil en échec reste une réponse normale, pas un échec de transport (PSR-18 §p2).

Niveau de risque HITL

Le serveur place chaque appel d’outil sur une échelle de risque human-in-the-loop (HITL) : Sûr (0) → Prudence (1) → Revue (2) → Approbation requise (3). create_pdf est Sûr et add_text est Prudence. output_pdf est Approbation requise, mais en mode base64 (sans file_path) il redescend à Revue et s’exécute sans confirmation humaine. Écrire dans un fichier le maintient à Approbation requise — voir output-approval et la référence des niveaux de risque HITL.

Enveloppe JSON de la barrière de confirmation

Cette recette reste en mode base64, donc la barrière de confirmation renvoie l’enveloppe d’autorisation :

{ "allowed": true }

L’enveloppe de défi (allowed: false, avec une chaîne challenge et un token à usage unique) est documentée dans output-approval.

Voir aussi

• Document multipage
• Intégration d’images
• Catalogue d’outils
• Niveaux de risque HITL