Overzicht van de NextPDF Connect-server

In een oogopslag

NextPDF Connect is het pakket nextpdf/server, een lang draaiende service die de NextPDF PDF 2.0-engine beschikbaar stelt aan AI-agents en HTTP-clients. De service gebruikt drie transporten: Model Context Protocol (MCP) via stdio, een REST-API en gRPC. Alle drie de transporten gebruiken één toolregister en één bevestigingspoort met een mens in de lus (HITL).

Installeren

composer require nextpdf/server

De Composer-constraint is nextpdf/core: ^3.0 met php: >=8.4 <9.0. Zie /connect/install/ voor de volledige procedure. Die pagina behandelt ook twee optionele aanvullingen: de extensie ext-redis en het pakket nextpdf/premium.

Conceptueel overzicht

nextpdf/server maakt van de framework-onafhankelijke NextPDF-kern een serviceoppervlak. Het bouwt de PDF-generatie niet opnieuw op. In plaats daarvan verpakt het elke engine-functie als een benoemde tool met een eigen schema en stelt het die catalogus vervolgens beschikbaar via verschillende wireprotocollen.

Het ontwerp rust op drie concepten:

Het toolregister. NextPDF\Server\ToolRegistry ontdekt en registreert tools tijdens het opstarten. Het pakket levert een kernset mee, die altijd beschikbaar is. Pro- en Enterprise-providers registreren extra tools, maar alleen wanneer de bijbehorende pakketten zijn geïnstalleerd. Het aantal tools dat beschikbaar wordt gesteld, is een runtime-eigenschap van de deployment, geen vaste constante. Zie /connect/tool-catalog/.
De transporten. Hetzelfde register wordt op drie manieren beschikbaar gesteld. MCP draait via stdio voor lokale AI-clients. REST draait via een PSR-15-middlewarepijplijn op een RoadRunner-workerpool voor netwerkclients. gRPC draait op een Spiral RoadRunner gRPC-worker voor getypeerde, streamende clients. Elk transport draait als een eigen proces met een eigen toegangspunt. Zie /transports/mcp/, /transports/rest/ en /transports/grpc/.
De bevestigingspoort. Elke tool specificeert een risiconiveau. Een tool op het hoogste niveau vereist expliciete menselijke bevestiging voordat deze wordt uitgevoerd. De poort geeft een challenge-token voor eenmalig gebruik uit. De agent moet dat token aan een mens doorgeven en de tool vervolgens opnieuw aanroepen met het token. Zie /connect/hitl-risk-niveaus/.

Het onderstaande diagram laat zien hoe één register drie transporten bedient. Ook laat het zien waar de bevestigingspoort zich in het verzoekpad bevindt.

NextPDF Connect component architecture

Het pakket valt onder de Apache-2.0-licentie, in lijn met nextpdf/core. De geïmplementeerde versie van het MCP-protocol is de op datum geversioneerde revisie 2025-06-18. Een OpenAPI 3.1-document beschrijft het REST-oppervlak. Het Protocol Buffers-pakket nextpdf.connect.v1 beschrijft het gRPC-oppervlak.

API-oppervlak

De publieke toegangspunten zijn de drie serverklassen. Elk daarvan heeft een wrapper voor de opdrachtregelinterface (CLI):

Toegangspunt	Klasse	Transport
`bin/nextpdf-mcp`	`NextPDF\Server\Mcp\McpServer`	MCP via stdio
`bin/nextpdf-server`	`NextPDF\Server\Http\HttpServer`	REST via RoadRunner HTTP
`bin/nextpdf-grpc`	`NextPDF\Server\Grpc\GrpcServer`	gRPC via RoadRunner gRPC
`bin/generate-skills`	`NextPDF\Server\Skills\SkillsDumper`	Export van toolcatalogus

McpServer::create(), HttpServer::create() en GrpcServer::create() bouwen elk een volledig geconfigureerde server op basis van omgevings- en configuratie-invoer. Het register, de documentopslag, het beveiligingsbeleid en de bevestigingspoort zijn gedeelde concepten voor alle drie de servers.

Codevoorbeeld — Snelstart

Voor de minimale MCP-server heb je één opdracht nodig. Je schrijft geen PHP-lijmcode:

./vendor/bin/nextpdf-mcp

De server leest JSON-RPC-verzoeken van standaardinvoer en schrijft antwoorden naar standaarduitvoer. Zie /connect/quickstart/ voor een uitvoerbare uitwisseling van initialize en tools/list en het bijbehorende REST-verzoek.

Randgevallen en valkuilen

Het aantal tools is niet 33, en ook geen ander vast getal. De server telt de tools tijdens runtime met count(ToolRegistry::all()), na beleidsfiltering en detectie van het niveau. Documentatie die een vast totaal noemt, is verouderd. Vraag het gezaghebbende aantal op bij de draaiende server. Gebruik het MCP-antwoord van initialize of het REST-eindpunt /api/v1/capabilities.

Het aantal tools dat beschikbaar wordt gesteld, hangt af van de geïnstalleerde pakketten en van het actieve beleid. Vraag het tijdens runtime op bij de draaiende server. Een vast getal in je code of documentatie raakt verouderd.
Een ontbrekend Pro- of Enterprise-pakket is geen fout. Het register controleert providerklassen met class_exists() en slaat daarna elk afwezig niveau stil over. Een deployment met uitsluitend open source start op en stelt de kerncatalogus gewoon beschikbaar.
De drie transporten delen geen proces. Als je de MCP-server draait, start dat niet de REST-server of de gRPC-server. Het omgekeerde geldt ook. Een gecombineerde deployment draait de RoadRunner-supervisor met een configuratie die beide workerpools start: de HTTP-pool en de gRPC-pool. Zie /connect/deployment/.

Prestaties

Elk transport werkt met workers. Een worker verwerkt één verzoek tegelijk. De REST- en gRPC-servers draaien op RoadRunner-workerpools, en de configuratie bepaalt de poolgrootte. De standaard is vier HTTP-workers. De RoadRunner-supervisor begrenst het geheugen van elke worker. De frontmatter performance_budget op deze pagina beschrijft een marge voor koude start en ontdekking. Dat is geen doel per verzoek. De onderliggende engine-bewerking bepaalt het grootste deel van de kosten van een verzoek.

Beveiligingsopmerkingen

Alle netwerktransporten authenticeren met een bearer-token op basis van een application programming interface (API)-sleutel. Het MCP-stdio-transport is een lokaal subproces dat de startende client vertrouwt, volgens het MCP-transportmodel. Tools met een hoog risico blijven op elk transport vergrendeld achter menselijke bevestiging. Zie /connect/security-and-operations/ voor het volledige dreigingsmodel, het authenticatiemodel en de configuratie van de transportbeveiliging.

Conformiteit

Deze pagina doet uitsluitend architectonische uitspraken. De normatieve protocol- en beveiligingscitaten staan vastgepind op de pagina’s die het gedrag specificeren: /connect/security-and-operations/, /transports/mcp/, /transports/rest/ en /transports/grpc/. De referentie voor de MCP-levenscyclus is de officiële specificatie op modelcontextprotocol.io (revisie 2025-06-18). De transportpagina’s leggen die referentie met de bijbehorende URL vast, omdat de MCP-specificatie geen deel uitmaakt van het afgeschermde corpus met standaarden.

Commerciële context

De kerncatalogus is compleet voor het aanmaken, inspecteren en diagnosticeren van documenten. Tools voor ondertekening, redactie, nalevingscertificering en forensische analyse verschijnen alleen wanneer nextpdf/premium naast de server is geïnstalleerd. Dit is een verpakkingsgrens, geen upsell-melding tijdens runtime. De server retourneert nooit marketinginhoud.

Zie ook

/connect/install/ — installatie en optionele pakketten
/connect/quickstart/ — eerste uitvoerbare MCP- en REST-uitwisseling
/connect/tool-catalog/ — de geverifieerde kerntoolset en hoe het aantal afhangt van de runtime
/connect/hitl-risk-niveaus/ — de bevestigingspoort en het risicomodel
/transports/mcp/, /transports/rest/, /transports/grpc/ — installatie per transport
/connect/security-and-operations/ — authenticatie, transportbeveiliging, dreigingsmodel
/connect/deployment/ — RoadRunner, Docker en deployment met gecombineerde transporten