NextPDF Connect — trasporto MCP

In sintesi

Il trasporto MCP esegue bin/nextpdf-mcp come sottoprocesso locale. Comunica in JSON-RPC 2.0 tramite standard input e standard output. Il server implementa la revisione MCP datata 2025-06-18.

Installazione

composer require nextpdf/server

Panoramica concettuale

Nel modello stdio di MCP, il client avvia il server come sottoprocesso. Il client scambia messaggi JSON-RPC delimitati da newline: un messaggio per riga, senza newline incorporati, in UTF-8. Il server scrive sullo standard output solo messaggi MCP validi e utilizza lo standard error per il logging. L’implementazione indirizza il proprio logger di audit allo standard error proprio per evitare che le righe di log corrompano il flusso del protocollo. Questo framing è definito dalla specifica MCP ufficiale, revisione 2025-06-18. Questa specifica non fa parte del corpus controllato degli standard, pertanto viene citata tramite URL: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports.

NextPDF Connect implementa il trasporto stdio. La specifica MCP definisce anche un trasporto Streamable HTTP. Stabilisce inoltre che i client dovrebbero supportare stdio ogni volta che è possibile e che un server può implementare solo stdio. Per accedere agli stessi strumenti tramite rete, utilizzare invece il trasporto REST o gRPC; vedere /transports/rest/ e /transports/grpc/.

Superficie API

Metodi

Metodo	Comportamento
`initialize`	Restituisce la versione del protocollo, le funzionalità e le informazioni del server
`notifications/initialized`	Una notifica (senza `id`); gestita senza risposta
`tools/list`	Elenca gli strumenti registrati, con filtro `params.category` facoltativo
`tools/call`	Esegue lo strumento indicato da `params.name` con `params.arguments`

Qualsiasi altro metodo restituisce method-not-found (-32601). Un messaggio non valido secondo JSON-RPC 2.0 produce invalid-request (-32600); un input non analizzabile produce parse-error (-32700). Per un id di richiesta duplicato viene restituita la risposta precedente memorizzata nella cache da un buffer di 64 voci, senza riesecuzione.

La risposta di initialize

Il risultato di initialize riporta protocolVersion 2025-06-18, serverInfo.name: NextPDF Connect e un oggetto capabilities. Oltre alla funzionalità standard tools, il server aggiunge un blocco capabilities.nextpdf:

tiers — i conteggi in tempo reale degli strumenti registrati per livello (core / pro / enterprise).
tool_count — il numero totale di strumenti registrati, calcolato a runtime.
risk_model_version — la versione del modello di rischio applicata dal server.
hitl_enabled — true; il gate di conferma è attivo.

tool_count è il numero autorevole per questo deployment. Si tratta di un conteggio a runtime, non di una costante documentata; vedere /connect/tool-catalog/.

Esempio di codice — Avvio rapido

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

Esempio di codice — Produzione

Un elenco filtrato per categoria limita il catalogo a un solo dominio:

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

I valori di categoria corrispondono alla categoria dichiarata di ciascuno strumento (ad esempio document, diagnostic).

Casi limite e insidie

Nessuna chiave API. Il trasporto stdio non ha alcun listener di rete né bearer token. Il confine di trust coincide con il limite di processo del sistema operativo, secondo il modello stdio di MCP. Non deve essere collegato a una rete.
Le richieste di conferma sono in-band. Uno strumento ApprovalRequired restituisce una risposta JSON-RPC con esito positivo che contiene il testo della richiesta e un token monouso, non un errore. Vedere /connect/hitl-risk-tiers/.
Le notifiche sono silenziose. Un messaggio privo di id non produce alcuna risposta. La sequenza di handshake è initialize (con id), poi la notifica initialized, poi le chiamate con id.

Prestazioni

Il server MCP è un singolo processo che gestisce una richiesta alla volta tramite pipe. Non prevede alcun round-trip di rete; la latenza è determinata principalmente dall’operazione sottostante del motore.

Note sulla sicurezza

Il trasporto eredita il trust del client che lo avvia. Il sottoprocesso deve restare locale. Gli strumenti ad alto rischio rimangono soggetti alla conferma umana anche in assenza di una chiave API. Vedere /connect/security-and-operations/.

Conformità

Il framing stdio e il comportamento di initialize/lifecycle sono conformi alla specifica ufficiale di Model Context Protocol, revisione 2025-06-18:

Trasporti: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports
Lifecycle: https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle

La specifica MCP non è inclusa nel corpus controllato degli standard, pertanto non ha alcun reference_id; gli URL ufficiali riportati sopra costituiscono la citazione di riferimento.

Contesto commerciale

tools/list restituisce gli strumenti Pro ed Enterprise solo quando nextpdf/premium è installato insieme al server. Il trasporto in sé è identico a prescindere dai livelli installati.

Vedere anche

/connect/quickstart/ — handshake eseguibile
/connect/tool-catalog/ — cosa restituisce tools/list e perché il conteggio varia
/connect/hitl-risk-tiers/ — il formato della richiesta di conferma
/transports/rest/ · /transports/grpc/ — alternative tramite rete
/connect/migrating-to-multi-transport/ — migrazione di un’integrazione solo MCP a REST/gRPC