NextPDF Connect Server – Überblick

Auf einen Blick

NextPDF Connect ist das nextpdf/server-Paket: ein langlebiger Dienst, der die NextPDF PDF 2.0-Engine für KI-Agenten und HTTP-Clients bereitstellt. Dafür nutzt er drei Transporte: Model Context Protocol (MCP) über stdio, eine REST-API und gRPC. Alle drei Transporte verwenden dieselbe Tool-Registry und dasselbe Human-in-the-Loop-Bestätigungs-Gate (HITL).

Installation

composer require nextpdf/server

Die Composer-Constraint lautet nextpdf/core: ^3.0 bei php: >=8.4 <9.0. Den vollständigen Ablauf finden Sie unter /connect/install/. Diese Seite beschreibt außerdem zwei optionale Add-ons: die ext-redis-Erweiterung und das nextpdf/premium-Paket.

Konzeptioneller Überblick

nextpdf/server bindet den framework-agnostischen NextPDF-Kern an eine Service-Oberfläche an. Es baut die PDF-Generierung nicht neu auf. Stattdessen kapselt es jede Engine-Fähigkeit als benanntes Tool mit einem eigenen Schema und stellt diesen Katalog über mehrere Wire-Protokolle bereit.

Drei Konzepte bilden die Grundlage des gesamten Designs:

Die Tool-Registry. NextPDF\Server\ToolRegistry findet und registriert Tools beim Start. Ein Kernsatz wird mit dem Paket ausgeliefert, und dieser Kernsatz ist immer verfügbar. Pro- und Enterprise-Provider registrieren weitere Tools, aber nur dann, wenn die passenden Pakete installiert sind. Die Anzahl der bereitgestellten Tools ist daher eine Laufzeiteigenschaft des Deployments und keine feste Konstante. Siehe /connect/tool-catalog/.
Die Transporte. Dieselbe Registry wird auf drei Wegen bereitgestellt. MCP läuft über stdio für lokale KI-Clients. REST läuft über eine PSR-15-Middleware-Pipeline auf einem RoadRunner-Worker-Pool für vernetzte Clients. gRPC läuft über einen Spiral-RoadRunner-gRPC-Worker für typisierte Clients mit Streaming. Jeder Transport ist ein eigener Prozess mit einem eigenen Einstiegspunkt. Siehe /transports/mcp/, /transports/rest/ und /transports/grpc/.
Das Bestätigungs-Gate. Jedes Tool deklariert eine Risikostufe. Ein Tool auf der höchsten Risikostufe erfordert eine ausdrückliche menschliche Bestätigung, bevor es ausgeführt wird. Das Gate stellt ein einmalig verwendbares Challenge-Token aus. Der Agent muss dieses Token an einen Menschen weitergeben und das Tool anschließend erneut mit dem Token aufrufen. Siehe /connect/hitl-risk-tiers/.

Das folgende Diagramm zeigt, wie eine Registry über drei Transporte erreichbar ist. Es zeigt außerdem, wo das Bestätigungs-Gate im Anfragepfad sitzt.

NextPDF Connect component architecture

Das Paket ist unter Apache-2.0 lizenziert und passt damit zu nextpdf/core. Die implementierte MCP-Protokollversion ist die datumsbasierte Revision 2025-06-18. Ein OpenAPI-3.1-Dokument beschreibt die REST-Oberfläche. Das Protocol-Buffers-Paket nextpdf.connect.v1 beschreibt die gRPC-Oberfläche.

API-Oberfläche

Die öffentlichen Einstiegspunkte sind die drei Server-Klassen. Für jede davon gibt es einen Command-Line-Interface-Wrapper (CLI):

Einstiegspunkt	Klasse	Transport
`bin/nextpdf-mcp`	`NextPDF\Server\Mcp\McpServer`	MCP über stdio
`bin/nextpdf-server`	`NextPDF\Server\Http\HttpServer`	REST über RoadRunner HTTP
`bin/nextpdf-grpc`	`NextPDF\Server\Grpc\GrpcServer`	gRPC über RoadRunner gRPC
`bin/generate-skills`	`NextPDF\Server\Skills\SkillsDumper`	Tool-Katalog-Export

McpServer::create(), HttpServer::create() und GrpcServer::create() bauen jeweils einen vollständig konfigurierten Server aus Umgebungs- und Konfigurationseingaben auf. Die Registry, der Document Store, die Security-Policy und das Bestätigungs-Gate sind Konzepte, die alle drei Server gemeinsam nutzen.

Codebeispiel – Schnellstart

Der minimale MCP-Server besteht aus einem einzigen Befehl. Sie schreiben keinen PHP-Glue-Code:

./vendor/bin/nextpdf-mcp

