Ikhtisar server NextPDF Connect

Sekilas pandang

NextPDF Connect adalah paket nextpdf/server, yaitu layanan yang berjalan terus-menerus untuk mengekspos mesin PDF 2.0 NextPDF kepada agen AI dan klien HTTP. Layanan ini mendukung tiga transport: Model Context Protocol (MCP) di atas stdio, REST API, dan gRPC. Ketiga transport tersebut berbagi satu registri tool dan satu gerbang konfirmasi human-in-the-loop (HITL).

Instalasi

composer require nextpdf/server

Batasan Composer-nya adalah nextpdf/core: ^3.0 dengan php: >=8.4 <9.0. Untuk prosedur lengkap, lihat /connect/install/. Halaman tersebut juga membahas dua add-on opsional: ekstensi ext-redis dan paket nextpdf/premium.

Ikhtisar konseptual

nextpdf/server mengadaptasi core NextPDF yang agnostik terhadap framework menjadi permukaan layanan. Paket ini tidak membangun ulang proses pembuatan PDF. Sebaliknya, paket ini membungkus setiap kapabilitas mesin sebagai tool bernama yang memiliki skema sendiri, lalu menyajikan katalog tersebut melalui beberapa protokol wire.

Tiga konsep menjadi fondasi keseluruhan desain ini:

• Registri tool. NextPDF\Server\ToolRegistry menemukan dan mendaftarkan tool saat boot. Satu set inti disertakan bersama paket dan selalu tersedia. Penyedia Pro dan Enterprise mendaftarkan lebih banyak tool, tetapi hanya ketika paket yang sesuai terpasang. Jumlah tool yang diekspos adalah properti runtime deployment, bukan konstanta tetap. Lihat /connect/tool-catalog/.

• Transport. Registri yang sama disajikan dengan tiga cara. MCP berjalan di atas stdio untuk klien AI lokal. REST berjalan di atas pipeline middleware PSR-15 pada pool worker RoadRunner untuk klien jaringan. gRPC berjalan pada worker gRPC Spiral RoadRunner untuk klien bertipe dan streaming. Setiap transport adalah proses tersendiri dengan entry point tersendiri. Lihat /transports/mcp/, /transports/rest/, dan /transports/grpc/.

• Gerbang konfirmasi. Setiap tool mendeklarasikan tingkat risiko. Tool pada tingkat tertinggi memerlukan konfirmasi manusia yang eksplisit sebelum dijalankan. Gerbang ini menerbitkan token tantangan sekali pakai. Agen harus menyerahkan token tersebut kepada manusia, lalu memanggil tool tersebut kembali dengan token itu. Lihat /connect/hitl-risk-tiers/.

Diagram di bawah ini menunjukkan bagaimana satu registri melayani tiga transport. Diagram ini juga menunjukkan di mana gerbang konfirmasi berada dalam jalur permintaan.

NextPDF Connect component architecture

Paket ini berlisensi Apache-2.0, selaras dengan nextpdf/core. Versi protokol MCP yang diimplementasikan adalah revisi bertanggal 2025-06-18. Dokumen OpenAPI 3.1 menjelaskan permukaan REST. Paket Protocol Buffers nextpdf.connect.v1 menjelaskan permukaan gRPC.

Permukaan API

Entry point publiknya terdiri dari tiga kelas server. Masing-masing memiliki pembungkus antarmuka baris perintah (CLI):

Entry point	Kelas	Transport
bin/nextpdf-mcp	NextPDF\Server\Mcp\McpServer	MCP di atas stdio
bin/nextpdf-server	NextPDF\Server\Http\HttpServer	REST di atas RoadRunner HTTP
bin/nextpdf-grpc	NextPDF\Server\Grpc\GrpcServer	gRPC di atas RoadRunner gRPC
bin/generate-skills	NextPDF\Server\Skills\SkillsDumper	Ekspor katalog tool

McpServer::create(), HttpServer::create(), dan GrpcServer::create() masing-masing membangun server yang terkonfigurasi penuh dari masukan environment dan konfigurasi. Registri, document store, kebijakan keamanan, dan gerbang konfirmasi merupakan konsep bersama di ketiga server tersebut.

Contoh kode — Mulai cepat

Server MCP minimal hanya memerlukan satu perintah. Anda tidak perlu menulis kode glue PHP apa pun:

./vendor/bin/nextpdf-mcp

