Pro edizione

MCP Tools — Riferimento approfondito

Disponibilità e licenza

Questa funzionalità è distribuita in NextPDF Pro (nextpdf/pro) e si attiva con un envelope di licenza di tier Pro. Un deployment privo di tale entitlement non carica le classi della funzionalità. Confronta le edizioni e ottieni una licenza.

Non esiste alcun flag di licenza per singola funzionalità. Il codice è distribuito con l’edizione Pro, e gli otto strumenti si registrano sotto il tier pro quando il pacchetto Pro si risolve all’avvio insieme a nextpdf/server.

Contratto di comportamento

NextPDF Server scopre i tier all’avvio sondando la classe del tool-provider Pro; se questa si risolve, il server registra gli otto strumenti sotto il tier pro. Il pacchetto Pro non è una dipendenza obbligatoria del server, pertanto gli strumenti Pro sono strettamente opzionali, attivabili tramite co-installazione. La registrazione dei tier è indipendente: un tier mancante o escluso da policy non blocca mai gli altri.
Ciascuno strumento dichiara uno di quattro livelli di rischio (safe, caution, review, approval-required). Un override opzionale dell’operatore può solo innalzare il livello di uno strumento, mai abbassarlo; il server registra nell’audit log qualsiasi esecuzione a livello caution o superiore. sign_pdf è approval-required.
L’input PDF si risolve in un ordine fisso: document_id dallo store in memoria, poi source come URI data:, percorso del filesystem o base64 grezzo. L’assenza di input restituisce un errore di convalida anziché elaborare un documento vuoto.
sign_pdf produce solo una firma baseline PAdES B-B — nessuna marca temporale, nessuna convalida a lungo termine. Gli algoritmi supportati e l’envelope di trasporto della chiave AES-GCM sono dettagliati di seguito; la decifratura fallisce in modo chiuso e lo strumento non utilizza mai il ciphertext come materiale di chiave.
Vedere le sezioni seguenti per il dettaglio completo su discovery, rischio, risoluzione dell’origine, singoli strumenti e firma. Questa pagina descrive solo il comportamento osservabile dall’esterno e il contratto pubblicato degli strumenti.

Ambito

Questa pagina è il riferimento per operatori e integratori degli otto strumenti MCP Pro. Copre il modello di discovery, la semantica di rischio/HITL applicata dal server, le regole di risoluzione dell’origine, l’envelope di trasporto della chiave di firma e il comportamento in caso di errore per ciascuno strumento. Descrive solo il comportamento osservabile dall’esterno e il contratto pubblicato degli strumenti. Per il catalogo rivolto all’utente, vedere la pagina MCP pubblica.

Modello di discovery e registrazione

NextPDF Server scopre i provider di tier all’avvio. Rileva il tier Pro sondando la classe del tool-provider Pro; se la classe si risolve, il server istanzia il provider e registra ciascuno strumento che esso restituisce sotto il tier pro. Il pacchetto Pro intenzionalmente non è una dipendenza obbligatoria del server — ciò mantiene il server open source installabile senza il pacchetto proprietario e rende gli strumenti Pro strettamente opzionali, attivabili tramite co-installazione.

Il server isola la registrazione per tier. Se il pacchetto Pro è assente, gli strumenti Core si registrano comunque; un provider di tier presente non blocca gli altri tier. La registrazione degli strumenti è inoltre soggetta alla allow-list della policy di sicurezza del server: uno strumento escluso da policy non viene registrato in modo silenzioso e non è conteggiato nel riepilogo del tier. Il server espone un conteggio per tier (core / pro / enterprise) a fini diagnostici e di logging.

Il provider restituisce gli otto strumenti in un ordine fisso: estrazione del testo, segmentazione, confronto, mascheramento dei PII, compilazione del modulo, rilettura del modulo, analisi dell’accessibilità, firma. L’ordine è stabile ma chi effettua la chiamata non deve dipendervi — risolvere gli strumenti tramite il loro nome di protocollo MCP.

Modello di rischio e semantica HITL

Ciascuno strumento dichiara uno di quattro livelli di rischio. Il server utilizza il livello dichiarato per l’applicazione del human-in-the-loop:

