Pro edycja

Narzędzia MCP

W skrócie

NextPDF Pro dodaje osiem narzędzi Model Context Protocol (MCP), które pozwalają agentowi AI wykonywać zaawansowane operacje na plikach PDF za pośrednictwem NextPDF Server. Narzędzia pojawiają się automatycznie, gdy zainstalowane są zarówno nextpdf/pro, jak i nextpdf/server — nie jest wymagany oddzielny krok rejestracji.

Dostępność i licencjonowanie

Ta funkcja jest dostarczana w NextPDF Pro (nextpdf/pro) i aktywuje się wraz z kopertą licencyjną warstwy Pro. Wdrożenie bez tego uprawnienia nie wczytuje klas tej funkcji. Porównaj edycje i uzyskaj licencję.

Bazowa powierzchnia MCP — tworzenie dokumentów, tekst, tabele, diagnostyka — jest dostarczana z otwartoźródłowym NextPDF Server i nie wymaga licencji. Osiem narzędzi opisanych na tej stronie wymaga licencji Pro i rejestruje się tylko wtedy, gdy podczas rozruchu rozwiąże się pakiet nextpdf/pro. Warstwa narzędzi pro bramkuje cały zestaw: każde narzędzie deklaruje swoją warstwę jawnie i nie ma flagi dla poszczególnych narzędzi — zainstalowanie nextpdf/pro obok nextpdf/server włącza zestaw.

Kontrakt zachowania

Osiem narzędzi MCP edycji Pro rejestruje się automatycznie, gdy podczas rozruchu rozwiążą się zarówno nextpdf/pro, jak i nextpdf/server, w warstwie pro, przez standardowy przepływ MCP tools/list oraz tools/call. Nie ma flagi dla poszczególnych narzędzi ani zmiany kodu w aplikacji korzystającej.
Każde narzędzie przyjmuje plik PDF za pomocą document_id z wcześniejszego wywołania create_pdf, wbudowanego źródła source (ścieżka pliku, base64 lub URI data:) lub — w przypadku compare_pdfs — dwóch takich źródeł. Narzędzia zwracają ustrukturyzowany JSON.
Każde narzędzie deklaruje klasę ryzyka HITL, którą serwer egzekwuje: bezpieczne (automatyczne wykonanie, tylko do odczytu), do przeglądu (wynik, który mógłby zostać nadużyty) oraz wymagające zatwierdzenia. sign_pdf wymaga zatwierdzenia i jest wstrzymywane do czasu potwierdzenia przez człowieka. Operator może jedynie zaostrzyć klasę ryzyka narzędzia, nigdy jej nie złagodzić.
sign_pdf tworzy wyłącznie podpis PAdES B-B (baseline) — bez zaufanego znacznika czasu i bez materiału do walidacji długoterminowej. Profile długoterminowe (B-LT / B-LTA), sprzętowe przechowywanie kluczy oraz podpisywanie ze ścieżką audytową należą do warstwy Enterprise i nie są dostarczane przez te narzędzia; B-T (podpis ze znacznikiem czasu) jest dostępny w silniku Core, gdy skonfigurowany jest dostawca znacznika czasu.
redact_pii wykonuje wykrywanie wzorców i maskowanie w warstwie tekstowej, a nie redakcję wizualną; check_accessibility to heurystyka strukturalna, a nie werdykt zgodności z PDF/UA lub WCAG. Autorytatywnym schematem wejścia/wyjścia jest aktywna odpowiedź serwera tools/list, a nie ta strona.

Przegląd koncepcyjny

NextPDF Server to deterministyczna warstwa wykonawcza MCP dla NextPDF. Wykrywa dostawców narzędzi podczas rozruchu za pomocą sondy istnienia klasy, więc pakiet Pro nie musi być wymieniony w zależnościach serwera. Gdy pakiet Pro jest obecny, serwer rejestruje swoje osiem narzędzi w warstwie pro i udostępnia je przez standardowy przepływ MCP tools/list oraz tools/call przez dowolny skonfigurowany transport.

Każde narzędzie Pro przyjmuje plik PDF z jednego z trzech źródeł: document_id zwróconego przez wcześniejsze wywołanie create_pdf, wbudowanego źródła source (ścieżka pliku, ciąg base64 lub URI data:) lub — w przypadku narzędzia porównującego — dwóch takich źródeł. Narzędzia zwracają ustrukturyzowane wyniki JSON: wyodrębniony tekst, regiony różnic, zamaskowany tekst, drzewa segmentów, ustalenia dotyczące dostępności lub podpisany plik PDF.

