MCP — szczegółowa referencja

W skrócie

Przestrzeń nazw NextPDF\Enterprise\Mcp dostarcza warstwę Enterprise katalogu narzędzi MCP NextPDF. Jej publiczna powierzchnia to jedenaście klas narzędzi, jedna fabryka klienta i jeden typowany wyjątek. Każde narzędzie implementuje kontrakt NextPDF\Server\Tools\ToolInterface ze środowiska uruchomieniowego nextpdf/server i deklaruje ToolTier::Enterprise. Sześć narzędzi analizuje pojedynczy plik PDF w procesie. Cztery narzędzia delegują zadania wsadowe i RAG do sidecara Spectrum poprzez NextPDF\Enterprise\Mcp\SpectrumClientFactory. Jedno narzędzie odczytuje wstrzykniętą przez konstruktor ścieżkę audytu mutacji AST zamiast bajtów PDF. Każde narzędzie samo opisuje swoją nazwę MCP, wejście w formacie JSON Schema, adnotacje klienta, RiskLevel oraz kategorię.

Dostępność i licencjonowanie

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

Powierzchnia publicznego API

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się niepowodzeniem z	Uwagi
ForensicAnalyzeTool::execute	array $arguments, InMemoryDocumentStore $store; argumenty: document_id lub source	Uruchamia analizę forensyczną: rewizje, aktualizacje przyrostowe, podpisy	ToolResult (raport JSON)	Błędny ToolResult; wyjątki są przechwytywane, nigdy nie są zgłaszane ponownie	Narzędzie forensic_analyze; RiskLevel::Safe; tylko do odczytu, idempotentne; kategoria document; od 2.0.0
BatchForensicAnalyzeTool::execute	argumenty: workspace_token, documents[] (każdy id + path)	Wsadowa analiza forensyczna przez sidecar Spectrum	ToolResult z status per dokument oraz licznikami udanych i nieudanych	Błędny ToolResult (brakujące argumenty, awaria sidecara)	Narzędzie batch_forensic_analyze; RiskLevel::Safe; kategoria document; od 2.1.0
ComplianceCheckTool::execute	argumenty: policy (enum 12-wartościowy), document_id lub source	Ocenia plik PDF względem jednej nazwanej polityki zgodności	ToolResult z ustaleniami, wynikiem pass/fail, duration_ms oraz polem disclaimer	Błędny ToolResult; nieznana polityka zwraca błąd wymieniający obsługiwane klucze	Narzędzie compliance_check; RiskLevel::Review; kategoria document; od 2.0.0
BatchComplianceCheckTool::execute	argumenty: workspace_token, documents[], policies (pdfa, pades, zugferd; domyślnie ["pdfa"])	Wsadowe kontrole zgodności przez sidecar Spectrum	ToolResult z licznikami zgodnych / niezgodnych	Błędny ToolResult; każdy element documents[] jest walidowany pod kątem niepustych id i path	Narzędzie batch_compliance_check; RiskLevel::Safe; kategoria document; od 2.1.0
LtvHealthCheckTool::execute	argumenty: document_id lub source	Uruchamia politykę kondycji LTV nad podpisanym plikiem PDF	ToolResult z ustaleniami i wynikiem pass/fail	Błędny ToolResult	Narzędzie ltv_health_check; RiskLevel::Safe; kategoria document; od 2.0.0
AiReadyCertifyTool::execute	argumenty: document_id lub source	Ocena gotowości do AI tylko do odczytu według czterech kryteriów	ToolResult z certification_level (certified, partial, not_certified) oraz wartościami logicznymi per kryterium	Błędny ToolResult	Narzędzie ai_ready_certify; RiskLevel::Review; tylko do odczytu; kategoria document; od 2.0.0
CertifyAiReadyTool::execute	argumenty: document_id lub source, return_stamped_pdf (domyślnie true)	Ocenia trzy kryteria i dołącza stempel proweniencji XMP	ToolResult; zawiera stamped_pdf_base64, chyba że wyłączono lub not_certified	Błędny ToolResult	Narzędzie certify_ai_ready; RiskLevel::Review; nie tylko do odczytu; kategoria document; od 3.0.0
AstAwareChunkTool::execute	argumenty: document_id lub source, max_chunk_chars (domyślnie 1500), overlap_chars (domyślnie 150)	Buduje AST i emituje fragmenty zakotwiczone cytatami z proweniencją	ToolResult z chunk_count oraz per fragment: identyfikator węzła, indeks strony, bbox, typ węzła	Błędny ToolResult	Narzędzie ast_aware_chunk; RiskLevel::Review; kategoria extraction; od 3.0.0
AuditAstMutationsTool::__construct	AstAuditTrailInterface $auditTrail	Wstrzykuje zaplecze ścieżki audytu	instancja	—	Zależność wstrzykiwana przez konstruktor; od 3.0.0
AuditAstMutationsTool::execute	argumenty: document_source_hash (SHA-256 hex, wymagane)	Zwraca wszystkie zarejestrowane zdarzenia mutacji AST dla tego dokumentu	ToolResult z entries[] i count	Błędny ToolResult, gdy argument jest brakujący lub pusty	Narzędzie audit_ast_mutations; RiskLevel::Review; kategoria document; od 3.0.0
EmbedDocumentsTool::execute	argumenty: collection_id, workspace_token, documents[] (wszystkie wymagane)	Wprowadza pliki PDF do kolekcji RAG przez sidecar Spectrum	ToolResult z licznikami udanych / łącznie / nieudanych	Błędny ToolResult	Narzędzie embed_documents; RiskLevel::Caution; nie tylko do odczytu, nieidempotentne; kategoria extraction; od 2.1.0
SearchDocumentsTool::execute	argumenty: collection_id, query (wymagane), top_k (domyślnie 10, ograniczane do 1–100), mode (hybrid, bm25, semantic)	Wyszukiwanie hybrydowe w załadowanej kolekcji	ToolResult z uszeregowanymi fragmentami i wynikami trafności	Błędny ToolResult; mode spoza listy dozwolonych jest odrzucany	Narzędzie search_documents; RiskLevel::Safe; kategoria extraction; od 2.1.0
SpectrumClientFactory::create	brak (odczytuje SPECTRUM_URL, SPECTRUM_TIMEOUT, SPECTRUM_AUTH_TOKEN, SPECTRUM_APP_SECRET)	Buduje i buforuje jednego klienta sidecara na cały proces	SpectrumClient	InvalidArgumentException, gdy SPECTRUM_URL jest zniekształcony lub wskazuje na zablokowany adres	Domyślny punkt końcowy http://127.0.0.1:7800; limit czasu 30.0 s; od 2.1.0
SpectrumClientFactory::reset	brak	Czyści zbuforowaną instancję klienta	void	—	Przeznaczone do testów
SpectrumClientFactory::createRequest	string $method, $uri (string lub UriInterface)	Buduje żądanie PSR-7 z klas HTTP Core	RequestInterface	—	Implementacja PSR-17 RequestFactoryInterface
SpectrumClientFactory::createStream	string $content = ''	Buduje strumień PSR-7 w pamięci	StreamInterface	—	Implementacja PSR-17 StreamFactoryInterface
SpectrumClientFactory::createStreamFromFile	string $filename, string $mode = 'r'	Otwiera plik i opakowuje go jako strumień	StreamInterface	McpStreamException, gdy pliku nie można otworzyć	McpStreamException rozszerza RuntimeException
SpectrumClientFactory::createStreamFromResource	$resource (zasób PHP)	Opakowuje istniejący zasób jako strumień	StreamInterface	—	Implementacja PSR-17 StreamFactoryInterface
McpStreamException	—	Typowane niepowodzenie pozyskania strumienia	—	—	final class, rozszerza RuntimeException; źródło dokumentuje zgodność z PSR-17 §1.5; źródło opatruje ją adnotacją @since 3.2.0 (obecną w bieżącej linii dev aliasowanej jako 3.1.0)

