Pro sürüm

MCP Tools — Derinlemesine başvuru

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) ile birlikte gelir ve bir Pro katmanı lisans zarfıyla etkinleşir. Bu yetkiye sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve bir lisans edinin.

Özellik başına lisans bayrağı yoktur. Kod, Pro sürümüyle birlikte gelir ve Pro paketi önyüklemede nextpdf/server ile birlikte çözümlendiğinde sekiz araç pro katmanı altında kaydolur.

Davranış sözleşmesi

NextPDF Server, önyüklemede Pro araç sağlayıcı sınıfını yoklayarak katmanları keşfeder; çözümlenirse, sunucu sekiz aracı pro katmanı altında kaydeder. Pro paketi, sunucunun zorunlu bir bağımlılığı değildir, bu nedenle Pro araçları kesinlikle yan yana yükleme yoluyla isteğe bağlıdır. Katman kaydı bağımsızdır: eksik veya ilkece dışlanmış bir katman, asla diğerlerini engellemez.
Her araç, dört risk düzeyinden birini (safe, caution, review, approval-required) bildirir. İsteğe bağlı bir operatör geçersiz kılması, bir aracın düzeyini yalnızca yükseltebilir, asla düşüremez; sunucu, caution veya üzeri herhangi bir yürütmeyi denetim günlüğüne kaydeder. sign_pdf, approval-required’dır.
PDF girişi sabit bir sırayla çözümlenir: bellek içi depodan document_id, ardından bir data: URI’si, dosya sistemi yolu veya ham base64 olarak source. Eksik giriş, boş bir belge işlemek yerine bir doğrulama hatası döndürür.
sign_pdf, yalnızca bir PAdES B-B temel imzası üretir — zaman damgası yok, uzun vadeli doğrulama yok. Desteklenen algoritmalar ve AES-GCM anahtar taşıma zarfı aşağıda ayrıntılandırılmıştır; şifre çözme güvenli biçimde başarısız olur ve araç, şifreli metni asla anahtar malzemesi olarak kullanmaz.
Tam keşif, risk, kaynak çözümleme, araç başına ve imzalama ayrıntısı için aşağıdaki bölümlere bakın. Bu sayfa yalnızca dışarıdan gözlemlenebilen davranışı ve yayımlanan araç sözleşmesini açıklar.

Kapsam

Bu sayfa, sekiz Pro MCP aracı için operatör ve entegratör başvurusudur. Keşif modelini, sunucunun uyguladığı risk/HITL anlamlarını, kaynak çözümleme kurallarını, imzalama anahtar taşıma zarfını ve araç başına hata davranışını kapsar. Yalnızca dışarıdan gözlemlenebilen davranışı ve yayımlanan araç sözleşmesini açıklar. Kullanıcıya yönelik katalog için herkese açık MCP sayfasına bakın.

Keşif ve kayıt modeli

NextPDF Server, önyüklemede katman sağlayıcılarını keşfeder. Pro araç sağlayıcı sınıfını yoklayarak Pro katmanını algılar; sınıf çözümlenirse, sunucu sağlayıcıyı örnekler ve döndürdüğü her aracı pro katmanı altında kaydeder. Pro paketi bilinçli olarak sunucunun zorunlu bir bağımlılığı değildir — bu, açık kaynaklı sunucunun tescilli paket olmadan kurulabilir kalmasını sağlar ve Pro araçlarını kesinlikle yan yana yükleme yoluyla isteğe bağlı kılar.

Sunucu, kaydı katman başına yalıtır. Pro paketi yoksa, Core araçları yine de kaydolur; mevcut bir katman sağlayıcısı diğer katmanları engellemez. Araç kaydı ayrıca sunucunun güvenlik ilkesi izin listesine de tabidir: ilke tarafından dışlanan bir araç sessizce kaydolmaz ve katman özetinde sayılmaz. Sunucu, tanılama ve günlükleme için katman başına bir sayı (core / pro / enterprise) sunar.

Sağlayıcı, sekiz aracı sabit bir sırayla döndürür: metin çıkarma, segmentasyon, karşılaştırma, KKB maskeleme, form doldurma, form geri okuma, erişilebilirlik analizi, imzalama. Sıra kararlıdır, ancak çağıranlar buna bağlı olmamalıdır — araçları MCP protokol adlarıyla çözümleyin.

Risk modeli ve HITL anlamları

Her araç, dört risk düzeyinden birini bildirir. Sunucu, insan-döngüde uygulaması için bildirilen düzeyi kullanır:

