NextPDF Connect: panoramica del server

In breve

NextPDF Connect è il pacchetto nextpdf/server: un servizio di lunga durata che espone il motore PDF 2.0 di NextPDF agli agenti IA e ai client HTTP. Opera tramite tre trasporti: Model Context Protocol (MCP) su stdio, API REST e gRPC. Tutti e tre si appoggiano allo stesso registro degli strumenti e allo stesso gate di conferma human-in-the-loop (HITL).

Installazione

composer require nextpdf/server

Il vincolo Composer è nextpdf/core: ^3.0 con php: >=8.4 <9.0. Per la procedura completa, vedere /connect/install/. La pagina descrive anche due componenti facoltativi: l’estensione ext-redis e il pacchetto nextpdf/premium.

Panoramica concettuale

nextpdf/server adatta il core NextPDF indipendente dal framework a una superficie di servizio. Non reimplementa la generazione dei PDF: espone invece ogni capacità del motore come uno strumento denominato, con il relativo schema, e serve tale catalogo su diversi protocolli di rete.

Tre concetti reggono l’intera architettura:

Il registro degli strumenti. NextPDF\Server\ToolRegistry rileva e registra gli strumenti all’avvio. Un insieme di base viene fornito con il pacchetto ed è sempre disponibile. I provider Pro ed Enterprise registrano strumenti aggiuntivi, ma solo quando i pacchetti corrispondenti sono installati. Il numero di strumenti esposti è quindi una proprietà runtime del deployment, non una costante fissa. Vedere /connect/tool-catalog/.
I trasporti. Lo stesso registro viene servito in tre modalità. MCP usa stdio per i client IA locali. REST usa una pipeline di middleware PSR-15 su un pool di worker RoadRunner per i client di rete. gRPC usa un worker gRPC Spiral RoadRunner per client tipizzati e in streaming. Ogni trasporto viene eseguito come processo separato, con il proprio punto di ingresso. Vedere /transports/mcp/, /transports/rest/ e /transports/grpc/.
Il gate di conferma. Ogni strumento dichiara un livello di rischio. Uno strumento al livello più alto richiede una conferma umana esplicita prima dell’esecuzione. Il gate emette un token di sfida monouso. L’agente deve trasmettere tale token a un essere umano, quindi richiamare lo strumento con il token. Vedere /connect/hitl-risk-tiers/.

Il diagramma seguente mostra come un unico registro viene esposto tramite tre trasporti. Mostra inoltre dove si colloca il gate di conferma nel percorso della richiesta.

NextPDF Connect component architecture

Il pacchetto è distribuito con licenza Apache-2.0, in linea con nextpdf/core. La versione del protocollo MCP implementata è la revisione datata 2025-06-18. La superficie REST è descritta da un documento OpenAPI 3.1; quella gRPC dal pacchetto Protocol Buffers nextpdf.connect.v1.

Superficie API

I punti di ingresso pubblici sono le tre classi server. Ciascuna dispone di un wrapper per l’interfaccia a riga di comando (CLI):

Punto di ingresso	Classe	Trasporto
`bin/nextpdf-mcp`	`NextPDF\Server\Mcp\McpServer`	MCP su stdio
`bin/nextpdf-server`	`NextPDF\Server\Http\HttpServer`	REST su RoadRunner HTTP
`bin/nextpdf-grpc`	`NextPDF\Server\Grpc\GrpcServer`	gRPC su RoadRunner gRPC
`bin/generate-skills`	`NextPDF\Server\Skills\SkillsDumper`	Esportazione del catalogo strumenti

McpServer::create(), HttpServer::create() e GrpcServer::create() costruiscono ciascuno un server completamente configurato a partire dagli input di ambiente e configurazione. Il registro, l’archivio dei documenti, i criteri di sicurezza e il gate di conferma sono concetti condivisi tra tutti e tre i server.

Esempio di codice — Avvio rapido

Per avviare il server MCP minimo basta un solo comando. Non occorre scrivere alcun codice PHP di collegamento:

./vendor/bin/nextpdf-mcp

