Enterprise editie

MCP — Diepe referentie

In één oogopslag

De NextPDF\Enterprise\Mcp-namespace levert het Enterprise-niveau van de NextPDF MCP-toolcatalogus. Het publieke oppervlak bestaat uit elf toolklassen, één clientfactory en één getypeerde exception. Elke tool implementeert het NextPDF\Server\Tools\ToolInterface-contract uit de nextpdf/server-runtime en declareert ToolTier::Enterprise. Zes tools analyseren één PDF in-process. Vier tools delegeren batch- en RAG-workloads naar de Spectrum-sidecar via NextPDF\Enterprise\Mcp\SpectrumClientFactory. Eén tool leest een via de constructor geïnjecteerde AST-mutatie-audittrail in plaats van PDF-bytes. Elke tool beschrijft zichzelf via zijn MCP-naam, JSON Schema-invoer, clientannotaties, RiskLevel en categorie.

Beschikbaarheid en licentie

Deze mogelijkheid wordt geleverd in NextPDF Enterprise (nextpdf/enterprise) en wordt geactiveerd met een licentie-envelop op Enterprise-niveau. Een deployment zonder dat recht laadt de klassen van deze mogelijkheid niet. Vergelijk edities en verkrijg een licentie.

Publiek API-oppervlak

Symbool	Parameters	Standaardgedrag	Retourneert	Gooit of faalt met	Opmerkingen
`ForensicAnalyzeTool::execute`	`array $arguments, InMemoryDocumentStore $store`; args: `document_id` of `source`	Voert forensische analyse uit: revisies, incrementele updates, handtekeningen	`ToolResult` (JSON-rapport)	Fout-`ToolResult`; exceptions worden opgevangen, nooit opnieuw gegooid	Tool `forensic_analyze`; `RiskLevel::Safe`; alleen-lezen, idempotent; categorie `document`; sinds 2.0.0
`BatchForensicAnalyzeTool::execute`	args: `workspace_token`, `documents[]` (elk `id` + `path`)	Batch forensische analyse via de Spectrum-sidecar	`ToolResult` met per-document `status`, aantallen geslaagd en gefaald	Fout-`ToolResult` (ontbrekende argumenten, sidecar-fout)	Tool `batch_forensic_analyze`; `RiskLevel::Safe`; categorie `document`; sinds 2.1.0
`ComplianceCheckTool::execute`	args: `policy` (enum met 12 waarden), `document_id` of `source`	Beoordeelt de PDF aan de hand van één benoemd compliancebeleid	`ToolResult` met bevindingen, geslaagd/gefaald, `duration_ms` en een `disclaimer`-veld	Fout-`ToolResult`; een onbekend beleid geeft een fout met de ondersteunde sleutels	Tool `compliance_check`; `RiskLevel::Review`; categorie `document`; sinds 2.0.0
`BatchComplianceCheckTool::execute`	args: `workspace_token`, `documents[]`, `policies` (`pdfa`, `pades`, `zugferd`; standaard `["pdfa"]`)	Batch compliancecontroles via de Spectrum-sidecar	`ToolResult` met aantallen conform / niet-conform	Fout-`ToolResult`; elk `documents[]`-element wordt gevalideerd op niet-lege `id` en `path`	Tool `batch_compliance_check`; `RiskLevel::Safe`; categorie `document`; sinds 2.1.0
`LtvHealthCheckTool::execute`	args: `document_id` of `source`	Voert het LTV-gezondheidsbeleid uit over een ondertekende PDF	`ToolResult` met bevindingen en geslaagd/gefaald	Fout-`ToolResult`	Tool `ltv_health_check`; `RiskLevel::Safe`; categorie `document`; sinds 2.0.0
`AiReadyCertifyTool::execute`	args: `document_id` of `source`	Alleen-lezen beoordeling van AI-gereedheid over vier criteria	`ToolResult` met `certification_level` (`certified`, `partial`, `not_certified`) en booleans per criterium	Fout-`ToolResult`	Tool `ai_ready_certify`; `RiskLevel::Review`; alleen-lezen; categorie `document`; sinds 2.0.0
`CertifyAiReadyTool::execute`	args: `document_id` of `source`, `return_stamped_pdf` (standaard `true`)	Beoordeelt drie criteria en voegt een XMP-herkomststempel toe	`ToolResult`; bevat `stamped_pdf_base64` tenzij uitgeschakeld of `not_certified`	Fout-`ToolResult`	Tool `certify_ai_ready`; `RiskLevel::Review`; niet alleen-lezen; categorie `document`; sinds 3.0.0
`AstAwareChunkTool::execute`	args: `document_id` of `source`, `max_chunk_chars` (standaard 1500), `overlap_chars` (standaard 150)	Bouwt de AST en produceert citaat-verankerde chunks met herkomst	`ToolResult` met `chunk_count` en per chunk node-ID, pagina-index, bbox, nodetype	Fout-`ToolResult`	Tool `ast_aware_chunk`; `RiskLevel::Review`; categorie `extraction`; sinds 3.0.0
`AuditAstMutationsTool::__construct`	`AstAuditTrailInterface $auditTrail`	Injecteert de audittrail-backend	instance	—	Via constructor geïnjecteerde afhankelijkheid; sinds 3.0.0
`AuditAstMutationsTool::execute`	args: `document_source_hash` (SHA-256 hex, vereist)	Retourneert alle geregistreerde AST-mutatiegebeurtenissen voor dat document	`ToolResult` met `entries[]` en `count`	Fout-`ToolResult` wanneer het argument ontbreekt of leeg is	Tool `audit_ast_mutations`; `RiskLevel::Review`; categorie `document`; sinds 3.0.0
`EmbedDocumentsTool::execute`	args: `collection_id`, `workspace_token`, `documents[]` (alle vereist)	Neemt PDF’s op in een RAG-collectie via de Spectrum-sidecar	`ToolResult` met aantallen geslaagd / totaal / gefaald	Fout-`ToolResult`	Tool `embed_documents`; `RiskLevel::Caution`; niet alleen-lezen, niet idempotent; categorie `extraction`; sinds 2.1.0
`SearchDocumentsTool::execute`	args: `collection_id`, `query` (vereist), `top_k` (standaard 10, begrensd 1–100), `mode` (`hybrid`, `bm25`, `semantic`)	Hybride retrieval over een opgenomen collectie	`ToolResult` met gerangschikte chunks en relevantiescores	Fout-`ToolResult`; een `mode` buiten de allowlist wordt geweigerd	Tool `search_documents`; `RiskLevel::Safe`; categorie `extraction`; sinds 2.1.0
`SpectrumClientFactory::create`	geen (leest `SPECTRUM_URL`, `SPECTRUM_TIMEOUT`, `SPECTRUM_AUTH_TOKEN`, `SPECTRUM_APP_SECRET`)	Bouwt en cachet één sidecar-client voor het hele proces	`SpectrumClient`	`InvalidArgumentException` wanneer `SPECTRUM_URL` misvormd is of een geblokkeerd adres aanwijst	Standaard-endpoint `http://127.0.0.1:7800`; timeout 30.0 s; sinds 2.1.0
`SpectrumClientFactory::reset`	geen	Wist de gecachete client-instance	`void`	—	Bedoeld voor tests
`SpectrumClientFactory::createRequest`	`string $method, $uri` (`string` of `UriInterface`)	Bouwt een PSR-7-request vanuit Core HTTP-klassen	`RequestInterface`	—	PSR-17 `RequestFactoryInterface`-implementatie
`SpectrumClientFactory::createStream`	`string $content = ''`	Bouwt een PSR-7-stream in het geheugen	`StreamInterface`	—	PSR-17 `StreamFactoryInterface`-implementatie
`SpectrumClientFactory::createStreamFromFile`	`string $filename, string $mode = 'r'`	Opent het bestand en wikkelt het als een stream	`StreamInterface`	`McpStreamException` wanneer het bestand niet geopend kan worden	`McpStreamException` breidt `RuntimeException` uit
`SpectrumClientFactory::createStreamFromResource`	`$resource` (PHP-resource)	Wikkelt een bestaande resource als een stream	`StreamInterface`	—	PSR-17 `StreamFactoryInterface`-implementatie
`McpStreamException`	—	Getypeerde fout bij het verkrijgen van een stream	—	—	`final class`, breidt `RuntimeException` uit; de source documenteert PSR-17 §1.5-compatibiliteit; de source annoteert het als `@since 3.2.0` (aanwezig in de huidige 3.1.0-gealiaste dev-lijn)

