NextPDF Connect — transport MCP

W skrócie

Transport Model Context Protocol (MCP) uruchamia bin/nextpdf-mcp jako lokalny podproces. Komunikacja odbywa się w protokole JSON-RPC 2.0 przez standardowe wejście i wyjście. Serwer implementuje wersję MCP 2025-06-18.

Instalacja

composer require nextpdf/server

Przegląd koncepcyjny

W modelu stdio MCP klient uruchamia serwer w formie podprocesu. Klient wymienia komunikaty JSON-RPC rozdzielane znakami nowej linii: po jednym komunikacie w wierszu, bez osadzonych znaków nowej linii, w kodowaniu UTF-8. Serwer zapisuje na standardowe wyjście wyłącznie prawidłowe komunikaty MCP, a logi kieruje na standardowe wyjście błędów. Implementacja kieruje wyjście rejestratora audytu na standardowe wyjście błędów, dzięki czemu wiersze logów nigdy nie uszkadzają strumienia protokołu. Oficjalna specyfikacja MCP w wersji 2025-06-18 definiuje to ramkowanie. Specyfikacja ta nie wchodzi w skład bramkowanego korpusu standardów, dlatego jest cytowana jako adres URL: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports.

NextPDF Connect implementuje transport stdio. Specyfikacja MCP definiuje także transport Streamable HTTP. Zgodnie ze specyfikacją klienci powinni obsługiwać stdio zawsze, gdy to możliwe, a serwer może implementować wyłącznie stdio. Aby uzyskać dostęp sieciowy do tych samych narzędzi, skorzystaj zamiast tego z transportu REST lub gRPC; zobacz /transports/rest/ oraz /transports/grpc/.

Powierzchnia API

Metody

Metoda	Zachowanie
`initialize`	Zwraca wersję protokołu, możliwości oraz informacje o serwerze
`notifications/initialized`	Powiadomienie (bez `id`); przyjmowane bez odpowiedzi
`tools/list`	Wymienia zarejestrowane narzędzia z opcjonalnym filtrem `params.category`
`tools/call`	Wykonuje narzędzie określone przez `params.name` z argumentami `params.arguments`

Każda pozostała metoda zwraca błąd „nie znaleziono metody” (-32601). Dla komunikatu, który nie jest prawidłowym JSON-RPC 2.0, zwracany jest błąd „nieprawidłowe żądanie” (-32600); dla danych wejściowych, których nie da się sparsować, zwracany jest błąd parsowania (-32700). Zduplikowane id żądania powoduje zwrócenie buforowanej wcześniejszej odpowiedzi z 64-elementowego bufora, bez ponownego wykonania.

Odpowiedź initialize

Wynik initialize zawiera protocolVersion 2025-06-18, serverInfo.name: NextPDF Connect oraz obiekt capabilities. Oprócz standardowej możliwości tools serwer dodaje blok capabilities.nextpdf:

tiers — aktualna liczba zarejestrowanych narzędzi w podziale na poziomy (core / pro / enterprise).
tool_count — łączna liczba zarejestrowanych narzędzi, obliczana w czasie wykonywania.
risk_model_version — wersja modelu ryzyka wymuszana przez serwer.
hitl_enabled — true; bramka potwierdzenia jest włączona.

tool_count jest miarodajną wartością dla tego wdrożenia. Ustalana jest w czasie wykonywania, nie jest udokumentowaną stałą; zobacz /connect/tool-catalog/.

Przykład kodu — szybki start

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"client","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
EOF

Przykład kodu — produkcja

Filtr kategorii zawęża katalog do jednej domeny:

./vendor/bin/nextpdf-mcp --config=/etc/nextpdf/nextpdf-mcp.yaml <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"client","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{"category":"diagnostic"}}
EOF

Wartości kategorii odpowiadają kategorii zadeklarowanej dla każdego narzędzia (na przykład document, diagnostic).

Przypadki brzegowe i pułapki

Brak klucza API. Transport stdio nie udostępnia nasłuchu sieciowego ani tokena bearer. Granicę procesu w systemie operacyjnym traktuj jako granicę zaufania, zgodnie z modelem stdio MCP. Nie mostkuj tego transportu do sieci.
Wyzwania potwierdzenia są przesyłane w ramach kanału. Narzędzie ApprovalRequired zwraca pomyślną odpowiedź JSON-RPC. Treść odpowiedzi obejmuje tekst wyzwania oraz jednorazowy token, a nie błąd. Zobacz /connect/hitl-risk-tiers/.
Powiadomienia są ciche. Komunikat bez id nie generuje odpowiedzi. Uzgadnianie połączenia obejmuje initialize (z id), następnie powiadomienie initialized, a potem wywołania zawierające id.

Wydajność

Serwer MCP działa jako pojedynczy proces i obsługuje po jednym żądaniu naraz przez potoki. Nie występuje sieciowy round trip; o opóźnieniu decyduje przede wszystkim operacja wykonywana przez bazowy silnik.

Uwagi dotyczące bezpieczeństwa

Transport dziedziczy zaufanie klienta, który go uruchamia. Utrzymuj podproces lokalnie. Narzędzia wysokiego ryzyka nadal wymagają potwierdzenia przez człowieka, mimo że nie ma klucza API. Zobacz /connect/security-and-operations/.

Zgodność

Ramkowanie stdio oraz zachowanie initialize/lifecycle są zgodne z oficjalną specyfikacją Model Context Protocol w wersji 2025-06-18:

Transporty: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports
Cykl życia: https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle

Specyfikacja MCP nie znajduje się w bramkowanym korpusie standardów, dlatego nie ma reference_id; powyższe oficjalne adresy URL stanowią wiążące źródła cytowania.

Kontekst komercyjny

tools/list zwraca narzędzia Pro i Enterprise tylko wtedy, gdy wraz z serwerem zainstalowano nextpdf/premium. Sam transport pozostaje taki sam niezależnie od zainstalowanych poziomów.

Zobacz też

/connect/quickstart/ — uruchamialny przykład uzgadniania połączenia
/connect/tool-catalog/ — co zwraca tools/list i dlaczego liczby się różnią
/connect/hitl-risk-tiers/ — format wyzwania potwierdzenia
/transports/rest/ · /transports/grpc/ — alternatywy sieciowe
/connect/migrating-to-multi-transport/ — przenoszenie integracji opartej wyłącznie na MCP do REST/gRPC