Panduan cepat NextPDF Connect

Sekilas pandang

Halaman ini memandu Anda menjalankan pertukaran paling sederhana yang berguna pada kedua transport: Model Context Protocol (MCP) dan Representational State Transfer (REST). Setiap permintaan menggunakan format wire persis seperti yang diimplementasikan oleh server. Anda tidak memerlukan software development kit (SDK).

Pemasangan

composer require nextpdf/server

Gambaran umum konseptual

Transport MCP menggunakan JSON-RPC 2.0 melalui standard input dan standard output. Anda harus mengirim rangkaian pesan tersebut secara berurutan. Pertama, kirim initialize. Setelah itu, kirim notifikasi pengakuan penerimaan notifications/initialized. Kemudian kirim tools/list dan tools/call. Server membaca satu pesan JSON per baris. Setiap baris harus diakhiri dengan newline. Server menulis satu respons per baris.

Transport REST mengekspos kemampuan engine yang sama sebagai operasi Hypertext Transfer Protocol (HTTP). Satu render stateless tunggal dilakukan dengan satu POST /api/v1/render berisi array operations yang berurutan. Body respons adalah berkas Portable Document Format (PDF).

Contoh kode — Panduan cepat (MCP melalui stdio)

Jalankan server, lalu alirkan handshake ke dalamnya. Ketiga permintaan ini menggunakan nama metode yang sudah diverifikasi dan dirutekan oleh penangan protokol:

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

Respons initialize melaporkan versi protokol 2025-06-18, nama server NextPDF Connect, dan blok capabilities.nextpdf. Blok tersebut mencakup jumlah tier langsung, tool_count runtime, versi model risiko, dan hitl_enabled: true. Respons tools/list mencantumkan tool persis yang terdaftar untuk instalasi ini. Baris notifikasi memang dirancang untuk tidak menghasilkan respons.

Sekarang panggil tool yang aman. Tool diagnostic.doctor menjalankan pemeriksaan lingkungan yang bersifat hanya-baca. Tool ini tidak memerlukan dokumen atau konfirmasi:

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

Contoh kode — Panduan cepat (REST)

Jalankan server REST, lalu render PDF dengan satu perintah. Server memerlukan kunci application programming interface (API) untuk setiap endpoint selain health; jadi, tetapkan satu terlebih dahulu:

export NEXTPDF_API_KEYS='npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef:demo:core:default'
./vendor/bin/rr serve -c .rr.yaml

Di shell kedua, kirim permintaan render. Body permintaan adalah RenderRequest. Permintaan tersebut berisi array operations berurutan yang terdiri atas operasi bertipe.

curl -sS -X POST http://localhost:8080/api/v1/render \
  -H 'Authorization: Bearer npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef' \
  -H 'Content-Type: application/json' \
  -d '{
        "page_size": "A4",
        "orientation": "portrait",
        "operations": [
          { "type": "add_text", "text": "Hello from NextPDF Connect" }
        ]
      }' \
  --output hello.pdf

Body respons 200 berupa PDF (Content-Type: application/pdf) yang ditulis ke hello.pdf. Probe health tidak memerlukan kunci:

curl -sS http://localhost:8080/healthz

Kasus tepi dan jebakan

• Urutan handshake itu penting. Penangan protokol memperlakukan pesan tanpa id sebagai notifikasi dan tidak mengembalikan apa pun. Kirim initialize dengan id, lalu notifikasi initialized, lalu permintaan Anda yang menyertakan id.

• id permintaan yang digunakan ulang akan dideduplikasi. Penangan menyimpan respons terbaru di cache pada circular buffer berkapasitas 64 entri. Untuk id duplikat, penangan mengembalikan respons dari cache tanpa menjalankan tool lagi. Gunakan id baru.

• Tool berisiko tinggi merespons dengan tantangan, bukan hasil. Memanggil output_pdf dengan file_path mengembalikan tantangan konfirmasi, bukan menjalankannya. Panggil ulang tool tersebut dengan _confirmation_token yang diterbitkan. Mode keluaran base64, tanpa file_path, tidak memerlukan konfirmasi. Lihat /connect/hitl-risk-tiers/.

• Permintaan REST yang tidak terautentikasi akan mendapatkan 401. Header Authorization: Bearer yang hilang atau berformat salah mengembalikan body problem-details dengan header WWW-Authenticate: Bearer. Probe /healthz dan /readyz adalah satu-satunya endpoint anonim.

Performa

Kedua jalur panduan cepat masing-masing menggunakan satu permintaan tunggal. Jalur REST juga menanggung biaya cold-start dari worker pool RoadRunner pada permintaan pertama setelah rr serve. Permintaan berikutnya menggunakan kembali worker yang sudah warm.

Catatan keamanan

Kunci npk_live_ di atas adalah nilai demo sekali pakai. Buat kunci sungguhan dengan entropi yang memadai, simpan di luar source control, dan utamakan penyimpanan kunci berbasis berkas untuk rotasi. Transport stdio MCP tidak memiliki kunci API karena transport tersebut merupakan subproses lokal yang dipercaya oleh klien yang meluncurkannya berdasarkan model transport MCP. Lihat /connect/security-and-operations/.

Kesesuaian

Format wire yang ditampilkan sesuai dengan revisi MCP 2025-06-18 yang diimplementasikan dan kontrak REST OpenAPI 3.1. Kutipan protokol dan autentikasi normatif dicantumkan pada /transports/mcp/, /transports/rest/, dan /connect/security-and-operations/.

Lihat juga

• /transports/mcp/ — referensi transport MCP lengkap
• /transports/rest/ — referensi transport REST lengkap dan render OpenAPI
• /connect/tool-catalog/ — tool mana saja yang dikembalikan tools/list dan mengapa
• /connect/hitl-risk-tiers/ — seperti apa bentuk tantangan konfirmasi
• /connect/configuration/ — membatasi katalog dan menyetel server