Guida rapida a NextPDF Connect

In sintesi

Questa pagina mostra lo scambio utile minimo su entrambi i trasporti: MCP e REST. Ogni richiesta usa l’esatto formato wire implementato dal server. Non viene coinvolto alcun software development kit (SDK).

Installazione

composer require nextpdf/server

Panoramica concettuale

Il trasporto MCP comunica tramite JSON-RPC 2.0 su standard input e output. La sequenza è obbligatoria e va eseguita nell’ordine indicato. Inviare prima initialize. Inviare poi la conferma notifications/initialized. Inviare quindi tools/list e tools/call. Il server legge un messaggio JSON per riga, con ogni riga terminata da un carattere di a capo, e scrive una risposta per riga.

Il trasporto REST espone le stesse funzionalità del motore sotto forma di operazioni HTTP. Una singola operazione di render stateless corrisponde a una POST /api/v1/render con un array ordinato di operazioni. Il corpo della risposta è il PDF.

Esempio di codice — Avvio rapido (MCP su stdio)

Avviare il server e inviare l’handshake tramite pipe. Le tre richieste seguenti usano i nomi di metodo verificati e instradati dal gestore di protocollo:

./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 risposta a initialize restituisce la versione di protocollo 2025-06-18, il nome del server NextPDF Connect e un blocco capabilities.nextpdf. Il blocco include i conteggi dei tier in tempo reale, il tool_count di runtime, la versione del modello di rischio e hitl_enabled: true. La risposta a tools/list elenca esattamente gli strumenti registrati da questa installazione. La riga di notifica, per progettazione, non produce alcuna risposta.

Ora chiamare uno strumento sicuro. Lo strumento diagnostic.doctor esegue un controllo dell’ambiente in sola lettura. 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":"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

Esempio di codice — Avvio rapido (REST)

Avviare il server REST, quindi generare un PDF di una riga. Il server richiede una chiave API su ogni endpoint diverso da quelli di health; quindi definirne prima una:

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

In una seconda shell, inviare una richiesta di render. Il corpo è un RenderRequest. La richiesta contiene un array operations ordinato di operazioni tipizzate.

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

Il corpo di una risposta 200 è il PDF (Content-Type: application/pdf), scritto in hello.pdf. Le sonde di health non richiedono alcuna chiave:

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

Casi limite e insidie

• L’ordine dell’handshake è importante. Il gestore di protocollo tratta come notifica un messaggio privo di id e non restituisce nulla. Inviare initialize con un id, quindi la notifica initialized e infine le richieste con il proprio id.

• Un id di richiesta ripetuto viene deduplicato. Il gestore memorizza nella cache le risposte recenti in un buffer circolare a 64 voci. Per un id duplicato, restituisce la risposta memorizzata in cache senza eseguire di nuovo lo strumento. Usare id nuovi.

• Uno strumento ad alto rischio risponde con una richiesta di conferma, non con un risultato. La chiamata a output_pdf con un file_path restituisce una richiesta di conferma anziché essere eseguita. Ripetere la chiamata con il _confirmation_token emesso. La modalità di output base64 (senza file_path) non richiede conferma. Vedere /connect/hitl-risk-tiers/.

• Una richiesta REST non autorizzata riceve 401. Un’intestazione Authorization: Bearer mancante o malformata restituisce un corpo problem-details con un’intestazione WWW-Authenticate: Bearer. Le sonde /healthz e /readyz sono gli unici endpoint anonimi.

Prestazioni

Entrambi i percorsi di avvio rapido sono a richiesta singola. Il percorso REST sostiene anche il costo di cold-start del pool di worker di RoadRunner alla prima richiesta dopo rr serve. Le richieste successive riutilizzano worker già attivi.

Note sulla sicurezza

La chiave npk_live_ riportata sopra è un valore dimostrativo usa e getta. Generare chiavi reali con entropia sufficiente, conservarle al di fuori del controllo del codice sorgente e preferire l’archivio di chiavi basato su file per la rotazione. Il trasporto MCP su stdio non usa alcuna chiave API perché è un sottoprocesso locale considerato attendibile dal client che lo avvia, secondo il modello di trasporto MCP. Vedere /connect/security-and-operations/.

Conformità

I formati wire mostrati corrispondono alla revisione MCP implementata 2025-06-18 e al contratto REST OpenAPI 3.1. Le citazioni normative su protocollo e autenticazione sono fissate in /transports/mcp/, /transports/rest/ e /connect/security-and-operations/.

Vedere anche

• /transports/mcp/ — il riferimento completo del trasporto MCP
• /transports/rest/ — il riferimento completo del trasporto REST e il rendering OpenAPI
• /connect/tool-catalog/ — quali strumenti tools/list restituisce e perché
• /connect/hitl-risk-tiers/ — come appare una richiesta di conferma
• /connect/configuration/ — limitare il catalogo e ottimizzare il server