Pro edisi

MCP Tools

Sekilas pandang

NextPDF Pro menambahkan delapan tool Model Context Protocol (MCP) yang memungkinkan agen AI menjalankan operasi PDF tingkat lanjut melalui NextPDF Server. Tool muncul secara otomatis ketika baik nextpdf/pro maupun nextpdf/server terpasang — tidak diperlukan langkah pendaftaran terpisah.

Ketersediaan & lisensi

Kapabilitas ini dikirimkan dalam NextPDF Pro (nextpdf/pro) dan aktif dengan amplop lisensi tingkat-Pro. Deployment tanpa hak tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Permukaan MCP dasar — pembuatan dokumen, teks, tabel, diagnostik — dikirimkan bersama NextPDF Server sumber terbuka dan tidak memerlukan lisensi. Delapan tool pada halaman ini memerlukan lisensi Pro dan mendaftar hanya ketika paket nextpdf/pro terselesaikan saat boot. Tingkat tool pro menggerbang seluruh set: setiap tool mendeklarasikan tingkatnya secara eksplisit, dan tidak ada flag per-tool — memasang nextpdf/pro di samping nextpdf/server mengaktifkan set tersebut.

Kontrak perilaku

Delapan tool MCP Pro mendaftar secara otomatis ketika baik nextpdf/pro maupun nextpdf/server terselesaikan saat boot, di bawah tingkat pro, melalui alur MCP tools/list dan tools/call standar. Tidak ada flag per-tool dan tidak ada perubahan kode di aplikasi yang mengonsumsi.
Setiap tool menerima PDF melalui document_id dari panggilan create_pdf sebelumnya, source inline (path berkas, base64, atau URI data:), atau — untuk compare_pdfs — dua sumber semacam itu. Tool mengembalikan JSON terstruktur.
Setiap tool mendeklarasikan kelas risiko HITL yang ditegakkan server: safe (eksekusi otomatis, hanya-baca), review (keluaran yang bisa disalahgunakan), dan approval-required. sign_pdf adalah approval-required dan ditahan hingga seorang manusia mengonfirmasinya. Operator hanya dapat memperketat kelas risiko sebuah tool, tidak pernah melonggarkannya.
sign_pdf hanya menghasilkan tanda tangan PAdES B-B (baseline) — tanpa trusted timestamp dan tanpa material validasi jangka panjang. Profil jangka panjang (B-LT / B-LTA), kustodi kunci perangkat keras, dan penandatanganan jejak-audit adalah tingkat Enterprise dan tidak disediakan oleh tool-tool ini; B-T (tanda tangan ber-timestamp) tersedia dari mesin Core ketika penyedia timestamp dikonfigurasi.
redact_pii melakukan deteksi dan penyamaran pola lapisan-teks, bukan penyamaran visual; check_accessibility adalah heuristik struktural, bukan vonis kesesuaian PDF/UA atau WCAG. Skema input/output yang otoritatif adalah respons tools/list langsung dari server, bukan halaman ini.

Tinjauan konseptual

NextPDF Server adalah lapisan eksekusi MCP deterministik untuk NextPDF. Ia menemukan penyedia tool saat boot menggunakan probe keberadaan-kelas, sehingga paket Pro tidak perlu dicantumkan dalam dependensi server. Ketika paket Pro hadir, server mendaftarkan delapan tool-nya di bawah tingkat pro dan memaparkannya melalui alur MCP tools/list dan tools/call standar di atas transport mana pun yang Anda konfigurasi.

Setiap tool Pro menerima PDF dari salah satu dari tiga sumber: document_id yang dikembalikan oleh panggilan create_pdf sebelumnya, source inline (path berkas, string base64, atau URI data:), atau — untuk tool perbandingan — dua sumber semacam itu. Tool mengembalikan hasil JSON terstruktur: teks terekstraksi, region diff, teks tersamarkan, pohon segmen, temuan aksesibilitas, atau PDF yang ditandatangani.

