Ihr erstes PDF mit NextPDF Connect erzeugen

Auf einen Blick

Dieses Rezept führt Sie auf dem kürzesten Weg von einer leeren Sitzung zu einem gerenderten PDF mit NextPDF Connect. Sie erstellen ein einseitiges A4-Dokument, schreiben eine Überschrift und einen Untertitel und geben die Datei anschließend als Base64 zurück. Drei Core-Tools erledigen die gesamte Arbeit: create_pdf, add_text und output_pdf. Sie benötigen keine Schriftarten, keine Bilder und keine lizenzierte Edition.

Ein Connect-Transport überträgt jeden Tool-Aufruf als Anfrage und gibt das Ergebnis des Tools als Antwort zurück. Die Transportschicht ist unabhängig von dem Ergebnis, das das Tool meldet (PSR-18 §p2).

Installation

Installieren Sie NextPDF Server und binden Sie einen Transport:

composer require nextpdf/server

Führen Sie den Server mit dem Transport aus, den Ihr Host erwartet – Model Context Protocol über stdio, REST oder gRPC. Siehe Transportverfügbarkeit weiter unten. Die Tools in diesem Rezept sind Core-Tools. Sie werden mit dem Server ausgeliefert, sodass Sie kein Pro- oder Enterprise-Paket benötigen.

Konzeptioneller Überblick

Eine Connect-Sitzung ist ein serverseitiger Dokumentspeicher, der über eine document_id adressiert wird. create_pdf öffnet eine Sitzung und gibt die ID zurück. Jeder spätere Tool-Aufruf bezieht sich auf diese ID. Das Dokument beginnt mit einer leeren Seite. Der Seitenbaum ist die Struktur, über die ein PDF-Leser jede Seite erreicht (ISO 32000-2 §7.7.3). output_pdf rendert die Sitzung zu einem PDF. Standardmäßig zerstört es anschließend die Sitzung, um Speicher freizugeben.

Wenn Sie add_text ohne ein explizites x oder y aufrufen, wird der Text automatisch positioniert: Er beginnt am aktuellen Cursor, und der Cursor rückt nach jedem Aufruf weiter.

API-Oberfläche

Die Tool-Registry löst beim Serverstart die unten aufgeführten Tools auf. Die Namen sind die Protokollnamen der Registry. Der maßgebliche Katalog ist der zusammengeführte Tool-Katalog. Welche Tools vorhanden sind, hängt von der installierten Edition ab, doch diese drei sind in Core stets vorhanden.

Tool	Rolle	Risikostufe
create_pdf	Eine Dokumentsitzung öffnen	Sicher
add_text	Text in das Dokument schreiben	Vorsicht
output_pdf	Das PDF rendern und zurückgeben	Genehmigung erforderlich (Dateimodus) / Prüfung (Base64)

Codebeispiel – Schnellstart

Der Host führt drei Tool-Aufrufe aus. In Worten:

1. Rufen Sie create_pdf mit page_size: "A4", orientation: "portrait" sowie mit Dokumenttitel und Autor auf. Der Server gibt eine document_id zurück.
2. Rufen Sie add_text mit dieser document_id, dem Überschriftentext, einer großen font_size, width: 0 (die volle Inhaltsbreite) und alignment: "center" auf.
3. Rufen Sie output_pdf mit der document_id auf. Ohne file_path gibt der Server das PDF als Base64 zurück und zerstört die Sitzung.

Hier ist ein minimales create_pdf-Argumentobjekt:

{
  "page_size": "A4",
  "orientation": "portrait",
  "title": "Hello World",
  "author": "NextPDF Cookbook"
}

Die Antwort enthält die document_id, die Seitenzahl und die Seitengeometrie. Behandeln Sie die ID als undurchsichtigen Wert und leiten Sie daraus keine Bedeutung ab.

Codebeispiel – Produktion

Ein produktionsreifer Aufrufer prüft jede Antwort vor dem nächsten Aufruf. Er verwendet eine document_id niemals erneut, nachdem output_pdf die Sitzung zerstört hat.

1. create_pdf – bestätigen Sie, dass die Antwort eine document_id enthält. Gibt der Server den Sitzungslimit-Fehler zurück, geben Sie ungenutzte Sitzungen frei und versuchen Sie es erneut.
2. add_text (Überschrift) – bestätigen Sie, dass die Antwort eine position zurückgibt.
3. add_text (Untertitel) – verwenden Sie eine kleinere font_size; der Cursor setzt sich unterhalb der Überschrift fort.
4. output_pdf – lesen Sie das Feld base64 und dekodieren Sie es zu Bytes. Das Flag destroyed bestätigt, dass die Sitzung zerstört wurde.

