Rozwiązywanie problemów z NextPDF Connect

W skrócie

Większość awarii pasuje do jednego z pięciu wzorców: nieprawidłowy handshake JavaScript Object Notation Remote Procedure Call (JSON-RPC), brakujący klucz application programming interface (API), narzędzie niezainstalowane w danej warstwie, brak odpowiedzi na wyzwanie potwierdzenia albo magazyn niewspółdzielony przez procesy robocze. Każdy wzorzec ma własną sygnaturę.

Instalacja

composer require nextpdf/server

Przegląd koncepcyjny

Transport Model Context Protocol (MCP) zwraca obiekty błędów JSON-RPC 2.0 ze standardowymi kodami. Transport Representational State Transfer (REST) zwraca dokumenty problem-details zgodne z Request for Comments (RFC) 7807. Każdy dokument zawiera adres URL type identyfikujący dany stan. Przy problemach ze środowiskiem zacznij od narzędzi diagnostycznych (diagnostic.doctor, diagnostic.capabilities). Te narzędzia zawsze znajdują się w katalogu core.

Powierzchnia API

Kody błędów JSON-RPC protokołu MCP

Kod	Nazwa	Przyczyna
`-32700`	Błąd parsowania	Wiersz nie zawierał poprawnego JSON
`-32600`	Nieprawidłowe żądanie	Komunikat jest niezgodny z JSON-RPC 2.0 (brak `jsonrpc`/`method`)
`-32601`	Nie znaleziono metody	Metoda jest inna niż `initialize`, `tools/list`, `tools/call`
`-32602`	Nieprawidłowe parametry	Brak `params.name` w `tools/call`
`-32603`	Błąd wewnętrzny	Narzędzie zgłosiło wyjątek podczas wykonywania

Narzędzie, które kończy się niepowodzeniem w sposób kontrolowany, nie używa tych kodów. Zamiast tego zwraca poprawną odpowiedź JSON-RPC z isError: true w wyniku i tekstowym wyjaśnieniem, np. że narzędzie jest nieznane, wyłączone przez zasady albo otrzymało nieprawidłowe argumenty.

Typy problem-details REST

HTTP	Slug `type`	Przyczyna
`401`	`unauthorized`	Brakujący/nieprawidłowy/wyłączony/wygasły klucz API
`403`	`capability-denied`	Warstwa klucza nie ma uprawnień do tej operacji
`413`	`payload-too-large` / `tier-payload-exceeded`	Treść przekracza globalny limit lub limit warstwy
`422`	`validation-failed`	Treść żądania nie przeszła walidacji schematu
`429`	`ip-rate-exceeded` / `client-rate-exceeded`	Przekroczono limit szybkości
`404`	`not-found`	Nieznana trasa lub identyfikator job/session
`504`	(przekroczenie limitu czasu żądania)	Operacja przekroczyła limit czasu warstwy

Przykład kodu — szybki start

Uruchom kontrolę kondycji środowiska. Dokument ani potwierdzenie nie są wymagane:

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"diag","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 — produkcja

Zanim zaczniesz diagnozować „brakujące narzędzie”, potwierdź, które narzędzia udostępnia to wdrożenie:

./vendor/bin/generate-skills --dry-run --list-tools

albo dla działającego serwera REST:

curl -sS http://localhost:8080/api/v1/capabilities \
  -H "Authorization: Bearer $NEXTPDF_KEY"

Przypadki brzegowe i pułapki