Safe — sola lettura, senza effetti collaterali. Si esegue automaticamente.
Caution — crea o modifica stato in memoria. Si esegue automaticamente con una voce nell’audit log.
Review — produce un output che potrebbe essere usato impropriamente. Si esegue automaticamente, ma le istruzioni della skill dell’agente lo contrassegnano affinché l’agente avverta l’utente.
Approval-required — distruttivo, legale o critico per la privacy. Il server richiede una conferma umana esplicita prima dell’esecuzione.

Classificazioni degli strumenti Pro: i cinque strumenti di estrazione/analisi (extract_text, segment_document, compare_pdfs, extract_form_data, check_accessibility) sono safe; redact_pii e fill_form sono review; sign_pdf è approval-required.

Il livello di rischio proviene esattamente da due fonti: la dichiarazione dello strumento stesso e un override opzionale dell’operatore a runtime. L’override può solo innalzare il livello di rischio di uno strumento (rendere più stringente l’applicazione); non può mai abbassarlo. Il server registra nell’audit log qualsiasi esecuzione a livello caution o superiore. Il modello di rischio porta una versione; il server pubblicizza tale versione nella propria risposta di inizializzazione affinché i client possano rilevare una modifica incompatibile.

Ordine di risoluzione dell’origine

Ogni strumento che riceve un PDF lo accetta attraverso una di tre forme di input, risolte in questo ordine:

document_id — il server recupera i byte dal proprio store di documenti in memoria. Un id sconosciuto fallisce con un errore esplicito che indirizza chi effettua la chiamata a creare prima il documento.
source come URI data: — lo strumento decodifica il corpo base64 dopo la virgola.
source come percorso del filesystem — lo strumento legge dal disco quando il percorso si risolve in un file.
source come stringa base64 grezza — lo strumento accetta e decodifica solo input sufficientemente lungo e conforme alla forma base64.

compare_pdfs applica la stessa risoluzione in modo indipendente a source_a e source_b, e accetta inoltre un valore document_id in uno dei due slot di origine. Se non viene fornito né un document_id né un source, lo strumento restituisce un errore di convalida anziché elaborare un documento vuoto.

Riferimento per singolo strumento

Tool	Risk	Inputs	Result fields	Behavioral boundary
`extract_text`	safe	PDF; opzionali `page_start` / `page_end` con indice da 1	testo, conteggio totale delle pagine	Solo text layer; intervalli limitati al numero reale di pagine; nessun OCR
`segment_document`	safe	PDF	conteggio dei segmenti, elenco dei segmenti	Segmenti derivati dal layout; non un albero di struttura di un PDF tagged
`compare_pdfs`	safe	due PDF	flag di identicità, totale delle modifiche, conteggi di pagina per documento, regioni (tipo, testo, indice di pagina, indice di riga, testo controparte opzionale)	Diff di contenuto testuale; non visivo né binario
`redact_pii`	review	PDF; opzionali `types` (`email`, `phone`, `ssn`, `credit_card`)	flag di presenza PII, conteggio rilevato, testo mascherato, tipi scansionati	Rilevamento/mascheramento sul text layer; non oscuramento visivo; basato su pattern, non esaustivo
`fill_form`	review	mappa `fields`; opzionale `pdf_filename`	documento XFDF, conteggio dei campi	Produce XFDF (ISO 19444-1); non scrive valori in un PDF
`extract_form_data`	safe	PDF	conteggio dei campi, mappa dei campi, nota esplicita quando nessuno	Legge solo l’XFDF incorporato
`check_accessibility`	safe	PDF	punteggio strutturale (0–100), problemi, riepilogo dei segmenti	Euristica strutturale con riferimenti WCAG; non un verdetto di conformità
`sign_pdf`	approval-required	PDF; certificato PEM + chiave PKCS#8; opzionali algoritmo, nome del firmatario, motivo, envelope di trasporto	PDF firmato, conteggio delle firme, flag di completamento, algoritmo, OID, digest	Solo baseline PAdES B-B; nessuna marca temporale, nessuna LTV

Firma: algoritmi e trasporto della chiave

sign_pdf produce una firma baseline PAdES B-B. Algoritmi supportati, accettati sia nella grafia con underscore sia in quella con trattino:

RSA con SHA-256 (predefinito).
RSA con SHA-3 256 / 384 / 512 — richiede una build di OpenSSL con supporto SHA-3.
Ed25519 — richiede l’estensione libsodium; la chiave deve essere un PEM PKCS#8 che incapsula la chiave privata Ed25519.

Lo strumento rifiuta gli identificatori non supportati e restituisce l’elenco dei valori accettati.

L’envelope opzionale di cifratura del trasporto consente a chi effettua la chiamata di far transitare la chiave privata attraverso un trasporto che non è confidenziale end-to-end. L’envelope è solo AES-GCM:

Chiave simmetrica: 16, 24 o 32 byte (AES-128/192/256), codificata in base64.
Nonce: esattamente 12 byte, codificato in base64.
Dati autenticati aggiuntivi opzionali, codificati in base64.
Il payload private_key è il ciphertext base64 con un tag di autenticazione GCM finale di 16 byte.

La decifratura fallisce in modo chiuso: una mancata corrispondenza del tag di autenticazione o un payload malformato restituisce un errore di decifratura, e lo strumento non utilizza mai il ciphertext come materiale di chiave. Lo strumento rifiuta dimensioni errate di chiave o nonce prima di qualsiasi lavoro crittografico.

Casi limite e modalità FIPS

extract_text: lo strumento limita una fine di intervallo di pagine che eccede il documento anziché rifiutarla, e normalizza un inizio antecedente alla prima pagina alla prima pagina.
compare_pdfs: un source_a o source_b mancante restituisce un errore di convalida; documenti identici restituiscono un risultato esplicito di identicità con zero modifiche.
extract_form_data: i PDF privi di uno stream XFDF incorporato restituiscono un risultato con zero campi e una nota esplicativa, non un errore.
redact_pii: una voce non riconosciuta in types viene ignorata; un elenco interamente non riconosciuto produce una scansione vuota anziché un errore.
sign_pdf: un certificato o una chiave privata mancante fallisce prima di qualsiasi lavoro di firma; lo strumento verifica i requisiti dell’algoritmo (supporto SHA-3 in OpenSSL, libsodium per Ed25519) al momento della firma e li espone come errori espliciti.
Modalità FIPS: la disponibilità degli algoritmi segue la build OpenSSL/libsodium dell’host. In una build vincolata da FIPS, gli algoritmi non approvati falliscono al confine crittografico con un errore esplicito anziché effettuare un downgrade silenzioso. Il layer MCP non aggiunge né allenta la policy crittografica — espone la decisione del provider crittografico dell’host.

Note di runbook per l’operatore

Mantenere sign_pdf come approval-required. Verificare che non vi sia alcun override dell’operatore che innalzi involontariamente il rischio sugli strumenti safe — gli override solo restringono, quindi un override accidentale degrada la disponibilità, non la sicurezza.
Conservazione dell’audit: ogni esecuzione a livello review o superiore viene registrata nell’audit log dal server. Dimensionare la conservazione dei log per il volume delle chiamate a redact_pii, fill_form e sign_pdf.
Scelta del trasporto: quando si opera su un trasporto che non è confidenziale end-to-end, richiedere l’envelope di trasporto della chiave AES-GCM per sign_pdf e trattare il materiale della chiave privata come un segreto nella policy di logging delle chiamate agli strumenti del proprio agente.
Conteggi dei tier: usare il conteggio per tier del server per asserire, al momento del deploy, che il tier Pro abbia registrato otto strumenti; un conteggio pari a zero indica che il pacchetto Pro non si è risolto.

Confine di edizione

Il tier Pro contribuisce esattamente con otto strumenti MCP. L’edizione Enterprise distribuisce un tier MCP separato con i propri strumenti — compliance, analisi forense, salute della convalida a lungo termine, certificazione AI-ready e ricerca/embedding dei documenti. Gli input, gli output e gli interni degli strumenti Enterprise sono fuori ambito qui e documentati insieme all’edizione Enterprise. Il server scopre i tier in modo indipendente; un tier mancante non disabilita mai un altro.

Confine di pubblicazione

Questa pagina documenta solo il comportamento osservabile dall’esterno e la superficie di API pubblica supportata. I percorsi di namespace interni, le classi di supporto, le tabelle di meccanismi, i nomi dei file di runbook e i prefissi dei ticket sono fuori ambito.