Szybki start NextPDF Connect

W skrócie

Ta strona prowadzi przez najmniejszą użyteczną wymianę z użyciem obu transportów: Model Context Protocol (MCP) oraz Representational State Transfer (REST). Każde żądanie używa dokładnie tego formatu przesyłania, który zaimplementowano na serwerze. Nie jest potrzebny zestaw narzędzi programistycznych (SDK).

Instalacja

composer require nextpdf/server

Przegląd koncepcyjny

Transport MCP korzysta z JSON-RPC 2.0 przez standardowe wejście i wyjście. Sekwencję trzeba wysłać w określonej kolejności. Najpierw wyślij initialize. Potem wyślij potwierdzenie notifications/initialized, a następnie tools/list oraz tools/call. Serwer odczytuje jeden komunikat JSON z każdego wiersza. Każdy wiersz musi kończyć się znakiem nowego wiersza. Serwer zapisuje jedną odpowiedź w wierszu.

Transport REST udostępnia te same możliwości silnika w postaci operacji Hypertext Transfer Protocol (HTTP). Pojedyncze bezstanowe renderowanie odpowiada jednemu żądaniu POST /api/v1/render z uporządkowaną tablicą operacji. Treścią odpowiedzi jest plik w formacie Portable Document Format (PDF).

Przykład kodu — szybki start (MCP przez stdio)

Uruchom serwer i przekieruj do niego potokiem sekwencję uzgadniania połączenia. Te trzy żądania używają zweryfikowanych nazw metod, które obsługa protokołu przekazuje dalej:

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

Odpowiedź initialize zgłasza wersję protokołu 2025-06-18, nazwę serwera NextPDF Connect oraz blok capabilities.nextpdf. Blok ten zawiera bieżące liczby narzędzi dla poszczególnych poziomów, środowiskową wartość tool_count, wersję modelu ryzyka oraz hitl_enabled: true. Odpowiedź tools/list wymienia dokładnie te narzędzia, które zarejestrowano dla tej instalacji. Wiersz powiadomienia celowo nie generuje żadnej odpowiedzi.

Teraz wywołaj bezpieczne narzędzie. Narzędzie diagnostic.doctor wykonuje kontrolę środowiska tylko do odczytu. Nie wymaga dokumentu ani potwierdzenia:

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

Przykład kodu — szybki start (REST)

Uruchom serwer REST, a następnie wyrenderuj jednowierszowy plik PDF. Serwer wymaga klucza interfejsu programistycznego aplikacji (API) dla każdego punktu końcowego innego niż kontrola stanu, więc najpierw zdefiniuj taki klucz:

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

W drugiej powłoce wyślij żądanie renderowania. Treść żądania to obiekt RenderRequest. Żądanie zawiera uporządkowaną tablicę operations z operacjami określonego typu.

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

Treścią odpowiedzi 200 jest plik PDF (Content-Type: application/pdf) zapisany do hello.pdf. Sondy kontroli stanu nie wymagają klucza:

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

Przypadki brzegowe i pułapki

• Kolejność uzgadniania połączenia ma znaczenie. Obsługa protokołu traktuje komunikat bez id jako powiadomienie i nie zwraca niczego. Wyślij initialize z polem id, następnie powiadomienie initialized, a potem żądania zawierające pole id.

• Powtórzony identyfikator id żądania jest deduplikowany. Mechanizm obsługi przechowuje ostatnie odpowiedzi w buforze cyklicznym o 64 wpisach. W przypadku zduplikowanego id zwraca odpowiedź z pamięci podręcznej bez ponownego uruchamiania narzędzia. Używaj nowych identyfikatorów żądań.

• Narzędzie wysokiego ryzyka odpowiada żądaniem potwierdzenia, a nie wynikiem. Wywołanie output_pdf z file_path zwraca żądanie potwierdzenia zamiast wykonać operację. Wywołaj narzędzie ponownie z otrzymanym _confirmation_token. Tryb danych wyjściowych base64, bez file_path, nie wymaga potwierdzenia. Zobacz /connect/hitl-risk-tiers/.

• Nieautoryzowane żądanie REST otrzymuje 401. Brakujący lub nieprawidłowy nagłówek Authorization: Bearer powoduje zwrócenie treści ze szczegółami problemu wraz z nagłówkiem WWW-Authenticate: Bearer. Sondy /healthz i /readyz to jedyne anonimowe punkty końcowe.

Wydajność

Obie ścieżki szybkiego startu używają pojedynczego żądania. Ścieżka REST ponosi również koszt zimnego startu puli procesów roboczych RoadRunner przy pierwszym żądaniu po rr serve. Kolejne żądania ponownie wykorzystują już rozgrzane procesy robocze.

Uwagi dotyczące bezpieczeństwa

Powyższy klucz npk_live_ to jednorazowa wartość demonstracyjna. Generuj prawdziwe klucze o wystarczającej entropii, przechowuj je poza systemem kontroli wersji i przy rotacji korzystaj przede wszystkim z plikowego magazynu kluczy. Transport MCP przez stdio nie używa klucza API, ponieważ jest lokalnym podprocesem, któremu klient uruchamiający ufa zgodnie z modelem transportu MCP. Zobacz /connect/security-and-operations/.

Zgodność

Pokazane formaty przesyłania odpowiadają zaimplementowanej rewizji MCP 2025-06-18 oraz kontraktowi REST OpenAPI 3.1. Normatywne odniesienia dotyczące protokołu i uwierzytelniania zamieszczono na stronach /transports/mcp/, /transports/rest/ oraz /connect/security-and-operations/.

Zobacz też

• /transports/mcp/ — pełny opis transportu MCP
• /transports/rest/ — pełny opis transportu REST oraz renderowania OpenAPI
• /connect/tool-catalog/ — które narzędzia zwraca tools/list i dlaczego
• /connect/hitl-risk-tiers/ — jak wygląda żądanie potwierdzenia
• /connect/configuration/ — ograniczanie katalogu i dostrajanie serwera