Pro Edition

MCP Tools — Ausführliche Referenz

Verfügbarkeit & Lizenzierung

Diese Funktion wird in NextPDF Pro (nextpdf/pro) ausgeliefert und mit einem Lizenz-Envelope der Pro-Stufe aktiviert. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Funktion nicht. Editionen vergleichen und Lizenz beziehen.

Es gibt kein Feature-spezifisches Lizenz-Flag. Der Code wird mit der Pro-Edition ausgeliefert, und die acht Tools registrieren sich unter der pro-Stufe, wenn das Pro-Paket beim Boot zusammen mit nextpdf/server aufgelöst wird.

Verhaltensvertrag

NextPDF Server entdeckt die Stufen beim Boot, indem er nach der Pro-Tool-Provider-Klasse sucht; wenn diese aufgelöst wird, registriert der Server die acht Tools unter der pro-Stufe. Das Pro-Paket ist keine harte Abhängigkeit des Servers, sodass die Pro-Tools durch Mit-Installation strikt opt-in sind. Die Stufenregistrierung ist unabhängig: Eine fehlende oder per Richtlinie ausgeschlossene Stufe blockiert niemals die anderen.
Jedes Tool deklariert eine von vier Risikostufen (safe, caution, review, approval-required). Ein optionaler Operator-Override kann die Stufe eines Tools nur anheben, niemals senken; der Server schreibt jede Ausführung auf caution oder darüber ins Audit-Log. sign_pdf ist approval-required.
Die PDF-Eingabe wird in einer festen Reihenfolge aufgelöst: document_id aus dem In-Memory-Store, dann source als data:-URI, Dateisystempfad oder rohes Base64. Eine fehlende Eingabe gibt einen Validierungsfehler zurück, statt ein leeres Dokument zu verarbeiten.
sign_pdf erzeugt nur eine PAdES-B-B-Baseline-Signatur — kein Zeitstempel, keine Langzeitvalidierung. Unterstützte Algorithmen und der AES-GCM-Schlüsseltransport-Envelope sind weiter unten detailliert beschrieben; die Entschlüsselung schlägt fail-closed fehl, und das Tool verwendet niemals Chiffretext als Schlüsselmaterial.
Siehe die Abschnitte unten für die vollständigen Details zu Discovery, Risiko, Quellauflösung, einzelnen Tools und Signierung. Diese Seite beschreibt nur extern beobachtbares Verhalten und den veröffentlichten Tool-Vertrag.

Geltungsbereich

Diese Seite ist die Operator- und Integrator-Referenz für die acht Pro-MCP-Tools. Sie behandelt das Discovery-Modell, die Risiko-/HITL-Semantik, die der Server anwendet, die Regeln zur Quellauflösung, den Schlüsseltransport-Envelope für die Signierung und das Fehlerverhalten je Tool. Sie beschreibt nur extern beobachtbares Verhalten und den veröffentlichten Tool-Vertrag. Den nutzerseitigen Katalog finden Sie auf der öffentlichen MCP-Seite.

Discovery- und Registrierungsmodell

NextPDF Server entdeckt die Stufen-Provider beim Boot. Er erkennt die Pro-Stufe, indem er nach der Pro-Tool-Provider-Klasse sucht; wenn die Klasse aufgelöst wird, instanziiert der Server den Provider und registriert jedes Tool, das er zurückgibt, unter der pro-Stufe. Das Pro-Paket ist bewusst keine harte Abhängigkeit des Servers — dies hält den Open-Source-Server ohne das proprietäre Paket installierbar und macht die Pro-Tools durch Mit-Installation strikt opt-in.

Der Server isoliert die Registrierung je Stufe. Wenn das Pro-Paket fehlt, registrieren sich Core-Tools dennoch; ein vorhandener Stufen-Provider blockiert keine anderen Stufen. Die Tool-Registrierung unterliegt außerdem der Allow-List der Sicherheitsrichtlinie des Servers: Ein per Richtlinie ausgeschlossenes Tool wird stillschweigend nicht registriert und nicht in der Stufenzusammenfassung gezählt. Der Server stellt eine Zählung je Stufe (core / pro / enterprise) für Diagnose und Logging bereit.

Der Provider gibt die acht Tools in einer festen Reihenfolge zurück: Textextraktion, Segmentierung, Vergleich, PII-Maskierung, Formularausfüllung, Formular-Rücklesen, Barrierefreiheitsanalyse, Signierung. Die Reihenfolge ist stabil, aber Aufrufer dürfen sich nicht darauf verlassen — lösen Sie Tools über ihren MCP-Protokollnamen auf.

Risikomodell und HITL-Semantik

Jedes Tool deklariert eine von vier Risikostufen. Der Server verwendet die deklarierte Stufe für die Human-in-the-Loop-Durchsetzung:

