NextPDF Connect entegrasyonu

Bir bakışta

NextPDF Connect’i sunucu olarak çalıştırıp entegre edin. Bir kütüphaneyi ana uygulamaya bağlamazsınız. Bir taşıma seçin; ardından ağ üzerinden çalışan her taşıma için kimlik doğrulamayı yapılandırın. Motor araçları onay kapısının arkasında kalır.

Kurulum

composer require nextpdf/server

Composer kısıtlaması nextpdf/core: ^3.0 değerindedir ve php: >=8.4 <9.0 ile birlikte gelir. İsteğe bağlı ext-redis ve nextpdf/premium kurulumu için /connect/install/. sayfasına bakın.

Kavramsal genel bakış

Paket bağımsız bir hizmet olarak çalışır. Bir ana çerçeveye servis sağlayıcı, paket ya da konteyner modülü kaydetmezsiniz. Entegrasyon noktası, çalıştırdığınız sürecin kendisidir. Her taşımanın kendi giriş noktası vardır ve her biri bağımsız olarak başlatılır. /connect/boot-and-discovery/. sayfasına bakın.

API yüzeyi

Giriş noktası	Taşıma	Profil
bin/nextpdf-mcp	MCP, stdio üzerinden	(yok — doğrudan alt süreç)
bin/nextpdf-server	REST, RoadRunner HTTP üzerinden	.rr.yaml
bin/nextpdf-grpc	gRPC, RoadRunner gRPC üzerinden	.rr.grpc.yaml
ağ üzerinden çalışan her iki taşıma	REST + gRPC	.rr.full.yaml

Başlatma ve otomatik keşif

Kayıt defteri her zaman çekirdek katmanı keşfeder. Ardından, sınıfları çözümlenebildiğinde Pro ve Enterprise sağlayıcılarını ekler; bunları, ortam kapılarının arkasında paketlenmiş soyut sözdizimi ağacı (AST) ve mutasyon sağlayıcıları izler. enabled_tools güvenlik izin listesi bunların tümünü filtreler; bu nedenle açığa çıkarılan katalog bu dağıtıma özgüdür. /connect/tool-catalog/ ve /connect/boot-and-discovery/. sayfalarına bakın.

Konteyner bağlamaları

Yok. Her sunucu fabrikası kendi nesne grafiğini açıkça oluşturur. Enjekte edilebilir bağlantı noktaları, uygulama bağlamasını değil, testleri destekler.

Yapılandırmayı yayımlama

MCP sunucusu isteğe bağlı bir YAML dosyasını (--config=PATH, nextpdf_mcp bölümü) ve NEXTPDF_MCP_* ortam geçersiz kılmalarını kabul eder. REST ve gRPC sunucuları NEXTPDF_* ortam değişkenlerini okur. Ayrıntılar için /connect/configuration/. sayfasına bakın.

Taşıma kullanılabilirliği (MCP / REST / gRPC)

Her üç taşıma da aynı kayıt defterini sunar:

• MCP — yerel alt süreç, stdio üzerinden JSON-RPC 2.0, API anahtarı yok, MCP revizyonu 2025-06-18. /transports/mcp/. sayfasına bakın.
• REST — RoadRunner HTTP işçi havuzu, OpenAPI 3.1 sözleşmesi, bearer API anahtarı, katman kapılı rotalar. /transports/rest/. sayfasına bakın.
• gRPC — RoadRunner gRPC işçi havuzu, nextpdf.connect.v1 Protobuf hizmeti, sunucu akışlı RPC’ler, üst veride bearer kimlik doğrulaması, birleşik profilde karşılıklı TLS. /transports/grpc/. sayfasına bakın.

Bir taşıma, giriş noktası veya RoadRunner profili çalışır durumdaysa “kullanılabilir” sayılır. Taşımalar birbirini otomatik olarak başlatmaz.

HITL risk katmanı