Każde narzędzie Pro niesie klasyfikację ryzyka, której serwer używa do egzekwowania trybu z udziałem człowieka (human-in-the-loop, HITL). Narzędzia analityczne tylko do odczytu mają rangę bezpiecznych i wykonują się automatycznie. Narzędzia generujące wynik, który wywołujący mógłby nadużyć, mają rangę do przeglądu. Narzędzie podpisujące ma rangę wymagającego zatwierdzenia, więc serwer wstrzymuje je do czasu potwierdzenia przez człowieka. Klasyfikację deklaruje samo narzędzie; operator może ją w czasie wykonania jedynie zaostrzyć — nigdy nie złagodzić.

Powierzchnia narzędzi MCP jest celowo oddzielona od silnika PDF edycji Pro. Narzędzia to cienkie adaptery: walidują dane wejściowe, rozwiązują plik PDF, delegują do komponentu silnika Pro i serializują wynik. Nie są drugim API silnika i nie są częścią publicznego API PHP edycji Pro — wspieranym punktem integracji jest protokół MCP udostępniany przez NextPDF Server.

Katalog narzędzi (osiem narzędzi Pro)

Osiem narzędzi MCP edycji Pro, według nazwy w protokole MCP. Poziomy ryzyka wynikają z modelu HITL serwera: safe (automatyczne wykonanie, tylko do odczytu), review (generuje wynik, który mógłby zostać nadużyty; ostrzeżenie w instrukcjach agenta) oraz approval-required (musi zostać potwierdzone przez człowieka).

`extract_text`

Cel: Wyodrębnianie tekstu. Wyodrębnij warstwę tekstową pliku PDF, opcjonalnie ograniczoną do zakresu stron indeksowanego od 1.
Wejścia: Plik PDF (document_id lub source); opcjonalne page_start i page_end.
Wyjścia: Wyodrębniony tekst i łączna liczba stron.
Ryzyko: Bezpieczne. Tylko do odczytu i idempotentne.
Granica: Wyodrębnia istniejącą warstwę tekstową. Nie wykonuje OCR na zeskanowanych lub wyłącznie obrazowych stronach.

`segment_document`

Cel: Segmentacja strukturalna. Podziel plik PDF na logiczne sekcje — tytuł, nagłówki, treść, tabele, ilustracje.
Wejścia: Plik PDF (document_id lub source).
Wyjścia: Liczba segmentów i ustrukturyzowana lista segmentów.
Ryzyko: Bezpieczne. Tylko do odczytu i idempotentne.
Granica: Segmentacja strukturalna oparta na analizie układu; nie jest to semantyczny konspekt ani drzewo struktury tagowanego PDF.

`compare_pdfs`

Cel: Różnica strukturalna. Porównaj dwa pliki PDF i zwróć ustrukturyzowaną różnicę ich zawartości tekstowej.
Wejścia: Dwa pliki PDF (source_a i source_b, każdy jako ścieżka, base64, URI data lub document_id).
Wyjścia: Flaga identyczności, łączna liczba zmian, liczby stron każdego dokumentu oraz lista zmienionych regionów z indeksami strony i wiersza.
Ryzyko: Bezpieczne. Tylko do odczytu i idempotentne.
Granica: Różnica zawartości tekstowej. Nie porównuje renderowania wizualnego, osadzonych czcionek ani struktury binarnej.

`redact_pii`

Cel: Wykrywanie i maskowanie PII. Wykryj dane osobowe w warstwie tekstowej pliku PDF i zwróć zamaskowany widok tekstu.
Wejścia: Plik PDF (document_id lub source); opcjonalny filtr types (email, phone, ssn, credit_card).
Wyjścia: Flaga obecności PII, liczba wykrytych wystąpień, zamaskowany tekst oraz lista przeskanowanych typów.
Ryzyko: Do przeglądu. Zamaskowany wynik mógłby zostać nadużyty, gdyby potraktować go jako dokument oczyszczony.
Granica: Jest to wykrywanie wzorców i maskowanie w warstwie tekstowej, a nie redakcja wizualna. Nie usuwa ani nie nadpisuje glifów w renderowanym pliku PDF, a dopasowywanie wzorców nie gwarantuje znalezienia każdego wystąpienia danych wrażliwych. Nie traktuj jego wyniku jako gwarancji pełnego usunięcia PII. W przypadku redakcji na poziomie dokumentu, która niszczy zawartość bazową, użyj dedykowanej powierzchni redakcji w otwartoźródłowych narzędziach serwera lub edycji Enterprise.