Każde narzędzie udostępnia również metody samoopisu ToolInterface: name, description, inputSchema, annotations, riskLevel, tier oraz category. Ich wartości per narzędzie pojawiają się w powyższej kolumnie Uwagi.

Sygnatury punktów wejścia, dosłownie ze źródła:

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function __construct(private readonly AstAuditTrailInterface $auditTrail)
public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public static function create(): SpectrumClient
public static function reset(): void
public function createRequest(string $method, $uri): RequestInterface
public function createStream(string $content = ''): StreamInterface
public function createStreamFromFile(string $filename, string $mode = 'r'): StreamInterface
public function createStreamFromResource($resource): StreamInterface

Kontrakt zachowania

• Każde narzędzie implementuje NextPDF\Server\Tools\ToolInterface i jawnie deklaruje ToolTier::Enterprise. Warstwa nigdy nie jest wnioskowana z przestrzeni nazw ani sposobu pakowania.
• execute nie zgłasza wyjątków. Każde niepowodzenie jest przechwytywane i zwracane jako błędny ToolResult niosący komunikat o niepowodzeniu.
• Narzędzia jednodokumentowe rozstrzygają bajty PDF według stałego priorytetu. document_id jest najpierw wyszukiwany w InMemoryDocumentStore. W przeciwnym razie source jest interpretowany jako URI data:, następnie jako surowy base64 (powyżej 256 znaków), a na końcu jako ścieżka pliku.
• Ścieżki source w systemie plików są domyślnie wyłączone. Aktywują się tylko wtedy, gdy zmienna środowiskowa NEXTPDF_MCP_INPUT_DIR nazywa ograniczony katalog wejściowy. Rozstrzygnięta ścieżka rzeczywista musi pozostać wewnątrz tego katalogu. Wszystko inne kończy się niepowodzeniem w trybie fail-closed.
• Schematy stream-wrapper (phar://, php://, file:// oraz dowolny inny schemat) i bajty null w ścieżce pliku source są odrzucane przed jakimkolwiek wywołaniem systemu plików. Próby przechodzenia po katalogach (traversal) i ucieczki przez dowiązania symboliczne nie przechodzą kontroli ograniczenia ścieżką rzeczywistą.
• Narzędzia wsparte przez sidecar (embed_documents, search_documents, batch_compliance_check, batch_forensic_analyze) pozyskują swojego klienta z SpectrumClientFactory::create. Fabryka waliduje nie-localhostowy SPECTRUM_URL względem prywatnych i zarezerwowanych zakresów adresów przed użyciem. Jawny localhost jest dozwolony dla lokalnego trybu sidecara.
• ai_ready_certify wyprowadza swój poziom z czterech kryteriów: integralności forensycznej, obecności podpisu, ważności LTV oraz braku szyfrowania. Spełnienie wszystkich czterech daje certified; od jednego do trzech daje partial; zero daje not_certified. Integralność forensyczna to heurystyka strukturalna nad łańcuchem rewizji, a nie kryptograficzna weryfikacja integralności bajtów. Kontrola szyfrowania inspekcjonuje wyłącznie obszar trailera.
• certify_ai_ready ocenia trzy kryteria i dołącza stempel proweniencji XMP. Ostemplowane bajty są zwracane w kodowaniu base64, chyba że return_stamped_pdf ma wartość false lub poziom to not_certified.
• compliance_check akceptuje dokładnie dwanaście kluczy polityk: pdfa4, pdfa4e, pdfa4f, pades-baseline, ltv-health, eidas-qualified, zugferd, fda-part11, sec-17a4, sec-17a4-compatible, sec-17a4-structural, sec-17a4-pre-sign. Nieznany klucz zwraca wynik błędu wymieniający obsługiwany zestaw.
• audit_ast_mutations odczytuje wyłącznie wstrzyknięty AstAuditTrailInterface. Sam niczego nie rejestruje.

Przypadki brzegowe i tryby awarii

• Nie podano ani document_id, ani source: wynik błędu instruujący wywołującego, aby dostarczył jeden z nich.
• Nieznany document_id: wynik błędu nazywający identyfikator i wskazujący na create_pdf.
• Ścieżka source w systemie plików przy nieustawionym NEXTPDF_MCP_INPUT_DIR: odrzucona z komunikatem nazywającym obsługiwane kanały.
• Ścieżka source rozstrzygająca się poza skonfigurowanym katalogiem wejściowym, w tym przez dowiązanie symboliczne: odrzucona. Porównanie odbywa się na granicy separatora katalogów, więc katalogi rodzeństwa dzielące prefiks nazwy nie mogą przejść.
• URI data: bez separatora przecinka lub z nieprawidłowym ładunkiem base64: wynik błędu.
• top_k w search_documents spoza zakresu 1–100: ograniczany, a nie odrzucany. Niecałkowity top_k wraca do skonfigurowanej wartości domyślnej potoku.
• mode w search_documents spoza hybrid, bm25, semantic: wynik błędu z listy dozwolonych potoku.
• Element documents[] w batch_compliance_check z brakującym id lub path, albo niosący puste ciągi: wynik błędu nazywający wadliwy indeks. batch_forensic_analyze waliduje wyłącznie kształt zewnętrznej tablicy; wady elementów ujawniają się z warstwy wsadowej.
• SpectrumClientFactory::create ze zniekształconym SPECTRUM_URL lub takim, który wskazuje na adres prywatny, link-local albo metadanych: InvalidArgumentException. Wewnątrz execute narzędzia objawia się to jako wynik błędu.
• SpectrumClientFactory::createStreamFromFile na nieczytelnej ścieżce: McpStreamException.
• Puste zmienne środowiskowe są traktowane jako nieustawione i wracają do wartości domyślnych.

Zgodność

NextPDF nie posiada żadnej certyfikacji ani żadnej nie udziela. Narzędzia MCP raportują oceny na poziomie możliwości; wsparcie to nie zgodność, a zgodność to nie certyfikacja. Wartości certification_level zwracane przez ai_ready_certify i certify_ai_ready to własne raportowane słownictwo narzędzi. Nie stanowią one atestacji strony trzeciej. Odpowiedzi compliance_check z tego samego powodu zawierają pole disclaimer produkowane przez raport bazowy. Odwołania do klauzul polityk, takie jak podstawa polityki LTV, którą źródło produktu podaje jako ISO 32000-2:2020 §12.8.4.3, są niesione w opisach narzędzi oraz w polach clause per ustalenie; ta strona nie dodaje niezależnych roszczeń standardowych. To, czy sprawdzany dokument spełnia daną regulację, jest ustaleniem dla operatora i jego asesorów.

Uwagi deweloperskie

• SpectrumClientFactory::create buforuje jednego klienta na proces. Wywołaj SpectrumClientFactory::reset w konfiguracji testu, aby wymusić świeżego klienta.
• Odczyty środowiska konsultują $_ENV, następnie $_SERVER, następnie getenv i traktują puste ciągi jako nieobecne.
• RiskLevel steruje obsługą po stronie hosta w środowisku uruchomieniowym serwera: Safe wykonuje się automatycznie, Caution i wyżej są rejestrowane w audycie, a ApprovalRequired wymaga potwierdzenia przez człowieka. Żadne narzędzie MCP Enterprise nie deklaruje ApprovalRequired. Nadpisania operatora mogą podnieść zadeklarowany poziom, nigdy go obniżyć.
• Wartości annotations (readOnlyHint, idempotentHint) to wskazówki dla klienta MCP, a nie egzekwowanie. Ograniczanie i walidacja odbywają się po stronie serwera niezależnie od wskazówek.
• Narzędzia raportują wartości category document lub extraction do filtrowania tools/list.
• AuditAstMutationsTool to jedyne narzędzie wymagające wstrzyknięcia przez konstruktor; zarejestruj je z konkretną implementacją AstAuditTrailInterface.

Zobacz też

• MCP (strona możliwości)
• Accelerator — szczegółowa referencja — powierzchnia klienta sidecara Spectrum.
• Forensics — szczegółowa referencja — analizator stojący za forensic_analyze.
• Compliance — szczegółowa referencja — polityki stojące za compliance_check.
• AST — szczegółowa referencja — dzielenie na fragmenty i ścieżka audytu mutacji.
• Validation — szczegółowa referencja

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ń są poza zakresem.