Pro edisi

MCP Tools — Referensi Mendalam

Ketersediaan & lisensi

Kapabilitas ini dikirimkan dalam NextPDF Pro (nextpdf/pro) dan diaktifkan dengan amplop lisensi tier Pro. Sebuah penerapan tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Tidak ada bendera lisensi per-fitur. Kode dikirimkan bersama edisi Pro, dan kedelapan perkakas teregistrasi di bawah tier pro ketika paket Pro teresolusi saat boot berdampingan dengan nextpdf/server.

Kontrak perilaku

NextPDF Server menemukan tier saat boot dengan memprobing kelas penyedia perkakas Pro; jika teresolusi, server meregistrasi kedelapan perkakas di bawah tier pro. Paket Pro bukan dependensi keras dari server, sehingga perkakas Pro bersifat opt-in penuh melalui ko-instalasi. Registrasi tier bersifat independen: tier yang hilang atau dikecualikan kebijakan tidak pernah memblokir tier lainnya.
Setiap perkakas mendeklarasikan salah satu dari empat tingkat risiko (safe, caution, review, approval-required). Override operator opsional hanya dapat menaikkan tingkat sebuah perkakas, tidak pernah menurunkannya; server mencatat audit setiap eksekusi pada tingkat caution atau lebih tinggi. sign_pdf bersifat approval-required.
Masukan PDF teresolusi dalam urutan tetap: document_id dari penyimpanan in-memory, lalu source sebagai sebuah data: URI, jalur sistem berkas, atau base64 mentah. Masukan yang hilang mengembalikan galat validasi alih-alih memproses dokumen kosong.
sign_pdf menghasilkan tanda tangan baseline PAdES B-B saja — tanpa stempel waktu, tanpa validasi jangka panjang. Algoritma yang didukung dan amplop key-transport AES-GCM dirinci di bawah; dekripsi gagal-tertutup dan perkakas tidak pernah menggunakan ciphertext sebagai materi kunci.
Lihat bagian di bawah untuk detail penuh tentang penemuan, risiko, resolusi sumber, per-perkakas, dan penandatanganan. Halaman ini hanya menjelaskan perilaku yang dapat diamati secara eksternal dan kontrak perkakas yang dipublikasikan.

Cakupan

Halaman ini adalah referensi operator dan integrator untuk kedelapan perkakas MCP Pro. Halaman ini mencakup model penemuan, semantik risk/HITL yang diterapkan server, aturan resolusi sumber, amplop key-transport penandatanganan, dan perilaku kegagalan per-perkakas. Halaman ini menjelaskan perilaku yang dapat diamati secara eksternal dan kontrak perkakas yang dipublikasikan saja. Untuk katalog yang berorientasi pengguna, lihat halaman MCP publik.

Model penemuan dan registrasi

NextPDF Server menemukan penyedia tier saat boot. Ia mendeteksi tier Pro dengan memprobing kelas penyedia perkakas Pro; jika kelas teresolusi, server menginstansiasi penyedia dan meregistrasi setiap perkakas yang dikembalikannya di bawah tier pro. Paket Pro secara sengaja bukan dependensi keras dari server — ini menjaga server sumber terbuka tetap dapat dipasang tanpa paket berpemilik, dan menjadikan perkakas Pro bersifat opt-in penuh melalui ko-instalasi.

Server mengisolasi registrasi per tier. Jika paket Pro tidak ada, perkakas Core tetap teregistrasi; penyedia tier yang hadir tidak memblokir tier lainnya. Registrasi perkakas juga tunduk pada daftar-izin kebijakan keamanan server: perkakas yang dikecualikan oleh kebijakan secara diam-diam tidak teregistrasi dan tidak dihitung dalam ringkasan tier. Server mengekspos hitungan per-tier (core / pro / enterprise) untuk diagnostik dan logging.

Penyedia mengembalikan kedelapan perkakas dalam urutan tetap: ekstraksi teks, segmentasi, perbandingan, penyamaran PII, pengisian formulir, pembacaan ulang formulir, analisis aksesibilitas, penandatanganan. Urutan stabil tetapi pemanggil tidak boleh bergantung padanya — resolusikan perkakas berdasarkan nama protokol MCP-nya.

Model risiko dan semantik HITL

Setiap perkakas mendeklarasikan salah satu dari empat tingkat risiko. Server menggunakan tingkat yang dideklarasikan untuk penegakan human-in-the-loop:

