MCP — Riferimento approfondito

In sintesi

Il namespace NextPDF\Enterprise\Mcp fornisce il livello Enterprise del catalogo di strumenti MCP di NextPDF. La sua superficie pubblica è composta da undici classi di strumenti, una factory di client e un’eccezione tipizzata. Ogni strumento implementa il contratto NextPDF\Server\Tools\ToolInterface del runtime nextpdf/server e dichiara ToolTier::Enterprise. Sei strumenti analizzano un singolo PDF in-process. Quattro strumenti delegano i carichi di lavoro batch e RAG al sidecar Spectrum tramite NextPDF\Enterprise\Mcp\SpectrumClientFactory. Uno strumento legge una traccia di audit delle mutazioni AST iniettata nel costruttore invece dei byte del PDF. Ogni strumento auto-descrive il proprio nome MCP, lo schema JSON di input, le annotazioni del client, il RiskLevel e la categoria.

Disponibilità e licenze

Questa capacità è fornita in NextPDF Enterprise (nextpdf/enterprise) e si attiva con un envelope di licenza di livello Enterprise. Una distribuzione priva di tale entitlement non carica le classi della capacità. Confronta le edizioni e ottieni una licenza.

Superficie API pubblica

Simbolo	Parametri	Comportamento predefinito	Restituisce	Solleva o fallisce con	Note
ForensicAnalyzeTool::execute	array $arguments, InMemoryDocumentStore $store; arg: document_id o source	Esegue l’analisi forense: revisioni, aggiornamenti incrementali, firme	ToolResult (report JSON)	ToolResult di errore; le eccezioni vengono catturate, mai rilanciate	Strumento forensic_analyze; RiskLevel::Safe; sola lettura, idempotente; categoria document; da 2.0.0
BatchForensicAnalyzeTool::execute	arg: workspace_token, documents[] (ciascuno id + path)	Analisi forense batch tramite il sidecar Spectrum	ToolResult con status per documento, conteggi di riusciti e falliti	ToolResult di errore (argomenti mancanti, fallimento del sidecar)	Strumento batch_forensic_analyze; RiskLevel::Safe; categoria document; da 2.1.0
ComplianceCheckTool::execute	arg: policy (enum a 12 valori), document_id o source	Valuta il PDF rispetto a una policy di conformità nominata	ToolResult con esiti, pass/fail, duration_ms e un campo disclaimer	ToolResult di errore; una policy sconosciuta restituisce un errore che elenca le chiavi supportate	Strumento compliance_check; RiskLevel::Review; categoria document; da 2.0.0
BatchComplianceCheckTool::execute	arg: workspace_token, documents[], policies (pdfa, pades, zugferd; predefinito ["pdfa"])	Verifiche di conformità batch tramite il sidecar Spectrum	ToolResult con conteggi di conformi / non conformi	ToolResult di errore; ogni elemento documents[] viene validato per id e path non vuoti	Strumento batch_compliance_check; RiskLevel::Safe; categoria document; da 2.1.0
LtvHealthCheckTool::execute	arg: document_id o source	Esegue la policy di salute LTV su un PDF firmato	ToolResult con esiti e pass/fail	ToolResult di errore	Strumento ltv_health_check; RiskLevel::Safe; categoria document; da 2.0.0
AiReadyCertifyTool::execute	arg: document_id o source	Valutazione di sola lettura della prontezza per l’IA su quattro criteri	ToolResult con certification_level (certified, partial, not_certified) e booleani per criterio	ToolResult di errore	Strumento ai_ready_certify; RiskLevel::Review; sola lettura; categoria document; da 2.0.0
CertifyAiReadyTool::execute	arg: document_id o source, return_stamped_pdf (predefinito true)	Valuta tre criteri e appone un timbro di provenienza XMP	ToolResult; include stamped_pdf_base64 salvo se disabilitato o not_certified	ToolResult di errore	Strumento certify_ai_ready; RiskLevel::Review; non sola lettura; categoria document; da 3.0.0
AstAwareChunkTool::execute	arg: document_id o source, max_chunk_chars (predefinito 1500), overlap_chars (predefinito 150)	Costruisce l’AST ed emette chunk ancorati a citazioni con provenienza	ToolResult con chunk_count e, per chunk, ID del nodo, indice di pagina, bbox, tipo di nodo	ToolResult di errore	Strumento ast_aware_chunk; RiskLevel::Review; categoria extraction; da 3.0.0
AuditAstMutationsTool::__construct	AstAuditTrailInterface $auditTrail	Inietta il backend della traccia di audit	istanza	—	Dipendenza iniettata nel costruttore; da 3.0.0
AuditAstMutationsTool::execute	arg: document_source_hash (SHA-256 esadecimale, obbligatorio)	Restituisce tutti gli eventi di mutazione AST registrati per quel documento	ToolResult con entries[] e count	ToolResult di errore quando l’argomento è mancante o vuoto	Strumento audit_ast_mutations; RiskLevel::Review; categoria document; da 3.0.0
EmbedDocumentsTool::execute	arg: collection_id, workspace_token, documents[] (tutti obbligatori)	Ingerisce PDF in una collezione RAG tramite il sidecar Spectrum	ToolResult con conteggi di riusciti / totali / falliti	ToolResult di errore	Strumento embed_documents; RiskLevel::Caution; non sola lettura, non idempotente; categoria extraction; da 2.1.0
SearchDocumentsTool::execute	arg: collection_id, query (obbligatorio), top_k (predefinito 10, limitato a 1–100), mode (hybrid, bm25, semantic)	Recupero ibrido su una collezione ingerita	ToolResult con chunk ordinati e punteggi di rilevanza	ToolResult di errore; un mode fuori dall’allowlist viene rifiutato	Strumento search_documents; RiskLevel::Safe; categoria extraction; da 2.1.0
SpectrumClientFactory::create	nessuno (legge SPECTRUM_URL, SPECTRUM_TIMEOUT, SPECTRUM_AUTH_TOKEN, SPECTRUM_APP_SECRET)	Costruisce e mette in cache un client sidecar unico per l’intero processo	SpectrumClient	InvalidArgumentException quando SPECTRUM_URL è malformato o punta a un indirizzo bloccato	Endpoint predefinito http://127.0.0.1:7800; timeout 30.0 s; da 2.1.0
SpectrumClientFactory::reset	nessuno	Svuota l’istanza di client in cache	void	—	Destinato ai test
SpectrumClientFactory::createRequest	string $method, $uri (string o UriInterface)	Costruisce una richiesta PSR-7 dalle classi HTTP di Core	RequestInterface	—	Implementazione PSR-17 RequestFactoryInterface
SpectrumClientFactory::createStream	string $content = ''	Costruisce uno stream PSR-7 in memoria	StreamInterface	—	Implementazione PSR-17 StreamFactoryInterface
SpectrumClientFactory::createStreamFromFile	string $filename, string $mode = 'r'	Apre il file e lo incapsula come stream	StreamInterface	McpStreamException quando il file non può essere aperto	McpStreamException estende RuntimeException
SpectrumClientFactory::createStreamFromResource	$resource (risorsa PHP)	Incapsula una risorsa esistente come stream	StreamInterface	—	Implementazione PSR-17 StreamFactoryInterface
McpStreamException	—	Fallimento tipizzato di acquisizione dello stream	—	—	final class, estende RuntimeException; la fonte documenta la compatibilità PSR-17 §1.5; la fonte la annota @since 3.2.0 (presente nell’attuale linea di sviluppo aliasata a 3.1.0)

