Pro editie

MCP Tools

In het kort

NextPDF Pro voegt acht Model Context Protocol (MCP)-tools toe waarmee een AI-agent geavanceerde PDF-bewerkingen kan uitvoeren via NextPDF Server. De tools verschijnen automatisch wanneer zowel nextpdf/pro als nextpdf/server zijn geïnstalleerd — een aparte registratiestap is niet nodig.

Beschikbaarheid en licenties

Deze mogelijkheid wordt geleverd in NextPDF Pro (nextpdf/pro) en wordt geactiveerd met een licentie-envelop van het Pro-niveau. Een implementatie zonder dat recht laadt de klassen van de mogelijkheid niet. Vergelijk edities en vraag een licentie aan.

Het basis-MCP-oppervlak — documentcreatie, tekst, tabellen, diagnostiek — wordt geleverd met de opensource-NextPDF Server en vereist geen licentie. De acht tools op deze pagina vereisen een Pro-licentie en registreren alleen wanneer het nextpdf/pro-pakket bij het opstarten resolveert. De pro-tooltier bewaakt de hele set: elke tool declareert zijn tier expliciet, en er is geen per-tool flag — het installeren van nextpdf/pro naast nextpdf/server schakelt de set in.

Gedragscontract

De acht Pro-MCP-tools registreren automatisch wanneer zowel nextpdf/pro als nextpdf/server bij het opstarten resolven, onder de pro-tier, via de standaard MCP-tools/list- en tools/call-flow. Er is geen per-tool flag en geen codewijziging in de gebruikende applicatie.
Elke tool accepteert een PDF via een document_id van een eerdere create_pdf-aanroep, een inline source (bestandspad, base64 of data:-URI), of — voor compare_pdfs — twee van zulke bronnen. Tools retourneren gestructureerde JSON.
Elke tool declareert een HITL-risicoklasse die de server afdwingt: safe (auto-execute, alleen-lezen), review (uitvoer die misbruikt zou kunnen worden) en approval-required. sign_pdf is approval-required en wordt vastgehouden totdat een mens het bevestigt. Een operator kan de risicoklasse van een tool alleen aanscherpen, nooit versoepelen.
sign_pdf produceert alleen een PAdES B-B (baseline)-handtekening — geen vertrouwde tijdstempel en geen langetermijnvalidatiemateriaal. Langetermijnprofielen (B-LT / B-LTA), sleutelbewaring in hardware en audit-trail-ondertekening zijn Enterprise-tier en worden niet door deze tools geleverd; B-T (een getijdstempelde handtekening) is beschikbaar vanuit de Core-engine wanneer een tijdstempelprovider is geconfigureerd.
redact_pii voert patroondetectie en -maskering op de tekstlaag uit, geen visuele redactie; check_accessibility is een structurele heuristiek, geen PDF/UA- of WCAG-conformiteitsoordeel. Het gezaghebbende invoer-/uitvoerschema is de live tools/list-respons van de server, niet deze pagina.

Conceptueel overzicht

NextPDF Server is de deterministische MCP-uitvoeringslaag voor NextPDF. Deze ontdekt toolproviders bij het opstarten met een class-existence-probe, zodat het Pro-pakket niet in de afhankelijkheden van de server hoeft te staan. Wanneer het Pro-pakket aanwezig is, registreert de server zijn acht tools onder de pro-tier en stelt deze beschikbaar via de standaard MCP-tools/list- en tools/call-flow over het transport dat je hebt geconfigureerd.

Elke Pro-tool accepteert een PDF uit een van drie bronnen: een document_id die door een eerdere create_pdf-aanroep is geretourneerd, een inline source (bestandspad, base64-string of data:-URI), of — voor de vergelijkingstool — twee van zulke bronnen. Tools retourneren gestructureerde JSON-resultaten: geëxtraheerde tekst, diff-regio’s, gemaskeerde tekst, segmentbomen, toegankelijkheidsbevindingen of een ondertekende PDF.