Der Server liest JSON-RPC-Anfragen über die Standardeingabe und schreibt Antworten auf die Standardausgabe. Einen lauffähigen Austausch mit initialize und tools/list sowie die passende REST-Anfrage finden Sie unter /connect/quickstart/.

Sonderfälle und Stolperfallen

Die Tool-Anzahl ist nicht 33 oder eine andere feste Zahl. Der Server zählt die Tools zur Laufzeit per count(ToolRegistry::all()), nach Policy-Filterung und Stufenerkennung. Dokumentation, die eine feste Gesamtzahl nennt, ist veraltet. Um die maßgebliche Anzahl zu erhalten, fragen Sie den laufenden Server ab. Nutzen Sie die MCP-initialize-Antwort oder den REST-Endpunkt /api/v1/capabilities.

Die Anzahl der bereitgestellten Tools hängt von den installierten Paketen und von der aktiven Policy ab. Lesen Sie sie zur Laufzeit vom laufenden Server aus. Eine feste Zahl, die Sie in Ihren eigenen Code oder Ihre Dokumentation kopieren, veraltet mit der Zeit.
Ein fehlendes Pro- oder Enterprise-Paket ist kein Fehler. Die Registry prüft mit class_exists() auf Provider-Klassen und überspringt anschließend stillschweigend jede fehlende Stufe. Ein reines Open-Source-Deployment startet und stellt seinen Kernkatalog wie gewohnt bereit.
Die drei Transporte teilen sich keinen Prozess. Wenn Sie den MCP-Server starten, werden weder der REST-Server noch der gRPC-Server gestartet. Umgekehrt gilt das ebenso. Ein kombiniertes Deployment betreibt den RoadRunner-Supervisor mit einer Konfiguration, die beide Worker-Pools startet: den HTTP-Pool und den gRPC-Pool. Siehe /connect/deployment/.

Performance

Jeder Transport basiert auf Workern. Ein Worker verarbeitet jeweils eine Anfrage. Der REST- und der gRPC-Server laufen auf RoadRunner-Worker-Pools, und die Konfiguration legt die Poolgröße fest. Standardmäßig sind es vier HTTP-Worker. Der RoadRunner-Supervisor begrenzt den Speicher jedes Workers. Der Wert in der performance_budget-Frontmatter auf dieser Seite beschreibt einen Rahmen für Kaltstart und Discovery. Er ist kein Zielwert pro Anfrage. Den Großteil der Kosten jeder Anfrage verursacht die zugrunde liegende Engine-Operation.

Sicherheitshinweise

Alle vernetzten Transporte authentifizieren Anfragen mit einem API-Key-Bearer-Token (Application Programming Interface). Der MCP-stdio-Transport ist ein lokaler Subprozess, dem der startende Client gemäß dem MCP-Transportmodell vertraut. Tools mit hohem Risiko bleiben auf jedem Transport durch eine menschliche Bestätigung geschützt. Das vollständige Bedrohungsmodell, das Authentifizierungsmodell und die Transport-Security-Konfiguration finden Sie unter /connect/security-and-operations/.

Konformität

Diese Seite trifft ausschließlich architektonische Aussagen. Die normativen Zitate zu Protokoll und Sicherheit sind auf den Seiten verankert, die das Verhalten festlegen: /connect/security-and-operations/, /transports/mcp/, /transports/rest/ und /transports/grpc/. Die Referenz für den MCP-Lebenszyklus ist die offizielle Spezifikation unter modelcontextprotocol.io (Revision 2025-06-18). Die Transport-Seiten verzeichnen diese Referenz mit ihrer URL, weil die MCP-Spezifikation nicht Teil des zugriffsbeschränkten Standardskorpus ist.

Kommerzieller Kontext

Der Kernkatalog deckt Dokumenterstellung, Inspektion und Diagnostik vollständig ab. Tools für Signierung, Schwärzung, Compliance-Zertifizierung und forensische Analyse erscheinen nur dann, wenn nextpdf/premium zusammen mit dem Server installiert ist. Das ist eine Paketierungsgrenze, keine Upselling-Aufforderung zur Laufzeit. Der Server gibt niemals Marketinginhalte aus.

Siehe auch

/connect/install/ — Installation und optionale Pakete
/connect/quickstart/ — erster lauffähiger MCP- und REST-Austausch
/connect/tool-catalog/ — der verifizierte Kern-Tool-Satz und warum die Anzahl laufzeitabhängig ist
/connect/hitl-risk-tiers/ — das Bestätigungs-Gate und das Risikomodell
/transports/mcp/, /transports/rest/, /transports/grpc/ — Einrichtung pro Transport
/connect/security-and-operations/ — Authentifizierung, Transport-Security und Bedrohungsmodell
/connect/deployment/ — RoadRunner, Docker und Deployment mit kombinierten Transporten