Safe — schreibgeschützt, keine Seiteneffekte. Führt automatisch aus.
Caution — erstellt oder verändert In-Memory-Zustand. Führt automatisch mit einem Audit-Log-Eintrag aus.
Review — erzeugt eine Ausgabe, die missbraucht werden könnte. Führt automatisch aus, aber die Anweisungen des Agent-Skills markieren es, sodass der Agent den Nutzer warnt.
Approval-required — destruktiv, rechtlich oder datenschutzkritisch. Der Server verlangt eine ausdrückliche menschliche Bestätigung vor der Ausführung.

Klassifizierungen der Pro-Tools: Die fünf Extraktions-/Analyse-Tools (extract_text, segment_document, compare_pdfs, extract_form_data, check_accessibility) sind safe; redact_pii und fill_form sind review; sign_pdf ist approval-required.

Die Risikostufe stammt aus genau zwei Quellen: der eigenen Deklaration des Tools und einem optionalen Operator-Override zur Laufzeit. Der Override kann die Risikostufe eines Tools nur anheben (die Durchsetzung verschärfen); er kann sie niemals senken. Der Server schreibt jede Ausführung auf caution-Stufe oder darüber ins Audit-Log. Das Risikomodell trägt eine Version; der Server gibt diese Version in seiner Initialisierungsantwort bekannt, sodass Clients eine inkompatible Änderung erkennen können.

Reihenfolge der Quellauflösung

Jedes Tool, das ein PDF entgegennimmt, akzeptiert es über eine von drei Eingabeformen, aufgelöst in dieser Reihenfolge:

document_id — der Server ruft die Bytes aus seinem In-Memory-Dokumentenspeicher ab. Eine unbekannte ID schlägt mit einem expliziten Fehler fehl, der den Aufrufer anweist, das Dokument zuerst zu erstellen.
source als data:-URI — das Tool dekodiert den Base64-Body nach dem Komma.
source als Dateisystempfad — das Tool liest von der Festplatte, wenn der Pfad zu einer Datei aufgelöst wird.
source als rohe Base64-Zeichenkette — das Tool akzeptiert und dekodiert nur ausreichend lange, Base64-förmige Eingaben.

compare_pdfs wendet dieselbe Auflösung unabhängig auf source_a und source_b an und akzeptiert zusätzlich einen document_id-Wert in beiden Source-Slots. Wenn weder eine document_id noch eine source angegeben wird, gibt das Tool einen Validierungsfehler zurück, statt ein leeres Dokument zu verarbeiten.

Referenz je Tool

Tool	Risk	Inputs	Result fields	Behavioral boundary
`extract_text`	safe	PDF; optionales 1-indiziertes `page_start` / `page_end`	Text, Gesamtseitenzahl	Nur Textebene; Bereiche auf reale Seitenzahl begrenzt; kein OCR
`segment_document`	safe	PDF	Segmentanzahl, Segmentliste	Layout-abgeleitete Segmente; kein Strukturbaum eines getaggten PDFs
`compare_pdfs`	safe	zwei PDFs	Identitäts-Flag, Gesamtänderungen, Seitenzahlen je Dokument, Regionen (Typ, Text, Seitenindex, Zeilenindex, optionaler Gegenstücktext)	Textinhalts-Diff; nicht visuell oder binär
`redact_pii`	review	PDF; optionale `types` (`email`, `phone`, `ssn`, `credit_card`)	PII-vorhanden-Flag, erkannte Anzahl, maskierter Text, gescannte Typen	Erkennung/Maskierung auf Textebene; keine visuelle Redaktion; musterbasiert, nicht erschöpfend
`fill_form`	review	`fields`-Map; optionaler `pdf_filename`	XFDF-Dokument, Feldanzahl	Erzeugt XFDF (ISO 19444-1); schreibt keine Werte in ein PDF
`extract_form_data`	safe	PDF	Feldanzahl, Feld-Map, expliziter Hinweis, wenn keine vorhanden	Liest nur eingebettetes XFDF
`check_accessibility`	safe	PDF	struktureller Score (0–100), Probleme, Segmentzusammenfassung	Strukturelle Heuristik mit WCAG-Referenzen; kein Konformitätsurteil
`sign_pdf`	approval-required	PDF; PEM-Zertifikat + PKCS#8-Schlüssel; optionaler Algorithmus, Signiername, Grund, Transport-Envelope	signiertes PDF, Signaturanzahl, Abschluss-Flag, Algorithmus, OID, Digest	Nur PAdES-B-B-Baseline; kein Zeitstempel, kein LTV

Signierung: Algorithmen und Schlüsseltransport

sign_pdf erzeugt eine PAdES-B-B-Baseline-Signatur. Unterstützte Algorithmen, akzeptiert sowohl in Unterstrich- als auch in Bindestrich-Schreibweise:

RSA mit SHA-256 (Standard).
RSA mit SHA-3 256 / 384 / 512 — erfordert einen OpenSSL-Build mit SHA-3-Unterstützung.
Ed25519 — erfordert die libsodium-Erweiterung; der Schlüssel muss ein PKCS#8-PEM sein, das den privaten Ed25519-Schlüssel umschließt.

