NextPDF Connect – Entwicklerhandbuch

Auf einen Blick

NextPDF Connect (nextpdf/server) kapselt die frameworkunabhängige NextPDF PDF 2.0-Engine als Dienst. Es implementiert die PDF-Generierung nicht neu, sondern stellt jede Engine-Fähigkeit als benanntes, durch ein Schema beschriebenes Tool bereit und liefert diesen Katalog über drei Transporte aus: das Model Context Protocol (MCP) über Standard-Ein- und -Ausgabe, eine Representational-State-Transfer-(REST-)API und gRPC. Nutzen Sie dieses Handbuch, wenn Sie gegen den Server entwickeln, sein Tool-Set erweitern oder ihn produktiv betreiben.

Drei Konzepte tragen das gesamte Design: die Tool-Registry, die drei unabhängigen Transporte und das Human-in-the-Loop-(HITL-)Bestätigungs-Gate. Diese Seite erklärt, wie sie zusammenspielen und wie Sie damit arbeiten, ohne das Sicherheitsmodell zu schwächen. Die exakten Tool-, RPC- und Nachrichtensymbole finden Sie in der API-Referenz.

Voraussetzungen sind PHP 8.4, Composer 2 und — für die vernetzten Transporte — das RoadRunner-Binary sowie mindestens ein API-Schlüssel. Installieren Sie mit composer require nextpdf/server.

Architekturgrenze

Belassen Sie Zuständigkeiten auf der richtigen Seite jeder Grenze. Ein Tool ist ein dünner Wrapper um einen Engine-Aufruf; es darf weder Layoutinterpretation, Dokumentsemantik noch Transformationslogik enthalten.

Schicht	Verantwortlich	Zuständigkeit	Gehört nicht hierher
Client oder Agent	Ihre Integration	Entscheidet, welches Tool aufgerufen wird; leitet Bestätigungsanfragen an einen Menschen weiter.	Engine-Logik oder Stufenerkennung.
Transport	`nextpdf/server`	Kapselt Anfragen (JSON-RPC, HTTP oder Protocol Buffers), authentifiziert sie und routet sie an den Tool-Executor.	Dokumentsemantik.
Tool-Registry	`nextpdf/server`	Erkennt Stufen, registriert Tools unter Vorbehalt der Sicherheits-Allowlist und schlägt ein Tool über seinen Namen nach.	PDF-Generierung.
Tool	`nextpdf/server`	Validiert Argumente anhand des Input-Schemas und ruft die Engine auf.	Layoutinterpretation oder mehrstufige Orchestrierung.
Bestätigungs-Gate	`nextpdf/server`	Hält eine `ApprovalRequired`-Operation zurück, bis ein Mensch sie autorisiert.	Aufrufer-Authentifizierung.
Engine	`nextpdf/core` (und `nextpdf/premium`)	Erzeugt, inspiziert und transformiert PDF-Inhalte.	Transport- oder Authentifizierungsbelange.

Laufzeit-Lebenszyklus

Jeder Transport hat einen eigenen Einstiegspunkt und eine eigene Boot-Factory; jeder baut seinen Objektgraphen explizit auf. Ein Dependency-Injection-Container wird nicht registriert.

Konfiguration laden. Der MCP-Server löst die Konfiguration auf: Umgebungsvariablen (NEXTPDF_MCP_*) haben Vorrang vor dem nextpdf_mcp-Abschnitt der YAML-Datei, dieser wiederum vor den eingebauten Standardwerten. Daraus entsteht eine readonlyMcpConfig. Die REST- und gRPC-Server lesen HttpConfig aus NEXTPDF_*-Umgebungsvariablen. Siehe Konfiguration.
Sicherheitsrichtlinie aufbauen. Die enabled_tools-Allowlist wird vor der Registry aufgebaut, damit sie die Erkennung bereits ab der ersten Registrierung einschränkt.
Registry aufbauen und Tools erkennen. ToolRegistry::registerDefaults() registriert die Core-Stufe, danach die Pro- und Enterprise-Provider, sobald ihre Klassen auflösbar sind, und schließlich die mitgelieferten AST- und Mutation-Provider unter Vorbehalt ihrer Umgebungs-Gates.
Gemeinsame Stores und Gate aufbauen. Der In-Memory-Dokumentstore wird mit der konfigurierten TTL und Kapazität aufgebaut; das ConfirmationGate wird mit seinem Einmal-Token-Store zusammengesetzt.
Transport binden. MCP wechselt über stdio in eine Lesen-Verarbeiten-Schreiben-Schleife, bis das Dateiende erreicht ist. REST und gRPC bauen ihre Routen- bzw. Servicetabelle aus den erkannten Stufen auf und übergeben die Request-Schleife an RoadRunner.

