Pro sürüm

MCP araçları

Bir bakışta

NextPDF Pro, bir AI aracısının NextPDF Server üzerinden gelişmiş PDF işlemleri çalıştırmasına olanak tanıyan sekiz Model Context Protocol (MCP) aracı ekler. Hem nextpdf/pro hem de nextpdf/server yüklendiğinde araçlar otomatik olarak ortaya çıkar — ayrı bir kayıt adımı gerekmez.

Kullanılabilirlik ve lisanslama

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

Temel MCP yüzeyi — belge oluşturma, metin, tablolar, tanılama — açık kaynaklı NextPDF Server ile birlikte gelir ve lisans gerektirmez. Bu sayfadaki sekiz araç bir Pro lisansı gerektirir ve yalnızca nextpdf/pro paketi önyüklemede çözümlendiğinde kaydolur. pro araç katmanı tüm seti kapılar: her araç katmanını açıkça bildirir ve araç başına bir bayrak yoktur — nextpdf/pro’yu nextpdf/server ile birlikte yüklemek seti etkinleştirir.

Davranış sözleşmesi

Sekiz Pro MCP aracı, hem nextpdf/pro hem de nextpdf/server önyüklemede çözümlendiğinde, pro katmanı altında, standart MCP tools/list ve tools/call akışı üzerinden otomatik olarak kaydolur. Araç başına bir bayrak ve tüketen uygulamada herhangi bir kod değişikliği yoktur.
Her araç bir PDF’yi; daha önceki bir create_pdf çağrısından gelen bir document_id aracılığıyla, satır içi bir source (dosya yolu, base64 veya data: URI) aracılığıyla ya da — compare_pdfs için — böyle iki kaynak aracılığıyla kabul eder. Araçlar yapılandırılmış JSON döndürür.
Her araç, sunucunun uyguladığı bir HITL risk sınıfı bildirir: safe (otomatik yürütülen, salt okunur), review (kötüye kullanılabilecek çıktı) ve approval-required. sign_pdf approval-required’dır ve bir insan onaylayana kadar bekletilir. Bir operatör, bir aracın risk sınıfını yalnızca sıkılaştırabilir, asla gevşetemez.
sign_pdf yalnızca bir PAdES B-B (baseline) imzası üretir — güvenilir zaman damgası ve uzun vadeli doğrulama malzemesi yoktur. Uzun vadeli (B-LT / B-LTA) profiller, donanım anahtar muhafazası ve denetim izi imzalama Enterprise katmanıdır ve bu araçlar tarafından sağlanmaz; B-T (zaman damgalı bir imza), bir zaman damgası sağlayıcısı yapılandırıldığında Core motorundan sağlanır.
redact_pii, görsel karartma değil, metin katmanı desen algılama ve maskeleme gerçekleştirir; check_accessibility, bir PDF/UA veya WCAG uygunluk kararı değil, yapısal bir sezgiseldir. Yetkili giriş/çıkış şeması, bu sayfa değil, sunucunun canlı tools/list yanıtıdır.

Kavramsal genel bakış

NextPDF Server, NextPDF için belirleyici MCP yürütme katmanıdır. Önyüklemede araç sağlayıcılarını bir sınıf-varlık yoklamasıyla keşfeder; böylece Pro paketinin sunucunun bağımlılıklarında listelenmesi gerekmez. Pro paketi mevcut olduğunda, sunucu sekiz aracını pro katmanı altında kaydeder ve bunları, yapılandırdığınız herhangi bir aktarım üzerinden standart MCP tools/list ve tools/call akışıyla sunar.

Her Pro aracı, bir PDF’yi üç kaynaktan birinden kabul eder: daha önceki bir create_pdf çağrısının döndürdüğü bir document_id, satır içi bir source (dosya yolu, base64 dizesi veya data: URI) ya da — karşılaştırma aracı için — böyle iki kaynak. Araçlar, yapılandırılmış JSON sonuçları döndürür: çıkarılan metin, fark bölgeleri, maskelenmiş metin, segment ağaçları, erişilebilirlik bulguları veya imzalanmış bir PDF.