Her araç dört risk düzeyinden birini bildirir: safe, caution, review, approval_required. approval_required düzeyindeki araçlar ilk çağrıda çalıştırılmaz. Onay kapısı, insan tarafından yetkilendirilmesi gereken tek kullanımlık bir doğrulama belirteci verir. Bir yapılandırma geçersiz kılması yalnızca bir aracın riskini yükseltebilir; bir approval_required aracının riskini asla düşüremez. Bu model, araçları yöneten her taşımada aynı şekilde uygulanır. /connect/hitl-risk-tiers/. sayfasına bakın.

Onay kapısı JSON zarfı

Kapı denetimi iki JSON biçiminden birini döndürür. İzin verildiğinde:

{ "allowed": true }

Doğrulama isteği:

{
  "allowed": false,
  "challenge": "<human-readable text naming the operation, its description, an overwrite warning when applicable, and the re-invocation instruction>",
  "token": "confirm_<nonce>"
}

Belirteç bağımsız değişkenleri bağlamaz; araç adını, rastgele bir nonce değerini ve 300 saniyelik bir TTL’yi bağlar. Devam etmek için çağıran taraf, değeri verilen belirteç olan bir _confirmation_token bağımsız değişkeniyle aynı aracı yeniden çağırır. Doğrulama isteği düz yönerge metni ve belirteçten oluşur; kriptografik olarak imzalanmış bir zarf değildir. /connect/hitl-risk-tiers/. sayfasına bakın.

Hizmet duman testi

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

Bu komut kayıt defterini ve katman algılamayı başlatır, ardından trafik kabul etmeden açığa çıkarılan araçları yazdırır. Entegrasyonun bağlandığını doğrulamak ve bu kurulumun hangi kataloğu ürettiğini denetlemek için bu komutu kullanın.

Uç durumlar ve dikkat edilmesi gerekenler

• Çerçeve kancası yok. Servis sağlayıcı ya da paket aramayın. Çalışan süreç, entegrasyonun kendisidir.
• Eksik bir katman hata değildir. Yalnızca çekirdek kurulumu başlatılır ve çekirdek kataloğunu sunar.
• Ağ üzerinden çalışan taşımalar bir anahtar gerektirir. Yalnızca /healthz ve /readyz (REST) ve sağlık RPC’leri (gRPC) anonimdir.

Performans

Başlatma maliyeti, süreç başına bir kez yapılan kayıt defteri taraması ve katman algılamasından oluşur. İstek başına maliyet, motorun yaptığı işlemdir. RoadRunner işçi havuzlarını gözlemlenen işleme gecikmesine göre boyutlandırın. /connect/production-usage/. sayfasına bakın.

Güvenlik notları

Ağ üzerinden çalışan taşımalar, sabit zamanda doğrulanan bir npk_live_ bearer anahtarıyla kimlik doğrulaması yapar; kapı, taşımadan bağımsız olarak yıkıcı işlemler için insan onayını zorunlu kılar. TLS’yi REST’in önünde sonlandırın ve güvenilmeyen ağlarda gRPC için karşılıklı TLS kullanın. /connect/security-and-operations/. sayfasına bakın.

Uygunluk

Protokol ve güvenlik kaynakları /transports/mcp/, /transports/rest/, /transports/grpc/ ve /connect/security-and-operations/. sayfalarında sabitlenmiştir.

Ticari bağlam

Ek Pro ve Enterprise araçlarını aynı çalışan sunucuya kaydetmek için nextpdf/premium paketini sunucuyla birlikte kurun. Ayrı bir süreç söz konusu değildir.

Ayrıca bakın

• /connect/overview/ — mimari
• /connect/quickstart/ — ilk çalıştırılabilir etkileşim
• /transports/mcp/ · /transports/rest/ · /transports/grpc/ — taşıma başına başvuru kaynağı
• /connect/hitl-risk-tiers/ — onay kapısının ayrıntıları
• /connect/tool-catalog/ — çalışma zamanına bağlı katalog
• /connect/security-and-operations/ — kimlik doğrulama ve tehdit modeli