MCP — Ausführliche Referenz

Auf einen Blick

Der Namensraum NextPDF\Enterprise\Mcp liefert die Enterprise-Stufe des NextPDF-MCP-Werkzeugkatalogs. Seine öffentliche Oberfläche umfasst elf Werkzeugklassen, eine Client-Factory und eine typisierte Ausnahme. Jedes Werkzeug implementiert den Vertrag NextPDF\Server\Tools\ToolInterface aus der Laufzeitumgebung nextpdf/server und deklariert ToolTier::Enterprise. Sechs Werkzeuge analysieren ein einzelnes PDF im Prozess. Vier Werkzeuge delegieren Batch- und RAG-Arbeitslasten über NextPDF\Enterprise\Mcp\SpectrumClientFactory an das Spectrum-Sidecar. Ein Werkzeug liest eine per Konstruktor eingebrachte AST-Mutations-Audit-Spur statt PDF-Bytes. Jedes Werkzeug beschreibt selbst seinen MCP-Namen, seine JSON-Schema-Eingabe, seine Client-Annotationen, seinen RiskLevel und seine Kategorie.

Verfügbarkeit und Lizenzierung

Diese Fähigkeit wird in NextPDF Enterprise (nextpdf/enterprise) ausgeliefert und wird mit einer Lizenzhülle der Enterprise-Stufe aktiviert. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Fähigkeit nicht. Editionen vergleichen und Lizenz erwerben.

