Catalogo degli strumenti di NextPDF Connect

In breve

Il numero di strumenti esposti da una distribuzione di NextPDF Connect non è una costante. Il server lo calcola a runtime in base ai pacchetti installati, all’allowlist di configurazione e a un insieme di gate ambientali. Questa pagina documenta il set di base verificato e il metodo con cui viene determinato il totale.

Installazione

composer require nextpdf/server

Panoramica concettuale

NextPDF\Server\ToolRegistry costruisce il catalogo all’avvio nel seguente ordine:

Livello core. Un insieme fisso di strumenti core viene registrato incondizionatamente. Altri due strumenti vengono registrati solo quando è soddisfatta la relativa precondizione.
Livello Pro. Gli strumenti Pro vengono registrati quando la classe del provider Pro viene risolta, cioè quando nextpdf/premium è installato. Il server salta silenziosamente questo passaggio quando la classe non viene risolta.
Livello Enterprise. Il provider Enterprise segue lo stesso schema del provider Pro.
Livelli estesi in bundle. I provider degli strumenti AST e di mutazione sono inclusi nel pacchetto del server e si registrano nel livello Pro. Un gate ambientale controlla ciascun provider; ogni provider si degrada gradualmente quando manca il relativo supporto core sottostante.
Filtro dei criteri di sicurezza. Il server interseca ogni registrazione con l’allowlist enabled_tools. Se l’allowlist non è vuota, esclude qualsiasi strumento che non vi sia presente. Il conteggio per livello include solo gli strumenti ammessi dai criteri.

La risposta MCP initialize riporta il valore tool_count risultante e i conteggi per livello del server in esecuzione. Quel valore è il numero autorevole. Considerare obsoleto qualsiasi totale fisso riportato nel testo.

Superficie API

Strumenti core verificati e sempre disponibili

Questi dodici strumenti vengono registrati incondizionatamente nel livello core. Il server legge dall’implementazione dello strumento il livello di rischio e ogni suggerimento di comportamento MCP.

Nome strumento	Categoria	Descrizione	Rischio
`create_pdf`	document	Crea un nuovo documento PDF e restituisce un `document_id`	caution
`add_text`	document	Aggiunge contenuto testuale a un documento PDF	caution
`add_image`	document	Aggiunge un’immagine da un percorso di file o da dati in base64	caution
`add_table`	document	Aggiunge una tabella HTML a un documento PDF	caution
`set_font`	document	Imposta il font per le operazioni di testo successive	caution
`add_page`	document	Aggiunge una nuova pagina al documento PDF	caution
`output_pdf`	document	Finalizza il PDF in un file o in base64	approval_required
`preview_layout`	document	Restituisce un riepilogo JSON dell’impaginazione senza rendering	safe
`diagnostic.doctor`	diagnostic	Esegue un controllo di integrità e restituisce una diagnostica strutturata dell’ambiente	safe
`diagnostic.capabilities`	diagnostic	Elenca le funzionalità con livello e stato	safe
`diagnostic.inspect`	diagnostic	Ispeziona un PDF e restituisce i metadati strutturali	safe
`diagnostic.verify`	diagnostic	Verifica l’integrità del PDF, con controllo PDF/A o PDF/UA facoltativo	caution

Strumenti core registrati condizionalmente

Nome strumento	Condizione
`generate_barcode`	Si registra quando il registro degli encoder di codici a barre del core è presente nel pacchetto installato `nextpdf/core`
`parse_pdf`	Si registra solo quando `NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED` è `true` oppure `1`

output_pdf è l’unico strumento core con livello di rischio approval_required. La scrittura di un file passa attraverso il gate human-in-the-loop; la modalità di output base64 no. Vedere /connect/hitl-risk-tiers/.

Strumenti aggiunti solo quando sono installati pacchetti aggiuntivi

Il server verifica la presenza delle classi provider con class_exists():