`fill_form`

Cel: Dane wypełniające AcroForm. Wygeneruj dane XFDF (ISO 19444-1), które wypełniają pola AcroForm pliku PDF na podstawie mapy nazw pól do wartości.
Wejścia: Mapa fields nazwy pola na wartość tekstową; opcjonalne pdf_filename osadzane jako odniesienie XFDF.
Wyjścia: Wygenerowany dokument XFDF i liczba pól.
Ryzyko: Do przeglądu. Tworzy dane formularza przeznaczone do zastosowania w dokumencie.
Granica: Tworzy XFDF zgodne ze standardem; nie zapisuje samodzielnie wartości z powrotem do pliku PDF. Zastosuj XFDF za pomocą dowolnego zgodnego czytnika lub narzędzia przetwarzającego.

`extract_form_data`

Cel: Odczyt AcroForm. Wyodrębnij nazwy i wartości pól AcroForm z XFDF osadzonego w pliku PDF.
Wejścia: Plik PDF (document_id lub source).
Wyjścia: Liczba pól oraz mapa nazw pól do wartości; jawna informacja, gdy brak osadzonych danych formularza.
Ryzyko: Bezpieczne. Tylko do odczytu i idempotentne.
Granica: Odczytuje osadzone strumienie XFDF (ISO 19444-1). Plik PDF przechowujący wartości formularza wyłącznie w obiektach AcroForm bez osadzonego XFDF zwraca pusty wynik.

`check_accessibility`

Cel: Strukturalna analiza dostępności. Przeanalizuj dostępność strukturalną pliku PDF — nagłówki, akapity, tabele i obrazy — i zgłoś prawdopodobne problemy z odniesieniami do WCAG.
Wejścia: Plik PDF (document_id lub source).
Wyjścia: Wynik strukturalny (0–100), lista problemów oraz podsumowanie segmentów.
Ryzyko: Bezpieczne. Tylko do odczytu i idempotentne.
Granica: Jest to heurystyka strukturalna, a nie werdykt zgodności. Pełne testowanie zgodności z PDF/UA i WCAG — drzewo tagów, kolejność czytania, kontrast kolorów — wymaga dedykowanego silnika dostępności. Wysoki wynik nie jest deklaracją zgodności z PDF/UA.

`sign_pdf`

Cel: Podpis cyfrowy PAdES B-B. Zastosuj podpis cyfrowy PAdES B-B (baseline) do pliku PDF za pomocą lokalnego certyfikatu X.509 i klucza prywatnego.
Wejścia: Plik PDF (document_id lub source); certyfikat PEM i klucz prywatny PKCS#8; opcjonalny algorytm (RSA-SHA256 domyślnie, RSA + SHA-3 256/384/512 lub Ed25519); opcjonalna nazwa podpisującego i powód; opcjonalna koperta transportowa AES-GCM wokół ładunku klucza prywatnego.
Wyjścia: Podpisany plik PDF, liczba podpisów, flaga ukończenia oraz użyty algorytm, OID i skrót.
Ryzyko: Wymagające zatwierdzenia. Podpisywanie to operacja prawnie znacząca i destrukcyjna; serwer wymaga jawnego potwierdzenia przez człowieka, zanim ją wykona.
Granica: To narzędzie tworzy podpis PAdES B-B (baseline) — nie osadza zaufanego znacznika czasu ani materiału do walidacji długoterminowej. Profile długoterminowe (B-LT / B-LTA), sprzętowe przechowywanie kluczy oraz podpisywanie ze ścieżką audytową są częścią edycji Enterprise; B-T (podpis ze znacznikiem czasu) jest dostępny w silniku Core, gdy skonfigurowany jest dostawca znacznika czasu. Zobacz powierzchnię podpisu Pro, aby poznać szersze możliwości podpisywania pakietu Pro, oraz edycję Enterprise w zakresie B-LT/B-LTA.

Jak pojawiają się narzędzia

composer require nextpdf/pro
composer require nextpdf/server

Po zainstalowaniu obu pakietów uruchom NextPDF Server z wybranym transportem. Serwer wykrywa warstwę Pro podczas rozruchu, a osiem narzędzi pojawia się w odpowiedzi MCP tools/list w warstwie pro obok otwartoźródłowych narzędzi Core. Twoja aplikacja nie wymaga zmiany kodu — wykrywanie odbywa się automatycznie, a brakująca warstwa nigdy nie blokuje wczytywania pozostałych.

