Migracja z trybu wyłącznie MCP do obsługi wielu transportów

W skrócie

Przenieś integrację z transportu stdio protokołu Model Context Protocol (MCP) na Representational State Transfer (REST) lub gRPC. Zachowanie silnika pozostaje bez zmian. Katalog, model ryzyka i bramka potwierdzenia pozostają takie same. Zmieniają się trzy rzeczy: protokół transmisji, uwierzytelnianie i model współbieżności.

Instalacja

composer require nextpdf/server
./vendor/bin/rr get-binary

Przegląd koncepcyjny

Wcześniejsza dokumentacja tego pakietu opisywała jeden transport: MCP przez stdio. Pakiet udostępnia teraz ten sam rejestr narzędzi przez trzy transporty. Aby przeprowadzić migrację, wybierz transport sieciowy, a następnie odwzoruj na niego wywołania MCP. Nie musisz przepisywać logiki obsługi dokumentu.

Wybierz transport pasujący do wdrożenia:

• Pozostań przy MCP, jeśli używasz pojedynczego lokalnego agenta, potrzebujesz najniższych opóźnień (bez przeskoku sieciowego) lub korzystasz z klienta natywnie obsługującego MCP, takiego jak lokalny asystent w środowisku IDE.
• Przejdź na REST, gdy potrzebujesz dostępu dla wielu klientów z kluczami API przypisanymi do poszczególnych klientów, wdrożenia w kontenerze lub Kubernetes, ograniczania liczby żądań dla poszczególnych klientów, zadań asynchronicznych albo klientów w dowolnym języku.
• Przejdź na gRPC, gdy potrzebujesz typowanych kontraktów, strumieniowania dużych plików PDF z serwera oraz wdrożeń między usługami z mutual TLS.

Powierzchnia API

Co pozostaje takie samo

• Rejestr narzędzi oraz katalog zależny od środowiska uruchomieniowego (zobacz /connect/tool-catalog/).
• Czteropoziomowy model ryzyka oraz bramka potwierdzenia (zobacz /connect/hitl-risk-tiers/).
• Model dokumentu i semantyka silnika.

Co się zmienia

Aspekt	MCP (stdio)	REST	gRPC
Format transmisji	JSON-RPC 2.0 przez stdio	JSON przez HTTP	Protobuf przez gRPC
Uwierzytelnianie	brak (lokalny podproces)	klucz API Authorization: Bearer	token bearer w metadanych wywołania
Współbieżność	jeden proces, jedno wywołanie	pula procesów roboczych RoadRunner	pula gRPC RoadRunner
Tryb asynchroniczny	nie dotyczy	punkty końcowe zadań	wywołania RPC zadań
Strumieniowanie	nie dotyczy	synchroniczny korpus odpowiedzi	wywołania RPC ze strumieniowaniem z serwera

Odwzorowanie pojęć

Typowa sekwencja MCP to create_pdf, następnie narzędzia treści, a na końcu output_pdf. W REST odpowiada jej jedno bezstanowe żądanie POST /api/v1/render z uporządkowaną tablicą operations. Gdy potrzebny jest stan utrzymywany między krokami, użyj zamiast tego opcjonalnych punktów końcowych sesji. W gRPC odpowiada temu wywołanie RPC Render lub RenderStream, gdy dane mają być dostarczane fragmentami. Przy budowaniu stanowym użyj wywołań RPC CreateSession, SessionOperation oraz SessionRender.

Sekwencja narzędzi MCP	REST	gRPC
create_pdf + narzędzia treści + output_pdf	POST /api/v1/render	Render / RenderStream
Budowanie stanowe w wielu wywołaniach	POST /api/v1/sessions (+ operacje sesji)	CreateSession (+ SessionOperation)
Długotrwałe renderowanie	POST /api/v1/jobs, a następnie odpytanie o wynik	SubmitJob, a następnie GetJobResult
Operacja ograniczona przez poziom licencji	POST /api/v1/<operation>	ExecuteCapability

Przykład kodu — szybki start

