Enterprise edizione

Strumenti MCP

In sintesi

NextPDF Enterprise aggiunge undici strumenti MCP al server NextPDF Connect. Offrono ad assistenti IA e framework agentici un accesso diretto e tipizzato al motore Enterprise: controlli di policy di conformità, analisi forense dei PDF, verifiche di integrità LTV, marcatura di prontezza IA, suddivisione consapevole dell’AST e ingestione e ricerca RAG. Ogni strumento dichiara il proprio livello di rischio e la propria postura di sola lettura, così l’host MCP può filtrare, registrare e sottoporre ad audit l’attività degli agenti con fiducia. I guasti non emergono mai come eccezioni; gli agenti ricevono sempre un risultato strutturato e analizzabile.

Disponibilità e licenze

Questa funzionalità è fornita in NextPDF Enterprise (nextpdf/enterprise) e si attiva con un envelope di licenza di livello Enterprise. Un deployment privo di tale titolo non carica le classi della funzionalità. Confronta le edizioni e ottieni una licenza.

Installazione

composer require nextpdf/enterprise:^3

L’host MCP stesso è NextPDF Connect, fornito nel pacchetto nextpdf/server; vedere Installazione di Connect. Quando entrambi i pacchetti sono presenti, il registro degli strumenti del server individua automaticamente NextPDF\Enterprise\McpToolProvider e registra gli undici strumenti Enterprise. Non è richiesto alcun codice di wiring. Se nextpdf/server è assente, il file del provider ritorna anticipatamente e non viene caricato nulla.

