NextPDF Connect — przegląd serwera

W skrócie

NextPDF Connect to pakiet nextpdf/server: długodziałająca usługa, która udostępnia silnik NextPDF PDF 2.0 agentom AI oraz klientom HTTP. Wykorzystuje trzy transporty: Model Context Protocol (MCP) przez stdio, interfejs API REST oraz gRPC. Wszystkie trzy transporty korzystają z jednego rejestru narzędzi i jednej bramki potwierdzeń z udziałem człowieka w pętli (HITL).

Instalacja

composer require nextpdf/server

W Composerze obowiązuje ograniczenie nextpdf/core: ^3.0 z php: >=8.4 <9.0. Pełna procedura znajduje się na stronie /connect/install/. Opisano tam również dwa opcjonalne dodatki: rozszerzenie ext-redis oraz pakiet nextpdf/premium.

Przegląd koncepcyjny

nextpdf/server przekształca niezależny od frameworka rdzeń NextPDF w warstwę usługową. Nie implementuje ponownie generowania plików PDF. Zamiast tego opakowuje każdą funkcję silnika w nazwane narzędzie z własnym schematem, a następnie udostępnia ten katalog przez kilka protokołów sieciowych.

Całą konstrukcję opierają trzy koncepcje:

Rejestr narzędzi. NextPDF\Server\ToolRegistry wykrywa i rejestruje narzędzia podczas uruchamiania. Podstawowy zestaw jest dostarczany wraz z pakietem i zawsze dostępny. Dostawcy Pro i Enterprise rejestrują dodatkowe narzędzia, ale tylko wtedy, gdy zainstalowane są odpowiednie pakiety. Liczba udostępnionych narzędzi jest cechą wdrożenia ustalaną w czasie wykonywania, a nie stałą wartością. Zobacz /connect/tool-catalog/.
Transporty. Ten sam rejestr jest udostępniany na trzy sposoby. MCP działa przez stdio dla lokalnych klientów AI. REST działa przez potok middleware PSR-15 na puli procesów roboczych RoadRunner dla klientów sieciowych. gRPC działa na procesie roboczym gRPC w Spiral RoadRunner dla typowanych lub strumieniowych klientów. Każdy transport jest osobnym procesem z własnym punktem wejścia. Zobacz /transports/mcp/, /transports/rest/ oraz /transports/grpc/.
Bramka potwierdzeń. Każde narzędzie deklaruje poziom ryzyka. Narzędzie z najwyższym poziomem ryzyka wymaga przed wykonaniem jednoznacznego potwierdzenia przez człowieka. Bramka wystawia jednorazowy token wyzwania. Agent musi przekazać token człowiekowi, a następnie ponownie wywołać narzędzie z tym tokenem. Zobacz /connect/hitl-risk-tiers/.

Poniższy diagram pokazuje, jak jeden rejestr obsługuje trzy transporty. Widać na nim również, gdzie na ścieżce żądania znajduje się bramka potwierdzeń.

NextPDF Connect component architecture

Pakiet jest udostępniany na licencji Apache-2.0, zgodnie z nextpdf/core. Zaimplementowana wersja protokołu MCP to rewizja wersjonowana datą 2025-06-18. Interfejs REST opisuje dokument OpenAPI 3.1. Interfejs gRPC opisuje pakiet Protocol Buffers nextpdf.connect.v1.

Powierzchnia API

Publiczne punkty wejścia to trzy klasy serwerów. Każda z nich ma nakładkę interfejsu wiersza poleceń (CLI):

Punkt wejścia	Klasa	Transport
`bin/nextpdf-mcp`	`NextPDF\Server\Mcp\McpServer`	MCP przez stdio
`bin/nextpdf-server`	`NextPDF\Server\Http\HttpServer`	REST przez RoadRunner HTTP
`bin/nextpdf-grpc`	`NextPDF\Server\Grpc\GrpcServer`	gRPC przez RoadRunner gRPC
`bin/generate-skills`	`NextPDF\Server\Skills\SkillsDumper`	Eksport katalogu narzędzi

Każda z metod McpServer::create(), HttpServer::create() oraz GrpcServer::create() buduje w pełni skonfigurowany serwer na podstawie środowiska i konfiguracji. Rejestr, magazyn dokumentów, zasady bezpieczeństwa oraz bramka potwierdzeń to koncepcje współdzielone przez wszystkie trzy serwery.

Przykład kodu — szybki start

Do uruchomienia minimalnego serwera MCP wystarczy jedno polecenie. Nie trzeba pisać żadnego kodu spajającego w PHP:

./vendor/bin/nextpdf-mcp

