Enterprise editie

MCP-tools

In het kort

NextPDF Enterprise voegt elf MCP-tools toe aan de NextPDF Connect-server. Ze geven AI-assistenten en agent-frameworks directe, getypeerde toegang tot de Enterprise-engine: compliancebeleidscontroles, PDF-forensiek, LTV-gezondheidscontroles, AI-gereedheidsstempeling, AST-bewuste chunking, en RAG-ingestie en -zoeken. Elke tool declareert zijn eigen risiconiveau en read-only-positie, zodat je MCP-host agentactiviteit met vertrouwen kan afschermen, loggen en auditen. Fouten verschijnen nooit als excepties; agents ontvangen altijd een gestructureerd, parseerbaar resultaat.

Beschikbaarheid en licenties

Deze functionaliteit wordt geleverd in NextPDF Enterprise (nextpdf/enterprise) en wordt geactiveerd met een licentie-envelop op Enterprise-niveau. Een deployment zonder die rechten laadt de klassen van de functionaliteit niet. Vergelijk edities en verkrijg een licentie.

Installatie

composer require nextpdf/enterprise:^3

De MCP-host zelf is NextPDF Connect, geleverd in het nextpdf/server-package; zie Connect installeren. Wanneer beide packages aanwezig zijn, ontdekt het toolregister van de server NextPDF\Enterprise\McpToolProvider automatisch en registreert het de elf Enterprise-tools. Er is geen bekabelingscode nodig. Als nextpdf/server ontbreekt, keert het providerbestand vroegtijdig terug en wordt er niets geladen.

