Pro edizione

Strumenti MCP

In breve

NextPDF Pro aggiunge otto strumenti Model Context Protocol (MCP) che consentono a un agente AI di eseguire operazioni avanzate sui PDF tramite NextPDF Server. Gli strumenti compaiono automaticamente quando sono installati sia nextpdf/pro sia nextpdf/server — non è richiesto alcun passaggio di registrazione separato.

Disponibilità e licensing

Questa funzionalità è inclusa 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.

La superficie MCP di base — creazione di documenti, testo, tabelle, diagnostica — è inclusa nell’open-source NextPDF Server e non necessita di licenza. Gli otto strumenti di questa pagina richiedono una licenza Pro e si registrano solo quando il pacchetto nextpdf/pro si risolve all’avvio. Il tier di strumenti pro controlla l’intero set: ogni strumento dichiara esplicitamente il proprio tier e non esiste un flag per ciascuno strumento — installare nextpdf/pro insieme a nextpdf/server abilita il set.

Contratto di comportamento

Gli otto strumenti MCP di Pro si registrano automaticamente quando sia nextpdf/pro sia nextpdf/server si risolvono all’avvio, sotto il tier pro, attraverso il flusso MCP standard tools/list e tools/call. Non esiste un flag per ciascuno strumento né alcuna modifica al codice nell’applicazione che consuma il servizio.
Ciascuno strumento accetta un PDF tramite un document_id proveniente da una precedente chiamata create_pdf, una source inline (percorso di file, base64 o URI data:) oppure — per compare_pdfs — due di tali sorgenti. Gli strumenti restituiscono JSON strutturato.
Ogni strumento dichiara una classe di rischio HITL che il server applica: safe (esecuzione automatica, sola lettura), review (output potenzialmente soggetto a uso improprio) e approval-required. sign_pdf è approval-required e viene trattenuto finché un essere umano non lo conferma. Un operatore può solo rendere più rigorosa la classe di rischio di uno strumento, mai allentarla.
sign_pdf produce esclusivamente una firma PAdES B-B (baseline) — nessuna marca temporale attendibile e nessun materiale di convalida a lungo termine. I profili a lungo termine (B-LT / B-LTA), la custodia delle chiavi su hardware e la firma con audit-trail sono di tier Enterprise e non sono forniti da questi strumenti; B-T (una firma con marca temporale) è disponibile nel motore Core quando è configurato un provider di marche temporali.
redact_pii esegue il rilevamento di pattern e il mascheramento sul livello di testo, non l’oscuramento visivo; check_accessibility è un’euristica strutturale, non un verdetto di conformità PDF/UA o WCAG. Lo schema di input/output autorevole è la risposta tools/list viva del server, non questa pagina.

Panoramica concettuale

NextPDF Server è il livello di esecuzione MCP deterministico per NextPDF. Individua i provider di strumenti all’avvio tramite una sonda di esistenza delle classi, così che il pacchetto Pro non debba essere elencato tra le dipendenze del server. Quando il pacchetto Pro è presente, il server registra i suoi otto strumenti sotto il tier pro e li espone attraverso il flusso MCP standard tools/list e tools/call su qualunque trasporto si sia configurato.

Ciascuno strumento Pro accetta un PDF da una di tre sorgenti: un document_id restituito da una precedente chiamata create_pdf, una source inline (percorso di file, stringa base64 o URI data:) oppure — per lo strumento di confronto — due di tali sorgenti. Gli strumenti restituiscono risultati JSON strutturati: testo estratto, regioni di diff, testo mascherato, alberi di segmenti, esiti di accessibilità o un PDF firmato.

Ogni strumento Pro porta con sé una classificazione di rischio che il server usa per l’enforcement human-in-the-loop (HITL). Gli strumenti di analisi in sola lettura sono classificati come safe e si eseguono automaticamente. Gli strumenti che generano un output suscettibile di uso improprio da parte di un chiamante sono classificati per review. Lo strumento di firma è classificato come approval-required, quindi il server lo trattiene finché un essere umano non lo conferma. È lo strumento stesso a dichiarare questa classificazione; un operatore può solo renderla più rigorosa a runtime — mai allentarla.

La superficie degli strumenti MCP è deliberatamente separata dal motore PDF di Pro. Gli strumenti sono adattatori sottili: convalidano gli input, risolvono il PDF, delegano a un componente del motore di Pro e serializzano il risultato. Non sono una seconda API per il motore e non fanno parte dell’API PHP pubblica di Pro — il punto di integrazione supportato è il protocollo MCP esposto da NextPDF Server.

Catalogo degli strumenti (otto strumenti Pro)

Gli otto strumenti MCP di Pro, secondo il nome del protocollo MCP. I livelli di rischio seguono il modello HITL del server: safe (esecuzione automatica, sola lettura), review (genera un output suscettibile di uso improprio; segnalato nelle istruzioni dell’agente) e approval-required (deve essere confermato da un essere umano).