Wywołanie MCP:

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"add_text","arguments":{"text":"Hello"}}}

zmienia się w żądanie REST:

curl -sS -X POST http://localhost:8080/api/v1/render \
  -H "Authorization: Bearer $NEXTPDF_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"type":"add_text","text":"Hello"}]}' \
  --output hello.pdf

Przykład kodu — środowisko produkcyjne

Uruchamiaj oba transporty podczas etapowej migracji. Połączony profil RoadRunner udostępnia REST i gRPC z jednego procesu nadzorującego. Stara integracja MCP może nadal działać lokalnie tam, gdzie wciąż się sprawdza:

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
./vendor/bin/rr serve -c .rr.full.yaml

Nie ma współdzielonego stanu do migracji. Transporty są niezależnymi procesami opartymi na tym samym silniku. Przenoś klientów stopniowo.

Przypadki brzegowe i pułapki

• Dodaj uwierzytelnianie. Transport MCP go nie wymagał, ponieważ działał jako lokalny podproces. Transporty sieciowe wymagają prawidłowego klucza API przy każdym żądaniu poza sprawdzeniem stanu. Przygotuj klucze przed przełączeniem. Zobacz /connect/security-and-operations/.

• Bramka potwierdzenia nadal działa. Narzędzie approval_required żąda potwierdzenia w REST i gRPC dokładnie tak samo jak w MCP. Przenieś przepływ potwierdzenia do nowej integracji. Nie zakładaj, że bramka działa wyłącznie w MCP. Zobacz /connect/hitl-risk-tiers/.

• Ograniczenia poziomu licencji pozostają bez zmian. Operacja Pro lub Enterprise wymaga zainstalowanego pakietu nextpdf/premium oraz uprawnionego klucza w nowym transporcie, tak samo jak odpowiadające jej narzędzie wymagało tego pakietu w MCP.

• Idempotentność to nowa, przydatna funkcja. REST dodaje mechanizm idempotentności, którego transport stdio nigdy nie miał. Użyj go, aby bezpiecznie ponawiać przesyłanie zadań. Zobacz /connect/production-usage/.

Wydajność

MCP działa w jednym procesie i zapewnia najniższe opóźnienia w przypadku jednego lokalnego agenta. Transporty sieciowe wprowadzają pulę procesów roboczych oraz przeskok sieciowy. W zamian skalują się do wielu równoczesnych klientów. W nowym transporcie przenieś długie renderowania do ścieżki zadań asynchronicznych, aby nie blokować procesów roboczych.

Uwagi dotyczące bezpieczeństwa

Migracja ze stdio zwiększa ekspozycję sieciową. Terminuj połączenia Transport Layer Security (TLS) przed REST, używaj mutual TLS dla gRPC w sieciach niezaufanych, ograniczaj zakres kluczy do poszczególnych klientów i utrzymuj enabled_tools na minimalnym poziomie. Model transportu MCP bez poświadczeń jest bezpieczny tylko dlatego, że działa jako lokalny podproces. Nie odtwarzaj tej ekspozycji w sieci. Zobacz /connect/security-and-operations/.

Zgodność

Ta strona zawiera wskazówki dotyczące migracji. Odwołania dotyczące protokołu i uwierzytelniania są przypięte do /transports/mcp/, /transports/rest/, /transports/grpc/ oraz /connect/security-and-operations/.

Kontekst komercyjny

Operacje ograniczone poziomem licencji wymagają pakietu nextpdf/premium niezależnie od transportu. Migracja nie zmienia tego, co należy do wersji core, a co do wersji Premium. Zmienia jedynie sposób uzyskiwania dostępu do katalogu.

Zobacz także

• /transports/mcp/ — transport, z którego migrujesz
• /transports/rest/ · /transports/grpc/ — transporty, na które migrujesz
• /connect/tool-catalog/ — katalog, identyczny dla wszystkich transportów
• /connect/hitl-risk-tiers/ — bramka, identyczna dla wszystkich transportów
• /connect/security-and-operations/ — uwierzytelnianie, które musisz dodać