Setiap tool Pro membawa klasifikasi risiko yang digunakan server untuk penegakan human-in-the-loop (HITL). Tool analisis hanya-baca diberi peringkat safe dan tereksekusi otomatis. Tool yang menghasilkan keluaran yang dapat disalahgunakan pemanggil diberi peringkat review. Tool penandatanganan diberi peringkat approval-required, sehingga server menahannya hingga seorang manusia mengonfirmasinya. Tool itu sendiri mendeklarasikan klasifikasi ini; operator hanya dapat memperketatnya saat runtime — tidak pernah melonggarkannya.

Permukaan tool MCP secara sengaja terpisah dari mesin PDF Pro. Tool adalah adapter tipis: mereka memvalidasi input, menyelesaikan PDF, mendelegasikan ke komponen mesin Pro, dan menserialisasi hasilnya. Mereka bukan API kedua untuk mesin dan bukan bagian dari API PHP publik Pro — titik integrasi yang didukung adalah protokol MCP yang dipaparkan oleh NextPDF Server.

Katalog tool (delapan tool Pro)

Delapan tool MCP Pro, menurut nama protokol MCP. Tingkat risiko mengikuti model HITL server: safe (eksekusi otomatis, hanya-baca), review (menghasilkan keluaran yang bisa disalahgunakan; diperingatkan dalam instruksi agen), dan approval-required (harus dikonfirmasi oleh seorang manusia).

`extract_text`

Tujuan: Ekstraksi teks. Mengekstrak lapisan teks PDF, opsional dibatasi pada rentang halaman ber-indeks-1.
Input: Sebuah PDF (document_id atau source); opsional page_start dan page_end.
Keluaran: Teks terekstraksi dan total jumlah halaman.
Risiko: Safe. Hanya-baca dan idempoten.
Batas: Mengekstrak lapisan teks yang sudah ada. Tidak melakukan OCR pada halaman hasil pindai atau hanya-citra.

`segment_document`

Tujuan: Segmentasi struktural. Membagi PDF menjadi bagian-bagian logis — judul, heading, badan, tabel, gambar.
Input: Sebuah PDF (document_id atau source).
Keluaran: Jumlah segmen dan daftar segmen terstruktur.
Risiko: Safe. Hanya-baca dan idempoten.
Batas: Segmentasi struktural berdasarkan analisis tata letak; ini bukan outline semantik atau pohon struktur tagged-PDF.

`compare_pdfs`

Tujuan: Diff struktural. Membandingkan dua PDF dan mengembalikan diff terstruktur dari konten teksnya.
Input: Dua PDF (source_a dan source_b, masing-masing berupa path, base64, data URI, atau document_id).
Keluaran: Flag identik, total jumlah perubahan, jumlah halaman per-dokumen, dan daftar region yang berubah dengan indeks halaman dan baris.
Risiko: Safe. Hanya-baca dan idempoten.
Batas: Diff konten-teks. Tidak melakukan diff rendering visual, fon tertanam, atau struktur biner.

`redact_pii`

Tujuan: Deteksi dan penyamaran PII. Mendeteksi informasi yang dapat mengidentifikasi pribadi di lapisan teks PDF dan mengembalikan tampilan teks yang tersamarkan.
Input: Sebuah PDF (document_id atau source); filter types opsional (email, phone, ssn, credit_card).
Keluaran: Flag has-PII, jumlah yang terdeteksi, teks tersamarkan, dan daftar tipe yang dipindai.
Risiko: Review. Keluaran tersamarkan bisa disalahgunakan jika diperlakukan sebagai dokumen yang telah disanitasi.
Batas: Ini adalah deteksi dan penyamaran pola lapisan-teks, bukan penyamaran visual. Tidak menghapus atau menimpa glyph di PDF yang dirender, dan pencocokan pola tidak menjamin setiap instans data sensitif ditemukan. Jangan perlakukan keluarannya sebagai jaminan penghapusan PII yang lengkap. Untuk penyamaran tingkat-dokumen yang menghancurkan konten yang mendasarinya, gunakan permukaan penyamaran khusus di tool server sumber terbuka atau edisi Enterprise.

`fill_form`