Elke Pro-tool draagt een risicoclassificatie die de server gebruikt voor human-in-the-loop (HITL)-handhaving. Alleen-lezen analysetools rangschikken als safe en voeren automatisch uit. Tools die uitvoer genereren die een caller zou kunnen misbruiken, rangschikken voor review. De ondertekeningstool rangschikt als approval-required, dus de server houdt deze vast totdat een mens het bevestigt. De tool zelf declareert deze classificatie; een operator kan deze tijdens runtime alleen aanscherpen — nooit versoepelen.

Het MCP-tooloppervlak is bewust gescheiden van de Pro-PDF-engine. De tools zijn dunne adapters: ze valideren invoer, resolveren de PDF, delegeren naar een Pro-engine-component en serialiseren het resultaat. Ze zijn geen tweede API voor de engine en maken geen deel uit van de publieke Pro-PHP-API — het ondersteunde integratiepunt is het MCP-protocol dat door NextPDF Server beschikbaar wordt gesteld.

Toolcatalogus (acht Pro-tools)

De acht Pro-MCP-tools, per MCP-protocolnaam. Risiconiveaus volgen het HITL-model van de server: safe (auto-execute, alleen-lezen), review (genereert uitvoer die misbruikt zou kunnen worden; gewaarschuwd in agentinstructies) en approval-required (moet door een mens worden bevestigd).

`extract_text`

Doel: Tekstextractie. Extraheer de tekstlaag van een PDF, optioneel beperkt tot een 1-geïndexeerd paginabereik.
Invoer: Een PDF (document_id of source); optionele page_start en page_end.
Uitvoer: Geëxtraheerde tekst en totale paginatelling.
Risico: Safe. Alleen-lezen en idempotent.
Grens: Extraheert de bestaande tekstlaag. Voert geen OCR uit op gescande of alleen-afbeelding-pagina’s.

`segment_document`

Doel: Structurele segmentatie. Splits een PDF in logische secties — titel, koppen, body, tabellen, figuren.
Invoer: Een PDF (document_id of source).
Uitvoer: Een segmenttelling en een gestructureerde lijst van segmenten.
Risico: Safe. Alleen-lezen en idempotent.
Grens: Structurele segmentatie op basis van lay-outanalyse; het is geen semantische outline of een tagged-PDF-structuurboom.

`compare_pdfs`

Doel: Structurele diff. Vergelijk twee PDF’s en retourneer een gestructureerde diff van hun tekstinhoud.
Invoer: Twee PDF’s (source_a en source_b, elk een pad, base64, data-URI of document_id).
Uitvoer: Een identical-vlag, totale wijzigingstelling, per-document paginatellingen en een lijst van gewijzigde regio’s met pagina- en regelindices.
Risico: Safe. Alleen-lezen en idempotent.
Grens: Tekstinhoud-diff. Het diff’t geen visuele weergave, ingebedde lettertypen of binaire structuur.

`redact_pii`

Doel: PII-detectie en -maskering. Detecteer persoonlijk identificeerbare informatie in de tekstlaag van een PDF en retourneer een gemaskeerde weergave van de tekst.
Invoer: Een PDF (document_id of source); optionele types-filter (email, phone, ssn, credit_card).
Uitvoer: Een has-PII-vlag, gedetecteerde telling, gemaskeerde tekst en de lijst van gescande typen.
Risico: Review. De gemaskeerde uitvoer zou misbruikt kunnen worden als deze als een gesaneerd document wordt behandeld.
Grens: Dit is patroondetectie en -maskering op de tekstlaag, geen visuele redactie. Het verwijdert of overschrijft geen glyphs in de weergegeven PDF, en patroonmatching garandeert niet dat elke instantie van gevoelige gegevens wordt gevonden. Behandel de uitvoer niet als een garantie van volledige PII-verwijdering. Voor redactie op documentniveau die de onderliggende inhoud vernietigt, gebruik het toegewijde redactie-oppervlak in de opensource-server-tools of de Enterprise-editie.

`fill_form`

