NextPDF Connect araç kataloğu

Bir bakışta

NextPDF Connect sabit sayıda araç sunmaz. Sunucu bu sayıyı çalışma zamanında kurulu paketlere, yapılandırma izin listesine ve ortam geçitlerine göre hesaplar. Bu sayfa, doğrulanmış çekirdek kümeyi ve toplamı belirleme yöntemini belgeler.

Kurulum

composer require nextpdf/server

Kavramsal genel bakış

NextPDF\Server\ToolRegistry başlatma sırasında kataloğu şu sırayla oluşturur:

Çekirdek katman. Sabit bir çekirdek araç kümesi koşulsuz kaydedilir. İki ek araç yalnızca bir ön koşul sağlandığında kaydedilir.
Pro katmanı. Pro araçları, Pro sağlayıcı sınıfı çözümlendiğinde kaydedilir; bu da nextpdf/premium kurulu olduğunda gerçekleşir. Sınıf çözümlenmediğinde sunucu bu adımı sessizce atlar.
Enterprise katmanı. Enterprise sağlayıcısı, Pro sağlayıcısıyla aynı deseni izler.
Paketle birlikte gelen genişletilmiş katmanlar. AST ve mutasyon araç sağlayıcıları sunucu paketiyle birlikte gelir ve Pro katmanı altında kaydedilir. Her sağlayıcı bir ortam geçidiyle denetlenir ve temel çekirdek desteği bulunmadığında sorunsuz biçimde devre dışı kalır.
Güvenlik ilkesi filtresi. Sunucu, her kaydı enabled_tools izin listesiyle kesiştirir. Boş olmayan bir izin listesi, içinde yer almayan her aracı çıkarır. Katman sayacı yalnızca ilkenin kabul ettiği araçları içerir.

Model Context Protocol (MCP) initialize yanıtı, çalışan sunucuda ortaya çıkan tool_count değerini ve katman başına sayıları bildirir. Yetkili değer budur. Metinde geçen tüm sabit toplamları eski kabul edin.

API yüzeyi

Doğrulanmış, her zaman kullanılabilir çekirdek araçlar

Bu on iki araç çekirdek katmanda her zaman kaydedilir. Sunucu, her risk katmanını ve her MCP davranış ipucunu araç uygulamasından okur.

Araç adı	Kategori	Açıklama	Risk
`create_pdf`	document	Bir PDF belgesi oluşturun ve şu kimliği döndürün: `document_id`	caution
`add_text`	document	Bir PDF belgesine metin içeriği ekleyin	caution
`add_image`	document	Bir dosya yolundan veya base64 verisinden görüntü ekleyin	caution
`add_table`	document	Bir PDF belgesine bir HTML tablosu ekleyin	caution
`set_font`	document	Sonraki metin işlemleri için yazı tipini ayarlayın	caution
`add_page`	document	PDF belgesine yeni bir sayfa ekleyin	caution
`output_pdf`	document	PDF’yi bir dosya veya base64 olarak sonlandırın	approval_required
`preview_layout`	document	İşleme yapmadan bir JSON yerleşim özeti döndürün	safe
`diagnostic.doctor`	diagnostic	Bir sağlık denetimi çalıştırın; yapılandırılmış ortam tanılaması sağlayın	safe
`diagnostic.capabilities`	diagnostic	Yetenekleri katman ve durumla birlikte listeleyin	safe
`diagnostic.inspect`	diagnostic	Bir PDF’yi inceleyin ve yapısal meta verileri döndürün	safe
`diagnostic.verify`	diagnostic	İsteğe bağlı PDF/A veya PDF/UA denetimleriyle PDF bütünlüğünü doğrulayın	caution

Koşullu olarak kaydedilen çekirdek araçlar

Araç adı	Koşul
`generate_barcode`	Kurulu `nextpdf/core` çekirdek barkod kodlayıcı kaydını içerdiğinde kaydedilir
`parse_pdf`	Yalnızca şu durumda kaydedilir: `NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED` değeri `true` veya `1`

output_pdf, approval_required risk seviyesindeki tek çekirdek araçtır. Dosyaya yazma işlemi insan onayı kapısından geçer; base64 çıktısı geçmez. /connect/hitl-risk-tiers/. sayfasına bakın.

Yalnızca ek paketler kurulduğunda eklenen araçlar

Sunucu, sağlayıcı sınıflarını class_exists() ile denetler:

Pro araçları, nextpdf/premium kurulu olduğunda ve Pro sağlayıcısı çözümlendiğinde kaydedilir.
Enterprise araçları, nextpdf/premium kurulu olduğunda ve Enterprise sağlayıcısı çözümlendiğinde kaydedilir. Gizlilik araçları (redaksiyon, kimliksizleştirme, bölge redaksiyonu) Enterprise sınıflarını sarmalar. Bu araçlar yalnızca o sınıflar otomatik yüklenebilir olduğunda Enterprise katmanı altında kaydedilir.
AST ve mutasyon araçları sunucuyla birlikte gelir ve Pro katmanı altında kaydedilir. Bu araçları NEXTPDF_AST_TOOLS_ENABLED ve NEXTPDF_MUTATION_TOOLS_ENABLED geçitleri denetler ve her iki geçit de varsayılan olarak etkindir.

Tam Pro ve Enterprise araç envanterlerini sunucu değil, Premium paketi tanımlar ve bu envanterleri o paketle birlikte belgeler. Sunucunun sözleşmesi, sabit bir Premium listesi değil, kayıt mekanizmasıdır.

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

Bir sunucu başlatmadan bu kurulumda sunulan araçları yazdırın:

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

Kod örneği — üretim

Yetkili sayıyı almak için çalışan sunucuyu MCP üzerinden sorgulayın:

./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/list","params":{}}
EOF

Sunucu, çalışan süreç için capabilities.nextpdf.tool_count ve tiers değerlerini initialize sonucunda hesaplar. REST üzerinden GET /api/v1/capabilities eşdeğer iç gözlemi döndürür.

Uç durumlar ve dikkat edilecek noktalar

Sabit bir “33 araç” — ya da herhangi bir sabit toplam — yoktur. Eski belgeler tek bir sayı belirtir, ancak o sayı sözleşme niteliği taşımaz. Sayı; kurulu paketlere, enabled_tools izin listesine ve parse_pdf, AST ve mutasyon ortam geçitlerine göre değişir. Bu sayıyı her zaman çalışan sunucudan okuyun.
İzin listesi çıkarır, asla eklemez. Bir Pro aracını enabled_tools içinde listelemek, nextpdf/premium bulunmadığında onun kaydedilmesini sağlamaz.
Eksik bir katman sessizce atlanır ve beklenen bir durumdur. Yalnızca açık kaynaklı bir kurulum, çekirdek kümeyi sunar ve sıfır Pro ile sıfır Enterprise aracı bildirir. Bu sonuç bir arıza değil, doğru davranıştır.
Katalogdaki katman, bildirilen bir değişmezdir. Her araç, kendi katmanını ve riskini kodda bildirir. Kayıt işlemi, bir katmanı asla ad alanından veya paketten türetmez.

Performans

Kayıt taraması ve katman algılaması başlatma sırasında bir kez çalışır. Sayfanın performance_budget değeri bu işlemleri sınırlar. Araç başına maliyet, araç adına göre O(1) olan katalog aramasından değil, temel motor işleminden kaynaklanır.

Güvenlik notları

En az ayrıcalık denetimi için enabled_tools öğesini kullanın: yalnızca bir entegrasyonun ihtiyaç duyduğu araçları sunun. Katalog, güvenlik ilkesinin reddettiği bir aracı asla içermez ve katman sayacı yalnızca kabul edilen araçları yansıtır. Yüksek riskli araçlar, katalog üyeliğinden bağımsız olarak insan onayı gerektirmeye devam eder. /connect/security-and-operations/. sayfasına bakın.

Uygunluk

Bu sayfa, kayıt mekanizmasını açıklar. tools/list ve initialize yüzeyleri için protokol alıntıları /transports/mcp/. sayfasında sabitlenmiştir. Risk modeli /connect/hitl-risk-tiers/. sayfasında açıklanmıştır.

Ticari bağlam

Çekirdek katalog oluşturma, inceleme ve tanılamayı kapsar. İmzalama, redaksiyon, uyumluluk ve adli analiz araçları yalnızca nextpdf/premium sunucuyla birlikte kurulduğunda görünür. Bu paketleme sınırı, çalışma zamanında bir istemci aracılığıyla değil, composer require zamanında uygulanır.

Ayrıca bakınız

/connect/hitl-risk-tiers/ — risk sütununun ne anlama geldiği ve uygulamanın nasıl çalıştığı
/connect/boot-and-discovery/ — tam başlatma ve keşif dizisi
/connect/configuration/ — enabled_tools ve ortam geçitleri
/transports/mcp/ — tools/list ve initialize tel biçimleri
/connect/overview/ — kataloğun neden tasarımı gereği çalışma zamanına bağlı olduğu