Eine Anfrage durchläuft anschließend diese Schritte: authentifizieren (REST und gRPC), das Tool oder die Operation auflösen, für ApprovalRequired-Arbeit das Bestätigungs-Gate durchlaufen, in der Engine ausführen und das Ergebnis zurückgeben. Siehe Boot und Discovery.

Transportmodell

Die drei Transporte teilen die Konzepte Registry, Konfiguration und Gate, laufen aber als unabhängige Prozesse. Einen Transport zu starten, startet die anderen nicht.

Transport	Einstiegspunkt	Wann Sie ihn wählen
MCP	`bin/nextpdf-mcp`	Ein lokaler KI-Client, der den Server als vertrauenswürdigen Subprozess startet.
REST	`bin/nextpdf-server`	Vernetzte HTTP-Clients; beschrieben durch ein OpenAPI 3.1-Dokument.
gRPC	`bin/nextpdf-grpc`	Typisierte, streamende Clients; der `nextpdf.connect.v1.NextPDFConnect`-Service.

Wählen Sie die Transporte über das RoadRunner-Profil, das Sie ausführen: .rr.yaml (nur REST), .rr.grpc.yaml (nur gRPC) oder .rr.full.yaml (beide). Der MCP-Transport ist ein einfacher Subprozess und benötigt keinen Supervisor. Die transportspezifischen Details auf Protokollebene finden Sie unter MCP-Transport, REST-Transport und gRPC-Transport.

Empfohlene Deployment-Struktur

Betreiben Sie die vernetzten Transporte unter RoadRunner mit gemeinsamen Stores und per Secret eingebundenen Schlüsseln. Im kombinierten Profil teilen sich REST und gRPC einen Supervisor.

Pfad oder Einstellung	Zweck
`.rr.full.yaml`	Kombiniertes REST- und gRPC-Profil unter einem Supervisor.
`NEXTPDF_API_KEYS_FILE`	Pfad zu einer als Secret eingebundenen, hot-reloading-fähigen API-Schlüsseldatei.
`NEXTPDF_REDIS_HOST`	Aktiviert Redis-gestützte Rate-Limit-, Idempotenz- und Dokumentstores für Multi-Worker-Pools.
`NEXTPDF_WORKER_COUNT` / `NEXTPDF_GRPC_WORKER_COUNT`	Dimensionierung der Worker-Pools für die HTTP- und gRPC-Pools.
Basisverzeichnis für die Ausgabe	Dediziertes Volume mit Dateisystemrechten nach dem Least-Privilege-Prinzip für Tools mit Dateiausgabe.

Das folgende Shell-Beispiel startet das kombinierte Profil mit per Secret eingebundenen Schlüsseln und einem gemeinsamen Redis-Store. Es enthält selbst keine Secrets; die Schlüssel werden unter /run/secrets/api-keys eingebunden.

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
export NEXTPDF_WORKER_COUNT=8
export NEXTPDF_GRPC_WORKER_COUNT=4
export NEXTPDF_REDIS_HOST=redis
./vendor/bin/rr serve -c .rr.full.yaml

Konfigurieren Sie für einen Multi-Worker-Pool Redis und stellen Sie sicher, dass ext-redis im laufenden Image vorhanden ist; ohne diese Erweiterung sind die Rate-Limit-, Idempotenz- und Dokumentstores pro Worker getrennt. Siehe Deployment.

Tool-Registry und Stufenauflösung

NextPDF\Server\ToolRegistry (src/ToolRegistry.php) baut den Katalog beim Booten auf. Die Stufe ist eine deklarierte Invariante: Jedes Tool gibt sein eigenes tier() und riskLevel() zurück; die Registry leitet die Stufe niemals aus dem Namespace oder dem Packaging ab.