Her Pro aracı, sunucunun döngüde insan (HITL) uygulaması için kullandığı bir risk sınıflandırması taşır. Salt okunur analiz araçları safe olarak sıralanır ve otomatik yürütülür. Bir çağıranın kötüye kullanabileceği çıktı üreten araçlar review olarak sıralanır. İmzalama aracı approval-required olarak sıralanır; böylece sunucu, bir insan onaylayana kadar onu bekletir. Bu sınıflandırmayı aracın kendisi bildirir; bir operatör çalışma zamanında onu yalnızca sıkılaştırabilir — asla gevşetemez.

MCP araç yüzeyi, kasıtlı olarak Pro PDF motorundan ayrıdır. Araçlar ince adaptörlerdir: girdileri doğrular, PDF’yi çözümler, bir Pro motor bileşenine yetki devreder ve sonucu serileştirir. Bunlar motor için ikinci bir API değildir ve Pro genel PHP API’sinin parçası değildir — desteklenen tümleştirme noktası, NextPDF Server’ın sunduğu MCP protokolüdür.

Araç kataloğu (sekiz Pro aracı)

MCP protokol adına göre sekiz Pro MCP aracı. Risk düzeyleri, sunucunun HITL modelini izler: safe (otomatik yürütülen, salt okunur), review (kötüye kullanılabilecek çıktı üretir; aracı yönergelerinde uyarılır) ve approval-required (bir insan tarafından onaylanmalıdır).

`extract_text`

Amaç: Metin çıkarma. Bir PDF’nin metin katmanını, isteğe bağlı olarak 1 tabanlı bir sayfa aralığıyla sınırlandırarak çıkarın.
Girdiler: Bir PDF (document_id veya source); isteğe bağlı page_start ve page_end.
Çıktılar: Çıkarılan metin ve toplam sayfa sayısı.
Risk: Safe. Salt okunur ve etkisizdir (idempotent).
Sınır: Mevcut metin katmanını çıkarır. Taranmış veya yalnızca görüntü içeren sayfalarda OCR gerçekleştirmez.

`segment_document`

Amaç: Yapısal bölümleme. Bir PDF’yi mantıksal bölümlere ayırın — başlık, başlıklar, gövde, tablolar, şekiller.
Girdiler: Bir PDF (document_id veya source).
Çıktılar: Bir segment sayısı ve yapılandırılmış bir segment listesi.
Risk: Safe. Salt okunur ve etkisizdir.
Sınır: Yerleşim analizine dayalı yapısal bölümleme; bir anlamsal taslak veya etiketli PDF yapı ağacı değildir.

`compare_pdfs`

Amaç: Yapısal fark. İki PDF’yi karşılaştırın ve metin içeriklerinin yapılandırılmış bir farkını döndürün.
Girdiler: İki PDF (source_a ve source_b; her biri bir yol, base64, data URI veya document_id).
Çıktılar: Bir özdeşlik bayrağı, toplam değişiklik sayısı, belge başına sayfa sayıları ve sayfa ve satır dizinleriyle birlikte değişen bölgelerin bir listesi.
Risk: Safe. Salt okunur ve etkisizdir.
Sınır: Metin içeriği farkı. Görsel oluşturmayı, gömülü yazı tiplerini veya ikili yapıyı karşılaştırmaz.

`redact_pii`

Amaç: PII algılama ve maskeleme. Bir PDF’nin metin katmanındaki kişisel olarak tanımlanabilir bilgileri algılayın ve metnin maskelenmiş bir görünümünü döndürün.
Girdiler: Bir PDF (document_id veya source); isteğe bağlı types filtresi (email, phone, ssn, credit_card).
Çıktılar: Bir PII-var bayrağı, algılanan sayı, maskelenmiş metin ve taranan türlerin listesi.
Risk: Review. Maskelenmiş çıktı, temizlenmiş bir belge olarak değerlendirilirse kötüye kullanılabilir.
Sınır: Bu, görsel karartma değil, metin katmanı desen algılama ve maskelemedir. Oluşturulan PDF’deki glifleri kaldırmaz veya üzerine yazmaz ve desen eşleştirme, hassas verilerin her örneğinin bulunduğunu garanti etmez. Çıktısını tam PII kaldırma garantisi olarak değerlendirmeyin. Temel içeriği yok eden belge düzeyinde karartma için, açık kaynaklı sunucu araçlarındaki ya da Enterprise sürümündeki özel karartma yüzeyini kullanın.

`fill_form`

