Pro edycja

Narzędzia MCP — szczegółowa dokumentacja referencyjna

Dostępność i licencjonowanie

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

Nie ma flagi licencji dla pojedynczej funkcji. Kod jest dostarczany z edycją Pro, a osiem narzędzi rejestruje się w warstwie pro, gdy pakiet Pro rozwiązuje się przy starcie obok nextpdf/server.

Kontrakt zachowania

NextPDF Server wykrywa warstwy przy starcie, sondując klasę dostawcy narzędzi Pro; jeśli się ona rozwiąże, serwer rejestruje osiem narzędzi w warstwie pro. Pakiet Pro nie jest twardą zależnością serwera, więc narzędzia Pro są ściśle opcjonalne i włączane przez współinstalację. Rejestracja warstw jest niezależna: brakująca lub wykluczona przez politykę warstwa nigdy nie blokuje pozostałych.
Każde narzędzie deklaruje jeden z czterech poziomów ryzyka (safe, caution, review, approval-required). Opcjonalne nadpisanie po stronie operatora może wyłącznie podnieść poziom narzędzia, nigdy go obniżyć; serwer rejestruje w dzienniku audytu każde wykonanie na poziomie caution lub wyższym. sign_pdf jest na poziomie approval-required.
Wejściowy PDF rozwiązuje się w stałej kolejności: document_id z magazynu w pamięci, następnie source jako URI data:, ścieżka w systemie plików lub surowy base64. Brak danych wejściowych zwraca błąd walidacji zamiast przetwarzania pustego dokumentu.
sign_pdf tworzy wyłącznie bazowy podpis PAdES B-B — bez znacznika czasu, bez walidacji długoterminowej. Obsługiwane algorytmy oraz koperta transportu klucza AES-GCM opisano poniżej; deszyfrowanie zawodzi w sposób zamknięty (fail closed), a narzędzie nigdy nie używa szyfrogramu jako materiału klucza.
Szczegóły wykrywania, ryzyka, rozwiązywania źródła, poszczególnych narzędzi oraz podpisywania znajdziesz w sekcjach poniżej. Ta strona opisuje wyłącznie obserwowalne z zewnątrz zachowanie oraz opublikowany kontrakt narzędzi.

Zakres

Ta strona jest dokumentacją referencyjną dla operatora i integratora ośmiu narzędzi MCP w edycji Pro. Obejmuje model wykrywania, semantykę ryzyka/HITL stosowaną przez serwer, reguły rozwiązywania źródła, kopertę transportu klucza przy podpisywaniu oraz zachowanie poszczególnych narzędzi przy awarii. Opisuje wyłącznie obserwowalne z zewnątrz zachowanie oraz opublikowany kontrakt narzędzi. Katalog dla użytkownika końcowego znajdziesz na publicznej stronie MCP.

Model wykrywania i rejestracji

NextPDF Server wykrywa dostawców warstw przy starcie. Wykrywa warstwę Pro, sondując klasę dostawcy narzędzi Pro; jeśli klasa się rozwiąże, serwer tworzy instancję dostawcy i rejestruje każde zwrócone przez niego narzędzie w warstwie pro. Pakiet Pro celowo nie jest twardą zależnością serwera — dzięki temu otwartoźródłowy serwer pozostaje instalowalny bez pakietu zastrzeżonego, a narzędzia Pro są ściśle opcjonalne i włączane przez współinstalację.

Serwer izoluje rejestrację dla każdej warstwy. Jeśli pakietu Pro brakuje, narzędzia Core nadal się rejestrują; obecny dostawca warstwy nie blokuje innych warstw. Rejestracja narzędzi podlega też liście dozwolonych z polityki bezpieczeństwa serwera: narzędzie wykluczone przez politykę nie zostaje cicho zarejestrowane i nie jest liczone w podsumowaniu warstwy. Serwer udostępnia liczbę narzędzi w każdej warstwie (core / pro / enterprise) na potrzeby diagnostyki i logowania.

Dostawca zwraca osiem narzędzi w stałej kolejności: ekstrakcja tekstu, segmentacja, porównanie, maskowanie PII, wypełnianie formularza, odczyt formularza, analiza dostępności, podpisywanie. Kolejność jest stabilna, ale wywołujący nie mogą na niej polegać — rozwiązuj narzędzia po ich nazwie w protokole MCP.

Model ryzyka i semantyka HITL

Każde narzędzie deklaruje jeden z czterech poziomów ryzyka. Serwer używa zadeklarowanego poziomu do egzekwowania udziału człowieka w pętli (human-in-the-loop):