Doel: AcroForm-invuldata. Genereer XFDF (ISO 19444-1)-data die PDF-AcroForm-velden invult vanuit een map van veldnamen naar waarden.
Invoer: Een fields-map van veldnaam naar string-waarde; optionele pdf_filename ingebed als de XFDF-referentie.
Uitvoer: Het gegenereerde XFDF-document en de veldtelling.
Risico: Review. Het produceert formuliergegevens die bedoeld zijn om op een document te worden toegepast.
Grens: Het produceert standaardconforme XFDF; het schrijft de waarden zelf niet terug in een PDF. Pas de XFDF toe met een conforme reader of verwerkingstool.

`extract_form_data`

Doel: AcroForm-uitlezing. Extraheer AcroForm-veldnamen en -waarden uit XFDF dat in een PDF is ingebed.
Invoer: Een PDF (document_id of source).
Uitvoer: Een veldtelling en een map van veldnamen naar waarden; een expliciete notitie wanneer er geen ingebedde formuliergegevens aanwezig zijn.
Risico: Safe. Alleen-lezen en idempotent.
Grens: Leest ingebedde XFDF (ISO 19444-1)-streams. Een PDF die formulierwaarden alleen in AcroForm-objecten bewaart zonder ingebedde XFDF, retourneert een leeg resultaat.

`check_accessibility`

Doel: Structurele toegankelijkheidsanalyse. Analyseer de structurele toegankelijkheid van een PDF — koppen, paragrafen, tabellen en afbeeldingen — en rapporteer waarschijnlijke problemen met WCAG-referenties.
Invoer: Een PDF (document_id of source).
Uitvoer: Een structurele score (0–100), een lijst van problemen en een segmentsamenvatting.
Risico: Safe. Alleen-lezen en idempotent.
Grens: Dit is een structurele heuristiek, geen conformiteitsoordeel. Volledige PDF/UA- en WCAG-conformiteitstests — tagboom, leesvolgorde, kleurcontrast — vereisen een toegewijde toegankelijkheidsengine. Een hoge score is geen verklaring van PDF/UA-conformiteit.

`sign_pdf`

Doel: PAdES B-B-digitale handtekening. Pas een PAdES B-B (baseline)-digitale handtekening toe op een PDF met een lokaal X.509-certificaat en een privésleutel.
Invoer: Een PDF (document_id of source); een PEM-certificaat en PKCS#8-privésleutel; een optioneel algoritme (RSA-SHA256 standaard, RSA + SHA-3 256/384/512 of Ed25519); een optionele ondertekenaarnaam en reden; een optionele AES-GCM-transportenvelop rond de privésleutel-payload.
Uitvoer: De ondertekende PDF, handtekeningtelling, completion-vlag en het gebruikte algoritme, de OID en de digest.
Risico: Approval-required. Ondertekenen is een juridisch significante, destructieve bewerking; de server vereist expliciete menselijke bevestiging voordat deze wordt uitgevoerd.
Grens: Deze tool produceert een PAdES B-B (baseline)-handtekening — het bedt geen vertrouwde tijdstempel of langetermijnvalidatiemateriaal in. Langetermijnprofielen (B-LT / B-LTA), hardware-ondersteunde sleutelbewaring en audit-trail-ondertekening maken deel uit van de Enterprise-editie; B-T (een getijdstempelde handtekening) is beschikbaar vanuit de Core-engine wanneer een tijdstempelprovider is geconfigureerd. Zie het Pro-handtekeningoppervlak voor de bredere ondertekeningsmogelijkheden van het Pro-pakket en de Enterprise-editie voor B-LT/B-LTA.

Hoe de tools beschikbaar worden

composer require nextpdf/pro
composer require nextpdf/server

Met beide pakketten geïnstalleerd start je NextPDF Server met je gekozen transport. De server ontdekt de Pro-tier bij het opstarten en de acht tools verschijnen in de MCP-tools/list-respons onder de pro-tier naast de opensource-Core-tools. Je applicatie heeft geen codewijziging nodig — discovery loopt automatisch en een ontbrekende tier blokkeert nooit het laden van de andere.

