Enterprise edycja

Narzędzia MCP

W skrócie

NextPDF Enterprise dodaje jedenaście narzędzi MCP do serwera NextPDF Connect. Dają one asystentom AI i frameworkom agentowym bezpośredni, typowany dostęp do silnika Enterprise: kontrole zasad zgodności, forensykę PDF, kontrole kondycji LTV, stemplowanie gotowości do AI, dzielenie na fragmenty świadome AST oraz przyjmowanie i wyszukiwanie RAG. Każde narzędzie deklaruje własny poziom ryzyka i postawę tylko do odczytu, więc Twój host MCP może bramkować, logować i audytować aktywność agentów z pewnością. Awarie nigdy nie ujawniają się jako wyjątki; agenci zawsze otrzymują ustrukturyzowany, parsowalny wynik.

Dostępność i licencjonowanie

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

Instalacja

composer require nextpdf/enterprise:^3

Samym hostem MCP jest NextPDF Connect, dostarczany w pakiecie nextpdf/server; zobacz Instalacja Connect. Gdy oba pakiety są obecne, rejestr narzędzi serwera automatycznie wykrywa NextPDF\Enterprise\McpToolProvider i rejestruje jedenaście narzędzi Enterprise. Nie jest wymagany żaden kod okablowania. Jeśli nextpdf/server jest nieobecny, plik dostawcy kończy działanie wcześnie i nic się nie ładuje.