Autorytatywnym schematem wejścia i wyjścia każdego narzędzia jest schemat publikowany przez serwer w odpowiedzi tools/list. Traktuj tę odpowiedź — a nie tę stronę — jako kontrakt: ten katalog opisuje intencje i granice; aktywny schemat opisuje dokładne nazwy i typy pól.

Przykład kodu — Szybki start

Narzędzia Pro są konsumowane przez protokół MCP, a nie przez API PHP edycji Pro. Integracją po stronie hosta jest uruchomienie NextPDF Server. Gdy nextpdf/pro jest obecny, osiem narzędzi rejestruje się przez wykrywanie w czasie wykonania — bez okablowania poszczególnych narzędzi — a host udostępnia je następnie agentom.

<?php

declare(strict_types=1);

use NextPDF\Server\Mcp\McpServer;

require __DIR__ . '/vendor/autoload.php';

// Runtime discovery registers the Pro tier when nextpdf/pro is installed
// alongside nextpdf/server. The consuming application changes no code.
$server = McpServer::create();

// A Pro tool name resolves only when the Pro package is present.
$signTool = $server->getToolRegistry()->get('sign_pdf');

\fwrite(\STDERR, $signTool !== null
    ? "Pro MCP tools active.\n"
    : "Pro MCP tools unavailable; install nextpdf/pro.\n");

// Serve the MCP protocol over stdio (Claude Desktop, Cursor, local agents).
$server->run();

Przykład kodu — Produkcja

Utwardź ścieżkę rozruchu. Wczytaj jawny plik polityki, odmów startu przy nieprawidłowym nadpisaniu poziomu ryzyka i potwierdź, że warstwa Pro się pojawiła, zanim zaczniesz obsługę. Okablowanie w McpServer::create() rzuca InvalidArgumentException, gdy blok risk_level_overrides próbuje osłabić narzędzie wymagające zatwierdzenia, takie jak sign_pdf, więc błędnie skonfigurowana polityka zawodzi w trybie fail closed przed pętlą obsługi.

<?php

declare(strict_types=1);

use NextPDF\Server\Mcp\McpServer;
use NextPDF\Server\Tools\ToolInterface;

require __DIR__ . '/vendor/autoload.php';

// A downgrade of an approval-required tool's HITL gate is rejected at boot,
// never silently applied — the server refuses to start on such a policy.
try {
    $server = McpServer::create(__DIR__ . '/nextpdf-mcp.yaml');
} catch (\InvalidArgumentException $e) {
    \fwrite(\STDERR, 'Refusing to start: invalid MCP policy. ' . $e->getMessage() . "\n");
    exit(1);
}

// Confirm the Pro tier surfaced before advertising it to agents.
$signTool = $server->getToolRegistry()->get('sign_pdf');

if (!$signTool instanceof ToolInterface) {
    \fwrite(\STDERR, "nextpdf/pro is not resolving; Pro MCP tools are unavailable.\n");
    exit(1);
}

// sign_pdf is approval-required; the server holds it for human confirmation.
$risk = $signTool->riskLevel()->label();
\fwrite(\STDERR, "Pro MCP tools ready. sign_pdf risk: {$risk}.\n");

$server->run();

Wskazówki produkcyjne

Bramkowanie HITL. Trzymaj sign_pdf za potwierdzeniem przez człowieka. Serwer egzekwuje to na podstawie deklarowanego poziomu ryzyka narzędzia; nie konfiguruj agenta tak, aby to obchodził. Operator może jedynie zaostrzyć poziom ryzyka narzędzia, nigdy go nie złagodzić.
Obsługa źródeł. Preferuj document_id dla dokumentów już obecnych w sesji. Dla danych wbudowanych narzędzia przyjmują URI base64 i data:; bardzo duże ładunki wbudowane działają wolniej niż dokument referencyjny.
Oczekiwania wobec PII. Jasno ustal oczekiwania wywołującego: redact_pii to pomoc w wykrywaniu i maskowaniu, a nie gwarancja oczyszczenia. W przypadku nieodwracalnego usuwania kieruj do dedykowanej powierzchni redakcji.
Klucze podpisujące. Dostarczaj klucze przez kopertę szyfrowania transportu, gdy transport nie jest poufny od końca do końca. Traktuj materiał klucza prywatnego jak sekret w polityce logowania wywołań narzędzi swojego agenta.
Logowanie audytowe. Narzędzia powyżej poziomu bezpiecznego są logowane audytowo przez serwer. Zadbaj, aby Twoje wdrożenie przechowywało te logi zgodnie z wymogami zgodności.