Server membaca permintaan JSON-RPC dari standard input dan menulis respons ke standard output. Untuk pertukaran initialize dan tools/list yang dapat dijalankan, serta permintaan REST yang sesuai, lihat /connect/quickstart/.

Kasus tepi dan jebakan

• Jumlah tool bukan 33, atau angka tetap lainnya. Server menghitung tool saat runtime sebagai count(ToolRegistry::all()), setelah pemfilteran kebijakan dan deteksi tier. Dokumentasi yang mengutip total tetap sudah usang. Untuk memperoleh jumlah yang otoritatif, kueri server yang sedang berjalan. Gunakan respons MCP initialize, atau endpoint REST /api/v1/capabilities.

  Jangan hard-code jumlah tool

  Jumlah tool yang diekspos bergantung pada paket yang terpasang dan kebijakan yang aktif. Bacalah dari server yang sedang berjalan saat runtime. Angka tetap di dalam kode atau dokumentasi Anda akan menjadi kedaluwarsa.

• Paket Pro atau Enterprise yang hilang bukanlah kesalahan. Registri memeriksa kelas penyedia dengan class_exists(), lalu melewati secara diam-diam tier mana pun yang tidak ada. Deployment khusus open-source tetap boot dan menyajikan katalog intinya secara normal.

• Ketiga transport tidak berbagi satu proses. Menjalankan server MCP tidak memulai server REST atau server gRPC. Hal sebaliknya juga berlaku. Deployment gabungan menjalankan supervisor RoadRunner dengan konfigurasi yang memulai kedua pool worker: pool HTTP dan pool gRPC. Lihat /connect/deployment/.

Kinerja

Setiap transport berbasis worker. Satu worker menangani satu permintaan pada satu waktu. Server REST dan gRPC berjalan pada pool worker RoadRunner, dan konfigurasi menetapkan ukuran pool. Standarnya adalah empat worker HTTP. Supervisor RoadRunner membatasi memori setiap worker. Front-matter performance_budget pada halaman ini menjelaskan batas cold boot dan discovery. Ini bukan target per permintaan. Operasi mesin yang mendasarinya menyumbang sebagian besar biaya permintaan.

Catatan keamanan

Semua transport jaringan melakukan autentikasi dengan token bearer kunci API. Transport stdio MCP adalah subproses lokal yang dipercaya oleh klien yang meluncurkannya, sesuai dengan model transport MCP. Tool berisiko tinggi tetap berada di balik gerbang konfirmasi manusia pada setiap transport. Untuk model ancaman lengkap, model autentikasi, dan konfigurasi keamanan transport, lihat /connect/security-and-operations/.

Transport stdio MCP mengandalkan kepercayaan lokal

Transport stdio MCP tidak membawa token bearer. Transport ini berjalan sebagai subproses lokal, dan klien yang meluncurkannya memiliki batas kepercayaan tersebut. Terapkan model autentikasi jaringan hanya pada transport REST dan gRPC.

Konformansi

Halaman ini hanya membuat klaim arsitektur. Kutipan normatif untuk protokol dan keamanan disematkan pada halaman-halaman yang menentukan perilakunya: /connect/security-and-operations/, /transports/mcp/, /transports/rest/, dan /transports/grpc/. Rujukan siklus hidup MCP adalah spesifikasi resmi di modelcontextprotocol.io (revisi 2025-06-18). Halaman transport mencatat rujukan tersebut beserta URL-nya, karena spesifikasi MCP bukan bagian dari korpus standar berakses terbatas.

Konteks komersial

Katalog inti sudah lengkap untuk pembuatan, inspeksi, dan diagnostik dokumen. Tool untuk penandatanganan, redaksi, sertifikasi kepatuhan, dan analisis forensik hanya muncul ketika nextpdf/premium terpasang bersama server. Ini adalah batasan pemaketan, bukan ajakan upsell saat runtime. Server tidak pernah mengirimkan konten pemasaran.

Lihat juga

• /connect/install/ — instalasi dan paket opsional
• /connect/quickstart/ — pertukaran MCP dan REST pertama yang dapat dijalankan
• /connect/tool-catalog/ — set tool inti yang terverifikasi dan cara jumlahnya bergantung pada runtime
• /connect/hitl-risk-tiers/ — gerbang konfirmasi dan model risiko
• /transports/mcp/, /transports/rest/, /transports/grpc/ — penyiapan untuk tiap transport
• /connect/security-and-operations/ — autentikasi, keamanan transport, model ancaman
• /connect/deployment/ — deployment RoadRunner, Docker, dan transport gabungan