Narzędzia batch i RAG dodatkowo wymagają sidecara Spectrum. Skonfiguruj go za pomocą zmiennych środowiskowych odczytywanych przez NextPDF\Enterprise\Mcp\SpectrumClientFactory: SPECTRUM_URL (domyślnie http://127.0.0.1:7800), SPECTRUM_TIMEOUT (domyślnie 30.0 sekund), SPECTRUM_AUTH_TOKEN oraz SPECTRUM_APP_SECRET.

Przegląd koncepcyjny

Model Context Protocol (MCP) to otwarty protokół, który pozwala asystentom AI i frameworkom agentowym wywoływać typowane narzędzia udostępniane przez serwer. Zamiast wklejać bajty PDF do promptu i mieć nadzieję, agent wywołuje nazwane narzędzie z ładunkiem walidowanym przez schemat JSON i otrzymuje deterministyczny, ustrukturyzowany wynik. NextPDF Connect jest tym serwerem dla plików PDF; pakiet Enterprise rozszerza jego katalog o poniższe narzędzia. Każde narzędzie to cienka nakładka na te same API Enterprise, które Twój kod PHP wywołuje bezpośrednio, więc kontrola uruchomiona przez agenta i kontrola uruchomiona przez kod dają ten sam werdykt.

Katalog narzędzi

Narzędzie MCP	Klasa	Co robi	Ryzyko	Tylko do odczytu
`compliance_check`	`ComplianceCheckTool`	Waliduje jeden PDF względem nazwanej zasady: `pdfa4`, `pdfa4e`, `pdfa4f`, `pades-baseline`, `ltv-health`, `eidas-qualified`, `zugferd`, `fda-part11` oraz cztery warianty `sec-17a4`.	Review	tak
`batch_compliance_check`	`BatchComplianceCheckTool`	Sprawdza wiele plików PDF względem zasad `pdfa`, `pades` lub `zugferd` w jednym wsadzie sidecara Spectrum.	Safe	tak
`forensic_analyze`	`ForensicAnalyzeTool`	Raportuje historię rewizji, aktualizacje przyrostowe i zdarzenia modyfikacji na potrzeby wykrywania manipulacji.	Safe	tak
`batch_forensic_analyze`	`BatchForensicAnalyzeTool`	Uruchamia analizę forensyczną wielu plików PDF w jednym wsadzie sidecara.	Safe	tak
`ltv_health_check`	`LtvHealthCheckTool`	Sprawdza podpisany PDF pod kątem materiału długoterminowej walidacji: słownik DSS, odpowiedzi OCSP, wpisy CRL, wpisy VRI i magazyny certyfikatów.	Safe	tak
`ai_ready_certify`	`AiReadyCertifyTool`	Werdykt gotowości do AI tylko do odczytu, zdefiniowany przez produkt, w oparciu o cztery kryteria: integralność forensyczna, obecność podpisu, ważność LTV, brak szyfrowania.	Review	tak
`certify_ai_ready`	`CertifyAiReadyTool`	Werdykt gotowości zdefiniowany przez produkt w oparciu o trzy kryteria (cztery kryteria narzędzia tylko do odczytu minus integralność forensyczna — z założenia, ponieważ to narzędzie przepisuje plik, który stempluje) i dołącza stempel proweniencji XMP; zwraca ostemplowany PDF jako base64.	Review	nie
`ast_aware_chunk`	`AstAwareChunkTool`	Dzieli PDF na fragmenty zakotwiczone cytowaniem wzdłuż granic nagłówków, z identyfikatorem węzła, indeksem strony i prostokątem ograniczającym na fragment.	Review	tak
`audit_ast_mutations`	`AuditAstMutationsTool`	Pobiera ślad audytowy mutacji AST dla dokumentu według skrótu źródłowego SHA-256.	Review	tak
`embed_documents`	`EmbedDocumentsTool`	Przyjmuje pliki PDF do kolekcji RAG: parsowanie, dzielenie na fragmenty, osadzanie, indeksowanie. Modyfikuje stan kolekcji.	Caution	nie
`search_documents`	`SearchDocumentsTool`	Wyszukiwanie hybrydowe (słowa kluczowe BM25 plus semantyczne) w przyjętej kolekcji, z rankingowanymi, ocenianymi fragmentami.	Safe	tak

Narzędzia „certify” wydają werdykt gotowości zdefiniowany przez produkt (certified, partial lub not_certified). Ten werdykt jest wynikiem kontroli technicznej, a nie certyfikacją przez jakikolwiek organ akredytacyjny.

Bramkowanie zatwierdzeń i postawa audytowa

Każde narzędzie deklaruje poziom ryzyka z czteropoziomowego modelu Connect. Narzędzia Safe wykonują się automatycznie. Narzędzia Caution wykonują się automatycznie z wpisem w dzienniku audytu. Narzędzia Review niosą ostrzeżenie w instrukcjach dla wywołującego agenta. Narzędzia ApprovalRequired wymagają potwierdzenia przez człowieka; żadne obecne narzędzie MCP Enterprise nie deklaruje tego poziomu, ponieważ żadne nie jest destrukcyjne. Konfiguracja w czasie wykonania może jedynie podnieść poziom ryzyka narzędzia, nigdy go obniżyć. Narzędzia publikują też adnotacje zachowania MCP (readOnlyHint, idempotentHint), więc zgodny klient może zastosować własne bramkowanie na wierzchu. Zobacz Poziomy ryzyka HITL, aby poznać pełny model.

Dlaczego działa to w ten sposób

Kluczową decyzją jest to, że narzędzia są cienkimi, deterministycznymi nakładkami z samozadeklarowanym zarządzaniem: każde narzędzie podaje własny poziom ryzyka i kategorię jako niezmiennik domenowy, nigdy nie wnioskowany z przestrzeni nazw ani sposobu pakowania. Utrzymuje to decyzję o bramkowaniu audytowalną na hoście bez zaufania do transportu. Narzędzia nie zawierają własnej inteligencji dokumentowej; delegują do tych samych API Enterprise, które wywołuje Twój kod, więc istnieje dokładnie jedno zachowanie do przetestowania i jeden werdykt, któremu można zaufać. Błędy wracają kanałem błędów MCP zamiast wymykać się jako wyjątki, ponieważ agent nie może przechwycić wyjątku PHP, ale zawsze może rozgałęzić się na isError. Dane wejściowe, które mogłyby dotknąć systemu plików, są domyślnie fail-closed, ponieważ argumenty MCP są z definicji osiągalne dla atakującego.

Tło projektowe: API, które odmawia zgadywania.

Powierzchnia API

Wszystkie jedenaście narzędzi implementuje kontrakt NextPDF\Server\Tools\ToolInterface z nextpdf/server i dzieli tę samą publiczną powierzchnię. Poniższe sygnatury pokazano raz na NextPDF\Enterprise\Mcp\ComplianceCheckTool jako reprezentatywne:

public function name(): string
public function description(): string
public function inputSchema(): array
public function annotations(): array
public function riskLevel(): RiskLevel
public function tier(): ToolTier
public function category(): string
public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

Rzuca lub kończy się niepowodzeniem z: execute() nigdy nie rzuca. Przechwytuje Throwable wewnętrznie i zwraca ToolResult::error() z isError = true. Nieprawidłowe argumenty (brakujący workspace_token, zniekształcone wpisy documents, nieznany document_id, niebezpieczny source) ujawniają się jako komunikaty InvalidArgumentException na tym kanale błędów.

Narzędzie śladu audytowego pobiera swój backend magazynu przez wstrzykiwanie w konstruktorze:

public function __construct(private readonly AstAuditTrailInterface $auditTrail)

Dostawca, który rejestruje katalog:

public function getTier(): string
public function getTools(): array

getTier() zwraca 'enterprise'. getTools() zwraca jedenaście instancji narzędzi; audit_ast_mutations jest domyślnie okablowany z NextPDF\Enterprise\Ast\InMemoryAstAuditTrail.

Fabryka klienta sidecara Spectrum, która jest również fabryką żądań i strumieni PSR-17:

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

Rzuca lub kończy się niepowodzeniem z: create() rzuca InvalidArgumentException, gdy SPECTRUM_URL jest zniekształcony lub gdy skonfigurowany punkt końcowy celuje w znany adres prywatny lub zarezerwowany (z wyjątkiem localhost). Jest to brama na etapie konfiguracji, a nie kontrola na warstwie sieciowej: nadal egzekwuj zasady wychodzącego ruchu, obsługę przekierowań i przypinanie DNS w środowisku hosta. createStreamFromFile() rzuca NextPDF\Enterprise\Mcp\McpStreamException (podklasę RuntimeException, zgodnie z kontraktem PSR-17), gdy pliku nie można otworzyć.

Przykład kodu — Szybki start

Uruchom kontrolę zgodności PDF/A-4 dokładnie tak, jak zrobiłby to agent, używając kanału URI data: w pamięci:

<?php

declare(strict_types=1);

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

use NextPDF\Enterprise\Mcp\ComplianceCheckTool;
use NextPDF\Enterprise\Mcp\McpStreamException;
use NextPDF\Enterprise\Mcp\SpectrumClientFactory;
use NextPDF\Server\Document\InMemoryDocumentStore;

$streams = new SpectrumClientFactory(); // PSR-17 stream factory from this module

try {
    $pdfBytes = (string) $streams->createStreamFromFile(__DIR__ . '/invoice.pdf');
} catch (McpStreamException $e) {
    fwrite(STDERR, 'Cannot read PDF: ' . $e->getMessage() . PHP_EOL);
    exit(1);
}

$tool   = new ComplianceCheckTool();
$result = $tool->execute(
    [
        'source' => 'data:application/pdf;base64,' . base64_encode($pdfBytes),
        'policy' => 'pdfa4',
    ],
    new InMemoryDocumentStore(),
);

// Tool failures arrive on the MCP error channel, never as exceptions.
if ($result->isError) {
    fwrite(STDERR, $result->content[0]['text'] . PHP_EOL);
    exit(1);
}

echo $result->content[0]['text'] . PHP_EOL;

Oczekiwane wyjście dla pliku zgodnego (liczby ustaleń różnią się w zależności od dokumentu):

Compliance check (PDF/A-4): PASS — 0 finding(s)

Pełny raport odczytywalny maszynowo, w tym waga poszczególnych ustaleń, identyfikator reguły, klauzula i sugestia, jest dostępny w $result->structured.

Przykład kodu — Produkcja

Wykonaj preflight sidecara, wyegzekwuj zadeklarowaną postawę ryzyka, a następnie uruchom wsadową kontrolę zgodności:

<?php

declare(strict_types=1);

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

use NextPDF\Enterprise\Mcp\BatchComplianceCheckTool;
use NextPDF\Enterprise\Mcp\SpectrumClientFactory;
use NextPDF\Server\Document\InMemoryDocumentStore;

// 1. Fail fast on sidecar misconfiguration before accepting agent traffic.
//    The factory validates SPECTRUM_URL and rejects private/reserved targets.
try {
    SpectrumClientFactory::create();
} catch (InvalidArgumentException $e) {
    fwrite(STDERR, 'Spectrum sidecar rejected: ' . $e->getMessage() . PHP_EOL);
    exit(1);
}

$tool = new BatchComplianceCheckTool();
$risk = $tool->riskLevel();

// 2. Enforce the declared risk posture before execution.
if ($risk->requiresHumanConfirmation()) {
    // Route to your approval queue instead of executing.
    exit(0);
}

if ($risk->requiresAuditLog()) {
    error_log(sprintf('[mcp-audit] tool=%s risk=%s', $tool->name(), $risk->label()));
}

// 3. Execute the batch.
$result = $tool->execute(
    [
        'workspace_token' => (string) getenv('SPECTRUM_WORKSPACE_TOKEN'),
        'documents'       => [
            ['id' => 'contract-001', 'path' => '/var/pdf-inbox/contract-001.pdf'],
            ['id' => 'contract-002', 'path' => '/var/pdf-inbox/contract-002.pdf'],
        ],
        'policies'        => ['pdfa', 'pades'],
    ],
    new InMemoryDocumentStore(),
);

echo $result->content[0]['text'] . PHP_EOL;

Oczekiwane wyjście (liczby odzwierciedlają Twoje dokumenty):

Batch compliance check complete: 1 compliant, 1 non-compliant

Przypadki brzegowe i pułapki

Ścieżki source w systemie plików są domyślnie wyłączone. Bez zmiennej środowiskowej NEXTPDF_MCP_INPUT_DIR source w kształcie ścieżki jest odrzucany z wynikiem błędu. Użyj zamiast tego document_id, URI data: lub surowego base64.
Surowy base64 jest rozpoznawany tylko powyżej 256 znaków. Krótszy blok base64 jest traktowany jako ścieżka do pliku i odrzucany. Owiń małe ładunki w URI data:application/pdf;base64,.
Nieznane wartości document_id kończą się niepowodzeniem ze wskazówką. Tekst błędu to Unknown document_id: ... Call create_pdf first. Dokumenty w magazynie w pamięci również wygasają zgodnie z TTL magazynu, więc nieaktualny identyfikator kończy się niepowodzeniem w ten sam sposób.
compliance_check odrzuca nieznane klucze zasad i wymienia obsługiwany zestaw w komunikacie o błędzie.
Narzędzia batch i RAG potrzebują sidecara. batch_compliance_check, batch_forensic_analyze, embed_documents oraz search_documents wymagają osiągalnego punktu końcowego Spectrum i workspace_token. Fabryka buforuje jednego klienta na proces; wywołaj SpectrumClientFactory::reset() w testach.
search_documents ogranicza top_k do 1–100; wartości niecałkowite wracają do domyślnej wartości serwera równej 10.
Domyślne wartości ast_aware_chunk to 1500 znaków na fragment z 150 znakami nakładki.
certify_ai_ready pomija ostemplowane bajty, gdy return_stamped_pdf ma wartość false lub werdykt to not_certified. Gdy są obecne, ładunek base64 jest o około jedną trzecią większy niż sam PDF.
Domyślny ślad audytowy AST jest w pamięci. Wpisy zapisane przez standardowe okablowanie dostawcy nie utrzymują się między procesami; wstrzyknij trwałą implementację AstAuditTrailInterface, aby uzyskać trwałe ślady audytowe.

Uwagi dotyczące bezpieczeństwa

Rozwiązywanie źródła fail-closed. Wywołujący MCP w pełni kontrolują argumenty narzędzia, więc resolver traktuje je jako wrogie. Nakładki strumieni (phar://, php://, file:// i dowolny schemat) oraz bajty null są odrzucane przed jakimkolwiek wywołaniem systemu plików. Traversal ścieżki jest odrzucany. Surowe ścieżki plików działają tylko wtedy, gdy ustawiono NEXTPDF_MCP_INPUT_DIR, a cel skanonizowany przez realpath musi rozwiązać się ściśle wewnątrz tego katalogu, porównywany na granicy separatora, aby zablokować ucieczki przez pomylenie prefiksu.
Zabezpieczenie SSRF na punkcie końcowym sidecara. SpectrumClientFactory zezwala na localhost dla trybu lokalnego sidecara i waliduje każdy inny SPECTRUM_URL względem zakresów prywatnych, zarezerwowanych, link-local i metadanych chmury, rzucając InvalidArgumentException przy zablokowanym adresie. Jest to brama na etapie konfiguracji na skonfigurowanym punkcie końcowym, a nie kontrola na warstwie sieciowej — utrzymuj zasady wychodzącego ruchu, obsługę przekierowań i przypinanie DNS w środowisku hosta.
Sekrety pozostają w środowisku. Token bearer sidecara (SPECTRUM_AUTH_TOKEN) i sekret podpisujący HMAC (SPECTRUM_APP_SECRET) są odczytywane ze zmiennych środowiskowych i nigdy nie pojawiają się w ładunkach ani wynikach narzędzi.
Błędy nieodbijające. Komunikaty o odrzuceniu ścieżki są z założenia ogólne (Source path is not permitted.), więc sondujący wywołujący niczego nie dowiaduje się o systemie plików hosta.
Nadpisania ryzyka idą tylko w górę. Konfiguracja operatora może podnieść zadeklarowany poziom ryzyka narzędzia, ale nigdy nie może obniżyć go poniżej własnej deklaracji narzędzia.

Zgodność

Wsparcie nie jest zgodnością, a zgodność nie jest certyfikacją. NextPDF nie posiada żadnej certyfikacji i żadnej nie udziela. Narzędzia zgodności sprawdzają strukturę dokumentu względem nazwanych profili zasad i raportują ustalenia z odniesieniami do klauzul; raport compliance_check dodatkowo niesie własne zastrzeżenie silnika, że jest to techniczna kontrola struktury do celów referencyjnych, a nie porada prawna ani poparcie zgodności. Werdykty ai_ready_certify i certify_ai_ready to poziomy gotowości zdefiniowane przez produkt, a nie atestacja przez jakikolwiek organ normalizacyjny. MCP to otwarty protokół publikowany przez jego dostawcę-opiekuna, a nie standard SDO; ta strona dokumentuje zachowanie implementacji NextPDF i nie wysuwa żadnego niezależnego roszczenia o zgodności protokołu ani certyfikacji.

Kontrakt zachowania

Awarie narzędzi są zwracane jako wyniki błędów (isError = true z komunikatem); wyjątki nigdy nie przekraczają granicy MCP.
Pomyślne wyniki niosą jednowierszowe podsumowanie czytelne dla człowieka plus ustrukturyzowany ładunek JSON ze stabilnym, udokumentowanym zestawem pól na narzędzie.
Każde narzędzie raportuje tier() = ToolTier::Enterprise i zadeklarowany RiskLevel; ryzyka nie można obniżyć w czasie wykonania.
Narzędzia tylko do odczytu deklarują readOnlyHint: true i nie modyfikują magazynu dokumentów, źródłowego PDF ani żadnej kolekcji.
certify_ai_ready nigdy nie zmienia dokumentu wejściowego w miejscu; stempel jest nakładany na zwracaną kopię.
Raporty zgodności i LTV zawierają znacznik czasu walidacji i liczby ustaleń według wagi; ładunek compliance_check dodatkowo zawiera ciąg zastrzeżenia prawnego silnika.

Rozwiązanie awaryjne Core

Sam host MCP nie wymaga Enterprise. NextPDF Connect (nextpdf/server, Apache-2.0) działa z otwartym silnikiem Core i obsługuje swój katalog narzędzi poziomu core: tworzenie dokumentów, operacje na tekście i treści oraz ekstrakcję. Zobacz katalog narzędzi. Sam Core nie zapewnia kontroli zasad zgodności, analizy forensycznej, kontroli kondycji LTV, stemplowania gotowości do AI, dzielenia na fragmenty świadomego AST, śladów audytowych mutacji ani narzędzi batch i RAG; te jedenaście narzędzi rejestruje się tylko z zainstalowanym i licencjonowanym nextpdf/enterprise.

Granica publikacji

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