`extract_text`

Scopo: estrazione di testo. Estrae il livello di testo di un PDF, facoltativamente limitato a un intervallo di pagine indicizzato a partire da 1.
Input: un PDF (document_id o source); facoltativi page_start e page_end.
Output: il testo estratto e il numero totale di pagine.
Rischio: safe. Sola lettura e idempotente.
Confine: estrae il livello di testo esistente. Non esegue OCR su pagine scansionate o di sole immagini.

`segment_document`

Scopo: segmentazione strutturale. Suddivide un PDF in sezioni logiche — titolo, intestazioni, corpo, tabelle, figure.
Input: un PDF (document_id o source).
Output: un conteggio dei segmenti e un elenco strutturato di segmenti.
Rischio: safe. Sola lettura e idempotente.
Confine: segmentazione strutturale basata sull’analisi del layout; non è una struttura semantica né un albero di struttura di un PDF taggato.

`compare_pdfs`

Scopo: diff strutturale. Confronta due PDF e restituisce un diff strutturato del loro contenuto testuale.
Input: due PDF (source_a e source_b, ciascuno un percorso, base64, URI data o document_id).
Output: un flag di identità, il conteggio totale delle modifiche, il numero di pagine per ciascun documento e un elenco delle regioni modificate con gli indici di pagina e di riga.
Rischio: safe. Sola lettura e idempotente.
Confine: diff del contenuto testuale. Non confronta il rendering visivo, i font incorporati né la struttura binaria.

`redact_pii`

Scopo: rilevamento e mascheramento di PII. Rileva informazioni di identificazione personale nel livello di testo di un PDF e restituisce una vista mascherata del testo.
Input: un PDF (document_id o source); filtro types facoltativo (email, phone, ssn, credit_card).
Output: un flag di presenza di PII, il conteggio dei rilevamenti, il testo mascherato e l’elenco dei tipi analizzati.
Rischio: review. L’output mascherato potrebbe essere usato in modo improprio se trattato come un documento sanificato.
Confine: si tratta di rilevamento di pattern e mascheramento sul livello di testo, non di oscuramento visivo. Non rimuove né sovrascrive i glifi nel PDF renderizzato e la corrispondenza di pattern non garantisce che ogni occorrenza di dati sensibili venga trovata. Non trattare il suo output come una garanzia di rimozione completa delle PII. Per un oscuramento a livello di documento che distrugge il contenuto sottostante, usare la superficie di oscuramento dedicata negli strumenti open-source del server o l’edizione Enterprise.

`fill_form`

Scopo: dati di compilazione AcroForm. Genera dati XFDF (ISO 19444-1) che compilano i campi AcroForm di un PDF a partire da una mappa di nomi di campo su valori.
Input: una mappa fields di nome di campo su valore stringa; pdf_filename facoltativo incorporato come riferimento XFDF.
Output: il documento XFDF generato e il conteggio dei campi.
Rischio: review. Produce dati di modulo destinati a essere applicati a un documento.
Confine: produce XFDF conforme allo standard; non scrive di per sé i valori all’interno di un PDF. Applicare l’XFDF con qualsiasi reader o strumento di elaborazione conforme.

`extract_form_data`

Scopo: rilettura di AcroForm. Estrae i nomi e i valori dei campi AcroForm dall’XFDF incorporato in un PDF.
Input: un PDF (document_id o source).
Output: un conteggio dei campi e una mappa di nomi di campo su valori; una nota esplicita quando non è presente alcun dato di modulo incorporato.
Rischio: safe. Sola lettura e idempotente.
Confine: legge gli stream XFDF (ISO 19444-1) incorporati. Un PDF che conserva i valori del modulo soltanto in oggetti AcroForm senza XFDF incorporato restituisce un risultato vuoto.

`check_accessibility`

Scopo: analisi strutturale di accessibilità. Analizza l’accessibilità strutturale di un PDF — intestazioni, paragrafi, tabelle e immagini — e segnala i probabili problemi con riferimenti WCAG.
Input: un PDF (document_id o source).
Output: un punteggio strutturale (0–100), un elenco di problemi e un riepilogo dei segmenti.
Rischio: safe. Sola lettura e idempotente.
Confine: si tratta di un’euristica strutturale, non di un verdetto di conformità. Il test completo di conformità PDF/UA e WCAG — albero dei tag, ordine di lettura, contrasto cromatico — richiede un motore di accessibilità dedicato. Un punteggio elevato non è una dichiarazione di conformità PDF/UA.

`sign_pdf`