Gli strumenti Pro vengono registrati quando nextpdf/premium è installato e il provider Pro viene risolto.
Gli strumenti Enterprise vengono registrati quando nextpdf/premium è installato e il provider Enterprise viene risolto. Gli strumenti per la privacy (redazione, de-identificazione, redazione per zone) incapsulano le classi Enterprise. Si registrano nel livello Enterprise solo quando tali classi sono caricabili automaticamente.
Gli strumenti AST e di mutazione sono inclusi nel server e si registrano nel livello Pro. I gate NEXTPDF_AST_TOOLS_ENABLED e NEXTPDF_MUTATION_TOOLS_ENABLED li controllano e sono entrambi abilitati per impostazione predefinita.

Il pacchetto Premium, non il server, definisce gli inventari esatti degli strumenti Pro ed Enterprise e li documenta insieme a quel pacchetto. Il contratto del server riguarda il meccanismo di registrazione, non un elenco Premium fisso.

Esempio di codice — Avvio rapido

Stampa gli strumenti esposti da questa installazione senza avviare un server:

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

Esempio di codice — Produzione

Interroga il server in esecuzione per ottenere il conteggio autorevole tramite MCP:

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

Nel risultato di initialize, il server espone i valori capabilities.nextpdf.tool_count e tiers calcolati per il processo in esecuzione. Tramite REST, GET /api/v1/capabilities restituisce un’introspezione equivalente.

Casi limite e insidie

Non esiste un valore fisso di “33 strumenti”, né alcun totale fisso. Il materiale meno recente cita un singolo numero, che però non costituisce un contratto. Il conteggio varia in base ai pacchetti installati, all’allowlist enabled_tools e ai gate ambientali parse_pdf, AST e di mutazione. Leggerlo sempre dal server in esecuzione.
L’allowlist sottrae, non aggiunge mai. Inserire uno strumento Pro in enabled_tools quando nextpdf/premium è assente non lo registra.
Un livello mancante è silenzioso e previsto. Un’installazione solo open source fornisce il set core e riporta zero strumenti Pro e zero strumenti Enterprise. Tale risultato è il funzionamento corretto, non un guasto.
Il livello nel catalogo è un invariante dichiarato. Ogni strumento dichiara nel codice il proprio livello e il proprio rischio. Il registro non deduce mai il livello dal namespace o dal packaging.

Prestazioni

La scansione del registro e il rilevamento del livello vengono eseguiti una sola volta all’avvio. Il valore performance_budget della pagina ne fissa i limiti. Il costo per strumento corrisponde all’operazione sottostante del motore, non alla ricerca nel catalogo, che è O(1) per nome dello strumento.

Note sulla sicurezza

Usare enabled_tools come controllo di privilegio minimo: esporre solo gli strumenti necessari a un’integrazione. Il catalogo non include mai uno strumento rifiutato dai criteri di sicurezza e il conteggio per livello riflette solo gli strumenti ammessi. Gli strumenti ad alto rischio restano soggetti a conferma umana indipendentemente dalla loro presenza nel catalogo. Vedere /connect/security-and-operations/.

Conformità

Questa pagina descrive il meccanismo del registro. Le citazioni di protocollo per le superfici tools/list e initialize sono definite in /transports/mcp/. Il modello di rischio è specificato in /connect/hitl-risk-tiers/.

Contesto commerciale

Il catalogo core è completo per creazione, ispezione e diagnostica. Gli strumenti di firma, redazione, conformità e analisi forense compaiono solo quando nextpdf/premium è installato insieme al server. Si tratta di un confine di packaging, applicato al momento di composer require, mai di un prompt a runtime.

Vedere anche

/connect/hitl-risk-tiers/ — che cosa significa la colonna del rischio e come viene applicata
/connect/boot-and-discovery/ — sequenza completa di avvio e individuazione
/connect/configuration/ — enabled_tools e i gate ambientali
/transports/mcp/ — formati wire di tools/list e initialize
/connect/overview/ — perché il catalogo dipende dal runtime per progettazione