NextPDF Connect-Integration

Auf einen Blick

Integrieren Sie NextPDF Connect, indem Sie es als Server betreiben. Sie binden keine Bibliothek in eine Host-Anwendung ein. Wählen Sie einen Transport und konfigurieren Sie die Authentifizierung, sobald dieser Transport vernetzt ist. Die Tools der Engine werden über das Bestätigungs-Gate abgesichert.

Installation

composer require nextpdf/server

Die Composer-Anforderung lautet nextpdf/core: ^3.0 mit php: >=8.4 <9.0. Details zum optionalen ext-redis und zu nextpdf/premium finden Sie unter /connect/install/.

Konzeptioneller Überblick

Das Paket ist ein eigenständiger Dienst. Es gibt keinen Service-Provider, kein Bundle und kein Container-Modul, das Sie in einem Host-Framework registrieren müssten. Der Integrationspunkt ist ein Prozess, den Sie betreiben. Jeder Transport hat seinen eigenen Einstiegspunkt und startet unabhängig. Weitere Informationen finden Sie unter /connect/boot-and-discovery/.

API-Oberfläche

Einstiegspunkt	Transport	Profil
bin/nextpdf-mcp	MCP über stdio	(keines — direkter Subprozess)
bin/nextpdf-server	REST über RoadRunner-HTTP	.rr.yaml
bin/nextpdf-grpc	gRPC über RoadRunner-gRPC	.rr.grpc.yaml
beide vernetzten Transporte	REST + gRPC	.rr.full.yaml

Boot und automatische Erkennung

Die Registry erkennt die Core-Stufe bedingungslos. Anschließend fügt sie die Pro- und Enterprise-Provider hinzu, sobald deren Klassen auflösbar sind; danach folgen die mitgelieferten AST- und Mutation-Provider, die durch Umgebungs-Gates gesteuert werden. Die Sicherheits-Allowlist enabled_tools filtert diese Gesamtheit, sodass der freigegebene Katalog eine Eigenschaft des jeweiligen Deployments ist. Weitere Informationen finden Sie unter /connect/tool-catalog/ und /connect/boot-and-discovery/.

Container-Bindings

Keine. Jede Server-Factory baut ihren eigenen Objektgraphen explizit auf. Die injizierbaren Schnittstellen sind für Tests vorgesehen, nicht für die Anwendungsverdrahtung.

Konfiguration veröffentlichen

Der MCP-Server akzeptiert eine optionale YAML-Datei (--config=PATH, Abschnitt nextpdf_mcp) und NEXTPDF_MCP_*-Umgebungs-Overrides. Die REST- und gRPC-Server lesen NEXTPDF_*-Umgebungsvariablen. Details finden Sie unter /connect/configuration/.

Transport-Verfügbarkeit (MCP / REST / gRPC)

Alle drei Transporte bedienen dieselbe Registry:

• MCP — lokaler Subprozess, JSON-RPC 2.0 über stdio, kein API-Key, MCP-Revision 2025-06-18. Siehe /transports/mcp/.
• REST — RoadRunner-HTTP-Worker-Pool, OpenAPI-3.1-Vertrag, Bearer-API-Key, stufenabhängige Routen. Siehe /transports/rest/.
• gRPC — RoadRunner-gRPC-Worker-Pool, Protobuf-Dienst nextpdf.connect.v1, Server-Streaming-RPCs, Bearer-Authentifizierung über Metadaten, Mutual TLS im kombinierten Profil. Siehe /transports/grpc/.

Ein Transport ist „verfügbar“, wenn sein Einstiegspunkt oder sein RoadRunner-Profil läuft. Transporte starten sich nicht automatisch gegenseitig.

HITL-Risikostufe

Jedes Tool deklariert eine von vier Risikostufen — safe, caution, review, approval_required. Tools der Stufe approval_required werden beim ersten Aufruf nicht ausgeführt. Das Bestätigungs-Gate stellt ein einmalig nutzbares Challenge-Token aus, das von einem Menschen autorisiert werden muss. Ein Konfigurations-Override darf das Risiko eines Tools nur erhöhen und niemals ein approval_required-Tool herabstufen. Das Modell gilt für jeden Transport, über den Tools ausgeführt werden, identisch. Weitere Informationen finden Sie unter /connect/hitl-risk-tiers/.

JSON-Envelope des Bestätigungs-Gates

Die Gate-Prüfung gibt eine von zwei JSON-Formen zurück. Erlaubt:

{ "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>"
}

Das Token bindet den Tool-Namen, eine zufällige Nonce und eine TTL von 300 Sekunden — nicht die Argumente. Um fortzufahren, ruft der Aufrufer dasselbe Tool erneut auf und setzt dabei das Argument _confirmation_token auf das ausgestellte Token. Die Challenge besteht ausschließlich aus Anweisungstext und dem Token; sie ist kein kryptografisch signierter Envelope. Weitere Informationen finden Sie unter /connect/hitl-risk-tiers/.

Service-Smoke-Test

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

Der Befehl startet die Registry und die Stufenerkennung und gibt anschließend die freigegebenen Tools aus, ohne Traffic anzunehmen. So lässt sich schnell bestätigen, dass die Integration verdrahtet ist, und prüfen, welchen Katalog diese Installation erzeugt.

Sonderfälle und Stolperfallen

• Keine Framework-Hooks. Suchen Sie nicht nach einem Service-Provider oder Bundle. Die Integration ist der laufende Prozess.
• Eine fehlende Stufe ist kein Fehler. Die Core-only-Installation startet und bedient ihren Core-Katalog.
• Vernetzte Transporte erfordern einen Key. Nur /healthz und /readyz (REST) sowie die Health-RPCs (gRPC) sind anonym.

Performance

Die Boot-Kosten bestehen aus dem Registry-Scan und der Stufenerkennung und fallen einmal pro Prozess an. Die Kosten pro Anfrage richten sich nach der jeweiligen Engine-Operation. Dimensionieren Sie die RoadRunner-Worker-Pools anhand der beobachteten Render-Latenz. Weitere Informationen finden Sie unter /connect/production-usage/.

Sicherheitshinweise

Vernetzte Transporte authentifizieren sich mit einem npk_live_-Bearer-Key, der in konstanter Zeit validiert wird; das Gate erzwingt bei destruktiven Operationen unabhängig vom Transport eine menschliche Bestätigung. Terminieren Sie TLS vor REST und verwenden Sie Mutual TLS für gRPC in nicht vertrauenswürdigen Netzwerken. Weitere Informationen finden Sie unter /connect/security-and-operations/.

Konformität

Protokoll- und Sicherheitsnachweise sind unter /transports/mcp/, /transports/rest/, /transports/grpc/ und /connect/security-and-operations/ festgehalten.

Kommerzieller Kontext

Wenn Sie nextpdf/premium zusätzlich zum Server installieren, werden die zusätzlichen Pro- und Enterprise-Tools im selben laufenden Server registriert. Es ist kein separater Prozess beteiligt.

Siehe auch

• /connect/overview/ — die Architektur
• /connect/quickstart/ — der erste lauffähige Austausch
• /transports/mcp/ · /transports/rest/ · /transports/grpc/ — Referenz je Transport
• /connect/hitl-risk-tiers/ — das Bestätigungs-Gate im Detail
• /connect/tool-catalog/ — der laufzeitabhängige Katalog
• /connect/security-and-operations/ — Authentifizierung und Bedrohungsmodell