Gli strumenti batch e RAG richiedono inoltre il sidecar Spectrum. Configurarlo tramite le variabili d’ambiente lette da NextPDF\Enterprise\Mcp\SpectrumClientFactory: SPECTRUM_URL (predefinito http://127.0.0.1:7800), SPECTRUM_TIMEOUT (predefinito 30.0 secondi), SPECTRUM_AUTH_TOKEN e SPECTRUM_APP_SECRET.

Panoramica concettuale

Il Model Context Protocol (MCP) è un protocollo aperto che consente ad assistenti IA e framework agentici di chiamare strumenti tipizzati esposti da un server. Invece di incollare i byte del PDF in un prompt sperando che funzioni, un agente chiama uno strumento denominato con un payload validato tramite JSON-schema e riceve un risultato deterministico e strutturato. NextPDF Connect è quel server per i PDF; il pacchetto Enterprise ne estende il catalogo con gli strumenti descritti di seguito. Ogni strumento è un sottile wrapper sulle stesse API Enterprise che il codice PHP chiama direttamente, così un controllo eseguito da un agente e uno eseguito dal codice producono lo stesso verdetto.

Catalogo degli strumenti

Strumento MCP	Classe	Cosa fa	Rischio	Sola lettura
`compliance_check`	`ComplianceCheckTool`	Valida un PDF rispetto a una policy denominata: `pdfa4`, `pdfa4e`, `pdfa4f`, `pades-baseline`, `ltv-health`, `eidas-qualified`, `zugferd`, `fda-part11` e quattro varianti `sec-17a4`.	Review	sì
`batch_compliance_check`	`BatchComplianceCheckTool`	Controlla molti PDF rispetto alle policy `pdfa`, `pades` o `zugferd` in un unico batch del sidecar Spectrum.	Safe	sì
`forensic_analyze`	`ForensicAnalyzeTool`	Riporta cronologia delle revisioni, aggiornamenti incrementali ed eventi di modifica per il rilevamento di manomissioni.	Safe	sì
`batch_forensic_analyze`	`BatchForensicAnalyzeTool`	Esegue l’analisi forense su molti PDF in un unico batch del sidecar.	Safe	sì
`ltv_health_check`	`LtvHealthCheckTool`	Controlla in un PDF firmato la presenza di materiale di validazione a lungo termine: dizionario DSS, risposte OCSP, voci CRL, voci VRI e archivi dei certificati.	Safe	sì
`ai_ready_certify`	`AiReadyCertifyTool`	Verdetto di prontezza IA di sola lettura, definito dal prodotto, su quattro criteri: integrità forense, presenza di firma, validità LTV, assenza di cifratura.	Review	sì
`certify_ai_ready`	`CertifyAiReadyTool`	Verdetto di prontezza definito dal prodotto su tre criteri (i quattro dello strumento di sola lettura meno l’integrità forense - per progettazione, poiché questo strumento riscrive il file che marca) e appende un timbro di provenienza XMP; restituisce il PDF marcato come base64.	Review	no
`ast_aware_chunk`	`AstAwareChunkTool`	Suddivide un PDF in chunk ancorati alle citazioni lungo i confini delle intestazioni, con ID nodo, indice di pagina e bounding box per ogni chunk.	Review	sì
`audit_ast_mutations`	`AuditAstMutationsTool`	Recupera la traccia di audit delle mutazioni AST di un documento tramite l’hash di origine SHA-256.	Review	sì
`embed_documents`	`EmbedDocumentsTool`	Ingerisce PDF in una collezione RAG: analisi, suddivisione, embedding, indicizzazione. Modifica lo stato della collezione.	Caution	no
`search_documents`	`SearchDocumentsTool`	Recupero ibrido (BM25 per parola chiave più semantico) su una collezione ingerita, con chunk ordinati e con punteggio.	Safe	sì

Gli strumenti «certify» emettono un verdetto di prontezza definito dal prodotto (certified, partial o not_certified). Tale verdetto è il risultato di un controllo tecnico, non una certificazione da parte di un organismo di accreditamento.

Filtro di approvazione e postura di audit

Ogni strumento dichiara un livello di rischio secondo il modello Connect a quattro livelli. Gli strumenti Safe si eseguono automaticamente. Gli strumenti Caution si eseguono automaticamente con una voce nel log di audit. Gli strumenti Review recano un avviso per le istruzioni dell’agente chiamante. Gli strumenti ApprovalRequired richiedono conferma umana; nessuno strumento MCP Enterprise dichiara attualmente questo livello, perché nessuno è distruttivo. La configurazione a runtime può solo innalzare il livello di rischio di uno strumento, mai abbassarlo. Gli strumenti pubblicano inoltre annotazioni di comportamento MCP (readOnlyHint, idempotentHint), così un client conforme può applicare il proprio filtro al di sopra. Vedere Livelli di rischio HITL per il modello completo.

Perché funziona così

La decisione portante è che gli strumenti sono wrapper sottili e deterministici con governance auto-dichiarata: ogni strumento dichiara il proprio livello di rischio e il proprio tier come invariante di dominio, mai dedotto dal namespace o dal packaging. Ciò mantiene auditabile la decisione di filtro presso l’host senza fidarsi del transport. Gli strumenti non contengono alcuna intelligenza documentale propria; delegano alle stesse API Enterprise che il codice chiama, così esiste esattamente un comportamento da testare e un verdetto di cui fidarsi. Gli errori tornano sul canale di errore MCP invece di sfuggire come eccezioni, perché un agente non può catturare un’eccezione PHP ma può sempre diramare su isError. L’input che potrebbe toccare il filesystem è fail-closed per impostazione predefinita, poiché gli argomenti MCP sono raggiungibili da un aggressore per definizione.

Contesto progettuale: Un’API che rifiuta di indovinare.

Superficie API

Tutti gli undici strumenti implementano il contratto NextPDF\Server\Tools\ToolInterface di nextpdf/server e condividono la stessa superficie pubblica. Le firme seguenti sono mostrate una volta su NextPDF\Enterprise\Mcp\ComplianceCheckTool come rappresentativo:

public function name(): string
public function description(): string
public function inputSchema(): array
public function annotations(): array
public function riskLevel(): RiskLevel
public function tier(): ToolTier
public function category(): string
public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

Solleva o fallisce con: execute() non solleva mai. Cattura internamente Throwable e restituisce ToolResult::error() con isError = true. Gli argomenti non validi (workspace_token mancante, voci documents malformate, document_id sconosciuto, source non sicuro) emergono come messaggi di InvalidArgumentException su quel canale di errore.

Lo strumento della traccia di audit riceve il proprio backend di archiviazione tramite constructor injection:

public function __construct(private readonly AstAuditTrailInterface $auditTrail)

Il provider che registra il catalogo:

public function getTier(): string
public function getTools(): array

getTier() restituisce 'enterprise'. getTools() restituisce le undici istanze degli strumenti; audit_ast_mutations è cablato con NextPDF\Enterprise\Ast\InMemoryAstAuditTrail per impostazione predefinita.

La factory del client del sidecar Spectrum, che è anche una factory PSR-17 di richieste e stream:

public static function create(): SpectrumClient
public static function reset(): void
public function createRequest(string $method, $uri): RequestInterface
public function createStream(string $content = ''): StreamInterface
public function createStreamFromFile(string $filename, string $mode = 'r'): StreamInterface
public function createStreamFromResource($resource): StreamInterface

Solleva o fallisce con: create() solleva InvalidArgumentException quando SPECTRUM_URL è malformato o quando l’endpoint configurato punta a un indirizzo privato o riservato noto (eccetto localhost). Si tratta di un gate a tempo di configurazione, non di un controllo a livello di rete: applicare comunque policy di egress, gestione dei redirect e DNS pinning nell’ambiente host. createStreamFromFile() solleva NextPDF\Enterprise\Mcp\McpStreamException (una sottoclasse di RuntimeException, secondo il contratto PSR-17) quando il file non può essere aperto.

Esempio di codice — Avvio rapido

Eseguire un controllo di conformità PDF/A-4 esattamente come farebbe un agente, utilizzando il canale URI data: in memoria:

<?php

declare(strict_types=1);

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

use NextPDF\Enterprise\Mcp\ComplianceCheckTool;
use NextPDF\Enterprise\Mcp\McpStreamException;
use NextPDF\Enterprise\Mcp\SpectrumClientFactory;
use NextPDF\Server\Document\InMemoryDocumentStore;

$streams = new SpectrumClientFactory(); // PSR-17 stream factory from this module

try {
    $pdfBytes = (string) $streams->createStreamFromFile(__DIR__ . '/invoice.pdf');
} catch (McpStreamException $e) {
    fwrite(STDERR, 'Cannot read PDF: ' . $e->getMessage() . PHP_EOL);
    exit(1);
}

$tool   = new ComplianceCheckTool();
$result = $tool->execute(
    [
        'source' => 'data:application/pdf;base64,' . base64_encode($pdfBytes),
        'policy' => 'pdfa4',
    ],
    new InMemoryDocumentStore(),
);

// Tool failures arrive on the MCP error channel, never as exceptions.
if ($result->isError) {
    fwrite(STDERR, $result->content[0]['text'] . PHP_EOL);
    exit(1);
}

echo $result->content[0]['text'] . PHP_EOL;

Output atteso per un file conforme (i conteggi dei findings variano per documento):

Compliance check (PDF/A-4): PASS — 0 finding(s)

Il report completo leggibile dalla macchina, comprensivo di severità per finding, ID regola, clausola e suggerimento, è disponibile su $result->structured.

Esempio di codice — Produzione

Effettuare il preflight del sidecar, applicare la postura di rischio dichiarata, quindi eseguire un controllo di conformità in batch:

<?php

declare(strict_types=1);

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

use NextPDF\Enterprise\Mcp\BatchComplianceCheckTool;
use NextPDF\Enterprise\Mcp\SpectrumClientFactory;
use NextPDF\Server\Document\InMemoryDocumentStore;

// 1. Fail fast on sidecar misconfiguration before accepting agent traffic.
//    The factory validates SPECTRUM_URL and rejects private/reserved targets.
try {
    SpectrumClientFactory::create();
} catch (InvalidArgumentException $e) {
    fwrite(STDERR, 'Spectrum sidecar rejected: ' . $e->getMessage() . PHP_EOL);
    exit(1);
}

$tool = new BatchComplianceCheckTool();
$risk = $tool->riskLevel();

// 2. Enforce the declared risk posture before execution.
if ($risk->requiresHumanConfirmation()) {
    // Route to your approval queue instead of executing.
    exit(0);
}

if ($risk->requiresAuditLog()) {
    error_log(sprintf('[mcp-audit] tool=%s risk=%s', $tool->name(), $risk->label()));
}

// 3. Execute the batch.
$result = $tool->execute(
    [
        'workspace_token' => (string) getenv('SPECTRUM_WORKSPACE_TOKEN'),
        'documents'       => [
            ['id' => 'contract-001', 'path' => '/var/pdf-inbox/contract-001.pdf'],
            ['id' => 'contract-002', 'path' => '/var/pdf-inbox/contract-002.pdf'],
        ],
        'policies'        => ['pdfa', 'pades'],
    ],
    new InMemoryDocumentStore(),
);

echo $result->content[0]['text'] . PHP_EOL;

Output atteso (i conteggi riflettono i tuoi documenti):

Batch compliance check complete: 1 compliant, 1 non-compliant

Casi limite e insidie

I percorsi source del filesystem sono disabilitati per impostazione predefinita. Senza la variabile d’ambiente NEXTPDF_MCP_INPUT_DIR, un source con forma di percorso viene rifiutato con un risultato di errore. Usare invece document_id, un URI data: o base64 grezzo.
Il base64 grezzo è riconosciuto solo oltre i 256 caratteri. Un blob base64 più corto è trattato come percorso di file e rifiutato. Incapsulare i payload piccoli in un URI data:application/pdf;base64,.
I valori document_id sconosciuti falliscono con indicazioni. Il testo di errore è Unknown document_id: ... Call create_pdf first. I documenti nello store in memoria scadono inoltre secondo il TTL dello store, quindi un ID obsoleto fallisce allo stesso modo.
compliance_check rifiuta le chiavi di policy sconosciute ed elenca l’insieme supportato nel messaggio di errore.
Gli strumenti batch e RAG necessitano del sidecar. batch_compliance_check, batch_forensic_analyze, embed_documents e search_documents richiedono un endpoint Spectrum raggiungibile e un workspace_token. La factory memorizza in cache un client per processo; chiamare SpectrumClientFactory::reset() nei test.
search_documents limita top_k a 1–100; i valori non interi ricadono sul valore predefinito del server di 10.
I valori predefiniti di ast_aware_chunk sono 1500 caratteri per chunk con 150 caratteri di sovrapposizione.
certify_ai_ready omette i byte marcati quando return_stamped_pdf è false o il verdetto è not_certified. Quando presente, il payload base64 è circa un terzo più grande del PDF stesso.
La traccia di audit AST predefinita è in memoria. Le voci registrate tramite il wiring standard del provider non persistono tra i processi; iniettare un’implementazione persistente di AstAuditTrailInterface per tracce di audit durevoli.

Note di sicurezza

Risoluzione della sorgente fail-closed. I chiamanti MCP controllano completamente gli argomenti degli strumenti, quindi il resolver li tratta come ostili. Gli stream wrapper (phar://, php://, file:// e qualsiasi schema) e i null byte vengono rifiutati prima di qualsiasi chiamata al filesystem. Il path traversal viene rifiutato. I percorsi di file grezzi funzionano solo quando NEXTPDF_MCP_INPUT_DIR è impostata, e il target canonicalizzato con realpath deve risolversi rigorosamente all’interno di quella directory, confrontato su un confine di separatore per bloccare le fughe da confusione di prefisso.
Guardia SSRF sull’endpoint del sidecar. SpectrumClientFactory consente localhost per la modalità sidecar locale e valida ogni altro SPECTRUM_URL rispetto agli intervalli privati, riservati, link-local e di metadati cloud, sollevando InvalidArgumentException su un indirizzo bloccato. Si tratta di un gate a tempo di configurazione sull’endpoint configurato, non di un controllo a livello di rete - mantenere policy di egress, gestione dei redirect e DNS pinning nell’ambiente host.
I segreti restano nell’ambiente. Il token bearer del sidecar (SPECTRUM_AUTH_TOKEN) e il segreto di firma HMAC (SPECTRUM_APP_SECRET) sono letti dalle variabili d’ambiente e non compaiono mai nei payload o nei risultati degli strumenti.
Errori non riflettenti. I messaggi di rifiuto del percorso sono generici per progettazione (Source path is not permitted.), così un chiamante che sonda non apprende nulla sul filesystem dell’host.
Gli override di rischio vanno solo verso l’alto. La configurazione dell’operatore può innalzare il livello di rischio dichiarato di uno strumento ma non può mai abbassarlo al di sotto della dichiarazione dello strumento stesso.

Conformità

Il supporto non è conformità, e la conformità non è certificazione. NextPDF non detiene alcuna certificazione e non ne concede alcuna. Gli strumenti di conformità controllano la struttura del documento rispetto ai profili di policy denominati e riportano i findings con riferimenti di clausola; il report di compliance_check reca inoltre il disclaimer del motore stesso, secondo cui si tratta di un controllo tecnico della struttura a scopo di riferimento, non di consulenza legale o di un’approvazione di conformità. I verdetti di ai_ready_certify e certify_ai_ready sono livelli di prontezza definiti dal prodotto, non un’attestazione da parte di alcun organismo normativo. MCP è un protocollo aperto pubblicato dal suo vendor steward, non uno standard SDO; questa pagina documenta il comportamento dell’implementazione di NextPDF e non avanza alcuna affermazione indipendente di conformità al protocollo o di certificazione.

Contratto di comportamento

I guasti degli strumenti sono restituiti come risultati di errore (isError = true con un messaggio); le eccezioni non attraversano mai il confine MCP.
I risultati riusciti recano un riepilogo leggibile su una riga più un payload JSON strutturato con un insieme di campi stabile e documentato per ciascuno strumento.
Ogni strumento riporta tier() = ToolTier::Enterprise e un RiskLevel dichiarato; il rischio non può essere abbassato a runtime.
Gli strumenti di sola lettura dichiarano readOnlyHint: true e non modificano lo store dei documenti, il PDF sorgente o alcuna collezione.
certify_ai_ready non altera mai il documento di input sul posto; il timbro è applicato a una copia restituita.
I report di conformità e LTV includono un timestamp di validazione e i conteggi dei findings per severità; il payload di compliance_check include inoltre la stringa di disclaimer legale del motore.

Fallback su Core

L’host MCP stesso non richiede Enterprise. NextPDF Connect (nextpdf/server, Apache-2.0) funziona con il motore Core aperto e serve il proprio catalogo di strumenti di livello core: creazione di documenti, operazioni su testo e contenuto ed estrazione. Vedere il catalogo degli strumenti. Il solo Core non fornisce controlli di policy di conformità, analisi forense, verifiche di integrità LTV, marcatura di prontezza IA, suddivisione consapevole dell’AST, tracce di audit delle mutazioni o gli strumenti batch e RAG; quegli undici strumenti si registrano solo con nextpdf/enterprise installato e concesso in licenza.

Confine di pubblicazione

Questa pagina documenta esclusivamente il comportamento osservabile dall’esterno e la superficie 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.