Safe — salt okunur, yan etkisi yok. Otomatik yürütülür.
Caution — bellek içi durum oluşturur veya değiştirir. Bir denetim günlüğü girişiyle otomatik yürütülür.
Review — kötüye kullanılabilecek çıktı üretir. Otomatik yürütülür, ancak aracı becerisi yönergeleri bunu işaretler, böylece aracı kullanıcıyı uyarır.
Approval-required — yıkıcı, hukuki veya gizlilik açısından kritik. Sunucu, yürütmeden önce açık bir insan onayı gerektirir.

Pro araç sınıflandırmaları: beş çıkarma/analiz aracı (extract_text, segment_document, compare_pdfs, extract_form_data, check_accessibility) safe’tir; redact_pii ve fill_form review’dir; sign_pdf approval-required’dır.

Risk düzeyi tam olarak iki kaynaktan gelir: aracın kendi bildirimi ve çalışma zamanında isteğe bağlı bir operatör geçersiz kılması. Geçersiz kılma, bir aracın risk düzeyini yalnızca yükseltebilir (uygulamayı sıkılaştırır); asla düşüremez. Sunucu, caution düzeyinde veya üzerindeki herhangi bir yürütmeyi denetim günlüğüne kaydeder. Risk modeli bir sürüm taşır; sunucu, istemcilerin uyumsuz bir değişikliği algılayabilmesi için bu sürümü başlatma yanıtında duyurur.

Kaynak çözümleme sırası

PDF alan her araç, onu şu sırayla çözümlenen üç giriş biçiminden biri aracılığıyla kabul eder:

document_id — sunucu, baytları bellek içi belge deposundan alır. Bilinmeyen bir kimlik, çağıranı önce belgeyi oluşturmaya yönlendiren açık bir hatayla başarısız olur.
data: URI’si olarak source — araç, virgülden sonraki base64 gövdesinin kodunu çözer.
dosya sistemi yolu olarak source — yol bir dosyaya çözümlendiğinde araç diskten okur.
ham base64 dizesi olarak source — araç, yalnızca yeterince uzun, base64 biçimli girişi kabul eder ve kodunu çözer.

compare_pdfs, aynı çözümlemeyi source_a ve source_b’ye bağımsız olarak uygular ve ek olarak her iki kaynak yuvasında da bir document_id değerini kabul eder. Ne bir document_id ne de bir source sağlanırsa, araç boş bir belge işlemek yerine bir doğrulama hatası döndürür.

Araç başına başvuru

Araç	Risk	Girişler	Sonuç alanları	Davranış sınırı
`extract_text`	safe	PDF; isteğe bağlı 1 tabanlı `page_start` / `page_end`	metin, toplam sayfa sayısı	Yalnızca metin katmanı; aralıklar gerçek sayfa sayısına sıkıştırılır; OCR yok
`segment_document`	safe	PDF	segment sayısı, segment listesi	Yerleşimden türetilen segmentler; etiketli PDF yapı ağacı değil
`compare_pdfs`	safe	iki PDF	aynı bayrağı, toplam değişiklik, belge başına sayfa sayısı, bölgeler (tür, metin, sayfa dizini, satır dizini, isteğe bağlı karşılık metni)	Metin içeriği karşılaştırması; görsel veya ikili değil
`redact_pii`	review	PDF; isteğe bağlı `types` (`email`, `phone`, `ssn`, `credit_card`)	KKB var bayrağı, algılanan sayı, maskelenmiş metin, taranan türler	Metin katmanı algılama/maskeleme; görsel maskeleme değil; örüntü tabanlı, kapsamlı değil
`fill_form`	review	`fields` eşlemesi; isteğe bağlı `pdf_filename`	XFDF belgesi, alan sayısı	XFDF üretir (ISO 19444-1); değerleri bir PDF’e yazmaz
`extract_form_data`	safe	PDF	alan sayısı, alan eşlemesi, hiçbiri yoksa açık not	Yalnızca gömülü XFDF’i okur
`check_accessibility`	safe	PDF	yapısal puan (0–100), sorunlar, segment özeti	WCAG başvurularıyla yapısal buluşsal yöntem; uygunluk kararı değil
`sign_pdf`	approval-required	PDF; PEM sertifikası + PKCS#8 anahtarı; isteğe bağlı algoritma, imzalayan adı, neden, taşıma zarfı	imzalı PDF, imza sayısı, tamamlama bayrağı, algoritma, OID, özet	Yalnızca PAdES B-B temel; zaman damgası yok, LTV yok

İmzalama: algoritmalar ve anahtar taşıma

sign_pdf, bir PAdES B-B temel imzası üretir. Hem alt çizgili hem de tireli yazımlarla kabul edilen desteklenen algoritmalar:

SHA-256 ile RSA (varsayılan).
SHA-3 256 / 384 / 512 ile RSA — SHA-3 desteğine sahip bir OpenSSL derlemesi gerektirir.
Ed25519 — libsodium uzantısını gerektirir; anahtar, Ed25519 özel anahtarını saran bir PKCS#8 PEM olmalıdır.

