Integracja NextPDF Connect

W skrócie

Zintegruj NextPDF Connect, uruchamiając usługę jako serwer. Nie podpinaj biblioteki do aplikacji hosta. Wybierz transport, a następnie skonfiguruj uwierzytelnianie dla każdego transportu sieciowego. Narzędzia silnika pozostają za bramką potwierdzenia.

Instalacja

composer require nextpdf/server

Ograniczenie Composera ma postać nextpdf/core: ^3.0 z php: >=8.4 <9.0. Opcjonalną konfigurację ext-redis i nextpdf/premium opisano w /connect/install/.

Przegląd koncepcyjny

Pakiet działa jako samodzielna usługa. Nie rejestruj dostawcy usług, pakietu ani modułu kontenera w frameworku docelowym. Punktem integracji jest uruchamiany proces. Każdy transport ma własny punkt wejścia i uruchamia się niezależnie. Zobacz /connect/boot-and-discovery/.

Powierzchnia API

Punkt wejścia	Transport	Profil
bin/nextpdf-mcp	MCP przez stdio	(brak — bezpośredni podproces)
bin/nextpdf-server	REST przez RoadRunner HTTP	.rr.yaml
bin/nextpdf-grpc	gRPC przez RoadRunner gRPC	.rr.grpc.yaml
oba transporty sieciowe	REST + gRPC	.rr.full.yaml

Uruchamianie i automatyczne wykrywanie

Rejestr zawsze wykrywa poziom core. Następnie dodaje dostawców Pro i Enterprise, gdy ich klasy zostaną odnalezione, a po nich dołączonych dostawców abstrakcyjnego drzewa składniowego (AST) i mutacji objętych bramkami środowiskowymi. Lista dozwolonych narzędzi enabled_tools filtruje wszystkich z nich, dzięki czemu udostępniony katalog odpowiada temu wdrożeniu. Zobacz /connect/tool-catalog/ oraz /connect/boot-and-discovery/.

Powiązania kontenera

Brak. Każda fabryka serwera jawnie buduje własny graf obiektów. Wstrzykiwalne punkty zaczepienia służą do testów, a nie do podpinania aplikacji.

Publikowanie konfiguracji

Serwer MCP przyjmuje opcjonalny plik YAML (--config=PATH, sekcja nextpdf_mcp) oraz nadpisania środowiskowe NEXTPDF_MCP_*. Serwery REST i gRPC odczytują zmienne środowiskowe NEXTPDF_*. Szczegóły znajdziesz w /connect/configuration/.

Dostępność transportów (MCP / REST / gRPC)

Wszystkie trzy transporty obsługują ten sam rejestr:

• MCP — lokalny podproces, JSON-RPC 2.0 przez stdio, bez klucza API, rewizja MCP 2025-06-18. Zobacz /transports/mcp/.
• REST — pula procesów roboczych RoadRunner HTTP, kontrakt OpenAPI 3.1, klucz API typu bearer, trasy objęte bramką poziomów. Zobacz /transports/rest/.
• gRPC — pula procesów roboczych RoadRunner gRPC, usługa Protobuf nextpdf.connect.v1, strumieniowanie RPC po stronie serwera, uwierzytelnianie bearer w metadanych oraz wzajemny TLS w profilu połączonym. Zobacz /transports/grpc/.

Transport jest „dostępny”, gdy działa jego punkt wejścia lub profil RoadRunner. Transporty nie uruchamiają się nawzajem automatycznie.

Poziom ryzyka HITL

Każde narzędzie deklaruje jeden z czterech poziomów ryzyka: safe, caution, review, approval_required. Narzędzia na poziomie approval_required nie uruchamiają się przy pierwszym wywołaniu. Bramka potwierdzenia wystawia jednorazowy token wyzwania, który musi zostać autoryzowany przez człowieka. Nadpisanie konfiguracji może jedynie podnieść ryzyko narzędzia, nigdy nie może obniżyć poziomu narzędzia approval_required. Model obowiązuje tak samo w każdym transporcie obsługującym narzędzia. Zobacz /connect/hitl-risk-tiers/.

Koperta JSON bramki potwierdzenia

Sprawdzenie bramki zwraca jeden z dwóch kształtów JSON. Przypadek dozwolony:

{ "allowed": true }

Wyzwanie:

{
  "allowed": false,
  "challenge": "<human-readable text naming the operation, its description, an overwrite warning when applicable, and the re-invocation instruction>",
  "token": "confirm_<nonce>"
}

Token wiąże nazwę narzędzia, losowy nonce i 300-sekundowy TTL, a nie argumenty. Aby kontynuować, wywołujący ponownie wywołuje to samo narzędzie z argumentem _confirmation_token ustawionym na wystawiony token. Wyzwanie jest zwykłym tekstem instruktażowym wraz z tokenem; nie jest kopertą podpisaną kryptograficznie. Zobacz /connect/hitl-risk-tiers/.

Test dymny usługi

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

Polecenie uruchamia rejestr i wykrywanie poziomów, a następnie wypisuje udostępnione narzędzia bez obsługiwania ruchu. Użyj go, aby potwierdzić, że integracja jest podpięta, i sprawdzić, jaki katalog tworzy ta instalacja.

Przypadki brzegowe i pułapki

• Brak punktów zaczepienia frameworka. Nie szukaj dostawcy usług ani pakietu. Działający proces jest integracją.
• Brakujący poziom nie jest błędem. Instalacja zawierająca tylko core uruchamia się i obsługuje własny katalog core.
• Transporty sieciowe wymagają klucza. Tylko /healthz i /readyz (REST) oraz health RPC (gRPC) są anonimowe.

Wydajność

Kosztem uruchomienia jest skanowanie rejestru i wykrywanie poziomów, wykonywane raz na proces. Kosztem pojedynczego żądania jest operacja silnika. Dobierz wielkość pul procesów roboczych RoadRunner do obserwowanego opóźnienia renderowania. Zobacz /connect/production-usage/.

Uwagi dotyczące bezpieczeństwa

Transporty sieciowe uwierzytelniają się kluczem bearer npk_live_, weryfikowanym w stałym czasie; bramka wymusza potwierdzenie przez człowieka dla operacji destrukcyjnych niezależnie od transportu. Terminuj TLS przed REST i używaj wzajemnego TLS dla gRPC w niezaufanych sieciach. Zobacz /connect/security-and-operations/.

Zgodność

Cytacje dotyczące protokołu i bezpieczeństwa przypięto na stronach /transports/mcp/, /transports/rest/, /transports/grpc/ oraz /connect/security-and-operations/.

Kontekst komercyjny

Zainstaluj nextpdf/premium obok serwera, aby zarejestrować dodatkowe narzędzia Pro i Enterprise w tym samym działającym serwerze. Nie bierze w tym udziału żaden osobny proces.

Zobacz także

• /connect/overview/ — architektura
• /connect/quickstart/ — pierwsza wymiana, którą można uruchomić
• /transports/mcp/ · /transports/rest/ · /transports/grpc/ — dokumentacja poszczególnych transportów
• /connect/hitl-risk-tiers/ — szczegóły bramki potwierdzenia
• /connect/tool-catalog/ — katalog zależny od środowiska uruchomieniowego
• /connect/security-and-operations/ — uwierzytelnianie i model zagrożeń