Safe — tylko do odczytu, bez efektów ubocznych. Wykonuje się automatycznie.
Caution — tworzy lub modyfikuje stan w pamięci. Wykonuje się automatycznie z wpisem w dzienniku audytu.
Review — tworzy wynik, który mógłby zostać niewłaściwie wykorzystany. Wykonuje się automatycznie, ale instrukcje umiejętności agenta oznaczają je tak, aby agent ostrzegł użytkownika.
Approval-required — niszczące, prawne lub krytyczne dla prywatności. Serwer wymaga jawnego potwierdzenia przez człowieka przed wykonaniem.

Klasyfikacje narzędzi Pro: pięć narzędzi ekstrakcji/analizy (extract_text, segment_document, compare_pdfs, extract_form_data, check_accessibility) jest safe; redact_pii i fill_form są review; sign_pdf jest approval-required.

Poziom ryzyka pochodzi dokładnie z dwóch źródeł: własnej deklaracji narzędzia oraz opcjonalnego nadpisania po stronie operatora w czasie działania. Nadpisanie może wyłącznie podnieść poziom ryzyka narzędzia (zaostrzyć egzekwowanie); nigdy nie może go obniżyć. Serwer rejestruje w dzienniku audytu każde wykonanie na poziomie caution lub wyższym. Model ryzyka niesie wersję; serwer ogłasza tę wersję w swojej odpowiedzi inicjalizacyjnej, aby klienci mogli wykryć niezgodną zmianę.

Kolejność rozwiązywania źródła

Każde narzędzie przyjmujące PDF akceptuje go w jednej z trzech postaci wejściowych, rozwiązywanych w tej kolejności:

document_id — serwer pobiera bajty ze swojego magazynu dokumentów w pamięci. Nieznany identyfikator zawodzi z jawnym błędem kierującym wywołującego do utworzenia dokumentu najpierw.
source jako URI data: — narzędzie dekoduje treść base64 po przecinku.
source jako ścieżka w systemie plików — narzędzie czyta z dysku, gdy ścieżka rozwiązuje się do pliku.
source jako surowy łańcuch base64 — narzędzie akceptuje i dekoduje wyłącznie dostatecznie długie dane wejściowe o kształcie base64.

compare_pdfs stosuje to samo rozwiązywanie niezależnie do source_a i source_b, a dodatkowo akceptuje wartość document_id w którymkolwiek slocie źródła. Jeśli nie podano ani document_id, ani source, narzędzie zwraca błąd walidacji zamiast przetwarzania pustego dokumentu.

Dokumentacja referencyjna poszczególnych narzędzi

Tool	Risk	Inputs	Result fields	Behavioral boundary
`extract_text`	safe	PDF; opcjonalne, indeksowane od 1 `page_start` / `page_end`	tekst, łączna liczba stron	Wyłącznie warstwa tekstu; zakresy przycinane do rzeczywistej liczby stron; bez OCR
`segment_document`	safe	PDF	liczba segmentów, lista segmentów	Segmenty wyprowadzone z układu; nie jest to drzewo struktury otagowanego PDF
`compare_pdfs`	safe	dwa pliki PDF	flaga identyczności, łączna liczba zmian, liczba stron każdego dokumentu, regiony (typ, tekst, indeks strony, indeks wiersza, opcjonalny tekst odpowiednika)	Różnica treści tekstowej; nie wizualna ani binarna
`redact_pii`	review	PDF; opcjonalne `types` (`email`, `phone`, `ssn`, `credit_card`)	flaga obecności PII, liczba wykrytych, zamaskowany tekst, przeskanowane typy	Wykrywanie/maskowanie w warstwie tekstu; nie redagowanie wizualne; oparte na wzorcach, nie wyczerpujące
`fill_form`	review	mapa `fields`; opcjonalne `pdf_filename`	dokument XFDF, liczba pól	Tworzy XFDF (ISO 19444-1); nie zapisuje wartości do PDF
`extract_form_data`	safe	PDF	liczba pól, mapa pól, jawna adnotacja, gdy brak	Odczytuje wyłącznie osadzony XFDF
`check_accessibility`	safe	PDF	wynik strukturalny (0–100), problemy, podsumowanie segmentów	Heurystyka strukturalna z odniesieniami do WCAG; nie werdykt zgodności
`sign_pdf`	approval-required	PDF; certyfikat PEM + klucz PKCS#8; opcjonalny algorytm, nazwa podpisującego, powód, koperta transportowa	podpisany PDF, liczba podpisów, flaga ukończenia, algorytm, OID, skrót	Wyłącznie bazowy PAdES B-B; bez znacznika czasu, bez LTV

Podpisywanie: algorytmy i transport klucza

sign_pdf tworzy bazowy podpis PAdES B-B. Obsługiwane algorytmy, akceptowane zarówno w zapisie z podkreśleniem, jak i z myślnikiem:

RSA z SHA-256 (domyślnie).
RSA z SHA-3 256 / 384 / 512 — wymaga kompilacji OpenSSL z obsługą SHA-3.
Ed25519 — wymaga rozszerzenia libsodium; klucz musi być kluczem PKCS#8 PEM opakowującym klucz prywatny Ed25519.

Narzędzie odrzuca nieobsługiwane identyfikatory i zwraca listę akceptowanych wartości.

Opcjonalna koperta szyfrowania transportowego pozwala wywołującemu przetunelować klucz prywatny przez transport, który nie jest poufny od końca do końca. Koperta jest wyłącznie AES-GCM:

Klucz symetryczny: 16, 24 lub 32 bajty (AES-128/192/256), zakodowany base64.
Nonce: dokładnie 12 bajtów, zakodowany base64.
Opcjonalne dodatkowe dane uwierzytelnione, zakodowane base64.
Ładunek private_key to szyfrogram base64 z dołączonym 16-bajtowym znacznikiem uwierzytelniania GCM.

Deszyfrowanie zawodzi w sposób zamknięty (fail closed): niezgodność znacznika uwierzytelniania lub zniekształcony ładunek zwraca błąd deszyfrowania, a narzędzie nigdy nie używa szyfrogramu jako materiału klucza. Narzędzie odrzuca błędne rozmiary klucza lub nonce przed jakąkolwiek pracą kryptograficzną.

Przypadki brzegowe i tryb FIPS

extract_text: narzędzie przycina koniec zakresu stron przekraczający dokument, zamiast go odrzucać, oraz normalizuje początek poniżej pierwszej strony do pierwszej strony.
compare_pdfs: brakujące source_a lub source_b zwraca błąd walidacji; identyczne dokumenty zwracają jawny wynik identyczności z zerową liczbą zmian.
extract_form_data: pliki PDF bez osadzonego strumienia XFDF zwracają wynik z zerową liczbą pól wraz z adnotacją wyjaśniającą, a nie błąd.
redact_pii: nierozpoznany wpis w types jest ignorowany; lista zawierająca wyłącznie wpisy nierozpoznane daje pusty skan, a nie awarię.
sign_pdf: brakujący certyfikat lub klucz prywatny zawodzi przed jakąkolwiek pracą podpisywania; narzędzie sprawdza wymagania algorytmu (obsługa SHA-3 w OpenSSL, libsodium dla Ed25519) w czasie podpisywania i zgłasza je jako jawne błędy.
Tryb FIPS: dostępność algorytmu zależy od kompilacji OpenSSL/libsodium na hoście. W kompilacji ograniczonej do FIPS algorytmy niezatwierdzone zawodzą na granicy kryptograficznej z jawnym błędem zamiast cichego obniżenia. Warstwa MCP nie dodaje ani nie luzuje polityki kryptograficznej — odzwierciedla decyzję dostawcy kryptografii hosta.

Notatki z runbooka operatora

Utrzymuj sign_pdf na poziomie approval-required. Potwierdź, że żadne nadpisanie operatora nie podnosi nieumyślnie ryzyka na narzędziach safe — nadpisania wyłącznie zaostrzają, więc przypadkowe nadpisanie pogarsza dostępność, a nie bezpieczeństwo.
Przechowywanie audytu: każde wykonanie na poziomie review lub wyższym jest rejestrowane w dzienniku audytu przez serwer. Dobierz retencję dziennika do wolumenu wywołań redact_pii, fill_form oraz sign_pdf.
Wybór transportu: przy uruchamianiu przez transport, który nie jest poufny od końca do końca, wymagaj koperty transportu klucza AES-GCM dla sign_pdf i traktuj materiał klucza prywatnego jako tajemnicę w polityce logowania wywołań narzędzi swojego agenta.
Liczba w warstwie: użyj liczby narzędzi w każdej warstwie zwracanej przez serwer, aby w czasie wdrożenia potwierdzić, że warstwa Pro zarejestrowała osiem narzędzi; liczba zero wskazuje, że pakiet Pro się nie rozwiązał.

Granica edycji

Warstwa Pro wnosi dokładnie osiem narzędzi MCP. Edycja Enterprise dostarcza odrębną warstwę MCP z własnymi narzędziami — zgodność, analiza śledcza, kondycja walidacji długoterminowej, certyfikacja gotowości dla AI oraz wyszukiwanie/osadzanie dokumentów. Wejścia, wyjścia i wewnętrzne działanie narzędzi Enterprise są tu poza zakresem i opisane przy edycji Enterprise. Serwer wykrywa warstwy niezależnie; brakująca warstwa nigdy nie wyłącza innej.

Granica publikacji

Ta strona dokumentuje wyłącznie obserwowalne z zewnątrz zachowanie oraz obsługiwaną publiczną powierzchnię API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń są poza zakresem.