Dépannage de NextPDF Connect

En bref

La plupart des échecs relèvent de l’un de ces cinq groupes : un échange d’initialisation JSON-RPC mal formé, une clé d’API manquante, un outil qui n’est pas installé dans ce niveau, un défi de confirmation resté sans réponse ou un store non partagé entre les workers. Chaque groupe a une signature distincte.

Installation

composer require nextpdf/server

Vue d’ensemble conceptuelle

Le transport MCP renvoie des objets d’erreur JSON-RPC 2.0 avec des codes standard. Le transport REST renvoie des documents problem-details RFC 7807. Chacun contient une URL type qui identifie la condition. Pour les problèmes d’environnement, commence par les outils de diagnostic (diagnostic.doctor, diagnostic.capabilities). Ces outils sont toujours présents dans le catalogue principal.

Surface d’API

Codes d’erreur JSON-RPC du MCP

Code	Nom	Cause
`-32700`	Erreur d’analyse	La ligne ne contenait pas de JSON valide
`-32600`	Requête invalide	Message non conforme à JSON-RPC 2.0 (`jsonrpc`/`method` manquant)
`-32601`	Méthode introuvable	Méthode différente de `initialize`, `tools/list` ou `tools/call`
`-32602`	Paramètres invalides	Champ `params.name` absent sur `tools/call`
`-32603`	Erreur interne	L’outil a levé une exception pendant l’exécution

Un outil qui échoue proprement n’utilise pas ces codes. À la place, il renvoie une réponse JSON-RPC réussie dont le résultat contient isError: true et une explication textuelle, par exemple un outil inconnu, un outil désactivé par la politique ou des arguments invalides.

Types de problem-details REST

HTTP	`type` slug	Cause
`401`	`unauthorized`	Clé d’API manquante, invalide, désactivée ou expirée
`403`	`capability-denied`	Le niveau de la clé n’autorise pas l’opération
`413`	`payload-too-large` / `tier-payload-exceeded`	Le corps dépasse le plafond global ou celui du niveau
`422`	`validation-failed`	Le corps de la requête n’a pas satisfait la validation du schéma
`429`	`ip-rate-exceeded` / `client-rate-exceeded`	Une limite de débit a été atteinte
`404`	`not-found`	Route inconnue ou id de job/session inconnu
`504`	(délai de requête dépassé)	L’opération a dépassé le délai d’expiration du niveau

Exemple de code — Démarrage rapide

Exécute le bilan de santé de l’environnement. Il n’a besoin d’aucun document ni d’aucune confirmation :

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"diag","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 — Production

Vérifie quels outils ce déploiement expose avant de déboguer un « outil manquant » :

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

ou, sur un serveur REST en cours d’exécution :

curl -sS http://localhost:8080/api/v1/capabilities \
  -H "Authorization: Bearer $NEXTPDF_KEY"

Cas limites et pièges

« Outil inconnu » pour un outil Pro/Enterprise. Le package contenant l’outil n’est pas installé. Le registre sonde les classes de fournisseur et ignore les niveaux absents sans avertissement. C’est le comportement attendu, pas un bug. Installe nextpdf/premium à côté du serveur, ou utilise un outil du catalogue principal. Le message d’erreur indique le chemin d’installation.
Un outil que j’ai configuré dans enabled_tools n’apparaît pas. La liste d’autorisation est croisée avec les outils découverts. Elle ne peut pas ajouter un outil que le registre n’a pas trouvé. Vérifie l’installation du niveau et les éventuels garde-fous d’environnement. Par exemple, parse_pdf est en opt-in via NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED.
tools/call a renvoyé un texte demandant un token. C’est le défi de confirmation, pas une erreur. Appelle de nouveau l’outil avec _confirmation_token défini sur le token émis, dans un délai de 300 secondes. Voir /connect/hitl-risk-tiers/.
La ligne de notification n’a produit aucune sortie. C’est correct. Un message JSON-RPC sans id est une notification, et le gestionnaire ne renvoie rien. Envoie des requêtes portant un id pour obtenir des réponses.
Un id de requête réutilisé a renvoyé une réponse périmée. Le gestionnaire supprime les doublons par id de requête dans un tampon de 64 entrées. Utilise un nouvel id pour chaque requête logique.
Les limites de débit se comportent de façon incohérente entre les workers. Le store en mémoire est propre à chaque worker. Pour un comptage partagé, définis NEXTPDF_REDIS_HOST et installe ext-redis. Voir /connect/deployment/.
Les documents disparaissent entre les requêtes. Le store de documents en mémoire est propre à chaque worker et limité par une durée de vie (document_ttl, 1800 s par défaut). Pour préserver la continuité des documents entre workers, utilise le store adossé à Redis, les points de terminaison de session, ou garde toutes les opérations dans un seul rendu synchrone.
Le serveur est retombé sur le mode en mémoire malgré la configuration Redis. Le serveur REST revient automatiquement en mode en mémoire si la connexion Redis échoue au démarrage. Vérifie l’accessibilité de Redis et confirme que ext-redis est présent dans l’image en cours d’exécution. Ne présume pas que Redis est utilisé sans l’avoir vérifié.
Le serveur refuse de démarrer avec une erreur de configuration. Une entrée risk_level_overrides a tenté de rétrograder un outil ApprovalRequired. Le chargeur rejette cela par conception. Supprime la rétrogradation ; les overrides ne peuvent qu’élever le risque.

Performance

Si les rendus sont lents sous charge, vérifie que le pool de workers n’est pas saturé. Vérifie le point de terminaison de métriques RoadRunner. Déplace ensuite les rendus longs vers le chemin de job asynchrone afin que les workers ne restent pas immobilisés. Voir /connect/production-usage/.

Notes de sécurité

Ne contourne pas un 401 en exposant le transport MCP non authentifié sur un réseau : cela supprime entièrement l’authentification. Corrige plutôt la clé d’API. N’augmente pas la verbosité des logs pour inspecter les arguments des outils dans un environnement partagé ; les charges utiles des arguments peuvent être sensibles. Voir /connect/security-and-operations/.

Conformité

Cette page est un guide opérationnel. Les citations de protocole et de sécurité s’appuient sur /transports/mcp/, /transports/rest/, et /connect/security-and-operations/.

Voir aussi

/connect/tool-catalog/ — ce que contient le catalogue principal et pourquoi le nombre varie
/connect/hitl-risk-tiers/ — les défis de confirmation en détail
/connect/deployment/ — Redis, pools de workers et partage du store
/connect/security-and-operations/ — défaillances d’authentification et posture