Serwer odczytuje żądania JSON-RPC ze standardowego wejścia i zapisuje odpowiedzi na standardowe wyjście. Gotowy do uruchomienia przebieg wymiany initialize oraz tools/list, wraz z odpowiadającym mu żądaniem REST, znajdziesz na stronie /connect/quickstart/.

Przypadki brzegowe i pułapki

Liczba narzędzi nie wynosi 33 ani żadnej innej stałej wartości. Serwer zlicza narzędzia w czasie wykonywania za pomocą count(ToolRegistry::all()), po zastosowaniu zasad i wykryciu poziomu. Dokumentacja podająca stałą sumę jest nieaktualna. Aby uzyskać miarodajną liczbę, odpytaj działający serwer. Użyj odpowiedzi initialize protokołu MCP lub punktu końcowego REST /api/v1/capabilities.

Liczba udostępnionych narzędzi zależy od zainstalowanych pakietów i aktywnych zasad. Odczytaj ją z działającego serwera w czasie wykonywania. Liczba wpisana na stałe w kodzie lub dokumentacji szybko stanie się nieaktualna.
Brak pakietu Pro lub Enterprise nie jest błędem. Rejestr sprawdza obecność klas dostawców za pomocą class_exists(), a następnie bez zgłaszania błędu pomija każdy brakujący poziom. Wdrożenie wyłącznie w wersji open source uruchamia się i normalnie udostępnia swój katalog podstawowy.
Trzy transporty nie współdzielą procesu. Uruchomienie serwera MCP nie uruchamia serwera REST ani serwera gRPC. To samo dotyczy odwrotnej sytuacji. Połączone wdrożenie uruchamia nadzorcę RoadRunner z konfiguracją, która startuje obie pule procesów roboczych: pulę HTTP i pulę gRPC. Zobacz /connect/deployment/.

Wydajność

Każdy transport opiera się na procesach roboczych. Jeden proces roboczy obsługuje jedno żądanie naraz. Serwery REST i gRPC działają na pulach procesów roboczych RoadRunner, a konfiguracja określa rozmiar puli. Wartością domyślną są cztery procesy robocze HTTP. Nadzorca RoadRunner ogranicza zużycie pamięci każdego procesu roboczego. Sekcja front-matter performance_budget na tej stronie opisuje budżet zimnego startu i wykrywania. Nie jest to cel dla pojedynczego żądania. Większość kosztu żądania wynika z bazowej operacji silnika.

Uwagi dotyczące bezpieczeństwa

Wszystkie transporty sieciowe uwierzytelniają się za pomocą tokena bearer z kluczem API. Transport MCP stdio jest lokalnym podprocesem, któremu ufa uruchamiający go klient, zgodnie z modelem transportu MCP. Narzędzia wysokiego ryzyka pozostają zabezpieczone potwierdzeniem przez człowieka w każdym transporcie. Pełny model zagrożeń, model uwierzytelniania oraz konfigurację zabezpieczeń transportu znajdziesz na stronie /connect/security-and-operations/.

Zgodność

Ta strona przedstawia wyłącznie twierdzenia architektoniczne. Normatywne odwołania do protokołu i bezpieczeństwa są zakotwiczone na stronach opisujących dane zachowanie: /connect/security-and-operations/, /transports/mcp/, /transports/rest/ oraz /transports/grpc/. Punktem odniesienia dla cyklu życia MCP jest oficjalna specyfikacja na modelcontextprotocol.io (rewizja 2025-06-18). Strony transportów zapisują to odniesienie wraz z jego adresem URL, ponieważ specyfikacja MCP nie należy do korpusu standardów objętego ograniczeniami.

Kontekst komercyjny

Katalog podstawowy jest kompletny w zakresie tworzenia, inspekcji i diagnostyki dokumentów. Narzędzia do podpisywania, redakcji, certyfikacji zgodności i analizy śledczej pojawiają się tylko wtedy, gdy obok serwera zainstalowano nextpdf/premium. Jest to granica wynikająca z pakietów, a nie komunikat sprzedażowy w czasie działania. Serwer nigdy nie emituje treści marketingowych.

Zobacz także

/connect/install/ — instalacja i opcjonalne pakiety
/connect/quickstart/ — pierwsza wymiana MCP i REST gotowa do uruchomienia
/connect/tool-catalog/ — zweryfikowany podstawowy zestaw narzędzi oraz zależność liczby narzędzi od czasu wykonywania
/connect/hitl-risk-tiers/ — bramka potwierdzeń i model ryzyka
/transports/mcp/, /transports/rest/, /transports/grpc/ — konfiguracja poszczególnych transportów
/connect/security-and-operations/ — uwierzytelnianie, bezpieczeństwo transportu, model zagrożeń
/connect/deployment/ — RoadRunner, Docker oraz wdrożenie z połączonymi transportami