Tujuan: Data pengisian AcroForm. Menghasilkan data XFDF (ISO 19444-1) yang mengisi bidang AcroForm PDF dari peta nama bidang ke nilai.
Input: Peta fields dari nama bidang ke nilai string; opsional pdf_filename yang disematkan sebagai referensi XFDF.
Keluaran: Dokumen XFDF yang dihasilkan dan jumlah bidang.
Risiko: Review. Menghasilkan data formulir yang dimaksudkan untuk diterapkan ke sebuah dokumen.
Batas: Menghasilkan XFDF yang patuh-standar; ia sendiri tidak menuliskan nilai kembali ke dalam PDF. Terapkan XFDF dengan pembaca atau tool pemroses apa pun yang patuh.

`extract_form_data`

Tujuan: Pembacaan-balik AcroForm. Mengekstrak nama dan nilai bidang AcroForm dari XFDF yang tertanam dalam PDF.
Input: Sebuah PDF (document_id atau source).
Keluaran: Jumlah bidang dan peta nama bidang ke nilai; catatan eksplisit ketika tidak ada data formulir tertanam.
Risiko: Safe. Hanya-baca dan idempoten.
Batas: Membaca stream XFDF (ISO 19444-1) tertanam. PDF yang menyimpan nilai formulir hanya di objek AcroForm tanpa XFDF tertanam mengembalikan hasil kosong.

`check_accessibility`

Tujuan: Analisis aksesibilitas struktural. Menganalisis aksesibilitas struktural PDF — heading, paragraf, tabel, dan citra — dan melaporkan kemungkinan masalah dengan referensi WCAG.
Input: Sebuah PDF (document_id atau source).
Keluaran: Skor struktural (0–100), daftar masalah, dan ringkasan segmen.
Risiko: Safe. Hanya-baca dan idempoten.
Batas: Ini adalah heuristik struktural, bukan vonis kesesuaian. Pengujian kesesuaian PDF/UA dan WCAG penuh — pohon tag, urutan baca, kontras warna — memerlukan mesin aksesibilitas khusus. Skor tinggi bukanlah pernyataan kesesuaian PDF/UA.

`sign_pdf`

Tujuan: Tanda tangan digital PAdES B-B. Menerapkan tanda tangan digital PAdES B-B (baseline) ke PDF menggunakan sertifikat X.509 lokal dan kunci privat.
Input: Sebuah PDF (document_id atau source); sertifikat PEM dan kunci privat PKCS#8; algoritma opsional (baku RSA-SHA256, RSA + SHA-3 256/384/512, atau Ed25519); nama dan alasan penanda tangan opsional; amplop transport AES-GCM opsional di sekitar payload kunci-privat.
Keluaran: PDF yang ditandatangani, jumlah tanda tangan, flag penyelesaian, serta algoritma, OID, dan digest yang digunakan.
Risiko: Approval-required. Penandatanganan adalah operasi yang signifikan secara hukum dan destruktif; server memerlukan konfirmasi manusia eksplisit sebelum ia berjalan.
Batas: Tool ini menghasilkan tanda tangan PAdES B-B (baseline) — ia tidak menyematkan trusted timestamp atau material validasi jangka panjang. Profil jangka panjang (B-LT / B-LTA), kustodi kunci berbasis perangkat keras, dan penandatanganan jejak-audit adalah bagian dari edisi Enterprise; B-T (tanda tangan ber-timestamp) tersedia dari mesin Core ketika penyedia timestamp dikonfigurasi. Lihat permukaan tanda tangan Pro untuk kapabilitas penandatanganan paket Pro yang lebih luas dan edisi Enterprise untuk B-LT/B-LTA.

Bagaimana tool muncul

composer require nextpdf/pro
composer require nextpdf/server

Dengan kedua paket terpasang, jalankan NextPDF Server dengan transport pilihan Anda. Server menemukan tingkat Pro saat boot dan delapan tool muncul dalam respons MCP tools/list di bawah tingkat pro di samping tool Core sumber terbuka. Aplikasi Anda tidak memerlukan perubahan kode — penemuan berjalan otomatis dan tingkat yang hilang tidak pernah menghalangi yang lain untuk dimuat.