Ogni strumento espone anche i metodi di auto-descrizione di ToolInterface: name, description, inputSchema, annotations, riskLevel, tier e category. I loro valori per strumento compaiono nella colonna Note qui sopra.

Firme dei punti di ingresso, verbatim dalla fonte:

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function __construct(private readonly AstAuditTrailInterface $auditTrail)
public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

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

Contratto di comportamento

• Ogni strumento implementa NextPDF\Server\Tools\ToolInterface e dichiara ToolTier::Enterprise in modo esplicito. Il tier non viene mai dedotto dal namespace o dal packaging.
• execute non solleva eccezioni. Ogni fallimento viene catturato e restituito come ToolResult di errore che riporta il messaggio di fallimento.
• Gli strumenti a documento singolo risolvono i byte del PDF con una priorità fissa. Un document_id viene prima cercato nell’InMemoryDocumentStore. Altrimenti source viene interpretato come URI data:, poi come base64 grezzo (oltre 256 caratteri), poi come percorso di file.
• I percorsi di source sul filesystem sono disabilitati per impostazione predefinita. Si attivano solo quando la variabile d’ambiente NEXTPDF_MCP_INPUT_DIR nomina una directory di input confinata. Il percorso reale risolto deve rimanere all’interno di tale directory. Tutto il resto fallisce in chiusura.
• Gli schemi wrapper di stream (phar://, php://, file:// e qualsiasi altro schema) e i byte null in un source che è un percorso di file vengono rifiutati prima di qualsiasi chiamata al filesystem. Attraversamenti ed escape tramite symlink falliscono contro la verifica di confinamento sul percorso reale.
• Gli strumenti basati su sidecar (embed_documents, search_documents, batch_compliance_check, batch_forensic_analyze) ottengono il proprio client da SpectrumClientFactory::create. La factory valida un SPECTRUM_URL non-localhost rispetto agli intervalli di indirizzi privati e riservati prima dell’uso. Il localhost esplicito è consentito per la modalità sidecar locale.
• ai_ready_certify deriva il proprio livello da quattro criteri: integrità forense, presenza della firma, validità LTV e assenza di cifratura. Il superamento di tutti e quattro produce certified; da uno a tre produce partial; zero produce not_certified. L’integrità forense è un’euristica strutturale sulla catena delle revisioni, non una verifica crittografica di integrità dei byte. Il controllo della cifratura ispeziona la sola regione del trailer.
• certify_ai_ready valuta tre criteri e appone un timbro di provenienza XMP. I byte timbrati vengono restituiti codificati in base64 salvo se return_stamped_pdf è false o il livello è not_certified.
• compliance_check accetta esattamente dodici chiavi di policy: pdfa4, pdfa4e, pdfa4f, pades-baseline, ltv-health, eidas-qualified, zugferd, fda-part11, sec-17a4, sec-17a4-compatible, sec-17a4-structural, sec-17a4-pre-sign. Una chiave sconosciuta restituisce un risultato di errore che nomina l’insieme supportato.
• audit_ast_mutations legge solo l’AstAuditTrailInterface iniettato. Non registra nulla di per sé.

Casi limite e modalità di fallimento

• Né document_id né source forniti: risultato di errore che istruisce il chiamante a fornirne uno.
• document_id sconosciuto: risultato di errore che nomina l’ID e rimanda a create_pdf.
• source sul filesystem con NEXTPDF_MCP_INPUT_DIR non impostata: rifiutato con un messaggio che nomina i canali supportati.
• Percorso source che si risolve al di fuori della directory di input configurata, anche tramite symlink: rifiutato. Il confronto avviene su un confine di separatore di directory, quindi directory fratelle che condividono un prefisso di nome non possono passare.
• URI data: senza separatore a virgola, o payload base64 non valido: risultato di errore.
• top_k di search_documents fuori dall’intervallo 1–100: limitato, non rifiutato. Un top_k non intero ricade sul valore predefinito configurato della pipeline.
• mode di search_documents fuori da hybrid, bm25, semantic: risultato di errore dall’allowlist della pipeline.
• Elemento documents[] di batch_compliance_check privo di id o path, o che riporta stringhe vuote: risultato di errore che nomina l’indice offendente. batch_forensic_analyze valida solo la forma dell’array esterno; i difetti degli elementi emergono dal livello batch.
• SpectrumClientFactory::create con un SPECTRUM_URL malformato, o che punta a un indirizzo privato, link-local o di metadati: InvalidArgumentException. All’interno di un execute di uno strumento ciò emerge come risultato di errore.
• SpectrumClientFactory::createStreamFromFile su un percorso non leggibile: McpStreamException.
• Le variabili d’ambiente vuote vengono trattate come non impostate e ricadono sui valori predefiniti.

Conformità

NextPDF non detiene alcuna certificazione e non ne concede alcuna. Gli strumenti MCP riportano valutazioni a livello di capacità; il supporto non è conformità e la conformità non è certificazione. I valori certification_level restituiti da ai_ready_certify e certify_ai_ready sono il vocabolario riportato dagli strumenti stessi. Non costituiscono un’attestazione di terze parti. Le risposte di compliance_check includono un campo disclaimer prodotto dal report sottostante per la stessa ragione. I riferimenti alle clausole di policy, come la base della policy LTV che la fonte del prodotto indica come ISO 32000-2:2020 §12.8.4.3, sono riportati nelle descrizioni degli strumenti e nei campi clause per esito; questa pagina non aggiunge alcuna affermazione indipendente sugli standard. Se un documento verificato soddisfi una normativa è una determinazione che spetta all’operatore e ai suoi valutatori.

Note di sviluppo

• SpectrumClientFactory::create mette in cache un client per processo. Chiamare SpectrumClientFactory::reset nel setup dei test per forzare un client fresco.
• Le letture d’ambiente consultano $_ENV, poi $_SERVER, poi getenv, e trattano le stringhe vuote come assenti.
• RiskLevel guida la gestione lato host nel runtime del server: Safe si auto-esegue, Caution e superiori vengono registrati nell’audit e ApprovalRequired richiede la conferma umana. Nessuno strumento MCP Enterprise dichiara ApprovalRequired. Gli override dell’operatore possono alzare un livello dichiarato, mai abbassarlo.
• I valori di annotations (readOnlyHint, idempotentHint) sono suggerimenti per il client MCP, non un’imposizione. Confinamento e validazione avvengono lato server indipendentemente dai suggerimenti.
• Gli strumenti riportano valori di category document o extraction per il filtraggio di tools/list.
• AuditAstMutationsTool è l’unico strumento che richiede l’iniezione nel costruttore; registrarlo con un’implementazione concreta di AstAuditTrailInterface.

Vedere anche

• MCP (pagina della capacità)
• Accelerator — Riferimento approfondito — la superficie del client sidecar Spectrum.
• Forensics — Riferimento approfondito — l’analizzatore dietro forensic_analyze.
• Compliance — Riferimento approfondito — le policy dietro compliance_check.
• AST — Riferimento approfondito — il chunking e la traccia di audit delle mutazioni.
• Validation — Riferimento approfondito

Confine di pubblicazione

Questa pagina documenta solo il comportamento osservabile esternamente e la superficie API pubblica supportata. Percorsi di namespace interni, classi helper, tabelle di meccanismi, nomi di file di runbook e prefissi di ticket sono fuori ambito.