„Nieznane narzędzie” dla narzędzia Pro/Enterprise. Pakiet tego narzędzia nie jest zainstalowany. Rejestr sprawdza klasy dostawców i pomija nieobecne warstwy bez ostrzeżenia. To zachowanie oczekiwane, a nie błąd. Zainstaluj nextpdf/premium razem z serwerem albo użyj narzędzia core. Komunikat błędu zawiera ścieżkę instalacji.
Narzędzie skonfigurowane w enabled_tools nie pojawia się. Mechanizm stosuje część wspólną listy dozwolonych i wykrytych narzędzi. Nie da się w ten sposób dodać narzędzia, którego rejestr nie znalazł. Sprawdź instalację warstwy oraz wszystkie bramki środowiskowe. Na przykład parse_pdf jest włączane opcjonalnie przez NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED.
tools/call zwróciło tekst z prośbą o token. To wyzwanie potwierdzenia, a nie błąd. Wywołaj narzędzie ponownie w ciągu 300 sekund z _confirmation_token ustawionym na wydany token. Zobacz /connect/hitl-risk-tiers/.
Wiersz powiadomienia nie wygenerował żadnych danych wyjściowych. To prawidłowe zachowanie. Komunikat JSON-RPC bez id jest powiadomieniem, a procedura obsługi niczego nie zwraca. Aby otrzymywać odpowiedzi, wysyłaj żądania z id.
Ponownie użyty identyfikator żądania zwrócił nieaktualną odpowiedź. Procedura obsługi eliminuje duplikaty według identyfikatora żądania, używając bufora o 64 wpisach. Używaj nowego identyfikatora dla każdego logicznego żądania.
Limity szybkości działają niespójnie między procesami roboczymi. Magazyn w pamięci jest przypisany do pojedynczego procesu roboczego. Aby współdzielić liczniki, ustaw NEXTPDF_REDIS_HOST i zainstaluj ext-redis. Zobacz /connect/deployment/.
Dokumenty znikają między żądaniami. Magazyn dokumentów w pamięci jest przypisany do pojedynczego procesu roboczego i ma ograniczony czas życia (document_ttl, domyślnie 1800 s). Aby zachować ciągłość dokumentów między procesami roboczymi, użyj magazynu opartego na Redis, punktów końcowych sesji albo wykonaj pełny zestaw operacji w jednym synchronicznym renderowaniu.
Serwer powrócił do trybu w pamięci pomimo konfiguracji Redis. Serwer REST automatycznie przełącza się na tryb awaryjny, jeśli połączenie z Redis nie powiedzie się podczas uruchamiania. Sprawdź dostępność Redis i potwierdź, że ext-redis jest obecne w działającym obrazie. Nie zakładaj, że Redis jest używany, dopóki tego nie zweryfikujesz.
Serwer odmawia uruchomienia z błędem konfiguracji. Wpis risk_level_overrides próbował obniżyć poziom narzędzia ApprovalRequired. Loader celowo to odrzuca. Usuń obniżenie poziomu; przesłonięcia mogą jedynie podnosić ryzyko.

Wydajność

Jeśli pod obciążeniem renderowanie działa wolno, sprawdź, czy pula procesów roboczych nie jest nasycona. Sprawdź punkt końcowy metryk RoadRunner. Następnie przenieś długie renderowania na ścieżkę zadań asynchronicznych, aby nie blokowały procesów roboczych. Zobacz /connect/production-usage/.

Uwagi dotyczące bezpieczeństwa

Nie obchodź błędu 401 przez wystawienie nieuwierzytelnionego transportu MCP do sieci; całkowicie usuwa to uwierzytelnianie. Zamiast tego napraw klucz API. Nie zwiększaj szczegółowości dzienników w celu sprawdzenia argumentów narzędzia we współdzielonym środowisku; treści argumentów mogą być poufne. Zobacz /connect/security-and-operations/.

Zgodność

Ta strona zawiera wskazówki operacyjne. Cytacje dotyczące protokołu i bezpieczeństwa znajdują się na stronach /transports/mcp/, /transports/rest/ oraz /connect/security-and-operations/.

Zobacz także

/connect/tool-catalog/ — co zawiera katalog core i dlaczego liczba narzędzi się zmienia
/connect/hitl-risk-tiers/ — szczegóły wyzwań potwierdzenia
/connect/deployment/ — Redis, pule procesów roboczych i współdzielenie magazynu
/connect/security-and-operations/ — awarie uwierzytelniania i postawa bezpieczeństwa