MCP — Referensi Mendalam

Sekilas pandang

Namespace NextPDF\Enterprise\Mcp menyediakan tier Enterprise dari katalog tool MCP NextPDF. Permukaan publiknya adalah sebelas kelas tool, satu client factory, dan satu exception bertipe. Setiap tool mengimplementasikan kontrak NextPDF\Server\Tools\ToolInterface dari runtime nextpdf/server dan mendeklarasikan ToolTier::Enterprise. Enam tool menganalisis satu PDF secara in-process. Empat tool mendelegasikan beban kerja batch dan RAG ke sidecar Spectrum melalui NextPDF\Enterprise\Mcp\SpectrumClientFactory. Satu tool membaca jejak audit mutasi AST yang di-inject melalui constructor alih-alih byte PDF. Setiap tool mendeskripsikan sendiri nama MCP-nya, input JSON Schema, anotasi client, RiskLevel, dan kategorinya.

Ketersediaan & lisensi

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

Permukaan API publik

Simbol	Parameter	Perilaku default	Mengembalikan	Melempar atau gagal dengan	Catatan
ForensicAnalyzeTool::execute	array $arguments, InMemoryDocumentStore $store; args: document_id atau source	Menjalankan analisis forensik: revisi, incremental update, tanda tangan	ToolResult (laporan JSON)	Error ToolResult; exception ditangkap, tidak pernah dilempar ulang	Tool forensic_analyze; RiskLevel::Safe; read-only, idempoten; kategori document; sejak 2.0.0
BatchForensicAnalyzeTool::execute	args: workspace_token, documents[] (masing-masing id + path)	Analisis forensik batch melalui sidecar Spectrum	ToolResult dengan status per dokumen, jumlah berhasil dan gagal	Error ToolResult (argumen hilang, kegagalan sidecar)	Tool batch_forensic_analyze; RiskLevel::Safe; kategori document; sejak 2.1.0
ComplianceCheckTool::execute	args: policy (enum 12-nilai), document_id atau source	Menilai PDF terhadap satu kebijakan kepatuhan bernama	ToolResult dengan temuan, lulus/gagal, duration_ms, dan field disclaimer	Error ToolResult; policy tak dikenal mengembalikan error yang mencantumkan key yang didukung	Tool compliance_check; RiskLevel::Review; kategori document; sejak 2.0.0
BatchComplianceCheckTool::execute	args: workspace_token, documents[], policies (pdfa, pades, zugferd; default ["pdfa"])	Pemeriksaan kepatuhan batch melalui sidecar Spectrum	ToolResult dengan jumlah patuh / tidak patuh	Error ToolResult; tiap elemen documents[] divalidasi agar id dan path tidak kosong	Tool batch_compliance_check; RiskLevel::Safe; kategori document; sejak 2.1.0
LtvHealthCheckTool::execute	args: document_id atau source	Menjalankan kebijakan kesehatan LTV atas PDF bertanda tangan	ToolResult dengan temuan dan lulus/gagal	Error ToolResult	Tool ltv_health_check; RiskLevel::Safe; kategori document; sejak 2.0.0
AiReadyCertifyTool::execute	args: document_id atau source	Penilaian kesiapan AI read-only atas empat kriteria	ToolResult dengan certification_level (certified, partial, not_certified) dan boolean per kriteria	Error ToolResult	Tool ai_ready_certify; RiskLevel::Review; read-only; kategori document; sejak 2.0.0
CertifyAiReadyTool::execute	args: document_id atau source, return_stamped_pdf (default true)	Menilai tiga kriteria dan menambahkan stempel provenance XMP	ToolResult; menyertakan stamped_pdf_base64 kecuali dinonaktifkan atau not_certified	Error ToolResult	Tool certify_ai_ready; RiskLevel::Review; bukan read-only; kategori document; sejak 3.0.0
AstAwareChunkTool::execute	args: document_id atau source, max_chunk_chars (default 1500), overlap_chars (default 150)	Membangun AST dan menghasilkan chunk berjangkar sitasi dengan provenance	ToolResult dengan chunk_count dan node ID, indeks halaman, bbox, tipe node per chunk	Error ToolResult	Tool ast_aware_chunk; RiskLevel::Review; kategori extraction; sejak 3.0.0
AuditAstMutationsTool::__construct	AstAuditTrailInterface $auditTrail	Meng-inject backend audit-trail	instance	—	Dependensi yang di-inject melalui constructor; sejak 3.0.0
AuditAstMutationsTool::execute	args: document_source_hash (SHA-256 hex, wajib)	Mengembalikan semua event mutasi AST yang tercatat untuk dokumen tersebut	ToolResult dengan entries[] dan count	Error ToolResult bila argumen hilang atau kosong	Tool audit_ast_mutations; RiskLevel::Review; kategori document; sejak 3.0.0
EmbedDocumentsTool::execute	args: collection_id, workspace_token, documents[] (semua wajib)	Meng-ingest PDF ke koleksi RAG melalui sidecar Spectrum	ToolResult dengan jumlah berhasil / total / gagal	Error ToolResult	Tool embed_documents; RiskLevel::Caution; bukan read-only, bukan idempoten; kategori extraction; sejak 2.1.0
SearchDocumentsTool::execute	args: collection_id, query (wajib), top_k (default 10, di-clamp 1–100), mode (hybrid, bm25, semantic)	Pengambilan hibrida atas koleksi yang telah di-ingest	ToolResult dengan chunk berperingkat dan skor relevansi	Error ToolResult; mode di luar allowlist ditolak	Tool search_documents; RiskLevel::Safe; kategori extraction; sejak 2.1.0
SpectrumClientFactory::create	tidak ada (membaca SPECTRUM_URL, SPECTRUM_TIMEOUT, SPECTRUM_AUTH_TOKEN, SPECTRUM_APP_SECRET)	Membangun dan meng-cache satu client sidecar untuk seluruh proses	SpectrumClient	InvalidArgumentException saat SPECTRUM_URL cacat atau menargetkan alamat yang diblokir	Endpoint default http://127.0.0.1:7800; timeout 30.0 s; sejak 2.1.0
SpectrumClientFactory::reset	tidak ada	Menghapus instance client yang di-cache	void	—	Ditujukan untuk pengujian
SpectrumClientFactory::createRequest	string $method, $uri (string atau UriInterface)	Membangun request PSR-7 dari kelas HTTP Core	RequestInterface	—	Implementasi PSR-17 RequestFactoryInterface
SpectrumClientFactory::createStream	string $content = ''	Membangun stream PSR-7 in-memory	StreamInterface	—	Implementasi PSR-17 StreamFactoryInterface
SpectrumClientFactory::createStreamFromFile	string $filename, string $mode = 'r'	Membuka file dan membungkusnya sebagai stream	StreamInterface	McpStreamException saat file tidak dapat dibuka	McpStreamException memperluas RuntimeException
SpectrumClientFactory::createStreamFromResource	$resource (resource PHP)	Membungkus resource yang ada sebagai stream	StreamInterface	—	Implementasi PSR-17 StreamFactoryInterface
McpStreamException	—	Kegagalan akuisisi stream bertipe	—	—	final class, memperluas RuntimeException; sumber mendokumentasikan kompatibilitas PSR-17 §1.5; sumber menganotasinya @since 3.2.0 (hadir dalam dev line 3.1.0-aliased saat ini)