Il server legge le richieste JSON-RPC dall’input standard e scrive le risposte sull’output standard. Per uno scambio eseguibile di initialize e tools/list e per la richiesta REST corrispondente, vedere /connect/quickstart/.

Casi limite e insidie

Il numero di strumenti non è 33, né alcun altro numero fisso. Il server conta gli strumenti a runtime tramite count(ToolRegistry::all()), dopo l’applicazione dei criteri e il rilevamento del livello. La documentazione che riporta un totale fisso è obsoleta. Per ottenere il conteggio autorevole, interrogare il server in esecuzione. Utilizzare la risposta MCP initialize oppure l’endpoint REST /api/v1/capabilities.

Il numero di strumenti esposti dipende dai pacchetti installati e dai criteri attivi. Leggerlo a runtime dal server in esecuzione. Un numero fisso copiato nel proprio codice o nella propria documentazione diventerà obsoleto.
Un pacchetto Pro o Enterprise mancante non è un errore. Il registro verifica la presenza delle classi provider con class_exists(), quindi ignora silenziosamente qualsiasi livello assente. Un deployment solo open source si avvia e serve normalmente il proprio catalogo di base.
I tre trasporti non condividono un processo. L’avvio del server MCP non avvia il server REST né il server gRPC. Vale anche il contrario. Un deployment combinato esegue il supervisore RoadRunner con una configurazione che avvia entrambi i pool di worker: il pool HTTP e il pool gRPC. Vedere /connect/deployment/.

Prestazioni

Ogni trasporto è basato su worker e ogni worker gestisce una richiesta alla volta. I server REST e gRPC vengono eseguiti su pool di worker RoadRunner, la cui dimensione è impostata dalla configurazione. Il valore predefinito è quattro worker HTTP. Il supervisore RoadRunner limita la memoria di ciascun worker. Il front-matter performance_budget di questa pagina descrive un intervallo di avvio a freddo e individuazione, non un obiettivo per singola richiesta. Il costo di ogni richiesta dipende soprattutto dall’operazione sottostante del motore.

Note sulla sicurezza

Tutti i trasporti di rete usano l’autenticazione con token bearer basato su chiave API. Il trasporto MCP su stdio è un sottoprocesso locale a cui il client che lo avvia accorda fiducia, in base al modello di trasporto MCP. Gli strumenti ad alto rischio restano soggetti a conferma umana su ogni trasporto. Per il modello di minaccia completo, il modello di autenticazione e la configurazione di sicurezza del trasporto, vedere /connect/security-and-operations/.

Conformità

Questa pagina contiene soltanto affermazioni architetturali. Le citazioni normative di protocollo e sicurezza sono ancorate alle pagine che specificano il comportamento: /connect/security-and-operations/, /transports/mcp/, /transports/rest/ e /transports/grpc/. Il riferimento per il ciclo di vita MCP è la specifica ufficiale pubblicata su modelcontextprotocol.io (revisione 2025-06-18). Le pagine dei trasporti registrano tale riferimento con il relativo URL, poiché la specifica MCP non fa parte del corpus degli standard sottoposto a gate.

Contesto commerciale

Il catalogo di base copre la creazione, l’ispezione e la diagnostica dei documenti. Gli strumenti per la firma, l’oscuramento, la certificazione di conformità e l’analisi forense compaiono solo quando nextpdf/premium è installato insieme al server. Si tratta di un confine di pacchettizzazione, non di un messaggio di upsell a runtime. Il server non emette mai contenuti di marketing.

Vedere anche

/connect/install/ — installazione e pacchetti facoltativi
/connect/quickstart/ — primo scambio MCP e REST eseguibile
/connect/tool-catalog/ — l’insieme verificato di strumenti di base e il modo in cui il conteggio dipende dal runtime
/connect/hitl-risk-tiers/ — il gate di conferma e il modello di rischio
/transports/mcp/, /transports/rest/, /transports/grpc/ — configurazione specifica del trasporto
/connect/security-and-operations/ — autenticazione, sicurezza del trasporto, modello di minaccia
/connect/deployment/ — RoadRunner, Docker e deployment con trasporti combinati