NextPDF Connect HITL risk katmanları

Bir bakışta

Her araç, dört risk seviyesinden birini bildirir. En yüksek seviye olan onay gerektiren seviye, ilk çağrıda yürütülmez. Bunun yerine ConfirmationGate, tek kullanımlık bir sınama belirteci döndürür. Çağıran taraf, bu belirteci yeniden çağrıyı yetkilendirecek bir insana iletmek zorundadır.

Kurulum

composer require nextpdf/server

Kavramsal genel bakış

Risk modelinde tam olarak sıralı dört seviye vardır:

seviye	Değer	Anlamı	Etki
safe	0	Salt okunur, yan etkisi yok	Otomatik yürütülür
caution	1	Bellek içi durumu oluşturur veya değiştirir	Otomatik yürütülür, denetim günlüğüne kaydedilir
review	2	Kötüye kullanılabilecek çıktı üretir	Otomatik yürütülür, denetim günlüğüne kaydedilir
approval_required	3	Yıkıcı, yasal veya gizlilik açısından kritik	İnsan onayı gerekir

Bir aracın riski tam olarak iki kaynaktan gelir: aracın kendi bildirimi ve operatörün isteğe bağlı yapılandırma geçersiz kılması. Üçüncü bir kaynak yoktur. Model bir sürüm numarası taşır. MCP initialize yanıtı bu numarayı dışa açar; böylece bir istemci uyumsuz bir değişikliği algılayabilir. caution seviyesi ve üzeri için denetim günlüğü kaydı yapılır.

Otomatik bir eylemi bir insan yetkilendirene kadar bekletmek, denetimi otomasyonun risk getirdiği noktaya yerleştirir. IEC 31010, bunu insan eylemiyle ortaya çıkan riskin getirildiği noktada veya yakınında denetlenmesi için uygun konum olarak tanımlar (IEC 31010:2019).

API yüzeyi

ConfirmationGate

Geçerli bir belirteç olmadan bir approval_required aracını çağırdığınızda, kapı bir sınama yayınlar. Kapı, iki biçimden birini döndürür.

{ "allowed": true }

veya

{ "allowed": false, "challenge": "<human-readable text>", "token": "confirm_<nonce>" }

Sınama metni, işlemi ve açıklamasını belirtir. Ayrıca bir hedef dosyanın üzerine yazılacağı durumlarda uyarır. Çağıran tarafa, aynı aracı _confirmation_token parametresi yayınlanan belirtece ayarlanmış olarak yeniden çağırmasını söyler. Belirteç 300 saniye sonra geçerliliğini yitirir.

Belirtecin bağlanma biçimi kasıtlıdır: belirteç araç adını, rastgele bir tek seferlik değeri ve TTL’yi birbirine bağlar — bağımsız değişkenleri değil. Yeniden denemede MCP istemcileri bağımsız değişkenleri farklı anahtar sıralaması veya normalleştirmeyle yeniden serileştirebilir; bu nedenle bağımsız değişkenlerin karması alınsaydı meşru onaylar bozulurdu. Belirteç tek kullanımlıktır. Belirtecin yeniden çağrı sırasında tüketilmesi, çağrıya tam olarak bir kez izin verir.

Aktarım bazında gösterim

Kapı, araçları yöneten her aktarımda zorunlu kılınır:

MCP: sınama, içeriği sınama metni olan başarılı bir JSON-RPC yanıtı olarak bant içinde döner. Çağıran taraf, tools/call çağrısını arguments._confirmation_token ile yeniden gönderir.
REST ve gRPC: aynı kapı, bir approval_required işleminden önce paylaşılan araç yürütücüsünde çalışır. Sınama, işlem yanıtında görünür. Çağıran taraf, işlemi belirteçle yineler.

Yerleşik düşürme koruması

Bir yapılandırma geçersiz kılması, bir aracın risk seviyesini yükseltebilir, ancak tasarımı gereği approval_required olan bir aracı asla düşüremez. Yapılandırma yükleyici, sabit bir kritik kümeyi uygular ve bir geçersiz kılma düşürmeye çalışırsa yükleme sırasında bir hata fırlatır. Sunucu, zayıflatılmış bir kapıyla çalışmak yerine başlatılmayı reddeder.

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