Araç, desteklenmeyen tanımlayıcıları reddeder ve kabul edilen değerlerin listesini döndürür.

İsteğe bağlı taşıma şifreleme zarfı, bir çağıranın özel anahtarı uçtan uca gizli olmayan bir taşıma üzerinden tünelle aktarmasına olanak tanır. Zarf yalnızca AES-GCM’dir:

Simetrik anahtar: 16, 24 veya 32 bayt (AES-128/192/256), base64 ile kodlanmış.
Nonce: tam olarak 12 bayt, base64 ile kodlanmış.
İsteğe bağlı ek kimliği doğrulanmış veri, base64 ile kodlanmış.
private_key yükü, sonunda 16 baytlık bir GCM kimlik doğrulama etiketi bulunan base64 şifreli metindir.

Şifre çözme güvenli biçimde başarısız olur: bir kimlik doğrulama etiketi uyumsuzluğu veya hatalı biçimli bir yük, bir şifre çözme hatası döndürür ve araç, şifreli metni asla anahtar malzemesi olarak kullanmaz. Araç, herhangi bir kriptografik işlemden önce yanlış anahtar veya nonce boyutlarını reddeder.

Uç durumlar ve FIPS modu

extract_text: araç, belgeyi aşan bir sayfa aralığı sonunu reddetmek yerine sıkıştırır ve ilk sayfanın altındaki bir başlangıcı ilk sayfaya normalleştirir.
compare_pdfs: eksik bir source_a veya source_b bir doğrulama hatası döndürür; aynı belgeler sıfır değişiklikle açık bir aynı sonucu döndürür.
extract_form_data: gömülü bir XFDF akışı olmayan PDF’ler, bir hata değil, açıklayıcı bir notla sıfır alanlı bir sonuç döndürür.
redact_pii: types içindeki tanınmayan bir giriş yok sayılır; tamamı tanınmayan bir liste, bir başarısızlık yerine boş bir tarama verir.
sign_pdf: eksik bir sertifika veya özel anahtar, herhangi bir imzalama işleminden önce başarısız olur; araç, imzalama sırasında algoritma gereksinimlerini (SHA-3 OpenSSL desteği, Ed25519 için libsodium) denetler ve bunları açık hatalar olarak yüzeye çıkarır.
FIPS modu: algoritma kullanılabilirliği, ana makine OpenSSL/libsodium derlemesini izler. FIPS kısıtlamalı bir derlemede, onaylanmamış algoritmalar sessizce düşürülmek yerine kriptografik sınırda açık bir hatayla başarısız olur. MCP katmanı kriptografik ilke eklemez veya gevşetmez — ana makinenin kripto sağlayıcısının kararını yüzeye çıkarır.

Operatör runbook notları

sign_pdf’i approval-required tutun. Safe araçlarda riski istemeden yükselten bir operatör geçersiz kılması olmadığını doğrulayın — geçersiz kılmalar yalnızca sıkılaştırır, bu nedenle kazara bir geçersiz kılma güvenliği değil, kullanılabilirliği düşürür.
Denetim saklama: review düzeyinde veya üzerindeki her yürütme, sunucu tarafından denetim günlüğüne kaydedilir. Günlük saklamanızı redact_pii, fill_form ve sign_pdf çağrılarının hacmine göre boyutlandırın.
Taşıma seçimi: uçtan uca gizli olmayan bir taşıma üzerinden çalışırken, sign_pdf için AES-GCM anahtar taşıma zarfını zorunlu kılın ve özel anahtar malzemesini aracınızın araç çağrısı günlükleme ilkesinde bir gizli bilgi olarak ele alın.
Katman sayıları: Pro katmanının sekiz araç kaydettiğini dağıtım zamanında doğrulamak için sunucunun katman başına sayısını kullanın; sıfır sayısı, Pro paketinin çözümlenmediğini gösterir.

Sürüm sınırı

Pro katmanı tam olarak sekiz MCP aracına katkıda bulunur. Enterprise sürümü, kendi araçlarıyla ayrı bir MCP katmanı sunar — uyumluluk, adli analiz, uzun vadeli doğrulama sağlığı, yapay zekâya hazır sertifikasyon ve belge arama/gömme. Enterprise araç girişleri, çıkışları ve iç işleyişi burada kapsam dışıdır ve Enterprise sürümüyle belgelenir. Sunucu katmanları bağımsız olarak keşfeder; eksik bir katman asla bir başkasını devre dışı bırakmaz.

Yayımlama sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilen davranışı ve desteklenen herkese açık API yüzeyini belgeler. İç ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, runbook dosya adları ve bilet önekleri kapsam dışıdır.