NextPDF Connect-snelstart

In een oogopslag

Op deze pagina voer je de kleinste bruikbare uitwisseling uit via beide transports: Model Context Protocol (MCP) en Representational State Transfer (REST). Elk verzoek gebruikt exact het wire-formaat dat de server implementeert. Je hebt geen software development kit (SDK) nodig.

Installeren

composer require nextpdf/server

Conceptueel overzicht

Het MCP-transport gebruikt JSON-RPC 2.0 via standaardinvoer en -uitvoer. Je moet de reeks in volgorde versturen. Verstuur eerst initialize. Verstuur vervolgens de notifications/initialized-bevestiging. Verstuur daarna tools/list en tools/call. De server leest één JSON-bericht per regel. Elke regel moet eindigen met een newline. De server schrijft één antwoord per regel.

Het REST-transport stelt dezelfde engine-mogelijkheden beschikbaar via Hypertext Transfer Protocol (HTTP)-bewerkingen. Eén stateless renderactie is één POST /api/v1/render met een geordende operations-array. De responsbody is het Portable Document Format (PDF)-bestand.

Codevoorbeeld — snelstart (MCP via stdio)

Start de server en pipe de handshake ernaartoe. Deze drie verzoeken gebruiken de geverifieerde methodenamen die de protocol-handler routeert:

./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

Het initialize-antwoord rapporteert de protocolversie 2025-06-18, de servernaam NextPDF Connect en een capabilities.nextpdf-blok. Dat blok bevat de live aantallen per niveau, de runtime-tool_count, de versie van het risicomodel en hitl_enabled: true. Het tools/list-antwoord toont exact de tools die voor deze installatie zijn geregistreerd. De notificatieregel levert opzettelijk geen antwoord op.

Roep nu een veilige tool aan. De tool diagnostic.doctor voert een alleen-lezen omgevingscontrole uit. Die heeft geen document of bevestiging nodig:

./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

Codevoorbeeld — snelstart (REST)

Start de REST-server en render daarna een PDF van één regel. De server vereist een application programming interface (API)-sleutel voor elk endpoint dat geen health-endpoint is, dus definieer er eerst een:

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

Verstuur in een tweede shell een renderverzoek. De body is een RenderRequest. Het verzoek bevat een geordende operations-array met getypeerde bewerkingen.

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

Een 200-responsbody is de PDF (Content-Type: application/pdf) die wordt weggeschreven naar hello.pdf. Health-probes hebben geen sleutel nodig:

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

Randgevallen en valkuilen

De volgorde van de handshake is belangrijk. De protocol-handler behandelt een bericht zonder id als een notificatie en retourneert niets. Verstuur initialize met een id, daarna de initialized-notificatie, en vervolgens je verzoeken die een id bevatten.
Een hergebruikte verzoek-id wordt gededupliceerd. De handler slaat recente antwoorden op in een circulaire buffer met 64 entries. Voor een dubbele id retourneert hij het gecachte antwoord zonder de tool opnieuw uit te voeren. Gebruik nieuwe id’s.
Een tool met hoog risico reageert met een challenge, niet met een resultaat. Als je output_pdf met een file_path aanroept, retourneert de tool een bevestigings-challenge in plaats van de bewerking uit te voeren. Roep de tool opnieuw aan met de uitgegeven _confirmation_token. De base64-uitvoermodus, zonder file_path, vereist geen bevestiging. Zie /connect/hitl-risk-niveaus/.
Een ongeautoriseerd REST-verzoek krijgt 401. Bij een ontbrekende of misvormde Authorization: Bearer-header retourneert de server een problem-details-body met een WWW-Authenticate: Bearer-header. De /healthz- en /readyz-probes zijn de enige anonieme endpoints.

Prestaties

Beide snelstart-paden gebruiken één enkel verzoek. Bij het REST-pad komen bij het eerste verzoek na rr serve ook de cold-startkosten van de RoadRunner-workerpool kijken. Latere verzoeken hergebruiken warme workers.

Opmerkingen over beveiliging

De npk_live_-sleutel hierboven is een wegwerp-demowaarde. Genereer echte sleutels met voldoende entropie, sla ze buiten versiebeheer op en gebruik bij voorkeur de bestandsgebaseerde sleutelopslag voor rotatie. Het MCP-stdio-transport heeft geen API-sleutel omdat het een lokaal subproces is dat binnen het MCP-transportmodel wordt vertrouwd door de client die het start. Zie /connect/security-and-operations/.

Conformiteit

De getoonde wire-formaten komen overeen met de geïmplementeerde MCP-revisie 2025-06-18 en het OpenAPI 3.1 REST-contract. Normatieve protocol- en authenticatiecitaten zijn vastgelegd op /transports/mcp/, /transports/rest/ en /connect/security-and-operations/.

Zie ook

/transports/mcp/ — de volledige MCP-transportreferentie
/transports/rest/ — de volledige REST-transportreferentie en OpenAPI-weergave
/connect/tool-catalog/ — welke tools tools/list retourneert en waarom
/connect/hitl-risk-niveaus/ — hoe een bevestigings-challenge eruitziet
/connect/configuration/ — de catalogus beperken en de server afstemmen