Safe — hanya-baca, tanpa efek samping. Tereksekusi otomatis.
Caution — membuat atau memodifikasi keadaan in-memory. Tereksekusi otomatis dengan sebuah entri audit-log.
Review — menghasilkan keluaran yang dapat disalahgunakan. Tereksekusi otomatis, tetapi instruksi skill agen menandainya sehingga agen memperingatkan pengguna.
Approval-required — destruktif, legal, atau kritis-privasi. Server memerlukan konfirmasi manusia eksplisit sebelum eksekusi.

Klasifikasi perkakas Pro: kelima perkakas ekstraksi/analisis (extract_text, segment_document, compare_pdfs, extract_form_data, check_accessibility) bersifat safe; redact_pii dan fill_form bersifat review; sign_pdf bersifat approval-required.

Tingkat risiko berasal dari tepat dua sumber: deklarasi perkakas itu sendiri, dan override operator opsional saat runtime. Override hanya dapat menaikkan tingkat risiko sebuah perkakas (memperketat penegakan); ia tidak pernah dapat menurunkannya. Server mencatat audit setiap eksekusi pada tingkat caution atau lebih tinggi. Model risiko membawa sebuah versi; server mengiklankan versi itu dalam respons inisialisasinya sehingga klien dapat mendeteksi perubahan yang tidak kompatibel.

Urutan resolusi sumber

Setiap perkakas yang menerima PDF menerimanya melalui salah satu dari tiga bentuk masukan, yang teresolusi dalam urutan ini:

document_id — server mengambil byte dari penyimpanan dokumen in-memory-nya. Id yang tidak dikenal gagal dengan galat eksplisit yang mengarahkan pemanggil untuk membuat dokumen terlebih dahulu.
source sebagai sebuah data: URI — perkakas mendekode badan base64 setelah tanda koma.
source sebagai jalur sistem berkas — perkakas membaca dari disk ketika jalur teresolusi ke sebuah berkas.
source sebagai string base64 mentah — perkakas menerima dan mendekode hanya masukan yang cukup panjang dan berbentuk base64.

compare_pdfs menerapkan resolusi yang sama secara independen pada source_a dan source_b, dan tambahan menerima sebuah nilai document_id di salah satu slot sumber. Jika baik document_id maupun source tidak disuplai, perkakas mengembalikan galat validasi alih-alih memproses dokumen kosong.

Referensi per-perkakas

Tool	Risk	Inputs	Result fields	Behavioral boundary
`extract_text`	safe	PDF; `page_start` / `page_end` opsional berindeks-1	teks, jumlah halaman total	Hanya lapisan-teks; rentang dijepit ke jumlah halaman nyata; tanpa OCR
`segment_document`	safe	PDF	jumlah segmen, daftar segmen	Segmen turunan-tata-letak; bukan pohon struktur PDF bertanda
`compare_pdfs`	safe	dua PDF	bendera identik, total perubahan, jumlah halaman per-dokumen, wilayah (tipe, teks, indeks halaman, indeks baris, teks rekan opsional)	Diff konten-teks; bukan visual atau biner
`redact_pii`	review	PDF; `types` opsional (`email`, `phone`, `ssn`, `credit_card`)	bendera ada-PII, jumlah terdeteksi, teks tersamarkan, tipe terpindai	Deteksi/penyamaran lapisan-teks; bukan penyamaran visual; berbasis pola, tidak menyeluruh
`fill_form`	review	map `fields`; `pdf_filename` opsional	dokumen XFDF, jumlah bidang	Menghasilkan XFDF (ISO 19444-1); tidak menulis nilai ke dalam PDF
`extract_form_data`	safe	PDF	jumlah bidang, map bidang, catatan eksplisit saat tidak ada	Membaca XFDF tersemat saja
`check_accessibility`	safe	PDF	skor struktural (0–100), isu, ringkasan segmen	Heuristik struktural dengan referensi WCAG; bukan vonis kesesuaian
`sign_pdf`	approval-required	PDF; sertifikat PEM + kunci PKCS#8; algoritma opsional, nama penandatangan, alasan, amplop transport	PDF tertandatangani, jumlah tanda tangan, bendera selesai, algoritma, OID, digest	Hanya baseline PAdES B-B; tanpa stempel waktu, tanpa LTV

Penandatanganan: algoritma dan transport kunci

