Enterprise Edition

MCP-Tools

Auf einen Blick

NextPDF Enterprise fügt dem NextPDF Connect Server elf MCP-Tools hinzu. Sie geben KI-Assistenten und Agenten-Frameworks direkten, typisierten Zugriff auf die Enterprise-Engine: Compliance-Richtlinienprüfungen, PDF-Forensik, LTV-Zustandsprüfungen, AI-Readiness-Stempelung, AST-bewusstes Chunking sowie RAG-Ingestion und -Suche. Jedes Tool deklariert seine eigene Risikostufe und Read-only-Haltung, sodass Ihr MCP-Host Agentenaktivität zuverlässig freigeben, protokollieren und auditieren kann. Fehler treten niemals als Ausnahmen auf; Agenten erhalten stets ein strukturiertes, parsbares Ergebnis.

Verfügbarkeit & Lizenzierung

Diese Funktion ist in NextPDF Enterprise (nextpdf/enterprise) enthalten und wird mit einem Lizenzumschlag der Enterprise-Stufe aktiviert. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Funktion nicht. Editionen vergleichen und Lizenz erwerben.

Installation

composer require nextpdf/enterprise:^3

Der MCP-Host selbst ist NextPDF Connect, ausgeliefert im Paket nextpdf/server; siehe Connect-Installation. Wenn beide Pakete vorhanden sind, erkennt die Tool-Registry des Servers NextPDF\Enterprise\McpToolProvider automatisch und registriert die elf Enterprise-Tools. Es ist kein Verdrahtungscode erforderlich. Fehlt nextpdf/server, kehrt die Provider-Datei frühzeitig zurück und es wird nichts geladen.

