Integrasi NextPDF Connect

Sekilas pandang

Integrasikan NextPDF Connect dengan menjalankannya sebagai server. Anda tidak menyambungkan pustaka ke aplikasi host. Pilih transport, lalu konfigurasikan autentikasi untuk setiap transport yang terhubung ke jaringan. Alat mesin tetap berada di balik gerbang konfirmasi.

Instalasi

composer require nextpdf/server

Batasan Composer adalah nextpdf/core: ^3.0 dengan php: >=8.4 <9.0. Untuk penyiapan opsional ext-redis dan nextpdf/premium, lihat /connect/install/.

Gambaran konseptual

Paket ini berjalan sebagai layanan mandiri. Anda tidak mendaftarkan service provider, bundle, atau modul container di dalam framework host. Titik integrasinya adalah proses yang Anda jalankan. Setiap transport memiliki titik masuknya sendiri dan melakukan boot secara independen. Lihat /connect/boot-and-discovery/.

Permukaan API

Titik masuk	Transport	Profil
bin/nextpdf-mcp	MCP melalui stdio	(tidak ada — subproses langsung)
bin/nextpdf-server	REST melalui RoadRunner HTTP	.rr.yaml
bin/nextpdf-grpc	gRPC melalui RoadRunner gRPC	.rr.grpc.yaml
kedua transport yang terhubung jaringan	REST + gRPC	.rr.full.yaml

Boot dan penemuan otomatis

Registry selalu menemukan tingkat core. Setelah itu, registry menambahkan provider Pro dan Enterprise ketika kelas-kelasnya berhasil di-resolve, lalu provider abstract syntax tree (AST) dan mutation yang dikemas di balik gerbang lingkungan. Daftar izin keamanan enabled_tools memfilter semuanya, sehingga katalog yang dipaparkan adalah katalog milik deployment ini. Lihat /connect/tool-catalog/ dan /connect/boot-and-discovery/.

Pengikatan container

Tidak ada. Setiap factory server membangun graf objeknya sendiri secara eksplisit. Titik penyisipan yang dapat diinjeksikan mendukung pengujian, bukan penyambungan aplikasi.

Publikasikan konfigurasi

Server MCP menerima berkas YAML opsional (--config=PATH, bagian nextpdf_mcp) dan override lingkungan NEXTPDF_MCP_*. Server REST dan gRPC membaca variabel lingkungan NEXTPDF_*. Untuk detailnya, lihat /connect/configuration/.

Ketersediaan transport (MCP / REST / gRPC)

Ketiga transport melayani registry yang sama:

• MCP — subproses lokal, JSON-RPC 2.0 melalui stdio, tanpa kunci API, revisi MCP 2025-06-18. Lihat /transports/mcp/.
• REST — kumpulan worker HTTP RoadRunner, kontrak OpenAPI 3.1, kunci API bearer, rute yang dibatasi per tingkat. Lihat /transports/rest/.
• gRPC — kumpulan worker gRPC RoadRunner, layanan Protobuf nextpdf.connect.v1, RPC dengan server-streaming, autentikasi bearer dalam metadata, mutual TLS pada profil gabungan. Lihat /transports/grpc/.

Sebuah transport dianggap “tersedia” ketika titik masuk atau profil RoadRunner-nya sedang berjalan. Transport tidak saling memulai secara otomatis.

HITL: tingkat risiko

Setiap alat mendeklarasikan salah satu dari empat tingkat risiko: safe, caution, review, approval_required. Alat pada tingkat approval_required tidak berjalan pada pemanggilan pertama. Gerbang konfirmasi menerbitkan token tantangan sekali pakai yang harus diotorisasi oleh manusia. Override konfigurasi hanya boleh menaikkan risiko alat, tidak pernah menurunkan alat approval_required. Model ini berlaku sama pada setiap transport yang menjalankan alat. Lihat /connect/hitl-risk-tiers/.

Amplop JSON gerbang konfirmasi

Pemeriksaan gerbang mengembalikan salah satu dari dua bentuk JSON. Diizinkan:

{ "allowed": true }

Tantangan:

{
  "allowed": false,
  "challenge": "<human-readable text naming the operation, its description, an overwrite warning when applicable, and the re-invocation instruction>",
  "token": "confirm_<nonce>"
}

Token tersebut mengikat nama alat, nonce acak, dan TTL 300 detik, bukan argumennya. Untuk melanjutkan, pemanggil menjalankan ulang alat yang sama dengan argumen _confirmation_token yang disetel ke token yang diterbitkan. Tantangan ini berupa teks instruksional biasa plus token; ini bukan amplop yang ditandatangani secara kriptografis. Lihat /connect/hitl-risk-tiers/.

Uji asap layanan

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

Perintah ini mem-boot registry dan deteksi tingkat, lalu mencetak alat yang dipaparkan tanpa melayani lalu lintas. Gunakan perintah ini untuk memastikan integrasi telah tersambung dan memeriksa katalog yang dihasilkan instalasi ini.

Kasus pinggiran dan jebakan

• Tidak ada hook framework. Jangan mencari service provider atau bundle. Proses yang berjalan itulah integrasinya.
• Tingkat yang tidak ada bukanlah kesalahan. Instalasi core-saja akan boot dan melayani katalog core-nya.
• Transport yang terhubung ke jaringan memerlukan kunci. Hanya /healthz dan /readyz (REST) serta RPC kesehatan (gRPC) yang bersifat anonim.

Kinerja

Biaya boot adalah pemindaian registry dan deteksi tingkat, sekali per proses. Biaya per permintaan adalah operasi mesin. Tentukan ukuran kumpulan worker RoadRunner berdasarkan latensi render yang diamati. Lihat /connect/production-usage/.

Catatan keamanan

Transport yang terhubung ke jaringan melakukan autentikasi dengan kunci bearer npk_live_ yang divalidasi dalam waktu konstan; gerbang menegakkan konfirmasi manusia untuk operasi destruktif, terlepas dari transport yang digunakan. Terminasikan TLS di depan REST, dan gunakan mutual TLS untuk gRPC pada jaringan yang tidak tepercaya. Lihat /connect/security-and-operations/.

Konformansi

Kutipan protokol dan keamanan disematkan pada /transports/mcp/, /transports/rest/, /transports/grpc/, dan /connect/security-and-operations/.

Konteks komersial

Pasang nextpdf/premium bersama server untuk mendaftarkan alat Pro dan Enterprise tambahan di server berjalan yang sama. Tidak ada proses terpisah yang terlibat.

Lihat juga

• /connect/overview/ — arsitekturnya
• /connect/quickstart/ — pertukaran pertama yang dapat dijalankan
• /transports/mcp/ · /transports/rest/ · /transports/grpc/ — referensi per transport
• /connect/hitl-risk-tiers/ — gerbang konfirmasi secara terperinci
• /connect/tool-catalog/ — katalog yang bergantung pada runtime
• /connect/security-and-operations/ — autentikasi dan model ancaman