Katalog tool NextPDF Connect

Sekilas

NextPDF Connect tidak mengekspos jumlah tool tetap. Server menghitung jumlahnya saat runtime berdasarkan paket yang terpasang, allowlist konfigurasi, dan gate lingkungan. Halaman ini mendokumentasikan set inti yang terverifikasi serta cara total tersebut ditentukan.

Pemasangan

composer require nextpdf/server

Tinjauan konseptual

NextPDF\Server\ToolRegistry membangun katalog saat boot dalam urutan berikut:

Tier inti. Sekumpulan tool inti selalu terdaftar tanpa syarat. Dua tool tambahan hanya terdaftar ketika prasyaratnya terpenuhi.
Tier Pro. Tool Pro terdaftar ketika kelas provider Pro berhasil diresolusi, yang terjadi saat nextpdf/premium terpasang. Server melewati langkah ini tanpa pesan ketika kelas tersebut tidak dapat diresolusi.
Tier Enterprise. Provider Enterprise mengikuti pola yang sama dengan provider Pro.
Tier diperluas bawaan. Provider tool AST dan mutation disertakan dalam paket server dan terdaftar di bawah tier Pro. Gate lingkungan mengendalikan setiap provider, dan setiap provider menurun secara wajar ketika dukungan inti yang menjadi landasannya tidak tersedia.
Filter kebijakan keamanan. Server menginterseksi setiap registrasi dengan allowlist enabled_tools. Allowlist yang tidak kosong akan menghilangkan tool apa pun yang tidak tercantum di dalamnya. Jumlah per tier hanya menyertakan tool yang diizinkan oleh kebijakan.

Respons initialize Model Context Protocol (MCP) melaporkan tool_count yang dihasilkan beserta jumlah per tier untuk server yang sedang berjalan. Nilai tersebut bersifat otoritatif. Anggap total tetap apa pun yang muncul dalam prosa sebagai usang.

Permukaan API

Tool inti terverifikasi yang selalu tersedia

Kedua belas tool ini selalu terdaftar di tier inti. Server mengambil setiap tingkat risiko dan setiap petunjuk perilaku MCP dari implementasi tool tersebut.

Nama tool	Kategori	Deskripsi	Risiko
`create_pdf`	document	Membuat dokumen PDF dan mengembalikan `document_id`	caution
`add_text`	document	Menambahkan konten teks ke dokumen PDF	caution
`add_image`	document	Menambahkan gambar dari path berkas atau data base64	caution
`add_table`	document	Menambahkan tabel HTML ke dokumen PDF	caution
`set_font`	document	Menetapkan font untuk operasi teks berikutnya	caution
`add_page`	document	Menambahkan halaman baru ke dokumen PDF	caution
`output_pdf`	document	Memfinalkan PDF sebagai berkas atau base64	approval_required
`preview_layout`	document	Mengembalikan ringkasan tata letak JSON tanpa melakukan rendering	safe
`diagnostic.doctor`	diagnostic	Menjalankan pemeriksaan kesehatan dan diagnostik lingkungan terstruktur	safe
`diagnostic.capabilities`	diagnostic	Menampilkan daftar kapabilitas beserta tier dan statusnya	safe
`diagnostic.inspect`	diagnostic	Memeriksa PDF dan mengembalikan metadata struktural	safe
`diagnostic.verify`	diagnostic	Memverifikasi integritas PDF dengan pemeriksaan PDF/A atau PDF/UA opsional	caution

Tool inti yang terdaftar secara bersyarat

Nama tool	Kondisi
`generate_barcode`	Terdaftar ketika `nextpdf/core` yang terpasang menyertakan registri encoder barcode inti
`parse_pdf`	Terdaftar hanya ketika `NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED` bernilai `true` atau `1`

output_pdf adalah satu-satunya tool inti pada tingkat risiko approval_required. Penulisan berkas harus melalui gate human-in-the-loop; keluaran base64 tidak. Lihat /connect/hitl-risk-tiers/.

Tool yang ditambahkan hanya ketika paket tambahan terpasang

Server memeriksa kelas provider menggunakan class_exists():

