Démarrage rapide de NextPDF Connect

En bref

Cette page te fait exécuter le plus petit échange utile sur les deux transports : MCP et REST. Chaque requête utilise exactement le format de communication implémenté par le serveur. Aucun kit de développement logiciel (SDK) n’est utilisé.

Installation

composer require nextpdf/server

Vue d’ensemble conceptuelle

Le transport MCP utilise JSON-RPC 2.0 sur l’entrée et la sortie standard. La séquence est obligatoire et doit être exécutée dans l’ordre. Envoie d’abord initialize. Envoie ensuite l’accusé de réception notifications/initialized. Envoie ensuite tools/list et tools/call. Le serveur lit un message JSON par ligne, chaque ligne étant terminée par un saut de ligne. Il écrit une réponse par ligne.

Le transport REST expose les mêmes capacités du moteur sous forme d’opérations HTTP. Un rendu unique et sans état correspond à un seul POST /api/v1/render avec un tableau d’opérations ordonné. Le corps de la réponse est le PDF.

Exemple de code — Démarrage rapide (MCP sur stdio)

Démarre le serveur et transmets-lui le handshake. Les trois requêtes ci-dessous utilisent les noms de méthode vérifiés que le gestionnaire de protocole achemine :

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"quickstart","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
EOF

La réponse initialize indique la version de protocole 2025-06-18, le nom du serveur NextPDF Connect et un bloc capabilities.nextpdf. Ce bloc contient les compteurs de niveau en direct, le tool_count à l’exécution, la version du modèle de risque et hitl_enabled: true. La réponse tools/list énumère exactement les outils enregistrés par cette installation. La ligne de notification ne produit aucune réponse, par conception.

Appelle maintenant un outil sûr. L’outil diagnostic.doctor effectue un contrôle de l’environnement en lecture seule. Il n’a besoin ni de document ni de confirmation :

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"quickstart","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"diagnostic.doctor","arguments":{}}}
EOF

Exemple de code — Démarrage rapide (REST)

Démarre le serveur REST, puis effectue le rendu d’un PDF d’une ligne. Le serveur exige une clé d’API sur chaque point de terminaison autre que ceux de santé ; définis-en donc une d’abord :

export NEXTPDF_API_KEYS='npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef:demo:core:default'
./vendor/bin/rr serve -c .rr.yaml

Dans un second terminal, envoie une requête de rendu. Son corps est une RenderRequest. Elle contient un tableau operations ordonné d’opérations typées.

curl -sS -X POST http://localhost:8080/api/v1/render \
  -H 'Authorization: Bearer npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef' \
  -H 'Content-Type: application/json' \
  -d '{
        "page_size": "A4",
        "orientation": "portrait",
        "operations": [
          { "type": "add_text", "text": "Hello from NextPDF Connect" }
        ]
      }' \
  --output hello.pdf

Une réponse 200 contient le PDF (Content-Type: application/pdf), écrit dans hello.pdf. Les sondes de santé n’ont besoin d’aucune clé :

curl -sS http://localhost:8080/healthz

Cas limites et pièges

L’ordre du handshake compte. Le gestionnaire de protocole traite un message sans id comme une notification et ne renvoie rien. Envoie initialize avec un id, puis la notification initialized, puis tes requêtes qui portent un id.
Un id de requête répété est dédupliqué. Le gestionnaire met en cache les réponses récentes dans un tampon circulaire de 64 entrées. En présence d’un id en double, il renvoie la réponse mise en cache sans réexécuter l’outil. Utilise des id distincts.
Un outil à haut risque répond par un défi, pas par un résultat. Appeler output_pdf avec un file_path renvoie un défi de confirmation au lieu d’exécuter l’outil. Réinvoque avec le _confirmation_token émis. Le mode de sortie base64 (sans file_path) n’exige aucune confirmation. Voir /connect/hitl-risk-tiers/.
Une requête REST non autorisée reçoit un 401. Un en-tête Authorization: Bearer manquant ou mal formé renvoie un corps problem-details avec un en-tête WWW-Authenticate: Bearer. Les sondes /healthz et /readyz sont les seuls points de terminaison accessibles sans authentification.

Performance

Les deux parcours de démarrage rapide utilisent une requête unique. Le parcours REST assume aussi le coût de démarrage à froid du pool de workers RoadRunner sur la première requête après rr serve. Les requêtes ultérieures réutilisent des workers chauds.

Notes de sécurité

La clé npk_live_ ci-dessus est une valeur de démonstration jetable. Génère de vraies clés avec une entropie suffisante, stocke-les en dehors du contrôle de version et privilégie le magasin de clés basé sur fichier pour la rotation. Le transport stdio MCP n’a pas de clé d’API, car il s’agit d’un sous-processus local approuvé par le client qui le lance, conformément au modèle de transport MCP. Voir /connect/security-and-operations/.

Conformité

Les formats de communication présentés correspondent à la révision MCP implémentée 2025-06-18 et au contrat REST OpenAPI 3.1. Les citations normatives de protocole et d’authentification sont épinglées sur /transports/mcp/, /transports/rest/, et /connect/security-and-operations/.

Voir aussi

/transports/mcp/ — la référence complète du transport MCP
/transports/rest/ — la référence complète du transport REST et le rendu OpenAPI
/connect/tool-catalog/ — quels outils tools/list renvoie et pourquoi
/connect/hitl-risk-tiers/ — à quoi ressemble un défi de confirmation
/connect/configuration/ — restreindre le catalogue et régler le serveur