NextPDF Connect sorunlarını giderme

Bir bakışta

Sorunların çoğu beş kalıptan birine girer: hatalı biçimlendirilmiş bir JavaScript Object Notation Remote Procedure Call (JSON-RPC) el sıkışması, eksik bir application programming interface (API) anahtarı, bu katmanda kurulu olmayan bir araç, yanıtlanmamış bir onay sınaması veya işçiler arasında paylaşılmayan bir depo. Her kalıbın kendine özgü bir belirtisi vardır.

Kurulum

composer require nextpdf/server

Kavramsal genel bakış

Model Context Protocol (MCP) taşıması, standart kodlar içeren JSON-RPC 2.0 hata nesneleri döndürür. Representational State Transfer (REST) taşıması, Request for Comments (RFC) 7807 problem-details belgeleri döndürür. Her belge, durumu tanımlayan bir type URL’si içerir. Ortam sorunlarını araştırırken tanılama araçlarıyla başlayın (diagnostic.doctor, diagnostic.capabilities). Bu araçlar her zaman çekirdek katalogda yer alır.

API yüzeyi

MCP JSON-RPC hata kodları

Kod	Ad	Neden
`-32700`	Ayrıştırma hatası	Satır geçerli bir JSON değeri değildi
`-32600`	Geçersiz istek	JSON-RPC 2.0 mesajı değil (`jsonrpc`/`method` eksik)
`-32601`	Yöntem bulunamadı	İzin verilenlerin dışında bir yöntem: `initialize`, `tools/list`, `tools/call`
`-32602`	Geçersiz parametreler	Eksik `params.name`, şu çağrıda: `tools/call`
`-32603`	İç hata	Araç yürütülürken bir özel durum fırlatıldı

Bir araç denetimli şekilde başarısız olduğunda bu kodları kullanmaz. Bunun yerine, sonucunda isError: true bulunan başarılı bir JSON-RPC yanıtı ve bilinmeyen araç, ilke tarafından devre dışı bırakılmış araç ya da geçersiz bağımsız değişkenler gibi bir metin açıklaması döndürür.

REST problem-details türleri

HTTP	`type` slug’ı	Neden
`401`	`unauthorized`	Eksik/geçersiz/devre dışı/süresi dolmuş API anahtarı
`403`	`capability-denied`	Anahtar katmanı bu işlem için yetkili değil
`413`	`payload-too-large` / `tier-payload-exceeded`	Gövde, genel veya katman üst sınırını aşıyor
`422`	`validation-failed`	İstek gövdesi, şema doğrulamasını geçemedi
`429`	`ip-rate-exceeded` / `client-rate-exceeded`	Bir hız sınırına ulaşıldı
`404`	`not-found`	Bilinmeyen yol ya da job/session kimliği
`504`	(istek zaman aşımı)	İşlem, katman zaman aşımını aştı

Kod örneği — Hızlı başlangıç

Ortam sağlık denetimini çalıştırın. Bu işlem belge veya onay gerektirmez:

./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

Kod örneği — Üretim

Bir “eksik araç” sorununu ayıklamadan önce, bu dağıtımın hangi araçları sunduğunu doğrulayın:

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

ya da çalışan bir REST sunucusuna şu isteği gönderin:

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

Uç durumlar ve dikkat edilmesi gerekenler