Tool Pro terdaftar ketika nextpdf/premium terpasang dan provider Pro berhasil diresolusi.
Tool Enterprise terdaftar ketika nextpdf/premium terpasang dan provider Enterprise berhasil diresolusi. Tool privasi (redaksi, de-identifikasi, redaksi zona) membungkus kelas Enterprise. Tool tersebut terdaftar di bawah tier Enterprise hanya ketika kelas-kelas itu dapat di-autoload.
Tool AST dan mutation disertakan bersama server dan terdaftar di bawah tier Pro. Gate NEXTPDF_AST_TOOLS_ENABLED dan NEXTPDF_MUTATION_TOOLS_ENABLED mengendalikannya, dan kedua gate aktif secara default.

Paket Premium, bukan server, yang mendefinisikan inventaris tool Pro dan Enterprise secara tepat serta mendokumentasikannya bersama paket tersebut. Kontrak server adalah mekanisme registrasi, bukan daftar Premium yang tetap.

Contoh kode — Mulai cepat

Cetak daftar tool yang diekspos oleh instalasi ini tanpa menjalankan server:

./vendor/bin/generate-skills --dry-run --list-tools

Contoh kode — Produksi

Kueri server yang sedang berjalan untuk mendapatkan jumlah yang otoritatif melalui MCP:

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"c","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
EOF

Server menghitung capabilities.nextpdf.tool_count dan tiers dalam hasil initialize untuk proses yang sedang berjalan. Melalui REST, GET /api/v1/capabilities mengembalikan data introspeksi yang setara.

Kasus khusus dan jebakan

Tidak ada “33 tool” yang tetap — atau total tetap apa pun. Materi lama menyebut satu angka, tetapi angka itu bukan kontrak. Jumlahnya berubah mengikuti paket yang terpasang, allowlist enabled_tools, serta gate lingkungan parse_pdf, AST, dan mutation. Selalu baca nilainya dari server yang sedang berjalan.
Allowlist mengurangi, tidak pernah menambah. Mencantumkan tool Pro di enabled_tools tidak akan membuatnya terdaftar ketika nextpdf/premium tidak ada.
Tier yang hilang bersifat senyap dan memang diharapkan. Instalasi yang hanya open source menyajikan set inti dan melaporkan nol tool Pro dan nol tool Enterprise. Hasil tersebut merupakan operasi yang benar, bukan kesalahan.
Tier dalam katalog adalah invariant yang dideklarasikan. Setiap tool mendeklarasikan tier dan risikonya sendiri di dalam kode. Registry tidak pernah menyimpulkan tier dari namespace atau paket.

Performa

Pemindaian registry dan deteksi tier berjalan sekali saat boot. performance_budget halaman menetapkan batas untuk keduanya. Biaya per tool berasal dari operasi engine yang mendasarinya, bukan dari pencarian katalog, yang bersifat O(1) berdasarkan nama tool.

Catatan keamanan

Gunakan enabled_tools sebagai kontrol hak akses minimal: ekspos hanya tool yang dibutuhkan oleh integrasi. Katalog tidak pernah menyertakan tool yang ditolak oleh kebijakan keamanan, dan jumlah per tier hanya mencerminkan tool yang diizinkan. Tool berisiko tinggi tetap dijaga oleh konfirmasi manusia terlepas dari keanggotaannya dalam katalog. Lihat /connect/security-and-operations/.

Kesesuaian

Halaman ini menjelaskan mekanisme registry. Kutipan protokol untuk permukaan tools/list dan initialize tersedia di /transports/mcp/. Model risiko dispesifikasikan di /connect/hitl-risk-tiers/.

Konteks komersial

Katalog inti mencakup pembuatan, pemeriksaan, dan diagnostik. Tool penandatanganan, redaksi, kepatuhan, dan forensik hanya muncul ketika nextpdf/premium terpasang bersama server. Batasan pemaketan ini diterapkan pada saat composer require, tidak pernah melalui prompt runtime.

Lihat juga

/connect/hitl-risk-tiers/ — arti kolom risiko dan cara kerja penegakannya
/connect/boot-and-discovery/ — urutan boot dan penemuan lengkap
/connect/configuration/ — enabled_tools dan gate lingkungan
/transports/mcp/ — tools/list dan initialize sebagai format wire
/connect/overview/ — alasan katalog bergantung pada runtime secara desain