Elke tool stelt ook de zelfbeschrijvende methoden van ToolInterface beschikbaar: name, description, inputSchema, annotations, riskLevel, tier en category. Hun waarden per tool staan in de kolom Opmerkingen hierboven.

Entry-point-signaturen, letterlijk uit de source:

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

Gedragscontract

Elke tool implementeert NextPDF\Server\Tools\ToolInterface en declareert ToolTier::Enterprise expliciet. Het niveau wordt nooit afgeleid uit de namespace of packaging.
execute gooit niet. Elke fout wordt opgevangen en geretourneerd als een fout-ToolResult met het foutbericht.
Tools voor één document lossen PDF-bytes op met een vaste prioriteit. Een document_id wordt eerst opgezocht in de InMemoryDocumentStore. Anders wordt source geïnterpreteerd als een data:-URI, dan als ruwe base64 (meer dan 256 tekens), dan als een bestandspad.
Bestandssysteem-source-paden zijn standaard uitgeschakeld. Ze worden alleen actief wanneer de omgevingsvariabele NEXTPDF_MCP_INPUT_DIR een afgebakende invoermap benoemt. Het opgeloste reële pad moet binnen die map blijven. Al het overige faalt gesloten.
Stream-wrapperschema’s (phar://, php://, file:// en elk ander schema) en null-bytes in een bestandspad-source worden geweigerd vóór elke bestandssysteemaanroep. Traversal- en symlink-ontsnappingen falen tegen de reële-pad-afbakeningscontrole.
Sidecar-ondersteunde tools (embed_documents, search_documents, batch_compliance_check, batch_forensic_analyze) verkrijgen hun client via SpectrumClientFactory::create. De factory valideert een niet-localhost-SPECTRUM_URL tegen private en gereserveerde adresbereiken vóór gebruik. Expliciete localhost is toegestaan voor de lokale sidecar-modus.
ai_ready_certify leidt zijn niveau af uit vier criteria: forensische integriteit, aanwezigheid van een handtekening, LTV-geldigheid en afwezigheid van encryptie. Als alle vier slagen, levert dat certified; één tot drie levert partial; nul levert not_certified. Forensische integriteit is een structurele heuristiek over de revisieketen, geen cryptografische byte-integriteitsverificatie. De encryptiecontrole inspecteert alleen het trailer-gebied.
certify_ai_ready evalueert drie criteria en voegt een XMP-herkomststempel toe. De gestempelde bytes worden base64-gecodeerd geretourneerd tenzij return_stamped_pdf false is of het niveau not_certified is.
compliance_check accepteert precies twaalf beleidssleutels: pdfa4, pdfa4e, pdfa4f, pades-baseline, ltv-health, eidas-qualified, zugferd, fda-part11, sec-17a4, sec-17a4-compatible, sec-17a4-structural, sec-17a4-pre-sign. Een onbekende sleutel geeft een foutresultaat dat de ondersteunde set benoemt.
audit_ast_mutations leest alleen de geïnjecteerde AstAuditTrailInterface. Zelf registreert het niets.

Randgevallen en foutmodi

Noch document_id noch source opgegeven: foutresultaat dat de aanroeper instrueert er één van te leveren.
Onbekende document_id: foutresultaat dat de ID benoemt en naar create_pdf verwijst.
Bestandssysteem-source terwijl NEXTPDF_MCP_INPUT_DIR niet is ingesteld: geweigerd met een bericht dat de ondersteunde kanalen benoemt.
source-pad dat buiten de geconfigureerde invoermap oplost, inclusief via symlink: geweigerd. De vergelijking gebeurt op een mapscheidingsgrens, zodat naburige mappen die een naamprefix delen er niet doorheen kunnen.
data:-URI zonder kommascheidingsteken, of ongeldige base64-payload: foutresultaat.
search_documents top_k buiten 1–100: begrensd, niet geweigerd. Een niet-integer top_k valt terug op de geconfigureerde pipeline-standaard.
search_documents mode buiten hybrid, bm25, semantic: foutresultaat uit de pipeline-allowlist.
batch_compliance_check documents[]-element zonder id of path, of met lege strings: foutresultaat dat de betreffende index benoemt. batch_forensic_analyze valideert alleen de vorm van de buitenste array; elementdefecten komen naar boven vanuit de batchlaag.
SpectrumClientFactory::create met een misvormde SPECTRUM_URL, of één die een privé-, link-local- of metadata-adres aanwijst: InvalidArgumentException. Binnen een tool-execute komt dit naar boven als een foutresultaat.
SpectrumClientFactory::createStreamFromFile op een onleesbaar pad: McpStreamException.
Lege omgevingsvariabelen worden als niet-ingesteld behandeld en vallen terug op standaardwaarden.

Conformiteit

NextPDF houdt geen certificering aan en verleent er geen. De MCP-tools rapporteren beoordelingen op capaciteitsniveau; ondersteuning is geen conformiteit, en conformiteit is geen certificering. De certification_level-waarden die ai_ready_certify en certify_ai_ready retourneren, zijn het eigen gerapporteerde vocabulaire van de tools. Ze vormen geen attestering door een derde partij. compliance_check-antwoorden bevatten om dezelfde reden een disclaimer-veld dat door het onderliggende rapport wordt geproduceerd. Beleidsclausuleverwijzingen, zoals de LTV-beleidsbasis die de productsource vermeldt als ISO 32000-2:2020 §12.8.4.3, worden meegedragen in de toolbeschrijvingen en de clause-velden per bevinding; deze pagina voegt geen onafhankelijke standaardenclaims toe. Of een gecontroleerd document aan een regelgeving voldoet, is een oordeel van de operator en diens beoordelaars.

Ontwikkelnotities

SpectrumClientFactory::create cachet één client per proces. Roep SpectrumClientFactory::reset aan in de test-setup om een verse client af te dwingen.
Omgevingslezingen raadplegen $_ENV, dan $_SERVER, dan getenv, en behandelen lege strings als afwezig.
RiskLevel stuurt de host-side afhandeling in de server-runtime aan: Safe voert automatisch uit, Caution en hoger worden audit-gelogd, en ApprovalRequired vereist menselijke bevestiging. Geen enkele Enterprise MCP-tool declareert ApprovalRequired. Operator-overrides kunnen een gedeclareerd niveau verhogen, nooit verlagen.
annotations-waarden (readOnlyHint, idempotentHint) zijn hints voor de MCP-client, geen afdwinging. Afbakening en validatie gebeuren server-side, ongeacht de hints.
Tools rapporteren category-waarden document of extraction voor filtering via tools/list.
AuditAstMutationsTool is de enige tool die constructor-injectie vereist; registreer hem met een concrete AstAuditTrailInterface-implementatie.

Zie ook

MCP (capaciteitspagina)
Accelerator — Diepe referentie — het clientoppervlak van de Spectrum-sidecar.
Forensics — Diepe referentie — de analyzer achter forensic_analyze.
Compliance — Diepe referentie — de beleidsregels achter compliance_check.
AST — Diepe referentie — chunking en de mutatie-audittrail.
Validation — Diepe referentie

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 de scope.