Bir Pro/Enterprise aracı için “Unknown tool”. Aracın paketi kurulu değildir. Kayıt, sağlayıcı sınıflarını denetler ve bulunmayan katmanları uyarı vermeden atlar. Bu beklenen bir durumdur, bir hata değildir. nextpdf/premium paketini sunucunun bulunduğu ortama kurun veya bir çekirdek araç kullanın. Hata mesajı, kurulum yolunu içerir.
enabled_tools içinde yapılandırdığınız bir araç görünmüyor. İzin listesi, keşfedilen araçlarla kesişir. İzin listesi, kaydın bulamadığı bir aracı ekleyemez. Katman kurulumunu ve varsa ortam kapılarını denetleyin. Örneğin, parse_pdf, NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED aracılığıyla isteğe bağlı olarak etkinleştirilir.
tools/call bir belirteç isteyen metin döndürdü. Bu, bir hata değil, onay sınamasıdır. 300 saniye içinde, _confirmation_token değerini verilen belirtece ayarlayarak aracı yeniden çağırın. Bkz. /connect/hitl-risk-tiers/.
Bildirim satırı hiçbir çıktı üretmedi. Bu beklenen davranıştır. id içermeyen bir JSON-RPC mesajı bir bildirimdir ve işleyici hiçbir şey döndürmez. Yanıt almak için istekleri bir id ile gönderin.
Yinelenen bir istek kimliği eski bir yanıt döndürdü. İşleyici, 64 girişlik bir arabellekte istek kimliğine göre yinelenen istekleri kaldırır. Her mantıksal istek için yeni bir id kullanın.
Hız sınırları işçiler arasında beklenmedik davranıyor. Bellek içi depo, her işçiye özeldir. Sayımı paylaşmak için NEXTPDF_REDIS_HOST değişkenini ayarlayın ve ext-redis kurun. Bkz. /connect/deployment/.
Belgeler istekler arasında kayboluyor. Bellek içi belge deposu her işçiye özeldir ve bir yaşam süresiyle sınırlıdır (document_ttl, varsayılan 1800 s). İşçiler arasında belge sürekliliği için Redis tabanlı depoyu kullanın, oturum uç noktalarını kullanın veya tüm işlem kümesini tek bir eşzamanlı işleme akışında tutun.
Redis yapılandırmasına rağmen sunucu bellek içi depoya geri döndü. Redis bağlantısı başlatma sırasında başarısız olursa REST sunucusu otomatik olarak geri döner. Redis’e erişilebilirliği denetleyin ve çalışan görüntünün ext-redis içerdiğini doğrulayın. Doğrulamadan Redis’in kullanımda olduğunu varsaymayın.
Sunucu bir yapılandırma hatasıyla başlatılmayı reddediyor. Bir risk_level_overrides girişi, bir ApprovalRequired aracını düşürmeye çalıştı. Yükleyici, tasarım gereği bunu reddeder. Düşürmeyi kaldırın; geçersiz kılmalar yalnızca riski yükseltebilir.

Performans

İşleme görevleri yük altında yavaşsa, işçi havuzunun doymadığını doğrulayın. RoadRunner ölçüm uç noktasını denetleyin. Ardından, işçileri meşgul etmemeleri için uzun işleme görevlerini eşzamansız iş yoluna taşıyın. Bkz. /connect/production-usage/.

Güvenlik notları

Bir 401 hatasını, kimliği doğrulanmamış MCP taşımasını ağda açığa çıkararak aşmaya çalışmayın; bu, kimlik doğrulamayı tamamen kaldırır. Bunun yerine API anahtarını düzeltin. Paylaşılan bir ortamda araç bağımsız değişkenlerini incelemek için günlük ayrıntı düzeyini yükseltmeyin; bağımsız değişken yükleri hassas olabilir. Bkz. /connect/security-and-operations/.

Uyumluluk

Bu sayfa operasyonel rehberlik sağlar. Protokol ve güvenlik kaynakları /transports/mcp/, /transports/rest/ ve /connect/security-and-operations/ sayfalarında sabitlenmiştir.

Ayrıca bkz.

/connect/tool-catalog/ — çekirdek kataloğun neler içerdiği ve sayının neden değiştiği
/connect/hitl-risk-tiers/ — onay sınamaları hakkında ayrıntılar
/connect/deployment/ — Redis, işçi havuzları ve depo paylaşımı
/connect/security-and-operations/ — kimlik doğrulama hataları ve güvenlik duruşu