Die Core-Stufe registriert sich bedingungslos: die Dokument- und Diagnose-Tools sowie generate_barcode, wenn die Core-Barcode-Encoder-Registry vorhanden ist; parse_pdf nur dann, wenn NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED auf true oder 1 gesetzt ist.
Pro- und Enterprise-Provider registrieren sich, sobald ihre Provider-Klassen über class_exists() auflösbar sind. Eine fehlende Stufe wird stillschweigend übersprungen.
Mitgelieferte AST- und Mutation-Provider registrieren sich unter der Pro-Stufe, gesteuert durch NEXTPDF_AST_TOOLS_ENABLED und NEXTPDF_MUTATION_TOOLS_ENABLED (beide standardmäßig aktiviert).
Der Sicherheitsrichtlinienfilter beschneidet jede Registrierung anhand der enabled_tools-Allowlist. Die Allowlist subtrahiert; sie fügt niemals etwas hinzu. Der Zähler je Stufe zählt nur Tools, die die Richtlinie zugelassen hat.

Die resultierenden Zählungen je Stufe und die Gesamtzahl werden in der MCP-initialize-Antwort und im REST-Endpunkt GET /api/v1/capabilities ausgegeben. Behandeln Sie jede feste Gesamtzahl im Fließtext als veraltet; fragen Sie den laufenden Server ab. Siehe Tool-Katalog.

Risikostufen und das Bestätigungs-Gate

Jedes Tool deklariert eine von vier Risikostufen aus dem RiskLevel-Enum (src/Config/RiskLevel.php): Safe (0), Caution (1), Review (2) und ApprovalRequired (3). Audit-Logging gilt ab Caution und höher. Ein Konfigurations-Override darf das Risiko eines Tools anheben; er darf ein Tool, das per Design ApprovalRequired ist, niemals absenken. Der Konfigurations-Loader wirft beim Laden eine Exception, und der Server verweigert den Start, statt mit einem geschwächten Gate zu laufen.

Wird ein ApprovalRequired-Tool ohne gültiges Token aufgerufen, gibt das ConfirmationGate (src/Mcp/ConfirmationGate.php) ein Einmal-Challenge-Token zurück. Das Token bindet den Tool-Namen, eine zufällige Nonce und eine Time-to-Live (TTL) von 300 Sekunden, nicht aber die Argumente, weil Clients die Argumente beim Wiederholungsversuch mit einer anderen Schlüsselreihenfolge neu serialisieren können. Der Agent leitet die Challenge an einen Menschen weiter und ruft dasselbe Tool mit dem Token im Argument _confirmation_token erneut auf. Das Token wird bei der Verwendung verbraucht und gibt genau einen durch das Gate geschützten Aufruf frei.

Das folgende PHP-Beispiel ist ein transportunabhängiger Helper, der einen MCP-Tool-Aufruf steuert und bei einer Bestätigungs-Challenge die Challenge einem menschlichen Genehmiger vorlegt, bevor er es mit dem ausgestellten Token erneut versucht. Er deklariert strict types, ist vollständig typisiert und fängt die spezifischste Exception ab, statt jeden Fehler zu verschlucken.

<?php

declare(strict_types=1);

namespace App\Connect;

use JsonException;

/**
 * Drives one tool call and resolves an ApprovalRequired confirmation
 * challenge through a human approver before retrying.
 */
final readonly class ConfirmingToolCaller
{
    public function __construct(
        private McpClientInterface $client,
        private HumanApproverInterface $approver,
    ) {}

    /**
     * @param non-empty-string     $toolName
     * @param array<string, mixed> $arguments
     *
     * @return array<string, mixed> The tool result content
     *
     * @throws JsonException         When a response cannot be decoded
     * @throws ApprovalDeniedException When the human declines the challenge
     */
    public function call(string $toolName, array $arguments): array
    {
        $response = $this->client->callTool($toolName, $arguments);

        if (!isset($response['challenge'], $response['token'])) {
            return $response;
        }

        $challenge = (string) $response['challenge'];
        $token = (string) $response['token'];

        if (!$this->approver->approve($toolName, $challenge)) {
            throw new ApprovalDeniedException($toolName);
        }

        $arguments['_confirmation_token'] = $token;

        return $this->client->callTool($toolName, $arguments);
    }
}

Verdrahten Sie McpClientInterface, HumanApproverInterface und ApprovalDeniedException mit Ihrem eigenen Transport- und Genehmigungskanal. Der Wiederholungsversuch verwendet erneut die ursprünglichen Argumente plus das ausgestellte Token; genehmigen Sie eine Challenge niemals automatisch ohne menschliche Entscheidung. Siehe HITL-Risikostufen.

