NextPDF Connect: opstart en detectie

In één oogopslag

Elk transport heeft een eigen toegangspunt en een eigen opstartvolgorde. Transporten delen het register, de configuratie en de poort als concepten. Ze draaien als onafhankelijke processen; het starten van het ene transport start het andere dus niet.

Installeren

composer require nextpdf/server

Conceptueel overzicht

MCP-opstartvolgorde

McpServer::create() zet de Model Context Protocol-server (MCP) in een vaste volgorde op. Eerst laadt de methode de configuratie, stelt daaruit het beveiligingsbeleid samen, construeert het toolregister en voert de niveaudetectie uit. Vervolgens bouwt ze de in-memory documentopslag op basis van de geconfigureerde time to live (TTL) en capaciteit, maakt ze het stdio-transport aan en stelt ze de JSON-RPC-protocolhandler samen met de bevestigingspoort en de auditlogger. Daarna gaat de server zijn read-handle-write-lus in en blijft die draaien totdat de standaardinvoer het einde van het bestand bereikt.

REST-opstartvolgorde

HttpServer::create() leest HttpConfig uit de omgeving en past overschrijvingen via de command-line interface (CLI) toe. Daarna lost de methode de opslag van application programming interface-sleutels (API) op in deze voorkeursvolgorde: eerst de hot-reloading-bestandsopslag, dan het statische bestand, dan de omgeving. Vervolgens lost ze de opslag voor rate-limiting en idempotentie op. Daarvoor gebruikt de server Redis wanneer Redis is geconfigureerd en bereikbaar is; anders valt hij terug op in-memory opslag. Vanaf dat punt opent de server de gedeelde SQLite-taakopslag, bouwt hij de applicatieservices op en construeert hij de routetabel. Omdat de routetabel wordt opgebouwd uit gedetecteerde niveaus, weerspiegelt deze de geïnstalleerde pakketten. RoadRunner stuurt vervolgens de aanvraaglus van de worker aan.

gRPC-opstartvolgorde

GrpcServer::create() lost dezelfde sleutelopslag op, bouwt dezelfde applicatieservices op en registreert de nextpdf.connect.v1-service bij de Spiral-gRPC-worker. Als de engine-afhankelijkheid niet beschikbaar is, start de gRPC-server nog steeds en beantwoordt hij health- en capability-query’s. In die toestand weigert het proces niet op te starten; in plaats daarvan mislukken gegevensdragende remote procedure calls (RPC’s) op gecontroleerde wijze.

Tooldetectie

Detectie is de standaardregistratiestap van het register. Het core-niveau wordt als eerste geregistreerd. Daarna registreren Pro- en Enterprise-providers zich als hun klassen via class_exists() oplosbaar zijn. Vervolgens registreren de meegeleverde Abstract Syntax Tree-providers (AST) en mutatieproviders zich onder het Pro-niveau, afhankelijk van hun omgevingspoorten. Elke registratie wordt gefilterd door de enabled_tools-beveiligingsallowlist; de MCP-initialize-respons rapporteert de resulterende aantallen per niveau. Zie /connect/tool-catalog/.

Transportdetectie

Geen enkele configuratie-instelling “schakelt transporten in.” Elk transport is een afzonderlijk toegangspunt. REST en gRPC hebben elk een afzonderlijk RoadRunner-profiel. Een deployment kiest transporten op basis van het profiel dat wordt gedraaid: .rr.yaml voor REST, .rr.grpc.yaml voor gRPC, of .rr.full.yaml voor beide. De transporten draaien als onafhankelijke processen. Een ontbrekende MCP-client blokkeert de REST-server nooit, en een ontbrekende REST-client blokkeert MCP nooit. Zie /connect/deployment/.

Resolutievolgorde van de configuratie

De MCP-server lost de configuratie op volgens deze prioriteitsvolgorde: de omgeving (NEXTPDF_MCP_*) heeft voorrang op de nextpdf_mcp-sectie van het YAML-bestand, die op haar beurt voorrang heeft op de ingebouwde standaardwaarden. De REST- en gRPC-servers lezen HttpConfig uit NEXTPDF_*-omgevingsvariabelen met veilige standaardwaarden. Ze lezen het MCP-YAML-bestand niet. Zie /connect/configuration/.

Container-bindingen

Er is geen dependency-injection-container of serviceprovider die je moet registreren. Elke create()-factory construeert zijn eigen objectgraaf expliciet en deterministisch. Er zijn twee injecteerbare naden — het transport en de worker-factory — en beide zijn bedoeld voor tests, niet om de applicatie te bedraden.

Codevoorbeeld — Snelstart

Inspecteer wat de detectie heeft opgeleverd zonder verkeer af te handelen:

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

Codevoorbeeld — Productie

Start de gecombineerde transporten onder één supervisor:

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
./vendor/bin/rr serve -c .rr.full.yaml

Randgevallen en valkuilen

• Bij een ontbrekend niveau mislukt de opstart niet. De niveaudetectie slaat een ontbrekend Pro- of Enterprise-pakket stilzwijgend over. De server start op met de core-catalogus.

• Bij een downgrade-overschrijving mislukt de opstart. Een risk_level_overrides-vermelding die een approval_required-tool verzwakt, werpt een uitzondering tijdens het laden van de configuratie; de server weigert te starten. Dit is opzettelijk.

• Een Redis-storing leidt tot degradatie, niet tot een crash. Als Redis is geconfigureerd maar bij de opstart onbereikbaar is, valt de REST-server terug op in-memory opslag. Controleer de gezondheid van Redis in plaats van ervan uit te gaan dat Redis in gebruik is.

Prestaties

De opstartkosten komen voort uit het parsen van de configuratie, het scannen van het register en het detecteren van niveaus. De performance_budget van de pagina begrenst deze kosten. De kosten worden eenmaal per processtart betaald, niet per aanvraag.

Beveiligingsopmerkingen

Het beveiligingsbeleid wordt vóór het register opgebouwd, zodat de enabled_tools-allowlist de detectie vanaf de eerste registratie beperkt. API-sleutels worden nooit uit het MCP-YAML-bestand gelezen; de transporten met netwerkverbinding halen sleutels uit een secret-bestand of de omgeving. Zie /connect/security-and-operations/.

Conformiteit

Deze pagina beschrijft hoe de opstart werkt. De protocol- en beveiligingsverwijzingen zijn vastgelegd op /transports/mcp/, /transports/rest/, /transports/grpc/ en /connect/security-and-operations/.

Commerciële context

Niveaudetectie tijdens de opstart is het enige moment waarop nextpdf/premium zijn Pro- en Enterprise-tools aan de catalogus toevoegt, wanneer nextpdf/premium naast de server is geïnstalleerd.

Zie ook

• /connect/tool-catalog/ — wat door detectie wordt geregistreerd en waarom het aantal varieert
• /connect/configuration/ — de resolutievolgorde in detail
• /connect/deployment/ — transporten kiezen via RoadRunner-profielen
• /transports/mcp/ · /transports/rest/ · /transports/grpc/ — details per transport