Bir dosyayı output_pdf ile yazarak bir sınamayı tetikleyin:

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"c","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"output_pdf","arguments":{"document_id":"<id>","file_path":"/var/lib/nextpdf/tmp/out.pdf"}}}
EOF

Yanıt, dosya değil, sınamadır. Yayınlanan belirteçle yeniden çağırın:

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"output_pdf","arguments":{"document_id":"<id>","file_path":"/var/lib/nextpdf/tmp/out.pdf","_confirmation_token":"confirm_<nonce>"}}}

Kod örneği — üretim

Sıkılaştırılmış bir dağıtım için normalde caution seviyesinde olan bir aracı onay gerektiren seviyeye yükseltin:

nextpdf_mcp:
  risk_level_overrides:
    add_image: 3      # require human confirmation for image insertion

Bir düşürme, yükleme sırasında reddedilir ve sunucu başlatılmaz. Örneğin, output_pdf değerini 3 altına ayarlamak bir düşürmedir.

Sınır durumları ve dikkat edilecek noktalar

base64 modunda output_pdf kapıyı uygulamaz. Diske yazma işlemi onay gerektirir; PDF’yi base64 olarak döndürmek (file_path olmadan) daha düşük risk olarak değerlendirilir ve onay olmadan çalışır.
Belirteç bir kimlik bilgisi değildir. Çağıran tarafın kimliğini doğrulamaz ve ağ üzerinden çalışan aktarımlarda bir API anahtarının yerini almaz. Yalnızca kapıdan geçen belirli bir çağrıyı 300 saniye içinde bir kez serbest bırakır.
Her seferinde yeni bir sınama. Bir belirteci iletmemek veya geçerliliğini yitirmesine izin vermek, aracı kalıcı olarak engellemez. Sonraki çağrı yeni bir sınama yayınlar. Belirteçler, periyodik atık toplama özelliğine sahip tek kullanımlık bir belirteç deposunda saklanır.
Denetim, sonuçtan bağımsız olarak gerçekleşir. Bir sınamanın yayınlanması, başarılı yürütme ve caution seviyesi ile üzerindeki başarısız yürütmelerin tümü araç adı ve risk seviyesiyle birlikte denetim günlüğüne kaydedilir.

Performans

Kapı, bir belirteç deposunda arama yapar ve sınama gerektiğinde rastgele belirteç üretir. Bu maliyet, kapının uygulandığı işlemin yanında ihmal edilebilir düzeydedir ve yalnızca approval_required araçları için geçerlidir.

Güvenlik notları

Kapı, bir kimlik doğrulama denetimi değil, bir sınırlama denetimidir. Aracı otonom bir taraf yönetse bile, yıkıcı, yasal veya gizlilik açısından kritik eylemleri bir insanın yetkilendirmesini sağlar. Bu işlemler için sunucu, insan gözetimi olmadan çalıştığı iddiasında bulunmaz ve yapılandırma kapıyı zayıflatamaz. Bunu, ağ üzerinden çalışan aktarımlarda API anahtarı modeliyle ve enabled_tools en az ayrıcalık kapsamı belirlemesiyle birlikte kullanın. /connect/security-and-operations/ sayfasına bakın.

Uyumluluk

İddia	Kaynak	`reference_id`
Riski, (insan tarafından) getirildiği noktada denetleyin	IEC 31010:2019

MCP initialize yanıtı risk modeli sürümünü taşır; böylece istemciler uyumsuz bir değişikliği algılayabilir. Veri yolu biçimi /transports/mcp/ sayfasında belgelenmiştir.

Ticari bağlam

Premium araçlar, kendi risk seviyelerini aynı dört seviyeli modelle bildirir. Redaksiyon gibi yıkıcı Premium işlemleri de aynı kapıyı kullanır. Kapı, Premium paketinin değil, sunucunun bir parçasıdır.

Ayrıca bkz.

/connect/tool-catalog/ — her doğrulanmış core araç için risk seviyeleri
/connect/configuration/ — yalnızca yükseltmeye izin veren risk geçersiz kılması
/connect/security-and-operations/ — kapının tehdit modeline nasıl uyduğu
/transports/mcp/ — bant içi sınama veri yolu biçimi
/connect/overview/ — kapının mimaride nerede yer aldığı