Skema input dan output yang otoritatif untuk setiap tool adalah skema yang dipublikasikan server dalam respons tools/list-nya. Perlakukan respons tersebut — bukan halaman ini — sebagai kontrak: katalog ini menjelaskan maksud dan batas; skema langsung menjelaskan nama dan tipe bidang yang tepat.

Contoh kode — Quick start

Tool Pro dikonsumsi melalui protokol MCP, bukan melalui API PHP Pro. Integrasi sisi-host adalah menjalankan NextPDF Server. Dengan nextpdf/pro hadir, delapan tool mendaftar melalui penemuan saat runtime — tanpa penyambungan per-tool — dan host lalu menyajikannya ke agen.

<?php

declare(strict_types=1);

use NextPDF\Server\Mcp\McpServer;

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

// Runtime discovery registers the Pro tier when nextpdf/pro is installed
// alongside nextpdf/server. The consuming application changes no code.
$server = McpServer::create();

// A Pro tool name resolves only when the Pro package is present.
$signTool = $server->getToolRegistry()->get('sign_pdf');

\fwrite(\STDERR, $signTool !== null
    ? "Pro MCP tools active.\n"
    : "Pro MCP tools unavailable; install nextpdf/pro.\n");

// Serve the MCP protocol over stdio (Claude Desktop, Cursor, local agents).
$server->run();

Contoh kode — Produksi

Perkeras jalur boot. Muat berkas kebijakan eksplisit, tolak start pada penimpaan tingkat-risiko yang tidak valid, dan konfirmasikan tingkat Pro telah muncul sebelum menyajikan. Penyambungan di McpServer::create() melempar InvalidArgumentException ketika blok risk_level_overrides mencoba melemahkan tool approval-required seperti sign_pdf, sehingga kebijakan yang salah-konfigurasi gagal-tertutup sebelum loop penyajian.

<?php

declare(strict_types=1);

use NextPDF\Server\Mcp\McpServer;
use NextPDF\Server\Tools\ToolInterface;

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

// A downgrade of an approval-required tool's HITL gate is rejected at boot,
// never silently applied — the server refuses to start on such a policy.
try {
    $server = McpServer::create(__DIR__ . '/nextpdf-mcp.yaml');
} catch (\InvalidArgumentException $e) {
    \fwrite(\STDERR, 'Refusing to start: invalid MCP policy. ' . $e->getMessage() . "\n");
    exit(1);
}

// Confirm the Pro tier surfaced before advertising it to agents.
$signTool = $server->getToolRegistry()->get('sign_pdf');

if (!$signTool instanceof ToolInterface) {
    \fwrite(\STDERR, "nextpdf/pro is not resolving; Pro MCP tools are unavailable.\n");
    exit(1);
}

// sign_pdf is approval-required; the server holds it for human confirmation.
$risk = $signTool->riskLevel()->label();
\fwrite(\STDERR, "Pro MCP tools ready. sign_pdf risk: {$risk}.\n");

$server->run();

Panduan produksi

Penggerbangan HITL. Pertahankan sign_pdf di balik konfirmasi manusia. Server menegakkan ini dari tingkat risiko yang dideklarasikan tool; jangan konfigurasi agen Anda untuk melewatinya. Operator hanya dapat memperketat tingkat risiko sebuah tool, tidak pernah melonggarkannya.
Penanganan sumber. Utamakan document_id untuk dokumen yang sudah berada dalam sesi. Untuk data inline, tool menerima base64 dan URI data:; payload inline yang sangat besar berjalan lebih lambat daripada dokumen yang dirujuk.
Ekspektasi PII. Tetapkan ekspektasi pemanggil secara eksplisit: redact_pii adalah alat bantu deteksi-dan-penyamaran, bukan jaminan sanitasi. Untuk penghapusan tak-terbalikkan, arahkan ke permukaan penyamaran khusus.
Kunci penandatanganan. Suplai kunci melalui amplop enkripsi transport ketika transport tidak rahasia secara end-to-end. Perlakukan material kunci-privat sebagai rahasia dalam kebijakan pencatatan panggilan-tool agen Anda.
Pencatatan audit. Tool di atas tingkat safe dicatat-audit oleh server. Pastikan penerapan Anda menyimpan log tersebut sesuai persyaratan kepatuhan Anda.

