Memecahkan masalah NextPDF Connect

Sekilas

Sebagian besar kegagalan masuk ke salah satu dari lima pola: handshake JavaScript Object Notation Remote Procedure Call (JSON-RPC) yang tidak valid, kunci application programming interface (API) yang hilang, alat yang tidak terpasang pada tier ini, tantangan konfirmasi yang tidak dijawab, atau store yang tidak dibagikan di antara worker. Setiap pola memiliki gejala khasnya sendiri.

Pemasangan

composer require nextpdf/server

Ikhtisar konseptual

Transport Model Context Protocol (MCP) mengembalikan objek kesalahan JSON-RPC 2.0 dengan kode standar. Transport Representational State Transfer (REST) mengembalikan dokumen problem-details sesuai Request for Comments (RFC) 7807. Setiap dokumen memuat URL type yang mengidentifikasi kondisinya. Untuk masalah lingkungan, mulailah dengan alat diagnostik (diagnostic.doctor, diagnostic.capabilities). Alat-alat ini selalu tersedia di katalog inti.

Permukaan API

Kode kesalahan JSON-RPC MCP

Kode	Nama	Penyebab
`-32700`	Kesalahan penguraian	Baris tersebut bukan JSON yang valid
`-32600`	Permintaan tidak valid	Bukan pesan JSON-RPC 2.0 (`jsonrpc`/`method` hilang)
`-32601`	Metode tidak ditemukan	Metode di luar `initialize`, `tools/list`, `tools/call`
`-32602`	Parameter tidak valid	Tidak ada `params.name` pada `tools/call`
`-32603`	Kesalahan internal	Alat memunculkan kesalahan saat dieksekusi

Alat yang gagal secara terkendali tidak menggunakan kode-kode ini. Sebagai gantinya, alat tersebut mengembalikan respons JSON-RPC yang berhasil dengan isError: true dalam hasil dan penjelasan teks, seperti alat tidak dikenal, dinonaktifkan oleh kebijakan, atau argumen tidak valid.

Tipe problem-details REST

HTTP	`type` slug	Penyebab
`401`	`unauthorized`	Kunci API yang hilang/tidak valid/dinonaktifkan/kedaluwarsa
`403`	`capability-denied`	Tier kunci tidak berhak atas operasi tersebut
`413`	`payload-too-large` / `tier-payload-exceeded`	Body melebihi batas global atau batas tier
`422`	`validation-failed`	Body permintaan gagal validasi skema
`429`	`ip-rate-exceeded` / `client-rate-exceeded`	Batas laju tercapai
`404`	`not-found`	Rute tidak dikenal atau id job/session tidak ditemukan
`504`	(batas waktu permintaan)	Operasi melampaui batas waktu tier

Contoh kode — Mulai cepat

Jalankan pemeriksaan kesehatan lingkungan. Pemeriksaan 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":"diag","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 — Produksi

Sebelum men-debug “alat yang hilang”, konfirmasikan alat apa saja yang diekspos oleh deployment ini:

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

atau, untuk server REST yang sedang berjalan:

curl -sS http://localhost:8080/api/v1/capabilities \
  -H "Authorization: Bearer $NEXTPDF_KEY"

Kasus tepi dan jebakan

“Alat tidak dikenal” untuk alat Pro/Enterprise. Paket alat tersebut belum terpasang. Registry memeriksa kelas penyedia dan melewati tier yang tidak tersedia tanpa peringatan. Ini memang perilaku yang diharapkan, bukan bug. Pasang nextpdf/premium bersama server, atau gunakan alat inti. Pesan kesalahan menyertakan jalur pemasangan.
Alat yang saya konfigurasikan di enabled_tools tidak muncul. Allowlist diiriskan dengan alat yang ditemukan. Allowlist tidak dapat menambahkan alat yang tidak ditemukan oleh registry. Periksa pemasangan tier dan setiap gerbang lingkungan. Misalnya, parse_pdf bersifat opt-in melalui NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED.
tools/call mengembalikan teks yang meminta token. Itu adalah tantangan konfirmasi, bukan kesalahan. Panggil alat tersebut lagi dalam 300 detik dengan _confirmation_token diatur ke token yang diterbitkan. Lihat /connect/hitl-risk-tiers/.
Baris notifikasi tidak menghasilkan keluaran. Itu memang benar. Pesan JSON-RPC tanpa id adalah notifikasi, dan handler tidak mengembalikan apa pun. Kirim permintaan dengan id untuk memperoleh respons.
id permintaan yang digunakan ulang mengembalikan respons usang. Handler menghapus duplikat berdasarkan id permintaan dalam buffer 64 entri. Gunakan id baru untuk setiap permintaan logis.
Batas laju berperilaku aneh di antara worker. Store dalam memori bersifat per-worker. Untuk berbagi penghitungan, atur NEXTPDF_REDIS_HOST dan pasang ext-redis. Lihat /connect/deployment/.
Dokumen menghilang di antara permintaan. Store dokumen dalam memori bersifat per-worker dan dibatasi oleh masa berlaku (document_ttl, standar 1800 s). Untuk kontinuitas dokumen di antara worker, gunakan store berbasis Redis, gunakan endpoint sesi, atau pertahankan seluruh kumpulan operasi dalam satu render sinkron.
Server kembali ke dalam memori meskipun ada konfigurasi Redis. Server REST otomatis kembali menggunakan store dalam memori jika koneksi Redis gagal saat boot. Periksa keterjangkauan Redis, dan konfirmasikan bahwa ext-redis ada di image yang sedang berjalan. Jangan berasumsi bahwa Redis sedang digunakan tanpa memverifikasinya.
Server menolak untuk boot dengan kesalahan konfigurasi. Ada entri risk_level_overrides yang mencoba menurunkan alat ApprovalRequired. Loader menolaknya sesuai desain. Hapus penurunan tersebut; override hanya boleh menaikkan risiko.

Kinerja

Jika render lambat di bawah beban, pastikan pool worker tidak jenuh. Periksa endpoint metrik RoadRunner. Kemudian pindahkan render yang lama ke jalur pekerjaan asinkron agar tidak menahan worker. Lihat /connect/production-usage/.

Catatan keamanan

Jangan menghindari 401 dengan mengekspos transport MCP tanpa autentikasi melalui jaringan; hal itu menghilangkan autentikasi sepenuhnya. Sebagai gantinya, perbaiki kunci API. Jangan menaikkan tingkat verbositas log untuk memeriksa argumen alat di lingkungan bersama; payload argumen mungkin bersifat sensitif. Lihat /connect/security-and-operations/.

Kesesuaian

Halaman ini menyediakan panduan operasional. Rujukan protokol dan keamanan berada di /transports/mcp/, /transports/rest/, dan /connect/security-and-operations/.

Lihat juga

/connect/tool-catalog/ — apa yang dimuat katalog inti dan mengapa jumlahnya bervariasi
/connect/hitl-risk-tiers/ — tantangan konfirmasi secara rinci
/connect/deployment/ — Redis, pool worker, dan berbagi store
/connect/security-and-operations/ — kegagalan autentikasi dan postur keamanan