NextPDF Connect-integratie

In een oogopslag

Integreer NextPDF Connect door het als server te draaien. Koppel geen bibliotheek aan een hosttoepassing. Kies een transport en configureer vervolgens authenticatie voor elk transport dat een netwerkverbinding gebruikt. De tools van de engine blijven afgeschermd door de bevestigingspoort.

Installeren

composer require nextpdf/server

De Composer-constraint is nextpdf/core: ^3.0 met php: >=8.4 <9.0. Zie /connect/install/ voor de optionele installatie van ext-redis en nextpdf/premium.

Conceptueel overzicht

Het pakket draait als zelfstandige service. Registreer geen service provider, bundle of containermodule in een hostframework. Het integratiepunt is het proces dat wordt uitgevoerd. Elk transport heeft een eigen entry point en start onafhankelijk. Zie /connect/boot-and-discovery/.

API-oppervlak

Entry point	Transport	Profiel
bin/nextpdf-mcp	MCP via stdio	(geen — direct subproces)
bin/nextpdf-server	REST via RoadRunner HTTP	.rr.yaml
bin/nextpdf-grpc	gRPC via RoadRunner gRPC	.rr.grpc.yaml
beide transporten met netwerkverbinding	REST + gRPC	.rr.full.yaml

Opstart en automatische detectie

Het register detecteert altijd de core-laag. Daarna voegt het de Pro- en Enterprise-providers toe wanneer hun klassen worden gevonden, gevolgd door de meegeleverde abstract syntax tree (AST)- en mutatieproviders achter environment-poorten. De enabled_tools-beveiligingstoelatingslijst filtert ze allemaal, zodat de zichtbare catalogus past bij deze deployment. Zie /connect/tool-catalog/ en /connect/boot-and-discovery/.

Container-bindingen

Geen. Elke server-factory bouwt expliciet zijn eigen objectgraaf op. De injecteerbare aanknopingspunten zijn bedoeld voor tests, niet voor het koppelen van een toepassing.

Configuratie publiceren

De MCP-server accepteert een optioneel YAML-bestand (--config=PATH, sectie nextpdf_mcp) en NEXTPDF_MCP_*-environment-overrides. De REST- en gRPC-servers lezen NEXTPDF_*-omgevingsvariabelen. Zie /connect/configuration/ voor details.

Beschikbaarheid van transporten (MCP / REST / gRPC)

Alle drie de transporten bedienen hetzelfde register:

• MCP — lokaal subproces, JSON-RPC 2.0 via stdio, geen API-sleutel, MCP-revisie 2025-06-18. Zie /transports/mcp/.
• REST — RoadRunner HTTP-workerpool, OpenAPI 3.1-contract, bearer-API-sleutel, routes die per laag zijn afgeschermd. Zie /transports/rest/.
• gRPC — RoadRunner gRPC-workerpool, nextpdf.connect.v1 Protobuf-service, server-streaming RPC’s, bearer-in-metadata-authenticatie, mutual TLS in het gecombineerde profiel. Zie /transports/grpc/.

Een transport is “beschikbaar” wanneer het bijbehorende entry point of RoadRunner-profiel draait. Transporten starten elkaar niet automatisch.

HITL-risiconiveau

Elke tool declareert een van vier risiconiveaus: safe, caution, review, approval_required. Tools met approval_required worden niet bij de eerste aanroep uitgevoerd. De bevestigingspoort geeft een eenmalig challenge-token uit dat door een mens moet worden geautoriseerd. Een configuratie-override mag het risico van een tool alleen verhogen en nooit een approval_required-tool verlagen. Het model geldt op dezelfde manier voor elk transport dat tools aanstuurt. Zie /connect/hitl-risk-niveaus/.

JSON-envelop van de bevestigingspoort

De poortcontrole retourneert een van twee JSON-vormen. Toegelaten:

{ "allowed": true }

Challenge:

{
  "allowed": false,
  "challenge": "<human-readable text naming the operation, its description, an overwrite warning when applicable, and the re-invocation instruction>",
  "token": "confirm_<nonce>"
}

Het token bindt de toolnaam, een willekeurige nonce en een TTL van 300 seconden, niet de argumenten. Om door te gaan, roept de aanroeper dezelfde tool opnieuw aan met een _confirmation_token-argument dat is ingesteld op het uitgegeven token. De challenge is eenvoudige instructietekst plus het token; het is geen cryptografisch ondertekende envelop. Zie /connect/hitl-risk-niveaus/.

Service-smoketest

./vendor/bin/generate-skills --dry-run --list-tools

Dit start het register en de laagdetectie op en drukt vervolgens de zichtbare tools af zonder verkeer af te handelen. Gebruik dit om te bevestigen dat de integratie is gekoppeld en om te controleren welke catalogus deze installatie oplevert.

Randgevallen en valkuilen

• Geen framework-hooks. Zoek niet naar een service provider of bundle. Het draaiende proces vormt de integratie.
• Een ontbrekende laag is geen fout. De core-only-installatie start op en bedient de eigen core-catalogus.
• Transporten die een netwerkverbinding gebruiken vereisen een sleutel. Alleen /healthz en /readyz (REST) en de health-RPC’s (gRPC) zijn anoniem.

Prestaties

De opstartkosten bestaan uit de registerscan en de laagdetectie, eenmaal per proces. De kosten per verzoek bestaan uit de engine-bewerking. Dimensioneer de RoadRunner-workerpools op basis van de waargenomen renderlatentie. Zie /connect/production-usage/.

Beveiligingsnotities

Transporten die een netwerkverbinding gebruiken authenticeren met een npk_live_-bearersleutel die in constante tijd wordt gevalideerd; de poort dwingt menselijke bevestiging af voor destructieve bewerkingen, ongeacht het transport. Termineer TLS vóór REST en gebruik mutual TLS voor gRPC op niet-vertrouwde netwerken. Zie /connect/security-and-operations/.

Conformiteit

Protocol- en beveiligingscitaties staan in /transports/mcp/, /transports/rest/, /transports/grpc/ en /connect/security-and-operations/.

Commerciële context

Installeer nextpdf/premium naast de server om de extra Pro- en Enterprise-tools bij dezelfde draaiende server te registreren. Er is geen apart proces bij betrokken.

Zie ook

• /connect/overview/ — de architectuur
• /connect/quickstart/ — de eerste uitvoerbare uitwisseling
• /transports/mcp/ · /transports/rest/ · /transports/grpc/ — referentie per transport
• /connect/hitl-risk-niveaus/ — de bevestigingspoort in detail
• /connect/tool-catalog/ — de runtime-afhankelijke catalogus
• /connect/security-and-operations/ — authenticatie en dreigingsmodel