Katalog narzędzi NextPDF Connect

W skrócie

NextPDF Connect nie udostępnia stałej, z góry określonej liczby narzędzi. Serwer oblicza ją w czasie działania na podstawie zainstalowanych pakietów, listy dozwolonych z konfiguracji oraz bramek środowiskowych. Strona dokumentuje zweryfikowany zestaw narzędzi rdzenia oraz sposób wyznaczania sumy.

Instalacja

composer require nextpdf/server

Przegląd koncepcyjny

NextPDF\Server\ToolRegistry buduje katalog podczas uruchamiania w tej kolejności:

Poziom rdzenia. Stały zestaw narzędzi rdzenia jest rejestrowany bezwarunkowo. Dwa kolejne narzędzia są rejestrowane tylko po spełnieniu warunku wstępnego.
Poziom Pro. Narzędzia Pro są rejestrowane, gdy klasa dostawcy Pro zostanie rozwiązana, co następuje po zainstalowaniu pakietu nextpdf/premium. Serwer po cichu pomija ten krok, jeśli klasy nie da się rozwiązać.
Poziom Enterprise. Dostawca Enterprise stosuje ten sam wzorzec co dostawca Pro.
Dołączone poziomy rozszerzone. Dostawcy narzędzi AST i mutacji są dostarczani wraz z pakietem serwera i rejestrują się na poziomie Pro. Każdym dostawcą steruje bramka środowiskowa, a każdy działa w trybie łagodnej degradacji, gdy brakuje obsługi leżącej u podstaw w rdzeniu.
Filtr polityki bezpieczeństwa. Serwer wyznacza przecięcie każdej rejestracji z listą dozwolonych enabled_tools. Niepusta lista dozwolonych powoduje odrzucenie każdego narzędzia, którego na niej nie ma. Licznik poziomu uwzględnia tylko narzędzia dopuszczone przez politykę.

Odpowiedź initialize protokołu Model Context Protocol (MCP) zgłasza wynikowe tool_count oraz liczby narzędzi na poszczególnych poziomach dla działającego serwera. Ten wynik jest rozstrzygający. Każdą stałą sumę podaną w tekście należy traktować jako nieaktualną.

Powierzchnia API

Zweryfikowane narzędzia rdzenia dostępne zawsze

Te dwanaście narzędzi jest zawsze rejestrowanych na poziomie rdzenia. Serwer odczytuje poziom ryzyka oraz wskazówkę dotyczącą zachowania MCP bezpośrednio z implementacji każdego narzędzia.

Nazwa narzędzia	Kategoria	Opis	Ryzyko
`create_pdf`	dokument	Utwórz dokument PDF i zwróć `document_id`	caution
`add_text`	dokument	Dodaj treść tekstową do dokumentu PDF	caution
`add_image`	dokument	Dodaj obraz ze ścieżki pliku lub z danych base64	caution
`add_table`	dokument	Dodaj tabelę HTML do dokumentu PDF	caution
`set_font`	dokument	Ustaw czcionkę dla kolejnych operacji na tekście	caution
`add_page`	dokument	Dodaj nową stronę do dokumentu PDF	caution
`output_pdf`	dokument	Sfinalizuj plik PDF jako plik lub base64	approval_required
`preview_layout`	dokument	Zwróć podsumowanie układu w formacie JSON bez renderowania	safe
`diagnostic.doctor`	diagnostyka	Uruchom kontrolę kondycji i zwróć ustrukturyzowaną diagnostykę środowiska	safe
`diagnostic.capabilities`	diagnostyka	Wypisz możliwości wraz z poziomem i statusem	safe
`diagnostic.inspect`	diagnostyka	Zbadaj plik PDF i zwróć metadane strukturalne	safe
`diagnostic.verify`	diagnostyka	Zweryfikuj integralność pliku PDF, z opcjonalnymi kontrolami PDF/A lub PDF/UA	caution

Narzędzia rdzenia rejestrowane warunkowo

Nazwa narzędzia	Warunek
`generate_barcode`	Jest rejestrowane, gdy zainstalowany `nextpdf/core` zawiera rejestr koderów kodów kreskowych rdzenia
`parse_pdf`	Jest rejestrowane tylko wtedy, gdy `NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED` ma wartość `true` lub `1`

output_pdf jest jedynym narzędziem rdzenia na poziomie ryzyka approval_required. Zapis pliku przechodzi przez bramkę human-in-the-loop; dane wyjściowe base64 nie. Zobacz /connect/hitl-risk-tiers/.

Narzędzia dodawane tylko po zainstalowaniu dodatkowych pakietów

Serwer sprawdza klasy dostawców za pomocą class_exists():