Scopo: firma digitale PAdES B-B. Applica una firma digitale PAdES B-B (baseline) a un PDF usando un certificato X.509 locale e una chiave privata.
Input: un PDF (document_id o source); un certificato PEM e una chiave privata PKCS#8; un algoritmo facoltativo (RSA-SHA256 predefinito, RSA + SHA-3 256/384/512 o Ed25519); nome e motivo del firmatario facoltativi; un envelope di trasporto AES-GCM facoltativo attorno al payload della chiave privata.
Output: il PDF firmato, il conteggio delle firme, il flag di completamento e l’algoritmo, l’OID e il digest utilizzati.
Rischio: approval-required. La firma è un’operazione giuridicamente rilevante e distruttiva; il server richiede una conferma umana esplicita prima di eseguirla.
Confine: questo strumento produce una firma PAdES B-B (baseline) — non incorpora una marca temporale attendibile né materiale di convalida a lungo termine. I profili a lungo termine (B-LT / B-LTA), la custodia delle chiavi su hardware e la firma con audit-trail fanno parte dell’edizione Enterprise; B-T (una firma con marca temporale) è disponibile nel motore Core quando è configurato un provider di marche temporali. Vedere la superficie di firma di Pro per le capacità di firma più ampie del pacchetto Pro e l’edizione Enterprise per B-LT/B-LTA.

Come compaiono gli strumenti

composer require nextpdf/pro
composer require nextpdf/server

Con entrambi i pacchetti installati, avviare NextPDF Server con il trasporto scelto. Il server individua il tier Pro all’avvio e gli otto strumenti compaiono nella risposta MCP tools/list sotto il tier pro accanto agli strumenti open-source di Core. L’applicazione non necessita di alcuna modifica al codice — l’individuazione avviene automaticamente e un tier mancante non blocca mai il caricamento degli altri.

Lo schema di input e output autorevole per ogni strumento è lo schema che il server pubblica nella sua risposta tools/list. Trattare quella risposta — non questa pagina — come il contratto: questo catalogo descrive intenti e confini; lo schema vivo descrive i nomi e i tipi esatti dei campi.

Esempio di codice — Avvio rapido

Gli strumenti Pro sono consumati tramite il protocollo MCP, non tramite un’API PHP di Pro. L’integrazione lato host consiste nell’avviare NextPDF Server. Con nextpdf/pro presente, gli otto strumenti si registrano tramite individuazione a runtime — nessun cablaggio per ciascuno strumento — e l’host li serve poi agli agenti.

<?php

declare(strict_types=1);

use NextPDF\Server\Mcp\McpServer;

require __DIR__ . '/vendor/autoload.php';

// Runtime discovery registers the Pro tier when nextpdf/pro is installed
// alongside nextpdf/server. The consuming application changes no code.
$server = McpServer::create();

// A Pro tool name resolves only when the Pro package is present.
$signTool = $server->getToolRegistry()->get('sign_pdf');

\fwrite(\STDERR, $signTool !== null
    ? "Pro MCP tools active.\n"
    : "Pro MCP tools unavailable; install nextpdf/pro.\n");

// Serve the MCP protocol over stdio (Claude Desktop, Cursor, local agents).
$server->run();

Esempio di codice — Produzione

Irrobustire il percorso di avvio. Caricare un file di policy esplicito, rifiutare l’avvio in presenza di un override non valido del livello di rischio e confermare che il tier Pro sia comparso prima di servire. Il cablaggio in McpServer::create() solleva InvalidArgumentException quando un blocco risk_level_overrides tenta di indebolire uno strumento approval-required come sign_pdf, così che una policy configurata male fallisca fail-closed prima del loop di servizio.

<?php

declare(strict_types=1);

use NextPDF\Server\Mcp\McpServer;
use NextPDF\Server\Tools\ToolInterface;

require __DIR__ . '/vendor/autoload.php';

// A downgrade of an approval-required tool's HITL gate is rejected at boot,
// never silently applied — the server refuses to start on such a policy.
try {
    $server = McpServer::create(__DIR__ . '/nextpdf-mcp.yaml');
} catch (\InvalidArgumentException $e) {
    \fwrite(\STDERR, 'Refusing to start: invalid MCP policy. ' . $e->getMessage() . "\n");
    exit(1);
}

// Confirm the Pro tier surfaced before advertising it to agents.
$signTool = $server->getToolRegistry()->get('sign_pdf');

if (!$signTool instanceof ToolInterface) {
    \fwrite(\STDERR, "nextpdf/pro is not resolving; Pro MCP tools are unavailable.\n");
    exit(1);
}

// sign_pdf is approval-required; the server holds it for human confirmation.
$risk = $signTool->riskLevel()->label();
\fwrite(\STDERR, "Pro MCP tools ready. sign_pdf risk: {$risk}.\n");

$server->run();

Indicazioni per la produzione

