NextPDF Connect: Boot und Discovery

Auf einen Blick

Jeder Transport hat einen eigenen Einstiegspunkt und eine eigene Boot-Sequenz. Die Transporte teilen Registry, Konfiguration und Gate als Konzepte. Sie laufen als unabhängige Prozesse; das Starten eines Transports startet daher keine anderen.

Installation

composer require nextpdf/server

Konzeptioneller Überblick

MCP-Boot-Sequenz

McpServer::create() setzt den MCP-Server in einer festen Reihenfolge zusammen. Zuerst lädt er die Konfiguration, baut daraus die Sicherheitsrichtlinie auf, konstruiert die Tool-Registry und führt die Stufen-Discovery aus. Als Nächstes erstellt er anhand der konfigurierten TTL und Kapazität den In-Memory-Dokumentenspeicher, erzeugt den stdio-Transport und setzt den JSON-RPC-Protokoll-Handler mit dem Bestätigungs-Gate und dem Audit-Logger zusammen. Sobald diese Komponenten bereitstehen, wechselt der Server in seine Read-Handle-Write-Schleife und läuft, bis die Standardeingabe das Dateiende erreicht.

REST-Boot-Sequenz

HttpServer::create() liest HttpConfig aus der Umgebung und wendet CLI-Overrides an. Anschließend ermittelt er den API-Key-Store in dieser Reihenfolge: zuerst den Hot-Reloading-Dateispeicher, dann die statische Datei, dann die Umgebung. Als Nächstes ermittelt er die Rate-Limit- und Idempotenz-Stores, die Redis verwenden, wenn Redis konfiguriert und erreichbar ist, und andernfalls auf In-Memory-Speicherung zurückfallen. Danach öffnet er den gemeinsamen SQLite-Job-Store, baut die Anwendungsdienste auf und konstruiert die Routentabelle. Da die Routentabelle aus den erkannten Stufen aufgebaut wird, spiegelt sie die installierten Pakete wider. Anschließend steuert RoadRunner die Worker-Request-Schleife.

gRPC-Boot-Sequenz

GrpcServer::create() ermittelt denselben Key-Store, baut dieselben Anwendungsdienste auf und registriert den Service nextpdf.connect.v1 beim Spiral-gRPC-Worker. Wenn die Engine-Abhängigkeit nicht verfügbar ist, startet der gRPC-Server trotzdem und beantwortet weiterhin Health- und Capability-Anfragen. In diesem Zustand bricht der Prozess den Boot nicht ab; stattdessen schlagen datentragende RPCs sauber fehl.

Tool-Discovery

Discovery ist der standardmäßige Registrierungsschritt der Registry. Die Core-Stufe registriert sich zuerst. Als Nächstes registrieren sich die Pro- und Enterprise-Provider, sofern ihre Klassen über class_exists() auflösbar sind. Die gebündelten AST- und Mutation-Provider registrieren sich danach unter der Pro-Stufe, sofern ihre Umgebungs-Gates dies zulassen. Jede Registrierung wird durch die Sicherheits-Allowlist enabled_tools gefiltert, und die daraus resultierenden Zähler pro Stufe werden in der MCP-initialize-Antwort gemeldet. Siehe /connect/tool-catalog/.

Transport-Discovery

Keine einzelne Konfigurationseinstellung „aktiviert Transporte“. Jeder Transport ist ein eigener Einstiegspunkt. REST und gRPC haben jeweils ein eigenes RoadRunner-Profil. Ein Deployment wählt die Transporte über das Profil aus, das es ausführt: .rr.yaml für REST, .rr.grpc.yaml für gRPC oder .rr.full.yaml für beide. Die Transporte laufen als unabhängige Prozesse. Ein fehlender MCP-Client blockiert niemals den REST-Server, und ein fehlender REST-Client blockiert niemals MCP. Siehe /connect/deployment/.

Reihenfolge der Konfigurationsauflösung

Der MCP-Server löst die Konfiguration in dieser Vorrangreihenfolge auf: Die Umgebung (NEXTPDF_MCP_*) hat Vorrang vor dem Abschnitt nextpdf_mcp der YAML-Datei, der wiederum Vorrang vor den eingebauten Defaults hat. Die REST- und gRPC-Server lesen HttpConfig aus NEXTPDF_*-Umgebungsvariablen mit sicheren Defaults. Sie lesen die MCP-YAML-Datei nicht. Siehe /connect/configuration/.

Container-Bindings

Es gibt keinen Dependency-Injection-Container, und es muss kein Service-Provider registriert werden. Jede create()-Factory konstruiert ihren eigenen Objektgraphen explizit und deterministisch. Es gibt zwei injizierbare Nahtstellen — den Transport und die Worker-Factory —; beide dienen dem Testen, nicht der Anwendungsverdrahtung.

Codebeispiel — Schnellstart

Prüfen Sie, was die Discovery erzeugt hat, ohne Traffic zu verarbeiten:

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

Codebeispiel — Produktion

Starten Sie die kombinierten Transporte unter einem Supervisor:

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

Randfälle und Stolperfallen

• Eine fehlende Stufe lässt den Boot nicht scheitern. Die Stufen-Discovery überspringt ein fehlendes Pro- oder Enterprise-Paket stillschweigend. Der Server bootet mit dem Core-Katalog.

• Ein Downgrade-Override lässt den Boot scheitern. Ein risk_level_overrides-Eintrag, der ein approval_required-Tool abschwächt, löst beim Laden der Konfiguration eine Exception aus; der Server verweigert den Start. Das ist beabsichtigt.

• Ein Redis-Ausfall degradiert, er stürzt nicht ab. Wenn Redis konfiguriert, beim Boot aber nicht erreichbar ist, fällt der REST-Server auf In-Memory-Stores zurück. Prüfen Sie den Health-Status von Redis, statt anzunehmen, dass Redis im Einsatz ist.

Performance

Die Boot-Kosten setzen sich aus dem Parsen der Konfiguration sowie dem Scan der Registry und der Stufenerkennung zusammen. Das performance_budget der Seite begrenzt diese Kosten. Diese Kosten fallen einmal pro Prozessstart an, nicht pro Anfrage.

Sicherheitshinweise

Die Sicherheitsrichtlinie wird vor der Registry aufgebaut, sodass die enabled_tools-Allowlist die Discovery ab der ersten Registrierung einschränkt. API-Keys werden niemals aus der MCP-YAML-Datei gelesen; die netzwerkbasierten Transporte ermitteln die Keys aus einer Secret-Datei oder der Umgebung. Siehe /connect/security-and-operations/.

Konformität

Diese Seite beschreibt die Boot-Mechanik. Die Protokoll- und Sicherheitszitate stehen auf /transports/mcp/, /transports/rest/, /transports/grpc/ und /connect/security-and-operations/.

Kommerzieller Kontext

Die Stufenerkennung beim Boot ist der einzige Punkt, an dem nextpdf/premium seine Pro- und Enterprise-Tools zum Katalog beiträgt, sofern nextpdf/premium neben dem Server installiert ist.

Siehe auch

• /connect/tool-catalog/ — was die Discovery registriert und warum die Anzahl variiert
• /connect/configuration/ — die Auflösungsreihenfolge im Detail
• /connect/deployment/ — Transporte über RoadRunner-Profile auswählen
• /transports/mcp/ · /transports/rest/ · /transports/grpc/ — Details je Transport