Het gezaghebbende invoer- en uitvoerschema voor elke tool is het schema dat de server publiceert in zijn tools/list-respons. Behandel die respons — niet deze pagina — als het contract: deze catalogus beschrijft intentie en grenzen; het live schema beschrijft exacte veldnamen en typen.

Codevoorbeeld — Snelstart

De Pro-tools worden geconsumeerd over het MCP-protocol, niet via een Pro-PHP-API. De host-side integratie is het opstarten van NextPDF Server. Met nextpdf/pro aanwezig registreren de acht tools zich via runtime-discovery — geen per-tool bedrading — en de host serveert ze vervolgens aan agents.

<?php

declare(strict_types=1);

use NextPDF\Server\Mcp\McpServer;

require __DIR__ . '/vendor/autoload.php';

// Runtime discovery registers the Pro tier when nextpdf/pro is installed
// alongside nextpdf/server. The consuming application changes no code.
$server = McpServer::create();

// A Pro tool name resolves only when the Pro package is present.
$signTool = $server->getToolRegistry()->get('sign_pdf');

\fwrite(\STDERR, $signTool !== null
    ? "Pro MCP tools active.\n"
    : "Pro MCP tools unavailable; install nextpdf/pro.\n");

// Serve the MCP protocol over stdio (Claude Desktop, Cursor, local agents).
$server->run();

Codevoorbeeld — Productie

Verstevig het bootpad. Laad een expliciet policybestand, weiger te starten bij een ongeldige risiconiveau-override en bevestig dat de Pro-tier is verschenen voordat je serveert. De bedrading in McpServer::create() gooit InvalidArgumentException wanneer een risk_level_overrides-blok een approval-required tool zoals sign_pdf probeert te verzwakken, zodat een verkeerd geconfigureerd policy gesloten faalt voordat de serving-lus begint.

<?php

declare(strict_types=1);

use NextPDF\Server\Mcp\McpServer;
use NextPDF\Server\Tools\ToolInterface;

require __DIR__ . '/vendor/autoload.php';

// A downgrade of an approval-required tool's HITL gate is rejected at boot,
// never silently applied — the server refuses to start on such a policy.
try {
    $server = McpServer::create(__DIR__ . '/nextpdf-mcp.yaml');
} catch (\InvalidArgumentException $e) {
    \fwrite(\STDERR, 'Refusing to start: invalid MCP policy. ' . $e->getMessage() . "\n");
    exit(1);
}

// Confirm the Pro tier surfaced before advertising it to agents.
$signTool = $server->getToolRegistry()->get('sign_pdf');

if (!$signTool instanceof ToolInterface) {
    \fwrite(\STDERR, "nextpdf/pro is not resolving; Pro MCP tools are unavailable.\n");
    exit(1);
}

// sign_pdf is approval-required; the server holds it for human confirmation.
$risk = $signTool->riskLevel()->label();
\fwrite(\STDERR, "Pro MCP tools ready. sign_pdf risk: {$risk}.\n");

$server->run();

Productierichtlijnen

HITL-gating. Houd sign_pdf achter menselijke bevestiging. De server dwingt dit af op basis van het gedeclareerde risiconiveau van de tool; configureer je agent niet om het te omzeilen. Een operator kan het risiconiveau van een tool alleen aanscherpen, nooit versoepelen.
Bronafhandeling. Geef de voorkeur aan document_id voor documenten die al in de sessie zitten. Voor inline data accepteren de tools base64- en data:-URI’s; zeer grote inline payloads draaien trager dan een gerefereerd document.
PII-verwachtingen. Stel callerverwachtingen expliciet: redact_pii is een detectie-en-maskeringshulp, geen sanitatiegarantie. Voor onomkeerbare verwijdering route je naar een toegewijd redactie-oppervlak.
Ondertekeningssleutels. Lever sleutels via de transportencryptie-envelop wanneer het transport niet end-to-end vertrouwelijk is. Behandel privésleutelmateriaal als een geheim in het tool-call-loggingbeleid van je agent.
Audit logging. Tools boven het safe-niveau worden door de server audit-gelogd. Zorg ervoor dat je implementatie die logs bewaart volgens je compliancevereisten.

