NextPDF Connect: avvio e individuazione

In breve

Ogni trasporto dispone di un proprio punto di ingresso e di una propria sequenza di avvio. I trasporti condividono registro, configurazione e gate come concetti. Vengono eseguiti come processi indipendenti, quindi l’avvio di uno non avvia gli altri.

Installazione

composer require nextpdf/server

Panoramica concettuale

Sequenza di avvio MCP

McpServer::create() inizializza il server MCP secondo un ordine fisso. Per prima cosa carica la configurazione, crea i criteri di sicurezza a partire da tale configurazione, costruisce il registro degli strumenti ed esegue l’individuazione dei livelli. Successivamente costruisce l’archivio documenti in memoria in base al TTL e alla capacità configurati, crea il trasporto stdio e assembla il gestore del protocollo JSON-RPC con il gate di conferma e il logger di audit. Una volta predisposto tutto, il server entra nel proprio ciclo di lettura-gestione-scrittura e viene eseguito finché lo standard input non raggiunge la fine del file.

Sequenza di avvio REST

HttpServer::create() legge HttpConfig dall’ambiente e applica gli override della CLI. Risolve quindi l’archivio delle chiavi API nel seguente ordine di preferenza: prima l’archivio su file con ricaricamento a caldo, poi il file statico e infine l’ambiente. Successivamente risolve gli archivi di rate limit e idempotenza, che usano Redis quando Redis è configurato e raggiungibile e, in caso contrario, ricorrono all’archiviazione in memoria. A quel punto apre l’archivio dei job SQLite condiviso, crea i servizi dell’applicazione e costruisce la tabella delle route. Poiché la tabella delle route viene costruita a partire dai livelli rilevati, riflette i pacchetti installati. RoadRunner gestisce quindi il ciclo delle richieste dei worker.

Sequenza di avvio gRPC

GrpcServer::create() risolve lo stesso archivio delle chiavi, crea gli stessi servizi dell’applicazione e registra il servizio nextpdf.connect.v1 con il worker gRPC di Spiral. Quando la dipendenza del motore non è disponibile, il server gRPC si avvia comunque e gestisce le query sullo stato di salute e sulle capacità. In tale stato, il processo non rifiuta l’avvio; sono invece le RPC che trasportano dati a fallire in modo pulito.

Individuazione degli strumenti

L’individuazione è la fase predefinita di registrazione del registro. Il livello core viene registrato per primo. I provider Pro ed Enterprise vengono registrati successivamente, se le rispettive classi vengono risolte tramite class_exists(). I provider AST e di mutazione inclusi nel pacchetto vengono poi registrati sotto il livello Pro, subordinatamente ai rispettivi gate di ambiente. Ogni registrazione viene filtrata attraverso l’allowlist di sicurezza enabled_tools e i conteggi risultanti per livello vengono riportati nella risposta initialize di MCP. Vedere /connect/tool-catalog/.

Individuazione dei trasporti

Non esiste una singola impostazione di configurazione che «abilita i trasporti». Ogni trasporto è un punto di ingresso distinto. REST e gRPC hanno ciascuno un profilo RoadRunner dedicato. Un deployment sceglie i trasporti in base al profilo eseguito: .rr.yaml per REST, .rr.grpc.yaml per gRPC oppure .rr.full.yaml per entrambi. I trasporti vengono eseguiti come processi indipendenti. L’assenza di un client MCP non blocca mai il server REST e l’assenza di un client REST non blocca mai MCP. Vedere /connect/deployment/.

Ordine di risoluzione della configurazione

Il server MCP risolve la configurazione nel seguente ordine di precedenza: l’ambiente (NEXTPDF_MCP_*) ha la priorità sulla sezione nextpdf_mcp del file YAML, che a sua volta ha la priorità sui valori predefiniti incorporati. I server REST e gRPC leggono HttpConfig dalle variabili di ambiente NEXTPDF_*, applicando valori predefiniti sicuri. Non leggono il file YAML di MCP. Vedere /connect/configuration/.

Binding del container

Non esiste alcun container di dependency injection o service provider da registrare. Ogni factory create() costruisce il proprio grafo di oggetti in modo esplicito e deterministico. Esistono due punti di iniezione — il trasporto e la factory dei worker — ed entrambi sono destinati al testing, non al wiring dell’applicazione.

Esempio di codice — Avvio rapido

Esaminare ciò che l’individuazione ha prodotto, senza gestire traffico:

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

Esempio di codice — Produzione

Avviare i trasporti combinati sotto un unico supervisore:

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
./vendor/bin/rr serve -c .rr.full.yaml

Casi limite e insidie

• Un livello mancante non fa fallire l’avvio. L’individuazione dei livelli ignora silenziosamente un pacchetto Pro o Enterprise assente. Il server si avvia con il catalogo core.

• Un override di downgrade fa fallire l’avvio. Una voce risk_level_overrides che indebolisce uno strumento approval_required genera un’eccezione al caricamento della configurazione; il server rifiuta l’avvio. Si tratta di un comportamento intenzionale.

• Un errore di Redis comporta un degrado, non un crash. Se Redis è configurato ma irraggiungibile all’avvio, il server REST ricorre agli archivi in memoria. Verificare lo stato di salute di Redis anziché presumere che Redis sia in uso.

Prestazioni

Il costo di avvio deriva dall’analisi della configurazione, dalla scansione del registro e dal rilevamento dei livelli. Il valore performance_budget della pagina delimita questo costo. Il costo viene sostenuto una sola volta per avvio del processo, non per richiesta.

Note sulla sicurezza

I criteri di sicurezza vengono creati prima del registro, quindi l’allowlist enabled_tools vincola l’individuazione fin dalla prima registrazione. Le chiavi API non vengono mai lette dal file YAML di MCP; i trasporti di rete risolvono le chiavi da un file di segreti o dall’ambiente. Vedere /connect/security-and-operations/.

Conformità

Questa pagina descrive i meccanismi di avvio. Le citazioni relative al protocollo e alla sicurezza sono fissate in /transports/mcp/, /transports/rest/, /transports/grpc/ e /connect/security-and-operations/.

Contesto commerciale

Il rilevamento dei livelli all’avvio è l’unico punto in cui nextpdf/premium aggiunge al catalogo i propri strumenti Pro ed Enterprise, quando nextpdf/premium è installato insieme al server.

Vedere anche

• /connect/tool-catalog/ — ciò che l’individuazione registra e perché il conteggio varia
• /connect/configuration/ — l’ordine di risoluzione nel dettaglio
• /connect/deployment/ — scelta dei trasporti tramite i profili RoadRunner
• /transports/mcp/ · /transports/rest/ · /transports/grpc/ — dettagli per ciascun trasporto