sign_pdf menghasilkan tanda tangan baseline PAdES B-B. Algoritma yang didukung, diterima baik dalam ejaan bergaris-bawah maupun bertanda-hubung:

RSA dengan SHA-256 (bawaan).
RSA dengan SHA-3 256 / 384 / 512 — memerlukan build OpenSSL dengan dukungan SHA-3.
Ed25519 — memerlukan ekstensi libsodium; kunci harus berupa PEM PKCS#8 yang membungkus kunci privat Ed25519.

Perkakas menolak pengidentifikasi yang tidak didukung dan mengembalikan daftar nilai yang diterima.

Amplop enkripsi-transport opsional memungkinkan pemanggil menerowongkan kunci privat melalui sebuah transport yang tidak rahasia ujung-ke-ujung. Amplop ini hanya AES-GCM:

Kunci simetris: 16, 24, atau 32 byte (AES-128/192/256), terenkode base64.
Nonce: tepat 12 byte, terenkode base64.
Data terautentikasi tambahan opsional, terenkode base64.
Muatan private_key adalah ciphertext base64 dengan tag autentikasi GCM 16-byte di akhir.

Dekripsi gagal-tertutup: ketidakcocokan tag-autentikasi atau muatan yang cacat mengembalikan sebuah galat dekripsi, dan perkakas tidak pernah menggunakan ciphertext sebagai materi kunci. Perkakas menolak ukuran kunci atau nonce yang salah sebelum kerja kriptografis apa pun.

Kasus tepi dan mode FIPS

extract_text: perkakas menjepit ujung rentang-halaman yang melampaui dokumen alih-alih menolaknya, dan menormalkan awal di bawah halaman pertama menjadi halaman pertama.
compare_pdfs: source_a atau source_b yang hilang mengembalikan galat validasi; dokumen identik mengembalikan hasil identik eksplisit dengan nol perubahan.
extract_form_data: PDF tanpa stream XFDF tersemat mengembalikan hasil nol-bidang dengan catatan penjelasan, bukan galat.
redact_pii: entri yang tak dikenal dalam types diabaikan; daftar yang semuanya tak dikenal menghasilkan pemindaian kosong alih-alih kegagalan.
sign_pdf: sertifikat atau kunci privat yang hilang gagal sebelum kerja penandatanganan apa pun; perkakas memeriksa persyaratan algoritma (dukungan SHA-3 OpenSSL, libsodium untuk Ed25519) pada saat penandatanganan dan menampilkannya sebagai galat eksplisit.
Mode FIPS: ketersediaan algoritma mengikuti build OpenSSL/libsodium host. Dalam build yang dibatasi FIPS, algoritma yang tidak disetujui gagal pada batas kriptografis dengan galat eksplisit alih-alih menurunkan tingkat secara diam-diam. Lapisan MCP tidak menambah atau melonggarkan kebijakan kriptografis — ia menampilkan keputusan penyedia kripto host.

Catatan runbook operator

Pertahankan sign_pdf tetap approval-required. Pastikan tidak ada override operator yang menaikkan risiko pada perkakas safe secara tidak sengaja — override hanya memperketat, sehingga override yang tidak disengaja menurunkan ketersediaan, bukan keamanan.
Retensi audit: setiap eksekusi pada tingkat review atau lebih tinggi dicatat audit oleh server. Ukur retensi log Anda untuk volume panggilan redact_pii, fill_form, dan sign_pdf.
Pilihan transport: ketika berjalan di atas transport yang tidak rahasia ujung-ke-ujung, wajibkan amplop key-transport AES-GCM untuk sign_pdf dan perlakukan materi kunci-privat sebagai rahasia dalam kebijakan logging panggilan-perkakas agen Anda.
Hitungan tier: gunakan hitungan per-tier server untuk menegaskan saat penerapan bahwa tier Pro meregistrasi delapan perkakas; hitungan nol menandakan paket Pro tidak teresolusi.

Batas edisi

Tier Pro menyumbang tepat delapan perkakas MCP. Edisi Enterprise mengirimkan tier MCP terpisah dengan perkakasnya sendiri — kepatuhan, forensik, kesehatan validasi-jangka-panjang, sertifikasi siap-AI, dan pencarian/embedding dokumen. Masukan, keluaran, dan internal perkakas Enterprise berada di luar cakupan di sini dan didokumentasikan bersama edisi Enterprise. Server menemukan tier secara independen; tier yang hilang tidak pernah menonaktifkan tier lain.

Batas publikasi

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