Pro editie

MCP Tools — Diepe referentie

Beschikbaarheid & licentiëring

Deze mogelijkheid wordt geleverd in NextPDF Pro (nextpdf/pro) en activeert met een licentie-envelop op Pro-niveau. Een deployment zonder die entitlement laadt de klassen van de mogelijkheid niet. Vergelijk edities en vraag een licentie aan.

Er is geen licentieflag per functie. De code wordt geleverd met de Pro-editie, en de acht tools registreren onder de pro-tier wanneer het Pro-pakket bij het opstarten naast nextpdf/server resolvet.

Gedragscontract

NextPDF Server detecteert tiers bij het opstarten door te zoeken naar de Pro-tool-providerklasse; als die resolvet, registreert de server de acht tools onder de pro-tier. Het Pro-pakket is geen harde afhankelijkheid van de server, dus de Pro-tools zijn strikt opt-in via co-installatie. Tier-registratie is onafhankelijk: een ontbrekende of door beleid uitgesloten tier blokkeert de andere nooit.
Elke tool declareert een van vier risiconiveaus (safe, caution, review, approval-required). Een optionele operator-override kan het niveau van een tool alleen verhogen, nooit verlagen; de server audit-logt elke uitvoering op caution of hoger. sign_pdf is approval-required.
PDF-invoer wordt in een vaste volgorde geresolved: document_id uit de in-memory-store, daarna source als een data:-URI, een bestandssysteempad of ruwe base64. Ontbrekende invoer retourneert een validatiefout in plaats van een leeg document te verwerken.
sign_pdf produceert alleen een PAdES B-B baseline-handtekening — geen tijdstempel, geen langetermijnvalidatie. De ondersteunde algoritmen en de AES-GCM-key-transport-envelop worden hieronder beschreven; decryptie faalt gesloten en de tool gebruikt nooit ciphertext als sleutelmateriaal.
Zie de onderstaande secties voor het volledige detail over discovery, risico, source-resolutie, per tool en ondertekening. Deze pagina beschrijft alleen extern waarneembaar gedrag en het gepubliceerde toolcontract.

Reikwijdte

Deze pagina is de operator- en integrator-referentie voor de acht Pro-MCP-tools. Het behandelt het discovery-model, de risk/HITL-semantiek die de server toepast, de source-resolutieregels, de signing-key-transport-envelop en het faalgedrag per tool. Het beschrijft alleen extern waarneembaar gedrag en het gepubliceerde toolcontract. Zie voor de gebruikersgerichte catalogus de openbare MCP-pagina.

Discovery- en registratiemodel

NextPDF Server detecteert tier-providers bij het opstarten. Het detecteert de Pro-tier door te zoeken naar de Pro-tool-providerklasse; als de klasse resolvet, instantieert de server de provider en registreert elke tool die deze retourneert onder de pro-tier. Het Pro-pakket is opzettelijk geen harde afhankelijkheid van de server — dit houdt de open-sourceserver installeerbaar zonder het proprietaire pakket, en maakt de Pro-tools strikt opt-in via co-installatie.

De server isoleert de registratie per tier. Als het Pro-pakket afwezig is, registreren de Core-tools nog steeds; een aanwezige tier-provider blokkeert de andere tiers niet. Toolregistratie is ook onderworpen aan de allow-list van het beveiligingsbeleid van de server: een tool die door het beleid wordt uitgesloten, wordt stilzwijgend niet geregistreerd en niet meegeteld in de tier-samenvatting. De server biedt een telling per tier (core / pro / enterprise) voor diagnostiek en logging.

De provider retourneert de acht tools in een vaste volgorde: tekstextractie, segmentatie, vergelijking, PII-maskering, formulier invullen, formulier teruglezen, toegankelijkheidsanalyse, ondertekening. De volgorde is stabiel, maar callers mogen er niet van afhangen — resolveer tools op hun MCP-protocolnaam.

Risicomodel en HITL-semantiek

Elke tool declareert een van vier risiconiveaus. De server gebruikt het gedeclareerde niveau voor human-in-the-loop-handhaving:

Safe — alleen-lezen, geen neveneffecten. Wordt automatisch uitgevoerd.
Caution — maakt of wijzigt in-memory-status. Wordt automatisch uitgevoerd met een audit-log-vermelding.
Review — produceert uitvoer die misbruikt zou kunnen worden. Wordt automatisch uitgevoerd, maar de agent-skill-instructies markeren dit zodat de agent de gebruiker waarschuwt.
Approval-required — destructief, juridisch of privacy-kritisch. De server vereist expliciete menselijke bevestiging vóór uitvoering.

Classificaties van de Pro-tools: de vijf extractie-/analysetools (extract_text, segment_document, compare_pdfs, extract_form_data, check_accessibility) zijn safe; redact_pii en fill_form zijn review; sign_pdf is approval-required.

Het risiconiveau komt uit exact twee bronnen: de eigen declaratie van de tool, en een optionele operator-override tijdens runtime. De override kan het risiconiveau van een tool alleen verhogen (de handhaving aanscherpen); het kan dit nooit verlagen. De server audit-logt elke uitvoering op caution-niveau of hoger. Het risicomodel draagt een versie; de server adverteert die versie in zijn initialisatieresponse zodat clients een incompatibele wijziging kunnen detecteren.

Source-resolutievolgorde

Elke tool die een PDF aanneemt, accepteert deze via een van drie invoervormen, die in deze volgorde worden geresolved:

document_id — de server haalt de bytes op uit zijn in-memory-documentstore. Een onbekende id faalt met een expliciete fout die de caller aanwijst om het document eerst aan te maken.
source als een data:-URI — de tool decodeert de base64-body na de komma.
source als een bestandssysteempad — de tool leest van schijf wanneer het pad naar een bestand verwijst.
source als een ruwe base64-string — de tool accepteert en decodeert alleen voldoende lange, base64-vormige invoer.

compare_pdfs past dezelfde resolutie onafhankelijk toe op source_a en source_b, en accepteert daarnaast een document_id-waarde in elke source-slot. Als noch een document_id, noch een source wordt aangeleverd, retourneert de tool een validatiefout in plaats van een leeg document te verwerken.

Referentie per tool

Tool	Risico	Invoer	Resultaatvelden	Gedragsgrens
`extract_text`	safe	PDF; optioneel 1-geïndexeerd `page_start` / `page_end`	tekst, totaal aantal pagina’s	Alleen tekstlaag; bereiken geclampt tot het echte aantal pagina’s; geen OCR
`segment_document`	safe	PDF	aantal segmenten, segmentlijst	Uit de lay-out afgeleide segmenten; geen structuurboom van een getagde PDF
`compare_pdfs`	safe	twee PDF’s	identiek-flag, totaal aantal wijzigingen, aantal pagina’s per document, regio’s (type, tekst, pagina-index, regelindex, optionele tegenpartij-tekst)	Diff van tekstinhoud; niet visueel of binair
`redact_pii`	review	PDF; optioneel `types` (`email`, `phone`, `ssn`, `credit_card`)	heeft-PII-flag, aantal gedetecteerd, gemaskeerde tekst, gescande typen	Detectie/maskering op de tekstlaag; geen visuele redactie; patroongebaseerd, niet uitputtend
`fill_form`	review	`fields`-map; optioneel `pdf_filename`	XFDF-document, aantal velden	Produceert XFDF (ISO 19444-1); schrijft geen waarden in een PDF
`extract_form_data`	safe	PDF	aantal velden, veldmap, expliciete notitie als er geen zijn	Leest alleen ingebedde XFDF
`check_accessibility`	safe	PDF	structurele score (0–100), problemen, segmentsamenvatting	Structurele heuristiek met WCAG-referenties; geen conformiteitsoordeel
`sign_pdf`	approval-required	PDF; PEM-certificaat + PKCS#8-sleutel; optioneel algoritme, ondertekenaarsnaam, reden, transport-envelop	ondertekende PDF, aantal handtekeningen, voltooiingsflag, algoritme, OID, digest	Alleen PAdES B-B baseline; geen tijdstempel, geen LTV

Ondertekening: algoritmen en key-transport

sign_pdf produceert een PAdES B-B baseline-handtekening. Ondersteunde algoritmen, geaccepteerd in zowel underscore- als streepjes-spelling:

RSA met SHA-256 (standaard).
RSA met SHA-3 256 / 384 / 512 — vereist een OpenSSL-build met SHA-3-ondersteuning.
Ed25519 — vereist de libsodium-extensie; de sleutel moet een PKCS#8-PEM zijn die de Ed25519-privésleutel omhult.

De tool weigert niet-ondersteunde identifiers en retourneert de lijst met geaccepteerde waarden.

De optionele transport-encryptie-envelop laat een caller de privésleutel tunnelen door een transport dat niet end-to-end vertrouwelijk is. De envelop is alleen AES-GCM:

Symmetrische sleutel: 16, 24 of 32 bytes (AES-128/192/256), base64-gecodeerd.
Nonce: exact 12 bytes, base64-gecodeerd.
Optionele aanvullende geauthenticeerde gegevens, base64-gecodeerd.
De private_key-payload is de base64-ciphertext met een afsluitende GCM-authenticatietag van 16 bytes.

Decryptie faalt gesloten: een mismatch van de authenticatietag of een misvormde payload retourneert een decryptiefout, en de tool gebruikt de ciphertext nooit als sleutelmateriaal. De tool weigert verkeerde sleutel- of nonce-groottes vóór enig cryptografisch werk.

Randgevallen en FIPS-modus

extract_text: de tool clampt een einde van het paginabereik dat het document overschrijdt in plaats van het te weigeren, en normaliseert een begin onder de eerste pagina naar de eerste pagina.
compare_pdfs: een ontbrekende source_a of source_b retourneert een validatiefout; identieke documenten retourneren een expliciet identiek resultaat met nul wijzigingen.
extract_form_data: PDF’s zonder een ingebedde XFDF-stream retourneren een resultaat met nul velden plus een toelichtende notitie, geen fout.
redact_pii: een niet-herkende vermelding in types wordt genegeerd; een lijst die volledig niet wordt herkend, levert een lege scan op in plaats van een fout.
sign_pdf: een ontbrekend certificaat of ontbrekende privésleutel faalt vóór enig ondertekeningswerk; de tool controleert de algoritmevereisten (SHA-3-OpenSSL-ondersteuning, libsodium voor Ed25519) op het moment van ondertekenen en brengt ze als expliciete fouten naar voren.
FIPS-modus: de beschikbaarheid van algoritmen volgt de OpenSSL-/libsodium-build van de host. In een FIPS-beperkte build falen niet-goedgekeurde algoritmen aan de cryptografische grens met een expliciete fout in plaats van stilzwijgend te degraderen. De MCP-laag voegt geen cryptografisch beleid toe en versoepelt het niet — het brengt de beslissing van de cryptoprovider van de host naar voren.

Operator-runbooknotities

Houd sign_pdf approval-required. Bevestig dat er geen operator-override is die het risico op de safe-tools onbedoeld verhoogt — overrides scherpen alleen aan, dus een onbedoelde override verslechtert de beschikbaarheid, niet de veiligheid.
Audit-bewaring: elke uitvoering op review-niveau of hoger wordt door de server audit-gelogd. Stem je log-bewaring af op het volume aan redact_pii-, fill_form- en sign_pdf-aanroepen.
Transportkeuze: bij gebruik over een transport dat niet end-to-end vertrouwelijk is, vereis de AES-GCM-key-transport-envelop voor sign_pdf en behandel privésleutelmateriaal als een geheim in het tool-call-loggingbeleid van je agent.
Tier-tellingen: gebruik de telling per tier van de server om bij deployment vast te stellen dat de Pro-tier acht tools registreerde; een telling van nul geeft aan dat het Pro-pakket niet resolvete.

Editie-grens

De Pro-tier draagt exact acht MCP-tools bij. De Enterprise-editie levert een aparte MCP-tier met eigen tools — compliance, forensics, langetermijnvalidatie-gezondheid, AI-ready-certificering en documentzoeken/-embedding. De invoer, uitvoer en internals van Enterprise-tools vallen hier buiten het bereik en worden gedocumenteerd bij de Enterprise-editie. De server detecteert tiers onafhankelijk; een ontbrekende tier schakelt een andere nooit uit.

Publicatiegrens

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde openbare API-oppervlak. Interne namespace-paden, helperklassen, mechanismetabellen, runbook-bestandsnamen en ticket-prefixen vallen buiten het bereik.