Enterprise edisi

Tool MCP

Sekilas

NextPDF Enterprise menambahkan sebelas tool MCP ke server NextPDF Connect. Tool-tool ini memberi asisten AI dan framework agen akses langsung yang bertipe ke engine Enterprise: pemeriksaan kebijakan kepatuhan, forensik PDF, pemeriksaan kesehatan LTV, penstempelan AI-readiness, chunking sadar-AST, serta ingesti dan pencarian RAG. Setiap tool mendeklarasikan tingkat risikonya sendiri dan postur read-only, sehingga host MCP Anda dapat menggerbangi, mencatat, dan mengaudit aktivitas agen dengan percaya diri. Kegagalan tidak pernah muncul sebagai exception; agen selalu menerima hasil terstruktur yang dapat diurai.

Ketersediaan & lisensi

Kapabilitas ini tersedia di NextPDF Enterprise (nextpdf/enterprise) dan diaktifkan dengan envelope lisensi tier Enterprise. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Instalasi

composer require nextpdf/enterprise:^3

Host MCP itu sendiri adalah NextPDF Connect, yang dikirim dalam paket nextpdf/server; lihat Instalasi Connect. Ketika kedua paket ada, registry tool server menemukan NextPDF\Enterprise\McpToolProvider secara otomatis dan meregistrasi sebelas tool Enterprise. Tidak diperlukan kode wiring. Jika nextpdf/server tidak ada, file provider kembali lebih awal dan tidak ada yang dimuat.

