NextPDF Connect hızlı başlangıcı

Bir bakışta

Bu sayfa, her iki taşıma katmanı için en küçük yararlı etkileşimi çalıştırır: Model Context Protocol (MCP) ve Representational State Transfer (REST). Her istek, sunucunun uyguladığı ağ biçimini birebir kullanır. Bir yazılım geliştirme kitine (SDK) ihtiyacınız yoktur.

Kurulum

composer require nextpdf/server

Kavramsal genel bakış

MCP taşıma katmanı, standart giriş ve çıkış üzerinden JSON-RPC 2.0 kullanır. İleti dizisini sırayla göndermeniz gerekir. Önce initialize gönderin. Ardından notifications/initialized bildirimini gönderin. Sonra tools/list ve tools/call gönderin. Sunucu, satır başına bir JSON iletisi okur. Her satır yeni satır karakteriyle bitmelidir. Sunucu, satır başına bir yanıt yazar.

REST taşıma katmanı, aynı motor yeteneklerini Hypertext Transfer Protocol (HTTP) işlemleri olarak sunar. Tek bir durumsuz işleme, sıralı bir işlemler dizisi içeren bir POST /api/v1/render isteğiyle yapılır. Yanıt gövdesi, Portable Document Format (PDF) dosyasıdır.

Kod örneği — hızlı başlangıç (stdio üzerinden MCP)

Sunucuyu başlatın ve el sıkışma iletilerini boru hattıyla sunucuya iletin. Bu üç istek, protokol işleyicisinin yönlendirdiği doğrulanmış yöntem adlarını kullanır:

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

Bu initialize yanıtı, protokol sürümünü 2025-06-18, sunucu adını NextPDF Connect ve bir capabilities.nextpdf bloğunu bildirir. Bu blok, canlı katman sayılarını, çalışma zamanı tool_count değerini, risk modeli sürümünü ve hitl_enabled: true değerini içerir. tools/list yanıtı, bu kurulum için kayıtlı araçların tamamını listeler. Bildirim satırı kasıtlı olarak hiçbir yanıt üretmez.

Şimdi güvenli bir aracı çağırın. diagnostic.doctor aracı, salt okunur bir ortam denetimi çalıştırır. Belge veya onay gerektirmez:

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

Kod örneği — hızlı başlangıç (REST)

REST sunucusunu başlatın, ardından tek satırlık bir PDF işleyin. Sunucu, sağlık dışındaki her uç noktada API anahtarı gerektirir; bu yüzden önce bir tane tanımlayın:

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

İkinci bir kabukta, bir işleme isteği gönderin. Gövde bir RenderRequest nesnesidir. Bu istek, tipli işlemlerden oluşan sıralı bir operations dizisi içerir.

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

Bir 200 yanıtının gövdesi, Content-Type: application/pdf olan ve hello.pdf dosyasına yazılan PDF’tir. Sağlık yoklamaları anahtar gerektirmez:

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

Uç durumlar ve dikkat edilecek noktalar

• El sıkışma sırası önemlidir. Protokol işleyicisi, id içermeyen bir iletiyi bildirim olarak değerlendirir ve hiçbir şey döndürmez. initialize komutunu bir id ile gönderin, ardından initialized bildirimini, ardından bir id içeren isteklerinizi gönderin.

• Tekrarlanan bir istek id değeri tekilleştirilir. İşleyici, son yanıtları 64 girişlik dairesel bir arabellekte önbelleğe alır. Yinelenen bir id için, aracı tekrar çalıştırmadan önbelleğe alınmış yanıtı döndürür. Yeni id değerleri kullanın.

• Yüksek riskli bir araç, bir sonuçla değil bir doğrulama isteğiyle yanıt verir. output_pdf aracının bir file_path ile çağrılması, çalıştırılmak yerine bir onay doğrulama isteği döndürür. Aracı, verilen _confirmation_token ile yeniden çağırın. file_path içermeyen base64 çıktı kipi, onay gerektirmez. Bkz. /connect/hitl-risk-tiers/.

• Yetkisiz bir REST isteği 401 yanıtı alır. Eksik veya hatalı biçimlendirilmiş bir Authorization: Bearer üst bilgisi, bir WWW-Authenticate: Bearer üst bilgisi içeren bir problem ayrıntıları gövdesi döndürür. /healthz ve /readyz yoklamaları, anonim olan tek uç noktalardır.

Performans

Her iki hızlı başlangıç yolu da tek bir istek kullanır. REST yolu ayrıca rr serve sonrasındaki ilk istekte RoadRunner çalışan havuzunun soğuk başlatma maliyetini de öder. Sonraki istekler, ısınmış çalışanları yeniden kullanır.

Güvenlik notları

Yukarıdaki npk_live_ anahtarı, tek kullanımlık bir tanıtım değeridir. Gerçek anahtarları yeterli entropiyle üretin, bunları sürüm denetiminin dışında saklayın ve döndürme için dosya tabanlı anahtar deposunu tercih edin. MCP stdio taşıma katmanı API anahtarı kullanmaz; çünkü MCP taşıma modeli kapsamında, kendisini başlatan istemci tarafından güvenilen yerel bir alt süreçtir. Bkz. /connect/security-and-operations/.

Uyumluluk

Gösterilen ağ biçimleri, uygulanan MCP revizyonu 2025-06-18 ve OpenAPI 3.1 REST sözleşmesiyle eşleşir. Normatif protokol ve kimlik doğrulama atıfları /transports/mcp/, /transports/rest/ ve /connect/security-and-operations/ sayfalarında sabitlenmiştir.

Ayrıca bkz.

• /transports/mcp/ — tam MCP taşıma başvurusu
• /transports/rest/ — tam REST taşıma başvurusu ve OpenAPI işlemesi
• /connect/tool-catalog/ — tools/list hangi araçları döndürür ve neden
• /connect/hitl-risk-tiers/ — bir onay doğrulama isteğinin nasıl göründüğü
• /connect/configuration/ — kataloğu kısıtlama ve sunucuyu ayarlama