Risoluzione dei problemi di NextPDF Connect

In breve

La maggior parte degli errori rientra in cinque gruppi: handshake JSON-RPC non valido, chiave API mancante, strumento non installato in questo tier, richiesta di conferma rimasta senza risposta o store non condiviso tra i worker. Ogni gruppo ha una firma riconoscibile.

Installazione

composer require nextpdf/server

Panoramica concettuale

Il transport MCP restituisce oggetti di errore JSON-RPC 2.0 con codici standard. Il transport REST restituisce documenti problem-details RFC 7807. Ciascuno contiene un URL type che identifica la condizione. Per i problemi legati all’ambiente, iniziare dagli strumenti di diagnostica (diagnostic.doctor, diagnostic.capabilities). Questi strumenti sono sempre presenti nel catalogo core.

Superficie API

Codici di errore MCP JSON-RPC

Codice	Nome	Causa
`-32700`	Errore di parsing	La riga non era un JSON valido
`-32600`	Richiesta non valida	Non è un messaggio JSON-RPC 2.0 (manca `jsonrpc`/`method`)
`-32601`	Metodo non trovato	Metodo diverso da `initialize`, `tools/list`, `tools/call`
`-32602`	Parametri non validi	Manca `params.name` in `tools/call`
`-32603`	Errore interno	Lo strumento ha generato un’eccezione durante l’esecuzione

Quando uno strumento fallisce in modo controllato, non utilizza questi codici. Restituisce invece una risposta JSON-RPC con esito positivo, il cui risultato contiene isError: true e una spiegazione testuale, ad esempio strumento sconosciuto, disabilitato da policy o argomenti non validi.

Tipi di problem-details REST

HTTP	`type` slug	Causa
`401`	`unauthorized`	Chiave API mancante/non valida/disabilitata/scaduta
`403`	`capability-denied`	Il tier della chiave non è abilitato all’operazione
`413`	`payload-too-large` / `tier-payload-exceeded`	Il corpo della richiesta supera il limite globale o di livello
`422`	`validation-failed`	Il corpo della richiesta non supera la validazione dello schema
`429`	`ip-rate-exceeded` / `client-rate-exceeded`	È stato raggiunto un limite di frequenza
`404`	`not-found`	Route sconosciuta o id di job/session
`504`	(timeout della richiesta)	L’operazione ha superato il timeout del tier

Esempio di codice — Avvio rapido

Eseguire il controllo dello stato dell’ambiente. Non richiede alcun documento né alcuna conferma:

./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

Esempio di codice — Produzione

Verificare quali strumenti espone questo deployment prima di eseguire il debug di uno «strumento mancante»:

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

oppure, su un server REST in esecuzione:

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

Casi limite e insidie

«Strumento sconosciuto» per uno strumento Pro/Enterprise. Il pacchetto dello strumento non è installato. Il registry ispeziona le classi provider e ignora i livelli assenti senza avvisi. Si tratta di un comportamento previsto, non di un bug. Installare nextpdf/premium insieme al server oppure utilizzare uno strumento core. Il messaggio di errore include il percorso di installazione.
Uno strumento configurato in enabled_tools non compare. L’allowlist viene applicata per intersezione agli strumenti individuati. Non può aggiungere uno strumento che il registry non ha trovato. Verificare l’installazione del tier ed eventuali gate ambientali. Ad esempio, parse_pdf è attivabile in modo esplicito tramite NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED.
tools/call ha restituito un testo che richiede un token. Si tratta della richiesta di conferma, non di un errore. Richiamare lo strumento impostando _confirmation_token sul token emesso entro 300 secondi. Vedere /connect/hitl-risk-tiers/.
La riga di notifica non ha prodotto alcun output. È il comportamento corretto. Un messaggio JSON-RPC privo di id è una notifica e l’handler non restituisce nulla. Inviare richieste che includono un id per ottenere risposte.
Un id di richiesta ripetuto ha restituito una risposta obsoleta. L’handler rimuove i duplicati in base all’id di richiesta in un buffer da 64 voci. Utilizzare un nuovo id per ogni richiesta logica.
I limiti di frequenza risultano incoerenti tra i worker. Lo store in memoria è per singolo worker. Per un conteggio condiviso, impostare NEXTPDF_REDIS_HOST e installare ext-redis. Vedere /connect/deployment/.
I documenti scompaiono tra una richiesta e l’altra. Lo store dei documenti in memoria è per singolo worker ed è soggetto a un time to live (document_ttl, predefinito 1800 s). Per mantenere la continuità dei documenti tra i worker, utilizzare lo store basato su Redis, oppure gli endpoint di sessione, oppure mantenere l’intero set di operazioni in un unico rendering sincrono.
Il server è tornato alla modalità in memoria nonostante la configurazione di Redis. Il server REST esegue automaticamente il fallback se la connessione a Redis fallisce all’avvio. Verificare la raggiungibilità di Redis e controllare che ext-redis sia presente nell’immagine in esecuzione. Non dare per scontato che Redis sia in uso senza verificarlo.
Il server si rifiuta di avviarsi con un errore di configurazione. Una voce risk_level_overrides ha tentato di declassare uno strumento ApprovalRequired. Il loader rifiuta questa operazione per scelta progettuale. Rimuovere il declassamento; gli override possono solo aumentare il rischio.

Prestazioni

Se i rendering risultano lenti sotto carico, verificare che il pool di worker non sia saturo. Controllare l’endpoint delle metriche di RoadRunner. Spostare quindi i rendering lunghi sul percorso dei job asincroni, così da non bloccare i worker. Vedere /connect/production-usage/.

Note di sicurezza

Non aggirare un 401 esponendo in rete il transport MCP non autenticato: questo elimina completamente l’autenticazione. Correggere invece la chiave API. Non aumentare il livello di verbosità del log per ispezionare gli argomenti degli strumenti in un ambiente condiviso; i payload degli argomenti possono contenere dati sensibili. Vedere /connect/security-and-operations/.

Conformità

Questa pagina fornisce indicazioni operative. Le citazioni relative al protocollo e alla sicurezza sono riportate in /transports/mcp/, /transports/rest/ e /connect/security-and-operations/.

Vedere anche

/connect/tool-catalog/ — che cosa contiene il catalogo core e perché il conteggio varia
/connect/hitl-risk-tiers/ — le richieste di conferma in dettaglio
/connect/deployment/ — Redis, pool di worker e condivisione dello store
/connect/security-and-operations/ — errori di autenticazione e posture di sicurezza