Randgevallen

extract_text-paginabereiken zijn 1-geïndexeerd en geklemd tot de werkelijke paginatelling van het document; een out-of-range einde geeft geen fout.
compare_pdfs vereist beide bronnen; het doorgeven van één retourneert een duidelijke validatiefout in plaats van een gedeeltelijke diff.
extract_form_data retourneert een ingevuld, expliciet “no embedded form data”-resultaat in plaats van een fout voor PDF’s zonder ingebedde XFDF.
sign_pdf wijst niet-ondersteunde algoritme-identifiers af met de lijst van ondersteunde waarden; Ed25519 vereist de libsodium-extensie en SHA-3-varianten vereisen een OpenSSL-build met SHA-3-ondersteuning.
check_accessibility scoort alleen-afbeelding-PDF’s slecht naar ontwerp — het markeert de afwezigheid van een leesbare tekstlaag in plaats van te falen.

Beveiligingsnotities

De ondertekeningstool is de enige approval-required tool; de server voert deze niet automatisch uit.
De optionele AES-GCM-envelop rond de privésleutel authenticeert de payload; een tag-mismatch faalt gesloten met een decryptiefout en valt nooit terug op het gebruik van de ciphertext.
redact_pii wijzigt de bron-PDF niet; het retourneert een gemaskeerde tekstweergave. Het is geen vervanging voor inhoudvernietiging.
De tool valideert invoer vóór elk engine-werk; het wijst misvormde bronnen, data-URI’s en base64-payloads af met expliciete fouten.

Conformiteit

Formuliertools produceren en consumeren XFDF volgens ISO 19444-1:2019 (XML Forms Data Format).
sign_pdf produceert een PAdES baseline (B-B)-handtekening afgestemd op de ETSI EN 319 142 PAdES-familie; langetermijnprofielen zijn een Enterprise-capaciteit, en B-T is beschikbaar vanuit de Core-engine wanneer een tijdstempelprovider is geconfigureerd.
check_accessibility rapporteert bevindingen met WCAG-succescriteriumreferenties (bijvoorbeeld 1.1.1, 1.3.1, 2.4.6) als heuristische richtlijn, niet als een conformiteitsattestatie.

Editie-grens

NextPDF Pro draagt exact acht MCP-tools bij, allemaal op de pro-tier. De Enterprise-editie levert zijn eigen, aparte MCP-toolset op de enterprise-tier — die compliancecontrole, forensische analyse, langetermijnvalidatiegezondheid, AI-ready-certificering en documentzoeken en -embedding dekt. Die tools, hun invoer en hun internals vallen buiten het bereik van deze pagina; zie de Enterprise-MCP-tools. De eigen documentatie van de server behandelt de Core (opensource)-tools die ermee worden geleverd. De server ontdekt de drie tiers onafhankelijk, en een ontbrekende tier schakelt de andere nooit uit.

Enterprise-grensnotitie

Pro draagt exact acht MCP-tools bij op de pro-tier. De Enterprise-editie levert een aparte MCP-toolset op de enterprise-tier (compliancecontrole, forensische analyse, langetermijnvalidatiegezondheid, AI-ready-certificering, documentzoeken en -embedding) en de getijdstempelde/langetermijnhandtekeningprofielen; die worden niet door de pro-tier geleverd. Zie de sectie Editie-grens hierboven voor de volledige tier-uitsplitsing.

Core-fallback / alternatief

De opensource-NextPDF Server geeft elke AI-agent een deterministische Core-PDF-toolset (documentcreatie, tekst, tabellen, diagnostiek) zonder licentie. De acht geavanceerde tools op deze pagina zijn Pro-toevoegingen. Zie /connect/tools/.

Publicatiegrens

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