NextPDF Connect — transport MCP

Sekilas pandang

Transport Model Context Protocol (MCP) menjalankan bin/nextpdf-mcp sebagai subproses lokal. Transport ini berkomunikasi menggunakan JSON-RPC 2.0 melalui standard input dan output. Server mengimplementasikan revisi MCP bertanggal 2025-06-18.

Pemasangan

composer require nextpdf/server

Tinjauan konseptual

Dalam model stdio MCP, klien meluncurkan server sebagai subproses. Klien bertukar pesan JSON-RPC yang dipisahkan baris baru: satu pesan per baris, tanpa baris baru di tengah pesan, dengan encoding UTF-8. Server hanya menulis pesan MCP yang valid ke standard output dan mengirim log ke standard error. Implementasi ini mengarahkan logger auditnya ke standard error sehingga baris log tidak pernah merusak aliran protokol. Spesifikasi MCP resmi, revisi 2025-06-18, mendefinisikan framing ini. Spesifikasi tersebut bukan bagian dari korpus standar yang dibatasi aksesnya, sehingga dikutip melalui URL: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports.

NextPDF Connect mengimplementasikan transport stdio. Spesifikasi MCP juga mendefinisikan transport Streamable HTTP. Spesifikasi tersebut menyatakan bahwa klien sebaiknya mendukung stdio bila memungkinkan, sementara server boleh hanya mengimplementasikan stdio. Untuk mengakses perkakas yang sama melalui jaringan, gunakan transport REST atau gRPC; lihat /transports/rest/ dan /transports/grpc/.

Permukaan API

Metode

Metode	Perilaku
`initialize`	Mengembalikan versi protokol, kapabilitas, dan info server
`notifications/initialized`	Sebuah notifikasi (tanpa `id`); diterima tanpa respons
`tools/list`	Mendaftar perkakas terdaftar dengan filter `params.category` opsional
`tools/call`	Menjalankan sebuah perkakas berdasarkan `params.name` dengan `params.arguments`

Metode lain mana pun mengembalikan method-not-found (-32601). Pesan yang bukan JSON-RPC 2.0 yang valid mengembalikan invalid-request (-32600); masukan yang tidak dapat diurai mengembalikan parse-error (-32700). Permintaan dengan id duplikat mengembalikan respons sebelumnya yang di-cache dari buffer 64 entri, tanpa menjalankannya ulang.

Respons initialize

Hasil initialize mengembalikan protocolVersion 2025-06-18, serverInfo.name: NextPDF Connect, dan objek capabilities. Selain kapabilitas tools standar, server menambahkan blok capabilities.nextpdf:

tiers — jumlah perkakas yang terdaftar langsung per tier (core / pro / enterprise).
tool_count — jumlah total perkakas yang terdaftar, dihitung saat runtime.
risk_model_version — versi model risiko yang diterapkan server.
hitl_enabled — true; gerbang konfirmasi aktif.

tool_count adalah angka otoritatif untuk deployment ini. Nilai ini dihitung saat runtime, bukan konstanta yang terdokumentasi; lihat /connect/tool-catalog/.

Contoh kode — Mulai cepat

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

Contoh kode — Produksi

Filter kategori membatasi katalog pada satu domain:

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

Nilai kategori berasal dari kategori yang dideklarasikan oleh setiap perkakas (misalnya document, diagnostic).

Kasus tepi dan jebakan

Tanpa kunci API. Transport stdio tidak memiliki listener jaringan dan tidak memiliki bearer token. Perlakukan batas proses sistem operasi sebagai batas kepercayaan, sesuai model stdio MCP. Jangan menjembatani transport ini ke jaringan.
Tantangan konfirmasi bersifat in-band. Perkakas ApprovalRequired mengembalikan respons JSON-RPC yang berhasil. Konten respons berupa teks tantangan dan token sekali pakai, bukan kesalahan. Lihat /connect/hitl-risk-tiers/.
Notifikasi bersifat senyap. Pesan tanpa id tidak menghasilkan respons. Urutan handshake-nya adalah initialize (dengan id), lalu notifikasi initialized, lalu panggilan yang membawa id.

Performa

Server MCP berjalan sebagai satu proses tunggal dan menangani satu permintaan dalam satu waktu melalui pipe. Tidak ada round trip jaringan; latensi didominasi oleh operasi engine yang mendasarinya.

Catatan keamanan

Transport mewarisi kepercayaan dari klien yang meluncurkannya. Jaga agar subproses tetap lokal. Perkakas berisiko tinggi tetap memerlukan konfirmasi manusia meskipun tidak ada kunci API. Lihat /connect/security-and-operations/.

Kesesuaian

Framing stdio dan perilaku initialize/lifecycle sesuai dengan spesifikasi Model Context Protocol resmi, revisi 2025-06-18:

Transport: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports
Lifecycle: https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle

Spesifikasi MCP tidak ada dalam korpus standar yang dibatasi aksesnya, sehingga tidak memiliki reference_id; URL resmi di atas adalah kutipan rujukan resminya.

Konteks komersial

tools/list mengembalikan perkakas Pro dan Enterprise hanya ketika nextpdf/premium terpasang bersama server. Transport itu sendiri tetap sama, apa pun tier yang terpasang.

Lihat juga

/connect/quickstart/ — handshake yang dapat dijalankan
/connect/tool-catalog/ — apa yang dikembalikan tools/list dan mengapa jumlahnya bervariasi
/connect/hitl-risk-tiers/ — format tantangan konfirmasi
/transports/rest/ · /transports/grpc/ — alternatif melalui jaringan
/connect/migrating-to-multi-transport/ — memindahkan integrasi khusus MCP ke REST/gRPC