NextPDF Connect – Schnellstart

Auf einen Blick

Diese Seite führt den kleinsten sinnvollen Austausch über beide Transporte aus: MCP und REST. Jede Anfrage entspricht exakt dem Wire-Format, das der Server implementiert. Ein Software Development Kit (SDK) ist nicht beteiligt.

Installation

composer require nextpdf/server

Konzeptioneller Überblick

Der MCP-Transport kommuniziert per JSON-RPC 2.0 über Standardeingabe und Standardausgabe. Die Sequenz ist erforderlich und muss in dieser Reihenfolge ablaufen. Senden Sie zuerst initialize. Senden Sie anschließend die Bestätigung notifications/initialized. Senden Sie danach tools/list und tools/call. Der Server liest eine JSON-Nachricht pro Zeile; jede Zeile endet mit einem Zeilenumbruch. Er schreibt jeweils eine Antwort pro Zeile.

Der REST-Transport macht dieselben Engine-Fähigkeiten als HTTP-Operationen verfügbar. Ein einzelnes zustandsloses Rendering erfolgt als POST /api/v1/render mit einem geordneten operations-Array. Der Antwort-Body ist das PDF.

Codebeispiel — Schnellstart (MCP über stdio)

Starten Sie den Server und leiten Sie den Handshake per Pipe an ihn weiter. Die folgenden drei Anfragen verwenden die verifizierten Methodennamen, die der Protokoll-Handler routet:

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"quickstart","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
EOF

Die initialize-Antwort liefert die Protokollversion 2025-06-18, den Servernamen NextPDF Connect und einen capabilities.nextpdf-Block. Dieser Block enthält die Live-Zählwerte der Stufen, den Laufzeitwert tool_count, die Version des Risikomodells und hitl_enabled: true. Die tools/list-Antwort listet genau die Tools auf, die diese Installation registriert hat. Die Benachrichtigungszeile erzeugt absichtlich keine Antwort.

Rufen Sie jetzt ein sicheres Tool auf. Das Tool diagnostic.doctor führt eine schreibgeschützte Umgebungsprüfung durch. Es benötigt weder ein Dokument noch eine Bestätigung:

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"quickstart","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"diagnostic.doctor","arguments":{}}}
EOF

Codebeispiel — Schnellstart (REST)

Starten Sie den REST-Server und rendern Sie dann ein einzeiliges PDF. Der Server verlangt an jedem Nicht-Health-Endpunkt einen API-Schlüssel; definieren Sie daher zuerst einen:

export NEXTPDF_API_KEYS='npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef:demo:core:default'
./vendor/bin/rr serve -c .rr.yaml

Senden Sie in einer zweiten Shell eine Render-Anfrage. Der Body ist ein RenderRequest. Diese Anfrage enthält ein geordnetes operations-Array aus typisierten Operationen.

curl -sS -X POST http://localhost:8080/api/v1/render \
  -H 'Authorization: Bearer npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef' \
  -H 'Content-Type: application/json' \
  -d '{
        "page_size": "A4",
        "orientation": "portrait",
        "operations": [
          { "type": "add_text", "text": "Hello from NextPDF Connect" }
        ]
      }' \
  --output hello.pdf

Bei 200 ist der Antwort-Body das PDF (Content-Type: application/pdf); die Ausgabe wird nach hello.pdf geschrieben. Health-Probes benötigen keinen Schlüssel:

curl -sS http://localhost:8080/healthz

Randfälle und Fallstricke

Die Reihenfolge des Handshakes ist wichtig. Der Protokoll-Handler behandelt eine Nachricht ohne id als Benachrichtigung und gibt nichts zurück. Senden Sie initialize mit einer id, dann die initialized-Benachrichtigung und danach Ihre Anfragen mit id.
Eine wiederholte Anfrage-id wird dedupliziert. Der Handler speichert die jüngsten Antworten in einem Ringpuffer mit 64 Einträgen. Bei einer doppelten id gibt er die zwischengespeicherte Antwort zurück, ohne das Tool erneut auszuführen. Verwenden Sie neue IDs.
Ein Tool mit hohem Risiko antwortet mit einer Rückfrage, nicht mit einem Ergebnis. Ein Aufruf von output_pdf mit einem file_path gibt eine Bestätigungs-Rückfrage zurück, anstatt ausgeführt zu werden. Rufen Sie es mit dem ausgestellten _confirmation_token erneut auf. Der base64-Ausgabemodus (kein file_path) erfordert keine Bestätigung. Siehe /connect/hitl-risk-tiers/.
Eine nicht autorisierte REST-Anfrage erhält 401. Ein fehlender oder fehlerhafter Authorization: Bearer-Header führt zu einem Problem-Details-Body mit einem WWW-Authenticate: Bearer-Header. Die /healthz- und /readyz-Probes sind die einzigen anonymen Endpunkte.

Leistung

Beide Schnellstart-Pfade bestehen aus einer einzigen Anfrage. Der REST-Pfad trägt bei der ersten Anfrage nach rr serve zusätzlich die Kaltstartkosten des RoadRunner-Worker-Pools. Spätere Anfragen nutzen warme Worker wieder.

Sicherheitshinweise

Der oben gezeigte npk_live_-Schlüssel ist ein Wegwerf-Demowert. Erzeugen Sie echte Schlüssel mit ausreichender Entropie, bewahren Sie sie außerhalb der Versionskontrolle auf und bevorzugen Sie für die Rotation den dateibasierten Key-Store. Der MCP-stdio-Transport hat keinen API-Schlüssel, weil er als lokaler Subprozess läuft und der startende Client ihm gemäß dem MCP-Transportmodell vertraut. Siehe /connect/security-and-operations/.

Konformität

Die gezeigten Wire-Formate entsprechen der implementierten MCP-Revision 2025-06-18 und dem OpenAPI-3.1-REST-Vertrag. Normative Belege zu Protokoll und Authentifizierung sind hier verankert: /transports/mcp/, /transports/rest/ und /connect/security-and-operations/.

Siehe auch

/transports/mcp/ — die vollständige MCP-Transport-Referenz
/transports/rest/ — die vollständige REST-Transport-Referenz und das OpenAPI-Rendering
/connect/tool-catalog/ — welche Tools tools/list zurückgibt und warum
/connect/hitl-risk-tiers/ — wie eine Bestätigungs-Rückfrage aussieht
/connect/configuration/ — den Katalog einschränken und den Server anpassen