Öffentliche API-Oberfläche

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder scheitert mit	Hinweise
ForensicAnalyzeTool::execute	array $arguments, InMemoryDocumentStore $store; args: document_id oder source	Führt forensische Analyse aus: Revisionen, inkrementelle Aktualisierungen, Signaturen	ToolResult (JSON-Bericht)	Fehler-ToolResult; Ausnahmen werden abgefangen, nie erneut geworfen	Werkzeug forensic_analyze; RiskLevel::Safe; schreibgeschützt, idempotent; Kategorie document; seit 2.0.0
BatchForensicAnalyzeTool::execute	args: workspace_token, documents[] (je id + path)	Batch-forensische Analyse über das Spectrum-Sidecar	ToolResult mit status je Dokument, Anzahl erfolgreich und fehlgeschlagen	Fehler-ToolResult (fehlende Argumente, Sidecar-Ausfall)	Werkzeug batch_forensic_analyze; RiskLevel::Safe; Kategorie document; seit 2.1.0
ComplianceCheckTool::execute	args: policy (Enum mit 12 Werten), document_id oder source	Bewertet das PDF anhand einer benannten Compliance-Richtlinie	ToolResult mit Befunden, Bestanden/Nicht bestanden, duration_ms und einem Feld disclaimer	Fehler-ToolResult; unbekannte Richtlinie liefert einen Fehler mit Auflistung der unterstützten Schlüssel	Werkzeug compliance_check; RiskLevel::Review; Kategorie document; seit 2.0.0
BatchComplianceCheckTool::execute	args: workspace_token, documents[], policies (pdfa, pades, zugferd; Standard ["pdfa"])	Batch-Compliance-Prüfungen über das Spectrum-Sidecar	ToolResult mit Anzahl konform / nicht konform	Fehler-ToolResult; jedes documents[]-Element wird auf nichtleere id und path geprüft	Werkzeug batch_compliance_check; RiskLevel::Safe; Kategorie document; seit 2.1.0
LtvHealthCheckTool::execute	args: document_id oder source	Führt die LTV-Zustandsrichtlinie über ein signiertes PDF aus	ToolResult mit Befunden und Bestanden/Nicht bestanden	Fehler-ToolResult	Werkzeug ltv_health_check; RiskLevel::Safe; Kategorie document; seit 2.0.0
AiReadyCertifyTool::execute	args: document_id oder source	Schreibgeschützte KI-Bereitschaftsbewertung über vier Kriterien	ToolResult mit certification_level (certified, partial, not_certified) und Booleschen Werten je Kriterium	Fehler-ToolResult	Werkzeug ai_ready_certify; RiskLevel::Review; schreibgeschützt; Kategorie document; seit 2.0.0
CertifyAiReadyTool::execute	args: document_id oder source, return_stamped_pdf (Standard true)	Bewertet drei Kriterien und hängt einen XMP-Provenienzstempel an	ToolResult; enthält stamped_pdf_base64, sofern nicht deaktiviert oder not_certified	Fehler-ToolResult	Werkzeug certify_ai_ready; RiskLevel::Review; nicht schreibgeschützt; Kategorie document; seit 3.0.0
AstAwareChunkTool::execute	args: document_id oder source, max_chunk_chars (Standard 1500), overlap_chars (Standard 150)	Baut den AST auf und gibt zitat-verankerte Chunks mit Provenienz aus	ToolResult mit chunk_count sowie Knoten-ID, Seitenindex, bbox und Knotentyp je Chunk	Fehler-ToolResult	Werkzeug ast_aware_chunk; RiskLevel::Review; Kategorie extraction; seit 3.0.0
AuditAstMutationsTool::__construct	AstAuditTrailInterface $auditTrail	Bringt das Audit-Spur-Backend ein	Instanz	—	Per Konstruktor eingebrachte Abhängigkeit; seit 3.0.0
AuditAstMutationsTool::execute	args: document_source_hash (SHA-256-Hex, erforderlich)	Gibt alle erfassten AST-Mutationsereignisse für dieses Dokument zurück	ToolResult mit entries[] und count	Fehler-ToolResult, wenn das Argument fehlt oder leer ist	Werkzeug audit_ast_mutations; RiskLevel::Review; Kategorie document; seit 3.0.0
EmbedDocumentsTool::execute	args: collection_id, workspace_token, documents[] (alle erforderlich)	Nimmt PDFs über das Spectrum-Sidecar in eine RAG-Sammlung auf	ToolResult mit Anzahl erfolgreich / gesamt / fehlgeschlagen	Fehler-ToolResult	Werkzeug embed_documents; RiskLevel::Caution; nicht schreibgeschützt, nicht idempotent; Kategorie extraction; seit 2.1.0
SearchDocumentsTool::execute	args: collection_id, query (erforderlich), top_k (Standard 10, begrenzt auf 1–100), mode (hybrid, bm25, semantic)	Hybrider Abruf über eine aufgenommene Sammlung	ToolResult mit gerankten Chunks und Relevanzwerten	Fehler-ToolResult; ein mode außerhalb der Positivliste wird abgelehnt	Werkzeug search_documents; RiskLevel::Safe; Kategorie extraction; seit 2.1.0
SpectrumClientFactory::create	keine (liest SPECTRUM_URL, SPECTRUM_TIMEOUT, SPECTRUM_AUTH_TOKEN, SPECTRUM_APP_SECRET)	Baut und cacht einen prozessweiten Sidecar-Client	SpectrumClient	InvalidArgumentException, wenn SPECTRUM_URL fehlerhaft ist oder auf eine gesperrte Adresse zielt	Standard-Endpunkt http://127.0.0.1:7800; Timeout 30.0 s; seit 2.1.0
SpectrumClientFactory::reset	keine	Leert die zwischengespeicherte Client-Instanz	void	—	Für Tests vorgesehen
SpectrumClientFactory::createRequest	string $method, $uri (string oder UriInterface)	Baut eine PSR-7-Anfrage aus Core-HTTP-Klassen	RequestInterface	—	Implementierung von PSR-17 RequestFactoryInterface
SpectrumClientFactory::createStream	string $content = ''	Baut einen In-Memory-PSR-7-Stream	StreamInterface	—	Implementierung von PSR-17 StreamFactoryInterface
SpectrumClientFactory::createStreamFromFile	string $filename, string $mode = 'r'	Öffnet die Datei und kapselt sie als Stream	StreamInterface	McpStreamException, wenn die Datei nicht geöffnet werden kann	McpStreamException erweitert RuntimeException
SpectrumClientFactory::createStreamFromResource	$resource (PHP-Ressource)	Kapselt eine bestehende Ressource als Stream	StreamInterface	—	Implementierung von PSR-17 StreamFactoryInterface
McpStreamException	—	Typisierter Fehler bei der Stream-Beschaffung	—	—	final class, erweitert RuntimeException; die Quelle dokumentiert PSR-17-§1.5-Kompatibilität; die Quelle annotiert sie mit @since 3.2.0 (in der aktuellen, auf 3.1.0 aliasierten Dev-Linie vorhanden)