Gating HITL. Mantenere sign_pdf dietro una conferma umana. Il server applica questo vincolo a partire dal livello di rischio dichiarato dello strumento; non configurare l’agente in modo da aggirarlo. Un operatore può solo rendere più rigoroso il livello di rischio di uno strumento, mai allentarlo.
Gestione delle sorgenti. Preferire document_id per i documenti già presenti nella sessione. Per i dati inline gli strumenti accettano base64 e URI data:; payload inline molto grandi sono più lenti di un documento referenziato.
Aspettative sulle PII. Definire esplicitamente le aspettative del chiamante: redact_pii è un ausilio di rilevamento e mascheramento, non una garanzia di sanificazione. Per una rimozione irreversibile, instradare verso una superficie di oscuramento dedicata.
Chiavi di firma. Fornire le chiavi tramite l’envelope di cifratura del trasporto quando il trasporto non è confidenziale end-to-end. Trattare il materiale della chiave privata come un segreto nella policy di logging delle chiamate degli strumenti dell’agente.
Audit logging. Gli strumenti al di sopra del livello safe sono soggetti ad audit logging da parte del server. Assicurarsi che il proprio deployment conservi tali log secondo i propri requisiti di compliance.

Casi limite

Gli intervalli di pagine di extract_text sono indicizzati a partire da 1 e limitati (clamp) al numero reale di pagine del documento; un valore finale fuori intervallo non genera errore.
compare_pdfs richiede entrambe le sorgenti; passarne una sola restituisce un chiaro errore di convalida anziché un diff parziale.
extract_form_data restituisce un risultato esplicito e popolato «nessun dato di modulo incorporato» anziché un errore per i PDF privi di XFDF incorporato.
sign_pdf rifiuta gli identificatori di algoritmo non supportati con l’elenco dei valori supportati; Ed25519 richiede l’estensione libsodium e le varianti SHA-3 richiedono una build di OpenSSL con supporto SHA-3.
check_accessibility assegna per progettazione un punteggio basso ai PDF di sole immagini — segnala l’assenza di un livello di testo leggibile anziché fallire.

Note sulla sicurezza

Lo strumento di firma è l’unico strumento approval-required; il server non lo esegue automaticamente.
L’envelope AES-GCM facoltativo attorno alla chiave privata autentica il payload; un tag non corrispondente fallisce fail-closed con un errore di decifratura e non ripiega mai sull’uso del ciphertext.
redact_pii non altera il PDF di origine; restituisce una rappresentazione testuale mascherata. Non sostituisce la distruzione del contenuto.
Lo strumento convalida gli input prima di qualsiasi lavoro del motore; rifiuta con errori espliciti le sorgenti malformate, gli URI data e i payload base64.

Conformità

Gli strumenti per i moduli producono e consumano XFDF secondo ISO 19444-1:2019 (XML Forms Data Format).
sign_pdf produce una firma PAdES baseline (B-B) allineata alla famiglia PAdES di ETSI EN 319 142; i profili a lungo termine sono una capacità Enterprise, e B-T è disponibile nel motore Core quando è configurato un provider di marche temporali.
check_accessibility segnala gli esiti con riferimenti ai criteri di successo WCAG (ad esempio 1.1.1, 1.3.1, 2.4.6) come guida euristica, non come attestazione di conformità.

Confine di edizione

NextPDF Pro contribuisce esattamente con otto strumenti MCP, tutti al tier pro. L’edizione Enterprise include un proprio set distinto di strumenti MCP al tier enterprise — che copre il controllo di conformità, l’analisi forense, lo stato di salute della convalida a lungo termine, la certificazione AI-ready e la ricerca e l’embedding dei documenti. Quegli strumenti, i loro input e i loro dettagli interni sono fuori ambito per questa pagina; vedere gli strumenti MCP di Enterprise. La documentazione del server stesso copre gli strumenti Core (open-source) inclusi con esso. Il server individua i tre tier in modo indipendente e un tier mancante non disabilita mai gli altri.

Nota sul confine Enterprise

Pro contribuisce esattamente con otto strumenti MCP al tier pro. L’edizione Enterprise include un set distinto di strumenti MCP al tier enterprise (controllo di conformità, analisi forense, stato di salute della convalida a lungo termine, certificazione AI-ready, ricerca ed embedding dei documenti) e i profili di firma con marca temporale/a lungo termine; questi non sono forniti dal tier Pro. Vedere la sezione Confine di edizione sopra per la suddivisione completa dei tier.

Fallback / alternativa di Core

L’open-source NextPDF Server fornisce a qualsiasi agente AI un toolset PDF di Core deterministico (creazione di documenti, testo, tabelle, diagnostica) senza licenza. Gli otto strumenti avanzati di questa pagina sono aggiunte di Pro. Vedere /connect/tools/.

Confine di pubblicazione

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