Narzędzia Pro są rejestrowane, gdy zainstalowany jest nextpdf/premium i dostawca Pro zostanie rozwiązany.
Narzędzia Enterprise są rejestrowane, gdy zainstalowany jest nextpdf/premium i dostawca Enterprise zostanie rozwiązany. Narzędzia ochrony prywatności (redakcja, deidentyfikacja, redakcja strefowa) stanowią opakowanie dla klas Enterprise. Rejestrują się na poziomie Enterprise tylko wtedy, gdy te klasy można automatycznie załadować.
Narzędzia AST i mutacji są dostarczane wraz z serwerem i rejestrują się na poziomie Pro. Sterują nimi bramki NEXTPDF_AST_TOOLS_ENABLED i NEXTPDF_MUTATION_TOOLS_ENABLED, a obie bramki są domyślnie włączone.

To pakiet Premium, a nie serwer, definiuje dokładne zestawy narzędzi Pro i Enterprise oraz dokumentuje je w ramach tego pakietu. Kontrakt serwera obejmuje mechanizm rejestracji, a nie stałą listę Premium.

Przykład kodu — szybki start

Wyświetl narzędzia udostępniane przez tę instalację bez uruchamiania serwera:

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

Przykład kodu — produkcja

Uzyskaj rozstrzygającą liczbę z działającego serwera przez MCP:

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

Działający proces serwera oblicza capabilities.nextpdf.tool_count oraz tiers w wyniku initialize. W REST endpoint GET /api/v1/capabilities zwraca równoważną introspekcję.

Przypadki brzegowe i pułapki

Nie istnieje stała liczba „33 narzędzia” — ani żadna stała suma. Starsze materiały podają jedną liczbę, ale nie jest ona kontraktem. Zmienia się wraz z zainstalowanymi pakietami, listą dozwolonych enabled_tools oraz bramkami środowiskowymi parse_pdf, AST i mutacji. Zawsze odczytuj ją z działającego serwera.
Lista dozwolonych odejmuje, nigdy nie dodaje. Umieszczenie narzędzia Pro na liście enabled_tools nie rejestruje go, gdy brakuje nextpdf/premium.
Brakujący poziom to oczekiwany, cichy przypadek. Instalacja wyłącznie open source udostępnia zestaw rdzenia i zgłasza zero narzędzi Pro oraz zero narzędzi Enterprise. Taki wynik oznacza poprawne działanie, a nie błąd.
Poziom w katalogu jest zadeklarowanym niezmiennikiem. Każde narzędzie deklaruje własny poziom i ryzyko w kodzie. Rejestr nigdy nie wnioskuje poziomu z przestrzeni nazw ani z pakietu.

Wydajność

Skanowanie rejestru i wykrywanie poziomów są wykonywane raz podczas uruchamiania. performance_budget strony wyznacza ich limity. Koszt użycia poszczególnego narzędzia wynika z operacji silnika leżącej u podstaw, a nie z wyszukiwania w katalogu, które jest O(1) względem nazwy narzędzia.

Uwagi dotyczące bezpieczeństwa

Używaj enabled_tools jako mechanizmu najmniejszych uprawnień: udostępniaj tylko narzędzia potrzebne integracji. Katalog nigdy nie zawiera narzędzia odrzuconego przez politykę bezpieczeństwa, a licznik poziomu odzwierciedla wyłącznie dopuszczone narzędzia. Narzędzia wysokiego ryzyka pozostają chronione potwierdzeniem człowieka, niezależnie od przynależności do katalogu. Zobacz /connect/security-and-operations/.

Zgodność

Ta strona opisuje mechanizm rejestru. Odniesienia protokołu dotyczące powierzchni tools/list i initialize są przypięte w /transports/mcp/. Model ryzyka jest określony w /connect/hitl-risk-tiers/.

Kontekst komercyjny

Katalog rdzenia obejmuje tworzenie, kontrolę i diagnostykę. Narzędzia do podpisywania, redakcji, zgodności i analizy śledczej pojawiają się tylko wtedy, gdy razem z serwerem zainstalowany jest nextpdf/premium. Granica pakietowania jest stosowana przy composer require, nigdy przez monit w czasie działania.

Zobacz także

/connect/hitl-risk-tiers/ — co oznacza kolumna ryzyka i jak działa egzekwowanie
/connect/boot-and-discovery/ — pełna sekwencja uruchamiania i wykrywania
/connect/configuration/ — enabled_tools oraz bramki środowiskowe
/transports/mcp/ — formaty przewodowe tools/list i initialize
/connect/overview/ — dlaczego katalog z założenia zależy od czasu działania