Amaç: AcroForm doldurma verisi. Bir alan adları-değerler eşlemesinden PDF AcroForm alanlarını dolduran XFDF (ISO 19444-1) verisi üretin.
Girdiler: Alan adından dize değerine bir fields eşlemesi; XFDF referansı olarak gömülen isteğe bağlı pdf_filename.
Çıktılar: Üretilen XFDF belgesi ve alan sayısı.
Risk: Review. Bir belgeye uygulanmak üzere tasarlanmış form verisi üretir.
Sınır: Standartlara uygun XFDF üretir; değerleri kendisi bir PDF’ye geri yazmaz. XFDF’yi uyumlu herhangi bir okuyucu veya işleme aracıyla uygulayın.

`extract_form_data`

Amaç: AcroForm geri okuma. Bir PDF’ye gömülü XFDF’den AcroForm alan adlarını ve değerlerini çıkarın.
Girdiler: Bir PDF (document_id veya source).
Çıktılar: Bir alan sayısı ve alan adlarından değerlere bir eşleme; gömülü form verisi yokken açık bir not.
Risk: Safe. Salt okunur ve etkisizdir.
Sınır: Gömülü XFDF (ISO 19444-1) akışlarını okur. Form değerlerini yalnızca AcroForm nesnelerinde, gömülü XFDF olmadan tutan bir PDF, boş bir sonuç döndürür.

`check_accessibility`

Amaç: Yapısal erişilebilirlik analizi. Bir PDF’nin yapısal erişilebilirliğini — başlıklar, paragraflar, tablolar ve görüntüler — analiz edin ve WCAG referanslarıyla olası sorunları raporlayın.
Girdiler: Bir PDF (document_id veya source).
Çıktılar: Bir yapısal puan (0–100), bir sorun listesi ve bir segment özeti.
Risk: Safe. Salt okunur ve etkisizdir.
Sınır: Bu, bir uygunluk kararı değil, yapısal bir sezgiseldir. Tam PDF/UA ve WCAG uygunluk testi — etiket ağacı, okuma sırası, renk karşıtlığı — özel bir erişilebilirlik motoru gerektirir. Yüksek bir puan, PDF/UA uygunluğu beyanı değildir.

`sign_pdf`

Amaç: PAdES B-B dijital imza. Yerel bir X.509 sertifikası ve özel anahtarı kullanarak bir PDF’ye bir PAdES B-B (baseline) dijital imzası uygulayın.
Girdiler: Bir PDF (document_id veya source); bir PEM sertifikası ve PKCS#8 özel anahtarı; isteğe bağlı bir algoritma (varsayılan RSA-SHA256, RSA + SHA-3 256/384/512 veya Ed25519); isteğe bağlı imzalayıcı adı ve nedeni; özel anahtar yükü etrafında isteğe bağlı bir AES-GCM aktarım zarfı.
Çıktılar: İmzalanmış PDF, imza sayısı, tamamlanma bayrağı ve kullanılan algoritma, OID ve özet.
Risk: Approval-required. İmzalama, hukuken anlamlı, yıkıcı bir işlemdir; sunucu, çalışmadan önce açık bir insan onayı gerektirir.
Sınır: Bu araç bir PAdES B-B (baseline) imzası üretir — bir güvenilir zaman damgası veya uzun vadeli doğrulama malzemesi gömmez. Uzun vadeli (B-LT / B-LTA) profiller, donanım destekli anahtar muhafazası ve denetim izi imzalama Enterprise sürümünün bir parçasıdır; B-T (zaman damgalı bir imza), bir zaman damgası sağlayıcısı yapılandırıldığında Core motorundan sağlanır. Pro paketinin daha geniş imzalama yetenekleri için Pro imza yüzeyi bölümüne ve B-LT/B-LTA için Enterprise sürümüne bakın.

Araçlar nasıl ortaya çıkar

composer require nextpdf/pro
composer require nextpdf/server

Her iki paket de yüklüyken, seçtiğiniz aktarımla NextPDF Server’ı başlatın. Sunucu, önyüklemede Pro katmanını keşfeder ve sekiz araç, MCP tools/list yanıtında pro katmanı altında, açık kaynaklı Core araçlarının yanında görünür. Uygulamanız herhangi bir kod değişikliği gerektirmez — keşif otomatik olarak çalışır ve eksik bir katman, diğerlerinin yüklenmesini asla engellemez.