Kasus tepi

Rentang halaman extract_text ber-indeks-1 dan dijepit ke jumlah halaman nyata dokumen; akhir di luar rentang tidak menimbulkan galat.
compare_pdfs memerlukan kedua sumber; memberikan satu mengembalikan galat validasi yang jelas alih-alih diff parsial.
extract_form_data mengembalikan hasil “tidak ada data formulir tertanam” yang terisi dan eksplisit alih-alih galat untuk PDF tanpa XFDF tertanam.
sign_pdf menolak pengenal algoritma yang tidak didukung dengan daftar nilai yang didukung; Ed25519 memerlukan ekstensi libsodium dan varian SHA-3 memerlukan build OpenSSL dengan dukungan SHA-3.
check_accessibility memberi skor rendah pada PDF hanya-citra secara sengaja — ia menandai ketiadaan lapisan teks yang dapat dibaca alih-alih gagal.

Catatan keamanan

Tool penandatanganan adalah satu-satunya tool approval-required; server tidak akan mengeksekusinya secara otomatis.
Amplop AES-GCM opsional di sekitar kunci privat mengautentikasi payload; ketidakcocokan tag gagal-tertutup dengan galat dekripsi dan tidak pernah jatuh ke penggunaan ciphertext.
redact_pii tidak mengubah PDF sumber; ia mengembalikan representasi teks yang tersamarkan. Ia bukan pengganti penghancuran konten.
Tool memvalidasi input sebelum pekerjaan mesin apa pun; ia menolak sumber, data URI, dan payload base64 yang malformasi dengan galat eksplisit.

Kesesuaian

Tool formulir menghasilkan dan mengonsumsi XFDF sesuai ISO 19444-1:2019 (XML Forms Data Format).
sign_pdf menghasilkan tanda tangan PAdES baseline (B-B) yang selaras dengan keluarga PAdES ETSI EN 319 142; profil jangka panjang adalah kapabilitas Enterprise, dan B-T tersedia dari mesin Core ketika penyedia timestamp dikonfigurasi.
check_accessibility melaporkan temuan dengan referensi success-criterion WCAG (misalnya 1.1.1, 1.3.1, 2.4.6) sebagai panduan heuristik, bukan atestasi kesesuaian.

Batas edisi

NextPDF Pro berkontribusi tepat delapan tool MCP, semuanya pada tingkat pro. Edisi Enterprise mengirimkan set tool MCP-nya sendiri yang terpisah pada tingkat enterprise — mencakup pemeriksaan kepatuhan, analisis forensik, kesehatan validasi-jangka-panjang, sertifikasi AI-ready, serta pencarian dan embedding dokumen. Tool-tool itu, input-nya, dan internal-nya berada di luar cakupan halaman ini; lihat Tool MCP Enterprise. Dokumentasi server itu sendiri mencakup tool Core (sumber terbuka) yang dikirimkan bersamanya. Server menemukan ketiga tingkat secara independen, dan tingkat yang hilang tidak pernah menonaktifkan yang lain.

Catatan batas Enterprise

Pro berkontribusi tepat delapan tool MCP pada tingkat pro. Edisi Enterprise mengirimkan set tool MCP terpisah pada tingkat enterprise (pemeriksaan kepatuhan, analisis forensik, kesehatan validasi-jangka-panjang, sertifikasi AI-ready, pencarian dan embedding dokumen) serta profil tanda tangan ber-timestamp/jangka-panjang; semua itu tidak disediakan oleh tingkat Pro. Lihat bagian Batas edisi di atas untuk rincian tingkat lengkap.

Fallback / alternatif Core

NextPDF Server sumber terbuka memberi setiap agen AI perangkat tool PDF Core yang deterministik (pembuatan dokumen, teks, tabel, diagnostik) tanpa lisensi. Delapan tool tingkat lanjut pada halaman ini adalah tambahan Pro. Lihat /connect/tools/.

Batas publikasi

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