Tool batch dan RAG tambahan memerlukan sidecar Spectrum. Konfigurasikan melalui variabel lingkungan yang dibaca oleh NextPDF\Enterprise\Mcp\SpectrumClientFactory: SPECTRUM_URL (default http://127.0.0.1:7800), SPECTRUM_TIMEOUT (default 30.0 detik), SPECTRUM_AUTH_TOKEN, dan SPECTRUM_APP_SECRET.

Tinjauan konseptual

Model Context Protocol (MCP) adalah protokol terbuka yang memungkinkan asisten AI dan framework agen memanggil tool bertipe yang diekspos oleh sebuah server. Alih-alih menempelkan byte PDF ke dalam prompt dan berharap, agen memanggil tool bernama dengan payload yang divalidasi JSON-schema dan menerima hasil terstruktur yang deterministik. NextPDF Connect adalah server tersebut untuk PDF; paket Enterprise memperluas katalognya dengan tool-tool di bawah ini. Setiap tool adalah pembungkus tipis atas API Enterprise yang sama yang dipanggil langsung oleh kode PHP Anda, sehingga pemeriksaan yang dijalankan agen dan pemeriksaan yang dijalankan kode menghasilkan verdict yang sama.

Katalog tool

Tool MCP	Kelas	Fungsinya	Risiko	Read-only
`compliance_check`	`ComplianceCheckTool`	Memvalidasi satu PDF terhadap kebijakan bernama: `pdfa4`, `pdfa4e`, `pdfa4f`, `pades-baseline`, `ltv-health`, `eidas-qualified`, `zugferd`, `fda-part11`, dan empat varian `sec-17a4`.	Review	ya
`batch_compliance_check`	`BatchComplianceCheckTool`	Memeriksa banyak PDF terhadap kebijakan `pdfa`, `pades`, atau `zugferd` dalam satu batch sidecar Spectrum.	Safe	ya
`forensic_analyze`	`ForensicAnalyzeTool`	Melaporkan riwayat revisi, pembaruan inkremental, dan peristiwa modifikasi untuk deteksi tamper.	Safe	ya
`batch_forensic_analyze`	`BatchForensicAnalyzeTool`	Menjalankan analisis forensik atas banyak PDF dalam satu batch sidecar.	Safe	ya
`ltv_health_check`	`LtvHealthCheckTool`	Memeriksa PDF yang ditandatangani untuk material validasi jangka panjang: kamus DSS, respons OCSP, entri CRL, entri VRI, dan penyimpanan sertifikat.	Safe	ya
`ai_ready_certify`	`AiReadyCertifyTool`	Verdict AI-readiness read-only yang didefinisikan produk atas empat kriteria: integritas forensik, keberadaan tanda tangan, validitas LTV, tanpa enkripsi.	Review	ya
`certify_ai_ready`	`CertifyAiReadyTool`	Verdict readiness yang didefinisikan produk atas tiga kriteria (empat kriteria tool read-only dikurangi integritas forensik - sesuai desain, karena tool ini menulis ulang file yang distempelnya) dan menambahkan stempel provenance XMP; mengembalikan PDF yang distempel sebagai base64.	Review	tidak
`ast_aware_chunk`	`AstAwareChunkTool`	Membagi PDF menjadi chunk berankor-sitasi di sepanjang batas heading, dengan node ID, indeks halaman, dan bounding box per chunk.	Review	ya
`audit_ast_mutations`	`AuditAstMutationsTool`	Mengambil jejak audit mutasi AST untuk sebuah dokumen berdasarkan source hash SHA-256.	Review	ya
`embed_documents`	`EmbedDocumentsTool`	Mengingesti PDF ke dalam koleksi RAG: parse, chunk, embed, index. Memodifikasi state koleksi.	Caution	tidak
`search_documents`	`SearchDocumentsTool`	Pengambilan hibrida (kata kunci BM25 plus semantik) atas koleksi yang telah diingesti, dengan chunk yang diperingkat dan diberi skor.	Safe	ya

Tool “certify” mengeluarkan verdict readiness yang didefinisikan produk (certified, partial, atau not_certified). Verdict tersebut adalah hasil pemeriksaan teknis, bukan sertifikasi oleh badan akreditasi mana pun.

Penggerbangan persetujuan dan postur audit

Setiap tool mendeklarasikan tingkat risiko dari model Connect empat-tingkat. Tool Safe mengeksekusi otomatis. Tool Caution mengeksekusi otomatis dengan entri audit-log. Tool Review membawa peringatan untuk instruksi agen pemanggil. Tool ApprovalRequired menuntut konfirmasi manusia; saat ini tidak ada tool MCP Enterprise yang mendeklarasikan tingkat ini, karena tidak ada yang destruktif. Konfigurasi runtime hanya dapat menaikkan tingkat risiko tool, tidak pernah menurunkannya. Tool juga menerbitkan anotasi perilaku MCP (readOnlyHint, idempotentHint), sehingga klien yang patuh dapat menerapkan penggerbangannya sendiri di atasnya. Lihat Tingkat risiko HITL untuk model lengkapnya.

Mengapa dirancang begini

Keputusan penyangga adalah bahwa tool merupakan pembungkus tipis dan deterministik dengan tata kelola yang dideklarasikan sendiri: setiap tool menyatakan tingkat risiko dan tier-nya sendiri sebagai invarian domain, tidak pernah disimpulkan dari namespace atau pemaketan. Ini menjaga keputusan penggerbangan tetap dapat diaudit di host tanpa mempercayai transport. Tool tidak memuat intelijen dokumen apa pun sendiri; mereka mendelegasikan ke API Enterprise yang sama yang dipanggil kode Anda, sehingga ada tepat satu perilaku untuk diuji dan satu verdict untuk dipercaya. Error dikembalikan pada kanal error MCP alih-alih lolos sebagai exception, karena agen tidak dapat menangkap exception PHP tetapi selalu dapat bercabang pada isError. Input yang dapat menyentuh filesystem bersifat fail-closed secara default, karena argumen MCP secara definisi dapat dijangkau penyerang.

Latar belakang desain: API yang menolak menebak.

Permukaan API

Kesebelas tool mengimplementasikan kontrak NextPDF\Server\Tools\ToolInterface dari nextpdf/server dan berbagi permukaan publik yang sama. Signature di bawah ditampilkan sekali pada NextPDF\Enterprise\Mcp\ComplianceCheckTool sebagai wakil:

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

Melempar atau gagal dengan: execute() tidak pernah melempar. Ia menangkap Throwable secara internal dan mengembalikan ToolResult::error() dengan isError = true. Argumen tidak valid (workspace_token hilang, entri documents cacat, document_id tidak dikenal, source tidak aman) muncul sebagai pesan InvalidArgumentException pada kanal error tersebut.

Tool jejak-audit menerima backend penyimpanannya melalui constructor injection:

public function __construct(private readonly AstAuditTrailInterface $auditTrail)

Provider yang meregistrasi katalog:

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

getTier() mengembalikan 'enterprise'. getTools() mengembalikan sebelas instans tool; audit_ast_mutations di-wire dengan NextPDF\Enterprise\Ast\InMemoryAstAuditTrail secara default.

Factory klien sidecar Spectrum, yang juga merupakan factory request dan stream 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

Melempar atau gagal dengan: create() melempar InvalidArgumentException ketika SPECTRUM_URL cacat atau ketika endpoint yang dikonfigurasi menargetkan alamat privat atau tercadang yang diketahui (kecuali localhost). Ini adalah gerbang waktu-konfigurasi, bukan kontrol lapisan-jaringan: tetap terapkan kebijakan egress, penanganan redirect, dan DNS pinning di lingkungan host. createStreamFromFile() melempar NextPDF\Enterprise\Mcp\McpStreamException (subclass RuntimeException, sesuai kontrak PSR-17) ketika file tidak dapat dibuka.

Contoh kode — Quick start

Jalankan pemeriksaan kepatuhan PDF/A-4 persis seperti yang dilakukan agen, menggunakan kanal data: URI dalam-memori:

<?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;

Output yang diharapkan untuk file yang konforman (jumlah temuan bervariasi per dokumen):

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

Laporan lengkap yang dapat dibaca mesin, termasuk severity per-temuan, rule ID, klausa, dan saran, tersedia pada $result->structured.

Contoh kode — Produksi

Preflight sidecar, terapkan postur risiko yang dideklarasikan, lalu jalankan pemeriksaan kepatuhan batch:

<?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;

Output yang diharapkan (jumlah mencerminkan dokumen Anda):

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

Kasus tepi & jebakan

Path source filesystem dinonaktifkan secara default. Tanpa variabel lingkungan NEXTPDF_MCP_INPUT_DIR, source yang berbentuk path ditolak dengan hasil error. Gunakan document_id, sebuah data: URI, atau base64 mentah sebagai gantinya.
Base64 mentah hanya dikenali di atas 256 karakter. Blob base64 yang lebih pendek diperlakukan sebagai file path dan ditolak. Bungkus payload kecil dalam sebuah URI data:application/pdf;base64,.
Nilai document_id yang tidak dikenal gagal dengan panduan. Teks error-nya adalah Unknown document_id: ... Call create_pdf first. Dokumen di penyimpanan dalam-memori juga kedaluwarsa pada TTL penyimpanan, sehingga ID basi gagal dengan cara yang sama.
compliance_check menolak kunci policy yang tidak dikenal dan mendaftar set yang didukung dalam pesan error.
Tool batch dan RAG memerlukan sidecar. batch_compliance_check, batch_forensic_analyze, embed_documents, dan search_documents memerlukan endpoint Spectrum yang dapat dijangkau dan sebuah workspace_token. Factory meng-cache satu klien per proses; panggil SpectrumClientFactory::reset() dalam pengujian.
search_documents menjepit top_k ke 1–100; nilai non-integer jatuh kembali ke default server yaitu 10.
Default ast_aware_chunk adalah 1500 karakter per chunk dengan overlap 150 karakter.
certify_ai_ready menghilangkan byte yang distempel ketika return_stamped_pdf bernilai false atau verdict-nya not_certified. Ketika ada, payload base64 kira-kira sepertiga lebih besar daripada PDF-nya sendiri.
Jejak audit AST default bersifat dalam-memori. Entri yang direkam melalui wiring provider standar tidak bertahan lintas proses; injeksikan implementasi AstAuditTrailInterface yang persisten untuk jejak audit yang tahan lama.

Catatan keamanan

Resolusi source yang fail-closed. Pemanggil MCP mengendalikan penuh argumen tool, sehingga resolver memperlakukannya sebagai musuh. Stream wrapper (phar://, php://, file://, dan skema apa pun) serta null byte ditolak sebelum panggilan filesystem apa pun. Path traversal ditolak. Path file mentah bekerja hanya ketika NEXTPDF_MCP_INPUT_DIR diset, dan target yang dikanonikalisasi realpath harus resolusi tepat di dalam direktori tersebut, dibandingkan pada batas separator untuk memblokir escape kebingungan-awalan.
Penjaga SSRF pada endpoint sidecar. SpectrumClientFactory mengizinkan localhost untuk mode sidecar-lokal dan memvalidasi setiap SPECTRUM_URL lainnya terhadap rentang privat, tercadang, link-local, dan cloud-metadata, melempar InvalidArgumentException pada alamat yang diblokir. Ini adalah gerbang waktu-konfigurasi pada endpoint yang dikonfigurasi, bukan kontrol lapisan-jaringan - jaga kebijakan egress, penanganan redirect, dan DNS pinning di lingkungan host.
Rahasia tetap di lingkungan. Token bearer sidecar (SPECTRUM_AUTH_TOKEN) dan rahasia penandatanganan HMAC (SPECTRUM_APP_SECRET) dibaca dari variabel lingkungan dan tidak pernah muncul dalam payload atau hasil tool.
Error non-reflektif. Pesan penolakan-path bersifat generik sesuai desain (Source path is not permitted.), sehingga pemanggil yang menyelidik tidak mempelajari apa pun tentang filesystem host.
Override risiko hanya naik. Konfigurasi operator dapat menaikkan tingkat risiko tool yang dideklarasikan tetapi tidak pernah dapat menurunkannya di bawah deklarasi tool itu sendiri.

Konformansi

Dukungan bukan konformansi, dan konformansi bukan sertifikasi. NextPDF tidak memegang sertifikasi dan tidak memberikan sertifikasi. Tool kepatuhan memeriksa struktur dokumen terhadap profil kebijakan bernama dan melaporkan temuan dengan referensi klausa; laporan compliance_check selain itu membawa disclaimer engine sendiri bahwa ia adalah pemeriksaan struktur teknis untuk referensi, bukan nasihat hukum atau dukungan kepatuhan. Verdict ai_ready_certify dan certify_ai_ready adalah tingkat readiness yang didefinisikan produk, bukan atestasi oleh badan standar mana pun. MCP adalah protokol terbuka yang diterbitkan oleh vendor stewardnya, bukan standar SDO; halaman ini mendokumentasikan perilaku implementasi NextPDF dan tidak membuat klaim konformansi-protokol atau sertifikasi independen.

Kontrak perilaku

Kegagalan tool dikembalikan sebagai hasil error (isError = true dengan sebuah pesan); exception tidak pernah melintasi batas MCP.
Hasil yang sukses membawa ringkasan satu-baris yang dapat dibaca manusia plus payload JSON terstruktur dengan set field yang stabil dan terdokumentasi per tool.
Setiap tool melaporkan tier() = ToolTier::Enterprise dan sebuah RiskLevel yang dideklarasikan; risiko tidak dapat diturunkan saat runtime.
Tool read-only mendeklarasikan readOnlyHint: true dan tidak memodifikasi penyimpanan dokumen, PDF sumber, atau koleksi apa pun.
certify_ai_ready tidak pernah mengubah dokumen input di tempat; stempel diterapkan pada salinan yang dikembalikan.
Laporan kepatuhan dan LTV mencakup timestamp validasi dan jumlah temuan menurut severity; payload compliance_check selain itu mencakup string disclaimer hukum engine.

Fallback Core

Host MCP itu sendiri tidak memerlukan Enterprise. NextPDF Connect (nextpdf/server, Apache-2.0) berjalan dengan engine Core terbuka dan melayani katalog tool tier-core-nya: pembuatan dokumen, operasi teks dan konten, serta ekstraksi. Lihat katalog tool. Core saja tidak menyediakan pemeriksaan kebijakan kepatuhan, analisis forensik, pemeriksaan kesehatan LTV, penstempelan AI-readiness, chunking sadar-AST, jejak audit mutasi, atau tool batch dan RAG; sebelas tool tersebut hanya meregistrasi ketika nextpdf/enterprise terpasang dan berlisensi.

Batas publikasi

Halaman ini hanya mendokumentasikan perilaku yang dapat diamati secara eksternal dan permukaan API publik yang didukung. Path namespace internal, kelas helper, tabel mekanisme, nama file runbook, dan awalan tiket berada di luar cakupan.