Erweiterungspunkte

Der Server wird erweitert, indem Sie Tools hinzufügen und Provider bereitstellen, nicht indem Sie die Registry bearbeiten.

Erweiterungspunkt	Wofür du ihn nutzt	Einschränkung
Eine Klasse, die `ToolInterface` implementiert	Eine neue Engine-Fähigkeit, die als Tool bereitgestellt wird.	Deklarieren Sie `tier()`, `riskLevel()`, `category()` und ein JSON-Schema `inputSchema()`; halten Sie es als dünnen Engine-Wrapper.
Ein `ToolProviderInterface`-Provider	Registrierung einer Reihe von Tools für eine Stufe.	Pro- und Enterprise-Provider werden über `class_exists()` erkannt; machen Sie das proprietäre Paket nicht zur Voraussetzung des Servers.
`enabled_tools`-Allowlist	Eingrenzung des bereitgestellten Katalogs nach dem Least-Privilege-Prinzip.	Die Allowlist subtrahiert nur; sie kann kein fehlendes Tool registrieren.
`risk_level_overrides`	Härtung eines Deployments durch Anheben des Risikos eines Tools.	Nur Heraufstufung; eine Herabstufung eines `ApprovalRequired`-Tools lässt den Boot scheitern.
Injizierbare Transport- und Worker-Nahtstellen	Testen des Servers in Isolation.	Diese Nahtstellen existieren für Tests, nicht für die Verdrahtung in der Anwendung.

Betriebsworkflow

Ein Profil wählen. Führen Sie .rr.yaml, .rr.grpc.yaml oder .rr.full.yaml für die Transporte aus, die Sie bereitstellen.
Schlüssel aus einem Secret einbinden. Richten Sie NEXTPDF_API_KEYS_FILE auf eine Secret-Datei; bevorzugen Sie den hot-reloading-fähigen File-Key-Store, damit die Rotation keinen Neustart erfordert.
Gemeinsame Stores konfigurieren. Setzen Sie NEXTPDF_REDIS_HOST und stellen Sie ext-redis für jeden Pool mit mehr als einem Worker sicher; legen Sie den SQLite-Job-Store auf einem Volume ab, das alle Worker beschreiben können.
TLS terminieren. Betreiben Sie REST hinter einem Transport-Layer-Security-(TLS-)Terminator; betreiben Sie gRPC in jedem nicht vertrauenswürdigen Netzwerk mit Mutual TLS, wobei Server-Key, Serverzertifikat und Client-Zertifizierungsstelle als Deployment-Secrets bereitgestellt werden.
Health prüfen. Nutzen Sie für Orchestrator-Probes die anonymen Endpunkte /healthz und /readyz (REST) oder die RPCs HealthCheck und ReadinessCheck (gRPC).
Den Katalog eingrenzen. Beschränken Sie enabled_tools auf den minimalen Satz, den eine Integration benötigt.

Prüfen Sie den Redis-Health, statt ihn vorauszusetzen: Der REST-Server fällt auf In-Memory-Stores zurück, wenn eine konfigurierte Redis-Verbindung fehlschlägt. Siehe Deployment und Sicherheit und Betrieb.

Fehlerbehandlung

Fehler	Wo er auftritt	Empfohlene Reaktion
Unbekannte `document_id`	Tool-Ausführung	Geben Sie dem Aufrufer einen definierten Fehler zurück; weisen Sie ihn an, zuerst `create_pdf` aufzurufen.
Veralteter ETag bei einer Mutation	AST-Mutation-Tool	Lesen Sie das Dokument mit `get_document_ast` erneut und versuchen Sie es mit dem frischen ETag noch einmal.
Fehlender oder ungültiger API-Schlüssel (REST)	Authentifizierungs-Middleware	Geben Sie `401` mit einer `WWW-Authenticate: Bearer`-Challenge zurück; verraten Sie nicht, welcher Teil falsch war.
Stufe nicht berechtigt (REST)	Autorisierung	Geben Sie `403` zurück; die Stufe des Schlüssels liegt unter der Stufe der Operation.
Stufenroute fehlt (REST)	Router	Geben Sie `404` zurück; das Paket ist nicht installiert. Erwartetes Verhalten, kein Fehler.
Ungültiges Token (gRPC)	gRPC-Authenticator	Lassen Sie den Aufruf mit `UNAUTHENTICATED` fehlschlagen.
Redis nicht erreichbar	Boot oder Laufzeit	Fallen Sie auf In-Memory-Stores zurück; alarmieren Sie den Betreiber und prüfen Sie den Redis-Health.
Ausgabepfad außerhalb des Basisverzeichnisses	Tool mit Dateiausgabe	Fail closed; der Pfad wird kanonisiert und Traversal wird abgewiesen.

