Integrazione di NextPDF Connect

In sintesi

Per integrare NextPDF Connect, eseguirlo come server. Non si integra una libreria in un’applicazione host. Scegliere un trasporto, quindi configurare l’autenticazione quando il trasporto è esposto in rete. Gli strumenti del motore sono protetti dal gate di conferma.

Installazione

composer require nextpdf/server

Il vincolo Composer è nextpdf/core: ^3.0 con php: >=8.4 <9.0. Per le dipendenze opzionali ext-redis e nextpdf/premium, vedere /connect/install/.

Panoramica concettuale

Il pacchetto è un servizio autonomo. Non esistono service provider, bundle o moduli container da registrare in un framework host. Il punto di integrazione è il processo da eseguire. Ogni trasporto espone il proprio entry point e si avvia in modo indipendente. Vedere /connect/boot-and-discovery/.

Superficie API

Entry point	Trasporto	Profilo
bin/nextpdf-mcp	MCP su stdio	(nessuno — sottoprocesso diretto)
bin/nextpdf-server	REST su RoadRunner HTTP	.rr.yaml
bin/nextpdf-grpc	gRPC su RoadRunner gRPC	.rr.grpc.yaml
entrambi i trasporti in rete	REST + gRPC	.rr.full.yaml

Avvio e rilevamento automatico

Il registro rileva sempre il tier core. Aggiunge poi i provider Pro ed Enterprise quando le rispettive classi risultano risolvibili, seguiti dai provider AST e di mutation inclusi, soggetti ai gate basati sull’ambiente. L’allowlist di sicurezza enabled_tools filtra l’intero insieme; il catalogo esposto è quindi una proprietà di questa distribuzione. Vedere /connect/tool-catalog/ e /connect/boot-and-discovery/.

Binding del container

Nessuno. Ogni factory del server costruisce esplicitamente il proprio grafo di oggetti. I punti di iniezione servono ai test, non al wiring dell’applicazione.

Pubblicazione della configurazione

Il server MCP accetta un file YAML facoltativo (--config=PATH, sezione nextpdf_mcp) e gli override d’ambiente NEXTPDF_MCP_*. I server REST e gRPC leggono le variabili d’ambiente NEXTPDF_*. Per i dettagli, vedere /connect/configuration/.

Disponibilità dei trasporti (MCP / REST / gRPC)

Tutti e tre i trasporti condividono lo stesso registro:

• MCP — sottoprocesso locale, JSON-RPC 2.0 su stdio, nessuna chiave API, revisione MCP 2025-06-18. Vedere /transports/mcp/.
• REST — pool di worker HTTP RoadRunner, contratto OpenAPI 3.1, chiave API bearer, route soggette a gating per tier. Vedere /transports/rest/.
• gRPC — pool di worker gRPC RoadRunner, servizio Protobuf nextpdf.connect.v1, RPC con server-streaming, autenticazione bearer nei metadati, TLS reciproco nel profilo combinato. Vedere /transports/grpc/.

Un trasporto è «disponibile» quando il relativo entry point o profilo RoadRunner è in esecuzione. I trasporti non si avviano automaticamente a vicenda.

Tier di rischio HITL

Ogni strumento dichiara uno tra quattro livelli di rischio — safe, caution, review, approval_required. Gli strumenti di livello approval_required non vengono eseguiti alla prima chiamata. Il gate di conferma emette un token di challenge monouso che deve essere autorizzato da un essere umano. Un override di configurazione può solo aumentare il rischio di uno strumento, mai ridurre quello di uno strumento approval_required. Il modello si applica allo stesso modo a ogni trasporto che esegue gli strumenti. Vedere /connect/hitl-risk-tiers/.

Envelope JSON del gate di conferma

Il controllo del gate restituisce una delle due forme JSON. Consentito:

{ "allowed": true }

Challenge:

{
  "allowed": false,
  "challenge": "<human-readable text naming the operation, its description, an overwrite warning when applicable, and the re-invocation instruction>",
  "token": "confirm_<nonce>"
}

Il token vincola il nome dello strumento, un nonce casuale e un TTL di 300 secondi — non gli argomenti. Per procedere, il chiamante richiama lo stesso strumento con un argomento _confirmation_token impostato sul token emesso. Il challenge consiste in semplice testo istruttivo più il token; non è un envelope firmato crittograficamente. Vedere /connect/hitl-risk-tiers/.

Smoke test del servizio

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

Questo avvia il registro e il rilevamento dei tier, quindi stampa gli strumenti esposti senza servire traffico. È un modo rapido per confermare che l’integrazione sia correttamente collegata e verificare quale catalogo produce questa installazione.

Casi limite e insidie

• Nessun hook del framework. Non cercare un service provider o un bundle. L’integrazione è il processo in esecuzione.
• Un tier mancante non è un errore. Un’installazione solo core si avvia e serve il proprio catalogo core.
• I trasporti in rete richiedono una chiave. Solo /healthz e /readyz (REST) e le RPC di health (gRPC) sono anonime.

Prestazioni

Il costo di avvio è la scansione del registro e il rilevamento dei tier, eseguiti una volta per processo. Il costo per richiesta corrisponde all’operazione del motore. Dimensionare i pool di worker RoadRunner in base alla latenza di rendering osservata. Vedere /connect/production-usage/.

Note sulla sicurezza

I trasporti in rete si autenticano con una chiave bearer npk_live_ convalidata a tempo costante; il gate impone la conferma umana per le operazioni distruttive in modo indipendente dal trasporto. Terminare il TLS davanti a REST e utilizzare il TLS reciproco per gRPC sulle reti non attendibili. Vedere /connect/security-and-operations/.

Conformità

Le citazioni relative a protocollo e sicurezza sono fissate in /transports/mcp/, /transports/rest/, /transports/grpc/ e /connect/security-and-operations/.

Contesto commerciale

Quando nextpdf/premium è installato insieme al server, gli ulteriori strumenti Pro ed Enterprise vengono registrati nello stesso server in esecuzione. Non è coinvolto alcun processo separato.

Vedere anche

• /connect/overview/ — l’architettura
• /connect/quickstart/ — il primo scambio eseguibile
• /transports/mcp/ · /transports/rest/ · /transports/grpc/ — riferimento per trasporto
• /connect/hitl-risk-tiers/ — il gate di conferma in dettaglio
• /connect/tool-catalog/ — il catalogo dipendente dal runtime
• /connect/security-and-operations/ — autenticazione e modello delle minacce