Die Datei wird inline zurückgegeben (Base64-Modus), sodass es keinen Dateisystem-Nebeneffekt und kein menschliches Genehmigungstor gibt – siehe HITL-Risikostufe.

Randfälle & Fallstricke

• Zerstörte Sitzung. Nachdem output_pdf mit dem Standard destroy: true ausgeführt wurde, ist die document_id nicht mehr gültig. Jeder weitere Aufruf mit dieser ID gibt einen Unbekanntes-Dokument-Fehler zurück. Erstellen Sie stattdessen eine neue Sitzung.
• Unbekanntes Seitenformat. Der Server lehnt einen page_size-Wert ab, den er nicht erkennt, und gibt einen klaren Fehler zurück. Verwenden Sie ein dokumentiertes Format (A3, A4, A5, A6, Letter, Legal, Tabloid).
• Leerer Text. Ein leerer text-Wert erzeugt einen Eintrag mit Breite null, keinen Fehler. Prüfen Sie Ihre Eingabe vor dem Aufruf.
• Sitzungslimit. Der In-Memory-Speicher begrenzt, wie viele Sitzungen gleichzeitig aktiv sein können. Geben Sie Sitzungen umgehend mit output_pdf frei.

Leistung

Eine reine Textseite rendert problemlos innerhalb des Budgets, und die Ausgabe ist üblicherweise 1–3 KB groß. Für dieses Rezept lautet das Reproduzierbarkeitsprofil des Doppelrenderings structural. Das PDF trägt im Trailer eine /ID und Zeitstempel, die sich von Lauf zu Lauf ändern, sodass ein struktureller (normalisierter) Vergleich sachgerecht ist.

Sicherheitshinweise

Der Base64-Pfad hat keinen Dateisystem-Nebeneffekt. Der Dateiausgabe-Pfad hat dagegen einen, und er ist abgesichert – siehe den HITL-Abschnitt. Behandeln Sie das zurückgegebene Base64 als Dokumentinhalt, nicht als vertrauenswürdigen Kanal. Es sind genau die Bytes, die die Tools erzeugt haben.

Konformität

Aussage	Spezifikation	Klausel	reference_id
Ein Transport sendet eine Anfrage und empfängt eine Antwort, unabhängig vom Ergebnis.	PSR-18	§p2
Seiten werden über den Seitenbaum des Dokuments erreicht.	ISO 32000-2	§7.7.3

Dieses Rezept beschreibt, wie der Server Ausgaben erzeugt. Es erhebt keinen Anspruch auf Profilkonformität.

Kommerzieller Kontext

Nicht zutreffend – alle drei Tools sind Core.

Transportverfügbarkeit

Transport	Verfügbar	Hinweise
MCP (stdio)	Ja	Tool-Aufrufe werden auf MCP tools/call abgebildet.
REST	Ja	Jedes Tool ist eine REST-Operation; das Ergebnis ist der Antwortkörper.
gRPC	Ja	Jedes Tool ist ein unärer Aufruf.

Das Tool-Ergebnis ist über alle Transporte hinweg gleich; nur die Transporthülle unterscheidet sich. Ein nicht erfolgreiches Ergebnis ist nach wie vor eine normale Antwort, kein Transportfehler (PSR-18 §p2).

HITL-Risikostufe

Der Server ordnet jeden Tool-Aufruf einer Human-in-the-Loop-Risikoabstufung (HITL) zu: Sicher (0) → Vorsicht (1) → Prüfung (2) → Genehmigung erforderlich (3). create_pdf ist Sicher und add_text ist Vorsicht. output_pdf ist Genehmigung erforderlich, doch im Base64-Modus (ohne file_path) wird es auf Prüfung herabgestuft und läuft ohne menschliche Bestätigung. Beim Schreiben in eine Datei bleibt es bei Genehmigung erforderlich – siehe output-approval und die HITL-Risikostufen-Referenz.

JSON-Umschlag des Bestätigungstors

Dieses Rezept bleibt im Base64-Modus, daher gibt das Bestätigungstor den Erlaubnis-Umschlag zurück:

{ "allowed": true }

Der Challenge-Umschlag (allowed: false, mit einer challenge-Zeichenkette und einem einmaligen token) ist in output-approval dokumentiert.

Siehe auch

• Mehrseitiges Dokument
• Bildeinbettung
• Tool-Katalog
• HITL-Risikostufen