Legen Sie Engine-Fehler als definierte Fehlerobjekte offen, niemals als stille Erfolge. Das Fehlermodell je Transport ist in der API-Referenz ausführlich beschrieben.

Sichere Standardwerte

Aspekt	Standard	Wann Sie überschreiben
`parse_pdf`	Deaktiviert (Opt-in über `NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED`).	Aktiviere es nur, wenn eine Integration strukturelle Inspektion benötigt.
`enabled_tools`	Leer (alle erkannten Tools erlaubt).	Setze eine explizite Allowlist für Least-Privilege-Deployments.
Risiko-Overrides	Keine.	Hebe das Risiko für ein gehärtetes Deployment an; versuche niemals eine Herabstufung.
`document_ttl` / `max_documents`	1800 Sekunden / 50 Dokumente.	Senken Sie die Werte für residency-sensible oder speicherbeschränkte Deployments.
`allow_file_output`	Aktiviert.	Setzen Sie den Wert auf `false` für zustandslose, residency-sensible Deployments.
Worker-Anzahl	Vier (HTTP), zwei (gRPC).	Dimensioniere anhand der beobachteten Latenz und der verfügbaren Cores.
REST-Listener	Klartext-HTTP hinter einem TLS-Terminator.	Terminieren Sie TLS immer vorgelagert; legen Sie Klartext niemals in einem nicht vertrauenswürdigen Netzwerk offen.
gRPC in nicht vertrauenswürdigen Netzwerken	Mutual TLS.	Erforderlich; betreiben Sie niemals einen Klartext-gRPC-Listener in einem nicht vertrauenswürdigen Netzwerk.

Test-Checkliste

Registry-Tests stellen sicher, dass eine fehlende Pro- oder Enterprise-Stufe stillschweigend übersprungen wird und der Core-Katalog trotzdem registriert wird.
Allowlist-Tests stellen sicher, dass enabled_tools subtrahiert und niemals ein Tool hinzufügt, das die Registry nicht erkannt hat.
Bestätigungs-Gate-Tests stellen sicher, dass ein ApprovalRequired-Tool beim ersten Aufruf eine Challenge zurückgibt, bei einem gültigen Einmal-Token genau einmal läuft und das Token nach seiner TTL abläuft.
Downgrade-Tests stellen sicher, dass ein risk_level_overrides-Eintrag, der ein ApprovalRequired-Tool schwächt, den Boot scheitern lässt.
Authentifizierungstests decken fehlende, fehlerhafte, deaktivierte und abgelaufene Schlüssel bei REST (401 mit WWW-Authenticate) und gRPC (UNAUTHENTICATED) sowie die Ablehnung wegen fehlender Stufenberechtigung (403) ab.
Nebenläufigkeitstests stellen sicher, dass ein veralteter ETag eine Mutation scheitern lässt und dass ein wiederholter idempotency_key das zwischengespeicherte Ergebnis erneut abspielt.
Path-Containment-Tests stellen sicher, dass ein Dateiausgabepfad, der außerhalb des Basisverzeichnisses aufgelöst wird, abgewiesen wird.
Halten Sie Fixtures klein und nicht sensibel; committen Sie niemals einen echten API-Schlüssel oder echten Dokumentinhalt.

Siehe auch

API-Referenz — die exakten Tool-, RPC- und Nachrichtensymbole
Tool-Katalog — der verifizierte Core-Satz und die Laufzeitzahl
HITL-Risikostufen — das Risikomodell und die Bestätigungshülle
Konfiguration — die Auflösungsreihenfolge und der nur heraufstufende Override
Deployment — RoadRunner-Profile, Redis und Mutual TLS
Sicherheit und Betrieb — Authentifizierung, Transportsicherheit und das Bedrohungsmodell