Przypadki brzegowe

Zakresy stron extract_text są indeksowane od 1 i przycinane do rzeczywistej liczby stron dokumentu; koniec poza zakresem nie powoduje błędu.
compare_pdfs wymaga obu źródeł; przekazanie jednego zwraca czytelny błąd walidacji zamiast częściowej różnicy.
extract_form_data zwraca wypełniony, jawny wynik „brak osadzonych danych formularza” zamiast błędu dla plików PDF bez osadzonego XFDF.
sign_pdf odrzuca nieobsługiwane identyfikatory algorytmów wraz z listą obsługiwanych wartości; Ed25519 wymaga rozszerzenia libsodium, a warianty SHA-3 wymagają kompilacji OpenSSL z obsługą SHA-3.
check_accessibility celowo nisko ocenia pliki PDF zawierające wyłącznie obrazy — sygnalizuje brak czytelnej warstwy tekstowej, zamiast zgłaszać błąd.

Uwagi dotyczące bezpieczeństwa

Narzędzie podpisujące to jedyne narzędzie wymagające zatwierdzenia; serwer nie wykona go automatycznie.
Opcjonalna koperta AES-GCM wokół klucza prywatnego uwierzytelnia ładunek; niezgodność tagu kończy się błędem deszyfrowania (fail closed) i nigdy nie przechodzi awaryjnie do użycia szyfrogramu.
redact_pii nie zmienia źródłowego pliku PDF; zwraca zamaskowaną reprezentację tekstu. Nie zastępuje zniszczenia zawartości.
Narzędzie waliduje dane wejściowe przed jakąkolwiek pracą silnika; odrzuca źle sformułowane źródła, URI data i ładunki base64 z jawnymi błędami.

Konformancja

Narzędzia formularzy tworzą i konsumują XFDF zgodnie z ISO 19444-1:2019 (XML Forms Data Format).
sign_pdf tworzy podpis PAdES baseline (B-B) zgodny z rodziną PAdES ETSI EN 319 142; profile długoterminowe to możliwość Enterprise, a B-T jest dostępny w silniku Core, gdy skonfigurowany jest dostawca znacznika czasu.
check_accessibility zgłasza ustalenia z odniesieniami do kryteriów sukcesu WCAG (na przykład 1.1.1, 1.3.1, 2.4.6) jako wskazówki heurystyczne, a nie poświadczenie zgodności.

Granica edycji

NextPDF Pro wnosi dokładnie osiem narzędzi MCP, wszystkie w warstwie pro. Edycja Enterprise dostarcza własny, odrębny zestaw narzędzi MCP w warstwie enterprise — obejmujący sprawdzanie zgodności, analizę śledczą, kondycję walidacji długoterminowej, certyfikację gotowości pod AI oraz wyszukiwanie i osadzanie dokumentów. Te narzędzia, ich wejścia i ich wewnętrzne mechanizmy wykraczają poza zakres tej strony; zobacz Narzędzia MCP Enterprise. Własna dokumentacja serwera obejmuje narzędzia Core (otwartoźródłowe), które są z nim dostarczane. Serwer wykrywa te trzy warstwy niezależnie, a brakująca warstwa nigdy nie wyłącza pozostałych.

Uwaga o granicy Enterprise

Pro wnosi dokładnie osiem narzędzi MCP w warstwie pro. Edycja Enterprise dostarcza odrębny zestaw narzędzi MCP w warstwie enterprise (sprawdzanie zgodności, analiza śledcza, kondycja walidacji długoterminowej, certyfikacja gotowości pod AI, wyszukiwanie i osadzanie dokumentów) oraz profile podpisu ze znacznikiem czasu/długoterminowe; nie są one dostarczane przez warstwę Pro. Pełny podział warstw znajdziesz w sekcji Granica edycji powyżej.

Rozwiązanie awaryjne / alternatywa Core

Otwartoźródłowy NextPDF Server daje każdemu agentowi AI deterministyczny zestaw narzędzi PDF Core (tworzenie dokumentów, tekst, tabele, diagnostyka) bez licencji. Osiem zaawansowanych narzędzi opisanych na tej stronie to dodatki Pro. Zobacz /connect/tools/.

Granica publikacji

Ta strona dokumentuje wyłącznie zewnętrznie obserwowalne zachowanie oraz wspieraną publiczną powierzchnię API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń wykraczają poza zakres.