Die Batch- und RAG-Tools erfordern zusätzlich den Spectrum-Sidecar. Konfigurieren Sie ihn über Umgebungsvariablen, die von NextPDF\Enterprise\Mcp\SpectrumClientFactory gelesen werden: SPECTRUM_URL (Standard http://127.0.0.1:7800), SPECTRUM_TIMEOUT (Standard 30.0 Sekunden), SPECTRUM_AUTH_TOKEN und SPECTRUM_APP_SECRET.

Konzeptioneller Überblick

Das Model Context Protocol (MCP) ist ein offenes Protokoll, mit dem KI-Assistenten und Agenten-Frameworks typisierte Tools aufrufen können, die ein Server bereitstellt. Anstatt PDF-Bytes in einen Prompt einzufügen und zu hoffen, ruft ein Agent ein benanntes Tool mit einer per JSON-Schema validierten Nutzlast auf und erhält ein deterministisches, strukturiertes Ergebnis. NextPDF Connect ist dieser Server für PDFs; das Enterprise-Paket erweitert dessen Katalog um die folgenden Tools. Jedes Tool ist ein dünner Wrapper über dieselben Enterprise-APIs, die Ihr PHP-Code direkt aufruft, sodass eine vom Agenten ausgeführte Prüfung und eine im Code ausgeführte Prüfung dasselbe Urteil liefern.

Tool-Katalog

MCP-Tool	Klasse	Funktion	Risiko	Read-only
`compliance_check`	`ComplianceCheckTool`	Validiert ein PDF gegen eine benannte Richtlinie: `pdfa4`, `pdfa4e`, `pdfa4f`, `pades-baseline`, `ltv-health`, `eidas-qualified`, `zugferd`, `fda-part11` und vier `sec-17a4`-Varianten.	Review	Ja
`batch_compliance_check`	`BatchComplianceCheckTool`	Prüft viele PDFs gegen die Richtlinien `pdfa`, `pades` oder `zugferd` in einem Spectrum-Sidecar-Batch.	Safe	Ja
`forensic_analyze`	`ForensicAnalyzeTool`	Meldet Revisionsverlauf, inkrementelle Aktualisierungen und Änderungsereignisse zur Manipulationserkennung.	Safe	Ja
`batch_forensic_analyze`	`BatchForensicAnalyzeTool`	Führt forensische Analysen über viele PDFs in einem Sidecar-Batch aus.	Safe	Ja
`ltv_health_check`	`LtvHealthCheckTool`	Prüft ein signiertes PDF auf Material zur Langzeitvalidierung: DSS-Dictionary, OCSP-Antworten, CRL-Einträge, VRI-Einträge und Zertifikatspeicher.	Safe	Ja
`ai_ready_certify`	`AiReadyCertifyTool`	Read-only-, produktdefiniertes AI-Readiness-Urteil über vier Kriterien: forensische Integrität, Vorhandensein einer Signatur, LTV-Gültigkeit, keine Verschlüsselung.	Review	Ja
`certify_ai_ready`	`CertifyAiReadyTool`	Produktdefiniertes Readiness-Urteil über drei Kriterien (die vier des Read-only-Tools minus forensische Integrität – bewusst so, da dieses Tool die Datei, die es stempelt, neu schreibt) und hängt einen XMP-Provenienzstempel an; gibt das gestempelte PDF als base64 zurück.	Review	Nein
`ast_aware_chunk`	`AstAwareChunkTool`	Teilt ein PDF entlang von Überschriftsgrenzen in zitatverankerte Chunks auf, mit Node-ID, Seitenindex und Bounding-Box pro Chunk.	Review	Ja
`audit_ast_mutations`	`AuditAstMutationsTool`	Ruft den AST-Mutations-Audit-Trail für ein Dokument anhand des SHA-256-Quell-Hash ab.	Review	Ja
`embed_documents`	`EmbedDocumentsTool`	Nimmt PDFs in eine RAG-Sammlung auf: parsen, chunken, einbetten, indexieren. Ändert den Zustand der Sammlung.	Caution	Nein
`search_documents`	`SearchDocumentsTool`	Hybrider Abruf (BM25-Schlüsselwort plus semantisch) über eine aufgenommene Sammlung, mit gerankten, bewerteten Chunks.	Safe	Ja

Die „certify”-Tools stellen ein produktdefiniertes Readiness-Urteil aus (certified, partial oder not_certified). Dieses Urteil ist ein technisches Prüfergebnis, keine Zertifizierung durch eine Akkreditierungsstelle.

Freigabe-Gating und Audit-Haltung

Jedes Tool deklariert eine Risikostufe aus dem vierstufigen Connect-Modell. Safe-Tools werden automatisch ausgeführt. Caution-Tools werden automatisch mit einem Audit-Log-Eintrag ausgeführt. Review-Tools tragen eine Warnung für die Anweisungen des aufrufenden Agenten. ApprovalRequired-Tools verlangen eine menschliche Bestätigung; derzeit deklariert kein Enterprise-MCP-Tool diese Stufe, da keines destruktiv ist. Die Laufzeitkonfiguration kann die Risikostufe eines Tools nur anheben, niemals senken. Tools veröffentlichen außerdem MCP-Verhaltensannotationen (readOnlyHint, idempotentHint), sodass ein konformer Client darüber hinaus sein eigenes Gating anwenden kann. Das vollständige Modell finden Sie unter HITL-Risikostufen.

Warum es so funktioniert

Die tragende Entscheidung ist, dass Tools dünne, deterministische Wrapper mit selbstdeklarierter Governance sind: Jedes Tool gibt seine eigene Risikostufe und Stufe als Domäneninvariante an, niemals abgeleitet aus Namespace oder Paketierung. Dadurch bleibt die Gating-Entscheidung am Host auditierbar, ohne dem Transport zu vertrauen. Tools enthalten keine eigene Dokumentenintelligenz; sie delegieren an dieselben Enterprise-APIs, die Ihr Code aufruft, sodass es genau ein zu testendes Verhalten und ein zu vertrauendes Urteil gibt. Fehler werden über den MCP-Fehlerkanal zurückgegeben, statt als Ausnahmen zu entkommen, denn ein Agent kann keine PHP-Ausnahme abfangen, kann aber immer auf isError verzweigen. Eingaben, die das Dateisystem berühren könnten, sind standardmäßig fail-closed, da MCP-Argumente per Definition für Angreifer erreichbar sind.

Design-Hintergrund: Eine API, die sich weigert zu raten.

API-Oberfläche

Alle elf Tools implementieren den Vertrag NextPDF\Server\Tools\ToolInterface aus nextpdf/server und teilen sich dieselbe öffentliche Oberfläche. Die folgenden Signaturen werden einmal stellvertretend an NextPDF\Enterprise\Mcp\ComplianceCheckTool gezeigt:

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

Wirft oder scheitert mit: execute() wirft niemals. Es fängt Throwable intern ab und gibt ToolResult::error() mit isError = true zurück. Ungültige Argumente (fehlendes workspace_token, fehlerhafte documents-Einträge, unbekannte document_id, unsicheres source) erscheinen als InvalidArgumentException-Meldungen auf diesem Fehlerkanal.

Das Audit-Trail-Tool erhält sein Speicher-Backend per Konstruktor-Injektion:

public function __construct(private readonly AstAuditTrailInterface $auditTrail)

Der Provider, der den Katalog registriert:

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

getTier() gibt 'enterprise' zurück. getTools() gibt die elf Tool-Instanzen zurück; audit_ast_mutations ist standardmäßig mit NextPDF\Enterprise\Ast\InMemoryAstAuditTrail verdrahtet.

Die Client-Factory des Spectrum-Sidecars, die zugleich eine PSR-17-Request- und -Stream-Factory ist:

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

Wirft oder scheitert mit: create() wirft InvalidArgumentException, wenn SPECTRUM_URL fehlerhaft ist oder wenn der konfigurierte Endpunkt auf eine bekannte private oder reservierte Adresse zielt (außer localhost). Dies ist ein Gate zur Konfigurationszeit, keine Kontrolle auf Netzwerkebene: Setzen Sie Egress-Richtlinie, Redirect-Handling und DNS-Pinning weiterhin in der Host-Umgebung durch. createStreamFromFile() wirft NextPDF\Enterprise\Mcp\McpStreamException (eine RuntimeException-Unterklasse gemäß dem PSR-17-Vertrag), wenn die Datei nicht geöffnet werden kann.

Codebeispiel — Schnellstart

Führen Sie eine PDF/A-4-Compliance-Prüfung genau so aus, wie es ein Agent täte, über den In-Memory-data:-URI-Kanal:

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

Erwartete Ausgabe für eine konforme Datei (die Anzahl der Befunde variiert je Dokument):

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

Der vollständige maschinenlesbare Bericht, einschließlich Schweregrad je Befund, Regel-ID, Klausel und Vorschlag, ist unter $result->structured verfügbar.

Codebeispiel — Produktion

Prüfen Sie den Sidecar vorab, setzen Sie die deklarierte Risiko-Haltung durch und führen Sie dann eine Batch-Compliance-Prüfung aus:

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

Erwartete Ausgabe (die Zahlen spiegeln Ihre Dokumente wider):

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

Grenzfälle & Fallstricke

Dateisystem-source-Pfade sind standardmäßig deaktiviert. Ohne die Umgebungsvariable NEXTPDF_MCP_INPUT_DIR wird ein pfadförmiges source mit einem Fehlerergebnis abgelehnt. Verwenden Sie stattdessen document_id, eine data:-URI oder rohes base64.
Rohes base64 wird erst ab 256 Zeichen erkannt. Ein kürzerer base64-Blob wird als Dateipfad behandelt und abgelehnt. Verpacken Sie kleine Nutzlasten in eine data:application/pdf;base64,-URI.
Unbekannte document_id-Werte scheitern mit einem Hinweis. Der Fehlertext lautet Unknown document_id: ... Call create_pdf first. Dokumente im In-Memory-Store verfallen zudem gemäß der TTL des Stores, sodass eine veraltete ID auf dieselbe Weise scheitert.
compliance_check lehnt unbekannte Richtlinienschlüssel ab und listet die unterstützte Menge in der Fehlermeldung auf.
Batch- und RAG-Tools benötigen den Sidecar. batch_compliance_check, batch_forensic_analyze, embed_documents und search_documents erfordern einen erreichbaren Spectrum-Endpunkt und ein workspace_token. Die Factory cacht einen Client pro Prozess; rufen Sie in Tests SpectrumClientFactory::reset() auf.
search_documents begrenzt top_k auf 1–100; nicht-ganzzahlige Werte fallen auf den Server-Standard von 10 zurück.
ast_aware_chunk-Standardwerte sind 1500 Zeichen pro Chunk mit 150 Zeichen Überlappung.
certify_ai_ready lässt die gestempelten Bytes weg, wenn return_stamped_pdf false ist oder das Urteil not_certified lautet. Wenn vorhanden, ist die base64-Nutzlast etwa ein Drittel größer als das PDF selbst.
Der standardmäßige AST-Audit-Trail ist In-Memory. Über die serienmäßige Provider-Verdrahtung erfasste Einträge bleiben nicht über Prozesse hinweg erhalten; injizieren Sie eine persistente AstAuditTrailInterface-Implementierung für dauerhafte Audit-Trails.

Sicherheitshinweise

Fail-closed-Quellauflösung. MCP-Aufrufer kontrollieren die Tool-Argumente vollständig, daher behandelt der Resolver sie als feindlich. Stream-Wrapper (phar://, php://, file:// und jedes Schema) sowie Null-Bytes werden vor jedem Dateisystemaufruf abgelehnt. Pfad-Traversal wird abgelehnt. Rohe Dateipfade funktionieren nur, wenn NEXTPDF_MCP_INPUT_DIR gesetzt ist, und das per realpath kanonisierte Ziel muss strikt innerhalb dieses Verzeichnisses aufgelöst werden, verglichen an einer Trennzeichengrenze, um Prefix-Confusion-Ausbrüche zu blockieren.
SSRF-Schutz am Sidecar-Endpunkt. SpectrumClientFactory erlaubt localhost für den lokalen Sidecar-Modus und validiert jede andere SPECTRUM_URL gegen private, reservierte, Link-local- und Cloud-Metadata-Bereiche und wirft bei einer blockierten Adresse InvalidArgumentException. Dies ist ein Gate zur Konfigurationszeit für den konfigurierten Endpunkt, keine Kontrolle auf Netzwerkebene – behalten Sie Egress-Richtlinie, Redirect-Handling und DNS-Pinning in der Host-Umgebung.
Geheimnisse bleiben in der Umgebung. Das Bearer-Token des Sidecars (SPECTRUM_AUTH_TOKEN) und das HMAC-Signaturgeheimnis (SPECTRUM_APP_SECRET) werden aus Umgebungsvariablen gelesen und erscheinen niemals in Tool-Nutzlasten oder -Ergebnissen.
Nicht-reflektierende Fehler. Meldungen zur Pfadablehnung sind bewusst generisch (Source path is not permitted.), sodass ein sondierender Aufrufer nichts über das Host-Dateisystem erfährt.
Risiko-Overrides gehen nur nach oben. Die Betreiberkonfiguration kann die deklarierte Risikostufe eines Tools anheben, sie aber niemals unter die eigene Deklaration des Tools senken.

Konformität

Unterstützung ist keine Konformität, und Konformität ist keine Zertifizierung. NextPDF besitzt keine Zertifizierung und erteilt keine. Die Compliance-Tools prüfen die Dokumentstruktur gegen die benannten Richtlinienprofile und melden Befunde mit Klauselverweisen; der compliance_check-Bericht trägt zusätzlich den eigenen Haftungsausschluss der Engine, dass es sich um eine technische Strukturprüfung zur Orientierung handelt, nicht um Rechtsberatung oder eine Compliance-Bestätigung. Die Urteile ai_ready_certify und certify_ai_ready sind produktdefinierte Readiness-Stufen, keine Bescheinigung durch ein Normungsgremium. MCP ist ein offenes Protokoll, das von seinem Anbieter-Steward veröffentlicht wird, kein SDO-Standard; diese Seite dokumentiert das Implementierungsverhalten von NextPDF und erhebt keinen eigenständigen Anspruch auf Protokollkonformität oder Zertifizierung.

Verhaltensvertrag

Tool-Fehler werden als Fehlerergebnisse zurückgegeben (isError = true mit einer Meldung); Ausnahmen überschreiten niemals die MCP-Grenze.
Erfolgreiche Ergebnisse tragen eine einzeilige, menschenlesbare Zusammenfassung sowie eine strukturierte JSON-Nutzlast mit einem stabilen, dokumentierten Feldsatz pro Tool.
Jedes Tool meldet tier() = ToolTier::Enterprise und ein deklariertes RiskLevel; das Risiko kann zur Laufzeit nicht gesenkt werden.
Read-only-Tools deklarieren readOnlyHint: true und ändern weder den Dokument-Store, das Quell-PDF noch eine Sammlung.
certify_ai_ready verändert das Eingabedokument niemals an Ort und Stelle; der Stempel wird auf eine zurückgegebene Kopie angewendet.
Compliance- und LTV-Berichte enthalten einen Validierungszeitstempel und Befundzahlen nach Schweregrad; die compliance_check-Nutzlast enthält zusätzlich den rechtlichen Haftungsausschluss-String der Engine.

Core-Fallback

Der MCP-Host selbst erfordert kein Enterprise. NextPDF Connect (nextpdf/server, Apache-2.0) läuft mit der offenen Core-Engine und stellt seinen Tool-Katalog der Core-Stufe bereit: Dokumenterstellung, Text- und Inhaltsoperationen sowie Extraktion. Siehe den Tool-Katalog. Core allein bietet keine Compliance-Richtlinienprüfungen, forensische Analyse, LTV-Zustandsprüfungen, AI-Readiness-Stempelung, AST-bewusstes Chunking, Mutations-Audit-Trails oder die Batch- und RAG-Tools; diese elf Tools registrieren sich nur, wenn nextpdf/enterprise installiert und lizenziert ist.

Veröffentlichungsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Hilfsklassen, Mechanismustabellen, Runbook-Dateinamen und Ticket-Präfixe liegen außerhalb des Umfangs.