Setiap tool juga mengekspos metode deskripsi-diri ToolInterface: name, description, inputSchema, annotations, riskLevel, tier, dan category. Nilai per-tool-nya muncul di kolom Catatan di atas.

Signature entry-point, verbatim dari sumber:

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

Kontrak perilaku

• Setiap tool mengimplementasikan NextPDF\Server\Tools\ToolInterface dan mendeklarasikan ToolTier::Enterprise secara eksplisit. Tier tidak pernah disimpulkan dari namespace atau packaging.
• execute tidak melempar. Setiap kegagalan ditangkap dan dikembalikan sebagai error ToolResult yang membawa pesan kegagalan.
• Tool dokumen-tunggal me-resolve byte PDF dengan prioritas tetap. Sebuah document_id dicari lebih dulu di InMemoryDocumentStore. Jika tidak, source ditafsirkan sebagai URI data:, lalu sebagai base64 mentah (lebih dari 256 karakter), lalu sebagai path file.
• Path source filesystem dinonaktifkan secara default. Path aktif hanya saat variabel lingkungan NEXTPDF_MCP_INPUT_DIR menamai direktori input terbatas. Real path yang di-resolve harus tetap berada di dalam direktori tersebut. Selebihnya gagal secara tertutup.
• Skema stream-wrapper (phar://, php://, file://, dan skema lain apa pun) serta null byte pada source path file ditolak sebelum panggilan filesystem apa pun. Traversal dan symlink escape gagal terhadap pemeriksaan confinement real-path.
• Tool berbasis sidecar (embed_documents, search_documents, batch_compliance_check, batch_forensic_analyze) memperoleh client-nya dari SpectrumClientFactory::create. Factory memvalidasi SPECTRUM_URL non-localhost terhadap rentang alamat privat dan cadangan sebelum digunakan. Localhost eksplisit diizinkan untuk mode sidecar lokal.
• ai_ready_certify menurunkan level-nya dari empat kriteria: integritas forensik, keberadaan tanda tangan, validitas LTV, dan ketiadaan enkripsi. Keempatnya lolos menghasilkan certified; satu hingga tiga menghasilkan partial; nol menghasilkan not_certified. Integritas forensik adalah heuristik struktural atas rantai revisi, bukan verifikasi integritas-byte kriptografis. Pemeriksaan enkripsi hanya memeriksa region trailer.
• certify_ai_ready mengevaluasi tiga kriteria dan menambahkan stempel provenance XMP. Byte yang distempel dikembalikan ter-encode base64 kecuali return_stamped_pdf bernilai false atau level-nya not_certified.
• compliance_check menerima persis dua belas key policy: pdfa4, pdfa4e, pdfa4f, pades-baseline, ltv-health, eidas-qualified, zugferd, fda-part11, sec-17a4, sec-17a4-compatible, sec-17a4-structural, sec-17a4-pre-sign. Key tak dikenal mengembalikan hasil error yang menamai himpunan yang didukung.
• audit_ast_mutations hanya membaca AstAuditTrailInterface yang di-inject. Ia sendiri tidak mencatat apa pun.

Kasus tepi & mode kegagalan

• Baik document_id maupun source tidak disediakan: hasil error yang menginstruksikan pemanggil untuk menyediakan salah satunya.
• document_id tak dikenal: hasil error yang menamai ID tersebut dan mengarahkan ke create_pdf.
• source filesystem dengan NEXTPDF_MCP_INPUT_DIR tidak disetel: ditolak dengan pesan yang menamai kanal yang didukung.
• Path source yang di-resolve di luar direktori input yang dikonfigurasi, termasuk melalui symlink: ditolak. Pembandingan terjadi pada batas pemisah-direktori, sehingga direktori bersaudara yang berbagi prefiks nama tidak dapat lolos.
• URI data: tanpa pemisah koma, atau payload base64 tak valid: hasil error.
• top_k pada search_documents di luar 1–100: di-clamp, bukan ditolak. top_k non-integer kembali ke default pipeline yang dikonfigurasi.
• mode pada search_documents di luar hybrid, bm25, semantic: hasil error dari allowlist pipeline.
• Elemen documents[] pada batch_compliance_check yang kehilangan id atau path, atau membawa string kosong: hasil error yang menamai indeks yang bermasalah. batch_forensic_analyze hanya memvalidasi bentuk array terluar; cacat elemen muncul dari lapisan batch.
• SpectrumClientFactory::create dengan SPECTRUM_URL cacat, atau yang menargetkan alamat privat, link-local, atau metadata: InvalidArgumentException. Di dalam execute sebuah tool ini muncul sebagai hasil error.
• SpectrumClientFactory::createStreamFromFile pada path yang tidak dapat dibaca: McpStreamException.
• Variabel lingkungan kosong diperlakukan sebagai tidak disetel dan kembali ke default.

Kesesuaian

NextPDF tidak memegang sertifikasi dan tidak memberikan sertifikasi apa pun. Tool MCP melaporkan penilaian tingkat-kapabilitas; dukungan bukanlah kesesuaian, dan kesesuaian bukanlah sertifikasi. Nilai certification_level yang dikembalikan oleh ai_ready_certify dan certify_ai_ready adalah kosakata laporan milik tool itu sendiri. Nilai tersebut bukan atestasi pihak ketiga. Respons compliance_check menyertakan field disclaimer yang dihasilkan oleh laporan pendasarnya untuk alasan yang sama. Referensi klausa kebijakan, seperti dasar kebijakan LTV yang dinyatakan sumber produk sebagai ISO 32000-2:2020 §12.8.4.3, dibawa dalam deskripsi tool dan field clause per temuan; halaman ini tidak menambahkan klaim standar independen. Apakah suatu dokumen yang diperiksa memenuhi sebuah regulasi adalah penetapan bagi operator dan para asesornya.

Catatan pengembangan

• SpectrumClientFactory::create meng-cache satu client per proses. Panggil SpectrumClientFactory::reset di setup pengujian untuk memaksa client baru.
• Pembacaan lingkungan mengonsultasi $_ENV, lalu $_SERVER, lalu getenv, dan memperlakukan string kosong sebagai tidak ada.
• RiskLevel menggerakkan penanganan sisi-host di runtime server: Safe mengeksekusi otomatis, Caution dan di atasnya di-audit-log, dan ApprovalRequired menuntut konfirmasi manusia. Tidak ada tool MCP Enterprise yang mendeklarasikan ApprovalRequired. Override operator dapat menaikkan level yang dideklarasikan, tidak pernah menurunkannya.
• Nilai annotations (readOnlyHint, idempotentHint) adalah hint client MCP, bukan penegakan. Confinement dan validasi terjadi di sisi server terlepas dari hint.
• Tool melaporkan nilai category document atau extraction untuk pemfilteran tools/list.
• AuditAstMutationsTool adalah satu-satunya tool yang memerlukan injeksi constructor; daftarkan ia dengan implementasi AstAuditTrailInterface konkret.

Lihat juga

• MCP (halaman kapabilitas)
• Accelerator — Referensi Mendalam — permukaan client sidecar Spectrum.
• Forensics — Referensi Mendalam — analyzer di balik forensic_analyze.
• Compliance — Referensi Mendalam — kebijakan di balik compliance_check.
• AST — Referensi Mendalam — chunking dan jejak audit mutasi.
• Validation — Referensi Mendalam

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 prefiks tiket berada di luar cakupan.