Das Tool lehnt nicht unterstützte Bezeichner ab und gibt die Liste der akzeptierten Werte zurück.

Der optionale Transport-Verschlüsselungs-Envelope erlaubt es einem Aufrufer, den privaten Schlüssel durch einen Transport zu tunneln, der nicht Ende-zu-Ende vertraulich ist. Der Envelope ist ausschließlich AES-GCM:

Symmetrischer Schlüssel: 16, 24 oder 32 Byte (AES-128/192/256), Base64-kodiert.
Nonce: genau 12 Byte, Base64-kodiert.
Optionale zusätzliche authentifizierte Daten, Base64-kodiert.
Die private_key-Nutzlast ist der Base64-Chiffretext mit einem nachgestellten 16-Byte-GCM-Authentifizierungs-Tag.

Die Entschlüsselung schlägt fail-closed fehl: Eine Nichtübereinstimmung des Authentifizierungs-Tags oder eine fehlerhafte Nutzlast gibt einen Entschlüsselungsfehler zurück, und das Tool verwendet den Chiffretext niemals als Schlüsselmaterial. Das Tool lehnt falsche Schlüssel- oder Nonce-Größen ab, bevor jegliche kryptografische Arbeit erfolgt.

Edge Cases und FIPS-Modus

extract_text: Das Tool begrenzt ein Bereichsende, das das Dokument überschreitet, statt es abzulehnen, und normalisiert einen Start unterhalb der ersten Seite auf die erste Seite.
compare_pdfs: Eine fehlende source_a oder source_b gibt einen Validierungsfehler zurück; identische Dokumente geben ein explizites Identitätsergebnis mit null Änderungen zurück.
extract_form_data: PDFs ohne eingebetteten XFDF-Stream geben ein Ergebnis mit null Feldern und einem erläuternden Hinweis zurück, keinen Fehler.
redact_pii: Ein nicht erkannter Eintrag in types wird ignoriert; eine vollständig nicht erkannte Liste ergibt einen leeren Scan statt eines Fehlers.
sign_pdf: Ein fehlendes Zertifikat oder ein fehlender privater Schlüssel schlägt fehl, bevor jegliche Signierarbeit erfolgt; das Tool prüft die Algorithmusanforderungen (SHA-3-OpenSSL-Unterstützung, libsodium für Ed25519) zur Signierzeit und gibt sie als explizite Fehler aus.
FIPS-Modus: Die Verfügbarkeit der Algorithmen folgt dem Host-OpenSSL/libsodium-Build. In einem FIPS-eingeschränkten Build schlagen nicht zugelassene Algorithmen an der kryptografischen Grenze mit einem expliziten Fehler fehl, statt stillschweigend herabzustufen. Die MCP-Ebene fügt keine kryptografische Richtlinie hinzu und lockert keine — sie gibt die Entscheidung des Host-Krypto-Providers aus.

Operator-Runbook-Hinweise

Halten Sie sign_pdf auf approval-required. Bestätigen Sie, dass es keinen Operator-Override gibt, der das Risiko der safe-Tools unbeabsichtigt anhebt — Overrides verschärfen nur, sodass ein versehentlicher Override die Verfügbarkeit beeinträchtigt, nicht die Sicherheit.
Audit-Aufbewahrung: Jede Ausführung auf review-Stufe oder darüber wird vom Server ins Audit-Log geschrieben. Dimensionieren Sie Ihre Log-Aufbewahrung für das Volumen der redact_pii-, fill_form- und sign_pdf-Aufrufe.
Transportwahl: Wenn Sie über einen Transport laufen, der nicht Ende-zu-Ende vertraulich ist, fordern Sie den AES-GCM-Schlüsseltransport-Envelope für sign_pdf und behandeln Sie privates Schlüsselmaterial in der Tool-Call-Logging-Richtlinie Ihres Agenten als Geheimnis.
Stufenzählungen: Verwenden Sie die Zählung je Stufe des Servers, um zur Deploy-Zeit zu bestätigen, dass die Pro-Stufe acht Tools registriert hat; eine Zählung von null zeigt an, dass das Pro-Paket nicht aufgelöst wurde.

Editionsgrenze

Die Pro-Stufe trägt genau acht MCP-Tools bei. Die Enterprise-Edition liefert eine separate MCP-Stufe mit eigenen Tools aus — Compliance, Forensik, Langzeitvalidierungs-Health, AI-Ready-Zertifizierung und Dokumentensuche/-Embedding. Eingaben, Ausgaben und Interna der Enterprise-Tools liegen hier außerhalb des Geltungsbereichs und sind bei der Enterprise-Edition dokumentiert. Der Server entdeckt die Stufen unabhängig; eine fehlende Stufe deaktiviert niemals eine andere.

Veröffentlichungsgrenze

Diese Seite dokumentiert nur 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 Geltungsbereichs.