Her araç için yetkili giriş ve çıkış şeması, sunucunun tools/list yanıtında yayımladığı şemadır. O yanıtı — bu sayfayı değil — sözleşme olarak değerlendirin: bu katalog niyeti ve sınırları açıklar; canlı şema, tam alan adlarını ve türlerini açıklar.

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

Pro araçları, bir Pro PHP API’si üzerinden değil, MCP protokolü üzerinden tüketilir. Ana bilgisayar tarafı tümleştirme, NextPDF Server’ı önyüklemektir. nextpdf/pro mevcutken, sekiz araç çalışma zamanı keşfi aracılığıyla kaydolur — araç başına bağlantı yoktur — ve ana bilgisayar sonra bunları aracılara sunar.

<?php

declare(strict_types=1);

use NextPDF\Server\Mcp\McpServer;

require __DIR__ . '/vendor/autoload.php';

// Runtime discovery registers the Pro tier when nextpdf/pro is installed
// alongside nextpdf/server. The consuming application changes no code.
$server = McpServer::create();

// A Pro tool name resolves only when the Pro package is present.
$signTool = $server->getToolRegistry()->get('sign_pdf');

\fwrite(\STDERR, $signTool !== null
    ? "Pro MCP tools active.\n"
    : "Pro MCP tools unavailable; install nextpdf/pro.\n");

// Serve the MCP protocol over stdio (Claude Desktop, Cursor, local agents).
$server->run();

Kod örneği — Üretim

Önyükleme yolunu sağlamlaştırın. Açık bir politika dosyası yükleyin, geçersiz bir risk düzeyi geçersiz kılmasında başlamayı reddedin ve sunmadan önce Pro katmanının ortaya çıktığını doğrulayın. McpServer::create() içindeki bağlantı, bir risk_level_overrides bloğu sign_pdf gibi approval-required bir aracı zayıflatmaya çalıştığında InvalidArgumentException fırlatır; böylece hatalı yapılandırılmış bir politika, sunma döngüsünden önce kapalı arızalar.

<?php

declare(strict_types=1);

use NextPDF\Server\Mcp\McpServer;
use NextPDF\Server\Tools\ToolInterface;

require __DIR__ . '/vendor/autoload.php';

// A downgrade of an approval-required tool's HITL gate is rejected at boot,
// never silently applied — the server refuses to start on such a policy.
try {
    $server = McpServer::create(__DIR__ . '/nextpdf-mcp.yaml');
} catch (\InvalidArgumentException $e) {
    \fwrite(\STDERR, 'Refusing to start: invalid MCP policy. ' . $e->getMessage() . "\n");
    exit(1);
}

// Confirm the Pro tier surfaced before advertising it to agents.
$signTool = $server->getToolRegistry()->get('sign_pdf');

if (!$signTool instanceof ToolInterface) {
    \fwrite(\STDERR, "nextpdf/pro is not resolving; Pro MCP tools are unavailable.\n");
    exit(1);
}

// sign_pdf is approval-required; the server holds it for human confirmation.
$risk = $signTool->riskLevel()->label();
\fwrite(\STDERR, "Pro MCP tools ready. sign_pdf risk: {$risk}.\n");

$server->run();

Üretim rehberliği

HITL kapılama. sign_pdf’yi insan onayının arkasında tutun. Sunucu bunu, aracın bildirdiği risk düzeyinden uygular; aracınızı bunu atlamak üzere yapılandırmayın. Bir operatör, bir aracın risk düzeyini yalnızca sıkılaştırabilir, asla gevşetemez.
Kaynak işleme. Oturumda zaten bulunan belgeler için document_id’yi tercih edin. Satır içi veriler için, araçlar base64 ve data: URI’lerini kabul eder; çok büyük satır içi yükler, başvurulan bir belgeden daha yavaş çalışır.
PII beklentileri. Çağıran beklentilerini açıkça ayarlayın: redact_pii bir algılama ve maskeleme yardımcısıdır, bir temizleme garantisi değildir. Geri döndürülemez kaldırma için, özel bir karartma yüzeyine yönlendirin.
İmzalama anahtarları. Aktarım uçtan uca gizli değilken, anahtarları aktarım şifreleme zarfı aracılığıyla sağlayın. Özel anahtar malzemesini, aracınızın araç çağrısı günlükleme politikasında bir gizli dizi olarak değerlendirin.
Denetim günlüğü. Safe düzeyinin üzerindeki araçlar, sunucu tarafından denetim günlüğüne kaydedilir. Dağıtımınızın bu günlükleri uyumluluk gereksinimlerinize göre sakladığından emin olun.