Jedes Werkzeug stellt außerdem die Selbstbeschreibungsmethoden von ToolInterface bereit: name, description, inputSchema, annotations, riskLevel, tier und category. Ihre Werte je Werkzeug erscheinen in der Spalte Hinweise oben.

Einsprungpunkt-Signaturen, wörtlich aus der Quelle:

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

Verhaltensvertrag

• Jedes Werkzeug implementiert NextPDF\Server\Tools\ToolInterface und deklariert ToolTier::Enterprise explizit. Die Stufe wird nie aus Namensraum oder Paketierung abgeleitet.
• execute wirft nicht. Jeder Fehler wird abgefangen und als Fehler-ToolResult mit der Fehlermeldung zurückgegeben.
• Einzeldokument-Werkzeuge lösen PDF-Bytes mit einer festen Priorität auf. Eine document_id wird zuerst im InMemoryDocumentStore nachgeschlagen. Andernfalls wird source als data:-URI, dann als rohes Base64 (über 256 Zeichen), dann als Dateipfad interpretiert.
• Dateisystem-source-Pfade sind standardmäßig deaktiviert. Sie werden nur aktiviert, wenn die Umgebungsvariable NEXTPDF_MCP_INPUT_DIR ein eingegrenztes Eingabeverzeichnis benennt. Der aufgelöste reale Pfad muss innerhalb dieses Verzeichnisses bleiben. Alles andere scheitert geschlossen.
• Stream-Wrapper-Schemata (phar://, php://, file:// und jedes andere Schema) sowie Null-Bytes in einem Dateipfad-source werden vor jedem Dateisystemaufruf abgelehnt. Traversierungs- und Symlink-Ausbrüche scheitern an der Realpfad-Eingrenzungsprüfung.
• Sidecar-gestützte Werkzeuge (embed_documents, search_documents, batch_compliance_check, batch_forensic_analyze) beziehen ihren Client von SpectrumClientFactory::create. Die Factory validiert eine Nicht-Localhost-SPECTRUM_URL vor der Verwendung gegen private und reservierte Adressbereiche. Explizites Localhost ist für den lokalen Sidecar-Modus erlaubt.
• ai_ready_certify leitet seine Stufe aus vier Kriterien ab: forensische Integrität, Vorhandensein einer Signatur, LTV-Gültigkeit und Fehlen von Verschlüsselung. Bestehen alle vier, ergibt sich certified; eines bis drei ergibt partial; null ergibt not_certified. Die forensische Integrität ist eine strukturelle Heuristik über die Revisionskette, keine kryptografische Byte-Integritätsprüfung. Die Verschlüsselungsprüfung inspiziert nur den Trailer-Bereich.
• certify_ai_ready bewertet drei Kriterien und hängt einen XMP-Provenienzstempel an. Die gestempelten Bytes werden Base64-kodiert zurückgegeben, sofern return_stamped_pdf nicht false ist oder die Stufe not_certified lautet.
• compliance_check akzeptiert genau zwölf Richtlinienschlüssel: pdfa4, pdfa4e, pdfa4f, pades-baseline, ltv-health, eidas-qualified, zugferd, fda-part11, sec-17a4, sec-17a4-compatible, sec-17a4-structural, sec-17a4-pre-sign. Ein unbekannter Schlüssel liefert ein Fehlerergebnis, das die unterstützte Menge benennt.
• audit_ast_mutations liest ausschließlich das eingebrachte AstAuditTrailInterface. Es erfasst selbst nichts.

Grenzfälle und Fehlermodi

• Weder document_id noch source angegeben: Fehlerergebnis, das den Aufrufer anweist, eines von beiden bereitzustellen.
• Unbekannte document_id: Fehlerergebnis, das die ID benennt und auf create_pdf verweist.
• Dateisystem-source bei nicht gesetztem NEXTPDF_MCP_INPUT_DIR: abgelehnt mit einer Meldung, die die unterstützten Kanäle benennt.
• source-Pfad, der außerhalb des konfigurierten Eingabeverzeichnisses aufgelöst wird, auch per Symlink: abgelehnt. Der Vergleich erfolgt an einer Verzeichnistrenner-Grenze, sodass Geschwisterverzeichnisse mit gemeinsamem Namenspräfix nicht durchkommen können.
• data:-URI ohne Komma-Trennzeichen oder ungültige Base64-Nutzlast: Fehlerergebnis.
• search_documents-top_k außerhalb von 1–100: begrenzt, nicht abgelehnt. Ein nicht ganzzahliger top_k fällt auf den konfigurierten Pipeline-Standard zurück.
• search_documents-mode außerhalb von hybrid, bm25, semantic: Fehlerergebnis aus der Pipeline-Positivliste.
• batch_compliance_check-documents[]-Element ohne id oder path oder mit leeren Zeichenketten: Fehlerergebnis, das den betreffenden Index benennt. batch_forensic_analyze validiert nur die äußere Array-Form; Elementdefekte treten aus der Batch-Schicht zutage.
• SpectrumClientFactory::create mit einer fehlerhaften SPECTRUM_URL oder einer, die auf eine private, Link-lokale oder Metadaten-Adresse zielt: InvalidArgumentException. Innerhalb eines Werkzeug-execute tritt dies als Fehlerergebnis zutage.
• SpectrumClientFactory::createStreamFromFile auf einem nicht lesbaren Pfad: McpStreamException.
• Leere Umgebungsvariablen werden als nicht gesetzt behandelt und fallen auf die Standardwerte zurück.

Konformität

NextPDF besitzt keine Zertifizierung und erteilt keine. Die MCP-Werkzeuge berichten Bewertungen auf Fähigkeitsebene; Unterstützung ist keine Konformität, und Konformität ist keine Zertifizierung. Die von ai_ready_certify und certify_ai_ready zurückgegebenen certification_level-Werte sind das eigene berichtete Vokabular der Werkzeuge. Sie stellen keine Bescheinigung durch Dritte dar. compliance_check-Antworten enthalten aus demselben Grund ein Feld disclaimer, das vom zugrunde liegenden Bericht erzeugt wird. Richtlinien-Klauselverweise, etwa die von der Produktquelle angegebene LTV-Richtliniengrundlage ISO 32000-2:2020 §12.8.4.3, werden in den Werkzeugbeschreibungen und den clause-Feldern je Befund geführt; diese Seite fügt keine unabhängigen Normaussagen hinzu. Ob ein geprüftes Dokument eine Vorschrift erfüllt, ist eine Feststellung für den Betreiber und dessen Prüfer.

Entwicklungshinweise

• SpectrumClientFactory::create cacht einen Client pro Prozess. Rufen Sie SpectrumClientFactory::reset im Test-Setup auf, um einen frischen Client zu erzwingen.
• Umgebungslesevorgänge konsultieren $_ENV, dann $_SERVER, dann getenv und behandeln leere Zeichenketten als abwesend.
• RiskLevel steuert die hostseitige Behandlung in der Server-Laufzeitumgebung: Safe führt automatisch aus, Caution und höher werden auditprotokolliert, und ApprovalRequired verlangt eine menschliche Bestätigung. Kein Enterprise-MCP-Werkzeug deklariert ApprovalRequired. Betreiber-Überschreibungen können eine deklarierte Stufe anheben, nie absenken.
• annotations-Werte (readOnlyHint, idempotentHint) sind Hinweise für den MCP-Client, keine Durchsetzung. Eingrenzung und Validierung erfolgen unabhängig von Hinweisen serverseitig.
• Werkzeuge berichten category-Werte document oder extraction für die tools/list-Filterung.
• AuditAstMutationsTool ist das einzige Werkzeug, das eine Konstruktor-Einbringung erfordert; registrieren Sie es mit einer konkreten AstAuditTrailInterface-Implementierung.

Siehe auch

• MCP (Fähigkeitsseite)
• Accelerator — Detailreferenz — die Client-Oberfläche des Spectrum-Sidecars.
• Forensics — Detailreferenz — der Analyzer hinter forensic_analyze.
• Compliance — Detailreferenz — die Richtlinien hinter compliance_check.
• AST — Detailreferenz — Chunking und die Mutations-Audit-Spur.
• Validation — Detailreferenz

Veröffentlichungsgrenze

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