De batch- en RAG-tools vereisen daarnaast de Spectrum-sidecar. Configureer die via omgevingsvariabelen die worden gelezen door NextPDF\Enterprise\Mcp\SpectrumClientFactory: SPECTRUM_URL (standaard http://127.0.0.1:7800), SPECTRUM_TIMEOUT (standaard 30.0 seconden), SPECTRUM_AUTH_TOKEN en SPECTRUM_APP_SECRET.

Conceptueel overzicht

Het Model Context Protocol (MCP) is een open protocol waarmee AI-assistenten en agent-frameworks getypeerde tools kunnen aanroepen die door een server worden aangeboden. In plaats van PDF-bytes in een prompt te plakken en te hopen, roept een agent een benoemde tool aan met een payload die is gevalideerd tegen een JSON-schema, en ontvangt die een deterministisch, gestructureerd resultaat. NextPDF Connect is die server voor PDF’s; het Enterprise-package breidt de catalogus uit met de onderstaande tools. Elke tool is een dunne wrapper rond dezelfde Enterprise-API’s die je PHP-code rechtstreeks aanroept, zodat een door een agent uitgevoerde controle en een door code uitgevoerde controle hetzelfde oordeel opleveren.

Toolcatalogus

MCP-tool	Klasse	Wat het doet	Risico	Read-only
`compliance_check`	`ComplianceCheckTool`	Valideert één PDF tegen een benoemd beleid: `pdfa4`, `pdfa4e`, `pdfa4f`, `pades-baseline`, `ltv-health`, `eidas-qualified`, `zugferd`, `fda-part11` en vier `sec-17a4`-varianten.	Review	ja
`batch_compliance_check`	`BatchComplianceCheckTool`	Controleert veel PDF’s tegen `pdfa`-, `pades`- of `zugferd`-beleid in één Spectrum-sidecarbatch.	Safe	ja
`forensic_analyze`	`ForensicAnalyzeTool`	Rapporteert revisiegeschiedenis, incrementele updates en wijzigingsgebeurtenissen voor manipulatiedetectie.	Safe	ja
`batch_forensic_analyze`	`BatchForensicAnalyzeTool`	Voert forensische analyse uit over veel PDF’s in één sidecarbatch.	Safe	ja
`ltv_health_check`	`LtvHealthCheckTool`	Controleert een ondertekende PDF op langetermijnvalidatiemateriaal: DSS-dictionary, OCSP-responses, CRL-vermeldingen, VRI-vermeldingen en certificaatstores.	Safe	ja
`ai_ready_certify`	`AiReadyCertifyTool`	Read-only, productgedefinieerd AI-gereedheidsoordeel over vier criteria: forensische integriteit, aanwezigheid van handtekening, LTV-geldigheid, geen encryptie.	Review	ja
`certify_ai_ready`	`CertifyAiReadyTool`	Productgedefinieerd gereedheidsoordeel over drie criteria (de vier van de read-only tool minus forensische integriteit - opzettelijk, omdat deze tool het bestand dat hij stempelt herschrijft) en voegt een XMP-herkomststempel toe; retourneert de gestempelde PDF als base64.	Review	nee
`ast_aware_chunk`	`AstAwareChunkTool`	Splitst een PDF in citaatverankerde chunks langs kopgrenzen, met node-ID, pagina-index en bounding box per chunk.	Review	ja
`audit_ast_mutations`	`AuditAstMutationsTool`	Haalt het AST-mutatie-audittrail voor een document op via SHA-256-bronhash.	Review	ja
`embed_documents`	`EmbedDocumentsTool`	Neemt PDF’s op in een RAG-collectie: parsen, chunken, embedden, indexeren. Wijzigt de collectiestatus.	Caution	nee
`search_documents`	`SearchDocumentsTool`	Hybride retrieval (BM25-trefwoord plus semantisch) over een opgenomen collectie, met gerangschikte, gescoorde chunks.	Safe	ja

De “certify”-tools geven een productgedefinieerd gereedheidsoordeel af (certified, partial of not_certified). Dat oordeel is een technisch controleresultaat, geen certificering door enige accreditatie-instantie.

Goedkeuringsafscherming en auditpositie

Elke tool declareert een risiconiveau uit het viertraps Connect-model. Safe-tools voeren automatisch uit. Caution-tools voeren automatisch uit met een audit-log-vermelding. Review-tools dragen een waarschuwing voor de instructies van de aanroepende agent. ApprovalRequired-tools vereisen menselijke bevestiging; op dit moment declareert geen enkele Enterprise-MCP-tool dit niveau, omdat geen ervan destructief is. Runtimeconfiguratie kan het risiconiveau van een tool alleen verhogen, nooit verlagen. Tools publiceren ook MCP-gedragsannotaties (readOnlyHint, idempotentHint), zodat een conforme client er zijn eigen afscherming bovenop kan toepassen. Zie HITL-risiconiveaus voor het volledige model.

Waarom het zo werkt

De dragende beslissing is dat tools dunne, deterministische wrappers zijn met zelf-gedeclareerde governance: elke tool geeft zijn eigen risiconiveau en tier op als een domeininvariant, nooit afgeleid uit namespace of packaging. Zo blijft de afschermingsbeslissing auditeerbaar op de host zonder het transport te vertrouwen. Tools bevatten geen eigen documentintelligentie; ze delegeren naar dezelfde Enterprise-API’s die je code aanroept, zodat er precies één gedrag is om te testen en één oordeel om te vertrouwen. Fouten keren terug via het MCP-foutkanaal in plaats van te ontsnappen als excepties, want een agent kan geen PHP-exceptie opvangen maar kan altijd vertakken op isError. Invoer die het bestandssysteem zou kunnen raken, is standaard fail-closed, aangezien MCP-argumenten per definitie bereikbaar zijn voor aanvallers.

Ontwerpachtergrond: Een API die weigert te gokken.

API-oppervlak

Alle elf tools implementeren het NextPDF\Server\Tools\ToolInterface-contract uit nextpdf/server en delen hetzelfde publieke oppervlak. De onderstaande signaturen worden één keer getoond op NextPDF\Enterprise\Mcp\ComplianceCheckTool als representant:

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

Gooit of faalt met: execute() gooit nooit. Het vangt intern Throwable op en retourneert ToolResult::error() met isError = true. Ongeldige argumenten (ontbrekende workspace_token, misvormde documents-vermeldingen, onbekende document_id, onveilige source) verschijnen als InvalidArgumentException-berichten op dat foutkanaal.

De audittrail-tool neemt zijn opslag-backend via constructor-injectie:

public function __construct(private readonly AstAuditTrailInterface $auditTrail)

De provider die de catalogus registreert:

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

getTier() retourneert 'enterprise'. getTools() retourneert de elf tool-instanties; audit_ast_mutations is standaard bekabeld met NextPDF\Enterprise\Ast\InMemoryAstAuditTrail.

De Spectrum-sidecar-clientfactory, die tevens een PSR-17-request- en streamfactory is:

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

Gooit of faalt met: create() gooit InvalidArgumentException wanneer SPECTRUM_URL misvormd is of wanneer het geconfigureerde endpoint gericht is op een bekend privé- of gereserveerd adres (behalve localhost). Dit is een gate op configuratietijd, geen controle op netwerklaagniveau: dwing egressbeleid, redirect-afhandeling en DNS-pinning nog steeds af in de hostomgeving. createStreamFromFile() gooit NextPDF\Enterprise\Mcp\McpStreamException (een subklasse van RuntimeException, conform het PSR-17-contract) wanneer het bestand niet kan worden geopend.

Codevoorbeeld — Snelstart

Voer een PDF/A-4-compliancecontrole uit precies zoals een agent dat zou doen, via het in-memory data:-URI-kanaal:

<?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;

Verwachte uitvoer voor een conform bestand (aantallen bevindingen variëren per document):

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

Het volledige machineleesbare rapport, inclusief severity per bevinding, regel-ID, clausule en suggestie, is beschikbaar op $result->structured.

Codevoorbeeld — Productie

Preflight de sidecar, dwing de gedeclareerde risicopositie af en voer vervolgens een batch-compliancecontrole uit:

<?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;

Verwachte uitvoer (aantallen weerspiegelen je documenten):

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

Randgevallen en valkuilen

Bestandssysteem-source-paden zijn standaard uitgeschakeld. Zonder de omgevingsvariabele NEXTPDF_MCP_INPUT_DIR wordt een padvormige source afgewezen met een foutresultaat. Gebruik in plaats daarvan document_id, een data:-URI of ruwe base64.
Ruwe base64 wordt alleen herkend boven 256 tekens. Een kortere base64-blob wordt als bestandspad behandeld en afgewezen. Verpak kleine payloads in een data:application/pdf;base64,-URI.
Onbekende document_id-waarden falen met begeleiding. De fouttekst is Unknown document_id: ... Call create_pdf first. Documenten in de in-memory store verlopen ook op de TTL van de store, dus een verouderd ID faalt op dezelfde manier.
compliance_check wijst onbekende beleidssleutels af en somt de ondersteunde set op in de foutmelding.
Batch- en RAG-tools hebben de sidecar nodig. batch_compliance_check, batch_forensic_analyze, embed_documents en search_documents vereisen een bereikbaar Spectrum-endpoint en een workspace_token. De factory cachet één client per proces; roep SpectrumClientFactory::reset() aan in tests.
search_documents klemt top_k tot 1–100; niet-gehele waarden vallen terug op de serverstandaard van 10.
ast_aware_chunk-standaarden zijn 1500 tekens per chunk met 150 tekens overlap.
certify_ai_ready laat de gestempelde bytes weg wanneer return_stamped_pdf false is of het oordeel not_certified is. Indien aanwezig is de base64-payload ongeveer een derde groter dan de PDF zelf.
Het standaard AST-audittrail is in-memory. Vermeldingen die via de standaard providerbekabeling worden vastgelegd, blijven niet bewaard tussen processen; injecteer een persistente AstAuditTrailInterface-implementatie voor duurzame audittrails.

Beveiligingsnotities

Fail-closed bronresolutie. MCP-aanroepers beheersen de toolargumenten volledig, dus de resolver behandelt ze als vijandig. Stream-wrappers (phar://, php://, file:// en elk schema) en null-bytes worden afgewezen vóór elke bestandssysteemaanroep. Path traversal wordt afgewezen. Ruwe bestandspaden werken alleen wanneer NEXTPDF_MCP_INPUT_DIR is ingesteld, en het via realpath gecanonicaliseerde doel moet strikt binnen die directory oplossen, vergeleken op een scheidingstekengrens om prefix-confusion-ontsnappingen te blokkeren.
SSRF-bescherming op het sidecar-endpoint. SpectrumClientFactory staat localhost toe voor de lokale-sidecarmodus en valideert elke andere SPECTRUM_URL tegen privé-, gereserveerde, link-local- en cloud-metadata-bereiken, waarbij het InvalidArgumentException gooit bij een geblokkeerd adres. Dit is een gate op configuratietijd op het geconfigureerde endpoint, geen controle op netwerklaagniveau - houd egressbeleid, redirect-afhandeling en DNS-pinning in de hostomgeving.
Secrets blijven in de omgeving. Het sidecar-bearertoken (SPECTRUM_AUTH_TOKEN) en het HMAC-ondertekeningsgeheim (SPECTRUM_APP_SECRET) worden uit omgevingsvariabelen gelezen en verschijnen nooit in toolpayloads of -resultaten.
Niet-reflectieve fouten. Pad-afwijzingsberichten zijn opzettelijk generiek (Source path is not permitted.), zodat een sonderende aanroeper niets leert over het bestandssysteem van de host.
Risico-overrides gaan alleen omhoog. Operatorconfiguratie kan het gedeclareerde risiconiveau van een tool verhogen, maar kan het nooit onder de eigen declaratie van de tool verlagen.

Conformiteit

Ondersteuning is geen conformiteit, en conformiteit is geen certificering. NextPDF bezit geen certificering en verleent er geen. De compliancetools controleren de documentstructuur tegen de benoemde beleidsprofielen en rapporteren bevindingen met clausuleverwijzingen; het compliance_check-rapport draagt daarnaast de eigen disclaimer van de engine dat het een technische structuurcontrole ter referentie is, geen juridisch advies of compliance-goedkeuring. De oordelen van ai_ready_certify en certify_ai_ready zijn productgedefinieerde gereedheidsniveaus, geen attestatie door enige normeringsinstantie. MCP is een open protocol dat door zijn vendor-beheerder wordt gepubliceerd, geen SDO-standaard; deze pagina documenteert het implementatiegedrag van NextPDF en doet geen onafhankelijke claim van protocolconformiteit of certificering.

Gedragscontract

Toolfouten worden geretourneerd als foutresultaten (isError = true met een bericht); excepties overschrijden nooit de MCP-grens.
Succesvolle resultaten dragen een menselijk leesbare samenvatting van één regel plus een gestructureerde JSON-payload met een stabiele, gedocumenteerde veldenset per tool.
Elke tool rapporteert tier() = ToolTier::Enterprise en een gedeclareerd RiskLevel; risico kan tijdens runtime niet worden verlaagd.
Read-only tools declareren readOnlyHint: true en wijzigen de document store, de bron-PDF of enige collectie niet.
certify_ai_ready wijzigt het invoerdocument nooit ter plaatse; de stempel wordt toegepast op een geretourneerde kopie.
Compliance- en LTV-rapporten bevatten een validatietijdstempel en aantallen bevindingen per severity; de compliance_check-payload bevat daarnaast de juridische disclaimer-string van de engine.

Core-fallback

De MCP-host zelf vereist geen Enterprise. NextPDF Connect (nextpdf/server, Apache-2.0) draait met de open Core-engine en serveert de toolcatalogus op core-niveau: documentcreatie, tekst- en inhoudsbewerkingen, en extractie. Zie de toolcatalogus. Core alleen biedt geen compliancebeleidscontroles, forensische analyse, LTV-gezondheidscontroles, AI-gereedheidsstempeling, AST-bewuste chunking, mutatie-audittrails of de batch- en RAG-tools; die elf tools registreren alleen wanneer nextpdf/enterprise is geïnstalleerd en gelicentieerd.

Publicatiegrens

Deze pagina documenteert uitsluitend extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helperklassen, mechanismetabellen, runbook-bestandsnamen en ticketprefixen vallen buiten de scope.