Uç durumlar

extract_text sayfa aralıkları 1 tabanlıdır ve belgenin gerçek sayfa sayısına sıkıştırılır; aralık dışı bir son, hata vermez.
compare_pdfs her iki kaynağı da gerektirir; birini geçirmek, kısmi bir fark yerine açık bir doğrulama hatası döndürür.
extract_form_data, gömülü XFDF içermeyen PDF’ler için bir hata yerine doldurulmuş, açık bir “gömülü form verisi yok” sonucu döndürür.
sign_pdf, desteklenen değerlerin listesiyle birlikte desteklenmeyen algoritma tanımlayıcılarını reddeder; Ed25519, libsodium uzantısını ve SHA-3 türevleri, SHA-3 desteğine sahip bir OpenSSL derlemesini gerektirir.
check_accessibility, yalnızca görüntü içeren PDF’leri tasarım gereği düşük puanlar — başarısız olmak yerine okunabilir bir metin katmanının yokluğunu işaretler.

Güvenlik notları

İmzalama aracı, onay gerektiren tek araçtır; sunucu onu otomatik yürütmez.
Özel anahtar etrafındaki isteğe bağlı AES-GCM zarfı, yükün kimliğini doğrular; bir etiket uyuşmazlığı, bir şifre çözme hatasıyla kapalı arızalar ve şifreli metni kullanmaya asla geri dönmez.
redact_pii, kaynak PDF’yi değiştirmez; maskelenmiş bir metin temsili döndürür. İçerik yok etmenin yerine geçmez.
Araç, herhangi bir motor işinden önce girdileri doğrular; hatalı biçimlendirilmiş kaynakları, data URI’lerini ve base64 yüklerini açık hatalarla reddeder.

Uygunluk

Form araçları, ISO 19444-1:2019 (XML Forms Data Format) uyarınca XFDF üretir ve tüketir.
sign_pdf, ETSI EN 319 142 PAdES ailesiyle hizalı bir PAdES baseline (B-B) imzası üretir; uzun vadeli profiller bir Enterprise yeteneğidir ve B-T, bir zaman damgası sağlayıcısı yapılandırıldığında Core motorundan sağlanır.
check_accessibility, bulguları bir uygunluk beyanı olarak değil, sezgisel rehberlik olarak WCAG başarı ölçütü referanslarıyla (örneğin 1.1.1, 1.3.1, 2.4.6) raporlar.

Sürüm sınırı

NextPDF Pro tam olarak sekiz MCP aracı katkıda bulunur; hepsi pro katmanındadır. Enterprise sürümü, enterprise katmanında kendi ayrı MCP araç setini sunar — uyumluluk denetimi, adli analiz, uzun vadeli doğrulama sağlığı, AI’ya hazır sertifikasyon ve belge arama ve gömme kapsar. Bu araçlar, girdileri ve iç yapıları bu sayfanın kapsamı dışındadır; Enterprise MCP araçlarına bakın. Sunucunun kendi belgeleri, onunla birlikte gelen Core (açık kaynaklı) araçları kapsar. Sunucu üç katmanı bağımsız olarak keşfeder ve eksik bir katman, diğerlerini asla devre dışı bırakmaz.

Enterprise sınır notu

Pro, pro katmanında tam olarak sekiz MCP aracına katkıda bulunur. Enterprise sürümü, enterprise katmanında ayrı bir MCP araç seti (uyumluluk denetimi, adli analiz, uzun vadeli doğrulama sağlığı, AI’ya hazır sertifikasyon, belge arama ve gömme) ve zaman damgalı/uzun vadeli imza profillerini sunar; bunlar Pro katmanı tarafından sağlanmaz. Tam katman dökümü için yukarıdaki Sürüm sınırı bölümüne bakın.

Core geri dönüşü / alternatifi

Açık kaynaklı NextPDF Server, herhangi bir AI aracına lisans olmadan belirleyici bir Core PDF araç seti (belge oluşturma, metin, tablolar, tanılama) verir. Bu sayfadaki sekiz gelişmiş araç, Pro eklentileridir. Bkz. /connect/tools/.

Yayımlama sınırı

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