Enterprise sürüm

MCP araçları

Bir bakışta

NextPDF Enterprise, NextPDF Connect sunucusuna on bir MCP aracı ekler. Bunlar, AI asistanlarına ve ajan çerçevelerine Enterprise motoruna doğrudan, tipli erişim sağlar: uyumluluk politikası denetimleri, PDF adli analizi, LTV sağlık denetimleri, AI hazırlık damgalama, AST duyarlı parçalama ve RAG alımı ile arama. Her araç kendi risk düzeyini ve salt okunur duruşunu bildirir; böylece MCP ana makineniz ajan etkinliğini güvenle geçitleyebilir, günlükleyebilir ve denetleyebilir. Hatalar hiçbir zaman istisna olarak yüzeye çıkmaz; ajanlar her zaman yapılandırılmış, ayrıştırılabilir bir sonuç alır.

Kullanılabilirlik ve lisanslama

Bu özellik NextPDF Enterprise (nextpdf/enterprise) içinde sunulur ve Enterprise katmanı lisans zarfıyla etkinleşir. Bu yetkiye sahip olmayan bir dağıtım, özelliğin sınıflarını yüklemez. Sürümleri karşılaştırın ve bir lisans edinin.

Kurulum

composer require nextpdf/enterprise:^3

MCP ana makinesinin kendisi, nextpdf/server paketiyle sunulan NextPDF Connect’tir; bkz. Connect kurulumu. Her iki paket de mevcut olduğunda, sunucunun araç kayıt defteri NextPDF\Enterprise\McpToolProvider sağlayıcısını otomatik olarak keşfeder ve on bir Enterprise aracını kaydeder. Herhangi bir bağlama kodu gerekmez. nextpdf/server yoksa, sağlayıcı dosyası erken döner ve hiçbir şey yüklenmez.

Batch ve RAG araçları ek olarak Spectrum yan bileşenini gerektirir. Bunu NextPDF\Enterprise\Mcp\SpectrumClientFactory tarafından okunan ortam değişkenleriyle yapılandırın: SPECTRUM_URL (varsayılan http://127.0.0.1:7800), SPECTRUM_TIMEOUT (varsayılan 30.0 saniye), SPECTRUM_AUTH_TOKEN ve SPECTRUM_APP_SECRET.

Kavramsal genel bakış

Model Context Protocol (MCP), AI asistanlarının ve ajan çerçevelerinin bir sunucu tarafından açığa çıkarılan tipli araçları çağırmasını sağlayan açık bir protokoldür. Bir ajan, PDF baytlarını bir isteme yapıştırıp umut etmek yerine, JSON şemasıyla doğrulanmış bir yük ile adlandırılmış bir aracı çağırır ve deterministik, yapılandırılmış bir sonuç alır. NextPDF Connect, PDF’ler için o sunucudur; Enterprise paketi kataloğunu aşağıdaki araçlarla genişletir. Her araç, PHP kodunuzun doğrudan çağırdığı aynı Enterprise API’leri üzerinde ince bir sarmalayıcıdır; böylece ajan tarafından çalıştırılan bir denetim ve kod tarafından çalıştırılan bir denetim aynı kararı üretir.

Araç kataloğu

MCP aracı	Sınıf	Ne yapar	Risk	Salt okunur
`compliance_check`	`ComplianceCheckTool`	Bir PDF’i adlandırılmış bir politikaya karşı doğrular: `pdfa4`, `pdfa4e`, `pdfa4f`, `pades-baseline`, `ltv-health`, `eidas-qualified`, `zugferd`, `fda-part11` ve dört `sec-17a4` çeşidi.	Review	evet
`batch_compliance_check`	`BatchComplianceCheckTool`	Birçok PDF’i tek bir Spectrum yan bileşeni batch’inde `pdfa`, `pades` veya `zugferd` politikalarına karşı denetler.	Safe	evet
`forensic_analyze`	`ForensicAnalyzeTool`	Kurcalama tespiti için revizyon geçmişini, artımlı güncellemeleri ve değişiklik olaylarını raporlar.	Safe	evet
`batch_forensic_analyze`	`BatchForensicAnalyzeTool`	Tek bir yan bileşen batch’inde birçok PDF üzerinde adli analiz çalıştırır.	Safe	evet
`ltv_health_check`	`LtvHealthCheckTool`	İmzalı bir PDF’i uzun süreli doğrulama materyali açısından denetler: DSS sözlüğü, OCSP yanıtları, CRL girdileri, VRI girdileri ve sertifika depoları.	Safe	evet
`ai_ready_certify`	`AiReadyCertifyTool`	Dört ölçüt üzerinde salt okunur, ürün tanımlı AI hazırlık kararı: adli bütünlük, imza varlığı, LTV geçerliliği, şifreleme yok.	Review	evet
`certify_ai_ready`	`CertifyAiReadyTool`	Üç ölçüt üzerinde ürün tanımlı hazırlık kararı (salt okunur aracın dört ölçütünden adli bütünlük çıkarılmış olarak — tasarım gereği, çünkü bu araç damgaladığı dosyayı yeniden yazar) verir ve bir XMP köken damgası ekler; damgalanmış PDF’i base64 olarak döndürür.	Review	hayır
`ast_aware_chunk`	`AstAwareChunkTool`	Bir PDF’i başlık sınırları boyunca alıntı çıpalı parçalara böler; her parça için düğüm kimliği, sayfa dizini ve sınırlayıcı kutu ile.	Review	evet
`audit_ast_mutations`	`AuditAstMutationsTool`	Bir belgenin AST mutasyon denetim izini SHA-256 kaynak karmasıyla getirir.	Review	evet
`embed_documents`	`EmbedDocumentsTool`	PDF’leri bir RAG koleksiyonuna alır: ayrıştır, parçala, göm, indeksle. Koleksiyon durumunu değiştirir.	Caution	hayır
`search_documents`	`SearchDocumentsTool`	Alınmış bir koleksiyon üzerinde hibrit erişim (BM25 anahtar sözcük artı anlamsal); sıralanmış, puanlanmış parçalarla.	Safe	evet

“Certify” araçları ürün tanımlı bir hazırlık kararı (certified, partial veya not_certified) verir. O karar teknik bir denetim sonucudur, herhangi bir akreditasyon kuruluşunun sertifikasyonu değildir.

Onay geçitleme ve denetim duruşu

Her araç, dört katmanlı Connect modelinden bir risk düzeyi bildirir. Safe araçlar otomatik yürütülür. Caution araçları bir denetim günlüğü girdisiyle otomatik yürütülür. Review araçları, çağıran ajanın talimatları için bir uyarı taşır. ApprovalRequired araçları insan onayı ister; hiçbiri yıkıcı olmadığından şu anda hiçbir Enterprise MCP aracı bu düzeyi bildirmez. Çalışma zamanı yapılandırması bir aracın risk düzeyini yalnızca yükseltebilir, asla düşüremez. Araçlar ayrıca MCP davranış açıklamaları (readOnlyHint, idempotentHint) yayımlar; böylece uyumlu bir istemci kendi geçitlemesini bunun üzerine uygulayabilir. Tam model için bkz. HITL risk katmanları.

Neden bu şekilde çalışır

Yük taşıyan karar, araçların kendi kendine bildirilen yönetişimle ince, deterministik sarmalayıcılar olmasıdır: her araç kendi risk düzeyini ve katmanını bir etki alanı değişmezi olarak bildirir, asla ad alanından veya paketlemeden çıkarsamaz. Bu, geçitleme kararını taşımaya güvenmeden ana makinede denetlenebilir tutar. Araçlar kendilerine ait hiçbir belge zekâsı içermez; kodunuzun çağırdığı aynı Enterprise API’lere devrederler; böylece test edilecek tam olarak bir davranış ve güvenilecek bir karar vardır. Hatalar istisna olarak kaçmak yerine MCP hata kanalında döner, çünkü bir ajan bir PHP istisnasını yakalayamaz ama her zaman isError üzerinde dallanabilir. Dosya sistemine dokunabilecek girdi varsayılan olarak fail-closed’dur, çünkü MCP argümanları tanım gereği saldırgan tarafından erişilebilirdir.

Tasarım arka planı: Tahmin etmeyi reddeden bir API.

API yüzeyi

On bir aracın tümü nextpdf/server içindeki NextPDF\Server\Tools\ToolInterface sözleşmesini uygular ve aynı genel yüzeyi paylaşır. Aşağıdaki imzalar temsili olarak yalnızca bir kez NextPDF\Enterprise\Mcp\ComplianceCheckTool üzerinde gösterilmiştir:

public function name(): string
public function description(): string
public function inputSchema(): array
public function annotations(): array
public function riskLevel(): RiskLevel
public function tier(): ToolTier
public function category(): string
public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

Şunu fırlatır veya şununla başarısız olur: execute() asla fırlatmaz. Dahili olarak Throwable yakalar ve isError = true ile ToolResult::error() döndürür. Geçersiz argümanlar (eksik workspace_token, hatalı biçimlendirilmiş documents girdileri, bilinmeyen document_id, güvensiz source) o hata kanalında InvalidArgumentException mesajları olarak yüzeye çıkar.

Denetim izi aracı, depolama arka ucunu yapıcı enjeksiyonuyla alır:

public function __construct(private readonly AstAuditTrailInterface $auditTrail)

Kataloğu kaydeden sağlayıcı:

public function getTier(): string
public function getTools(): array

getTier() 'enterprise' döndürür. getTools() on bir araç örneğini döndürür; audit_ast_mutations varsayılan olarak NextPDF\Enterprise\Ast\InMemoryAstAuditTrail ile bağlanır.

Aynı zamanda bir PSR-17 istek ve akış fabrikası olan Spectrum yan bileşeni istemci fabrikası:

public static function create(): SpectrumClient
public static function reset(): void
public function createRequest(string $method, $uri): RequestInterface
public function createStream(string $content = ''): StreamInterface
public function createStreamFromFile(string $filename, string $mode = 'r'): StreamInterface
public function createStreamFromResource($resource): StreamInterface

Şunu fırlatır veya şununla başarısız olur: SPECTRUM_URL hatalı biçimlendirildiğinde veya yapılandırılan uç nokta bilinen bir özel ya da ayrılmış adresi (localhost hariç) hedeflediğinde create() bir InvalidArgumentException fırlatır. Bu, ağ katmanı denetimi değil, yapılandırma zamanı bir geçittir: yine de ana makine ortamında çıkış politikasını, yönlendirme işlemeyi ve DNS sabitlemeyi uygulayın. Dosya açılamadığında createStreamFromFile(), NextPDF\Enterprise\Mcp\McpStreamException (PSR-17 sözleşmesi uyarınca bir RuntimeException alt sınıfı) fırlatır.

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

Bir PDF/A-4 uyumluluk denetimini, tam olarak bir ajanın yapacağı gibi, bellek içi data: URI kanalını kullanarak çalıştırın:

<?php

declare(strict_types=1);

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

use NextPDF\Enterprise\Mcp\ComplianceCheckTool;
use NextPDF\Enterprise\Mcp\McpStreamException;
use NextPDF\Enterprise\Mcp\SpectrumClientFactory;
use NextPDF\Server\Document\InMemoryDocumentStore;

$streams = new SpectrumClientFactory(); // PSR-17 stream factory from this module

try {
    $pdfBytes = (string) $streams->createStreamFromFile(__DIR__ . '/invoice.pdf');
} catch (McpStreamException $e) {
    fwrite(STDERR, 'Cannot read PDF: ' . $e->getMessage() . PHP_EOL);
    exit(1);
}

$tool   = new ComplianceCheckTool();
$result = $tool->execute(
    [
        'source' => 'data:application/pdf;base64,' . base64_encode($pdfBytes),
        'policy' => 'pdfa4',
    ],
    new InMemoryDocumentStore(),
);

// Tool failures arrive on the MCP error channel, never as exceptions.
if ($result->isError) {
    fwrite(STDERR, $result->content[0]['text'] . PHP_EOL);
    exit(1);
}

echo $result->content[0]['text'] . PHP_EOL;

Uyumlu bir dosya için beklenen çıktı (bulgu sayıları belgeye göre değişir):

Compliance check (PDF/A-4): PASS — 0 finding(s)

Bulgu bazında önem derecesi, kural kimliği, cümle ve öneri dahil tam makine tarafından okunabilir rapor $result->structured üzerinde bulunur.

Kod örneği — Üretim

Yan bileşeni ön denetleyin, bildirilen risk duruşunu uygulayın, ardından bir batch uyumluluk denetimi çalıştırın:

<?php

declare(strict_types=1);

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

use NextPDF\Enterprise\Mcp\BatchComplianceCheckTool;
use NextPDF\Enterprise\Mcp\SpectrumClientFactory;
use NextPDF\Server\Document\InMemoryDocumentStore;

// 1. Fail fast on sidecar misconfiguration before accepting agent traffic.
//    The factory validates SPECTRUM_URL and rejects private/reserved targets.
try {
    SpectrumClientFactory::create();
} catch (InvalidArgumentException $e) {
    fwrite(STDERR, 'Spectrum sidecar rejected: ' . $e->getMessage() . PHP_EOL);
    exit(1);
}

$tool = new BatchComplianceCheckTool();
$risk = $tool->riskLevel();

// 2. Enforce the declared risk posture before execution.
if ($risk->requiresHumanConfirmation()) {
    // Route to your approval queue instead of executing.
    exit(0);
}

if ($risk->requiresAuditLog()) {
    error_log(sprintf('[mcp-audit] tool=%s risk=%s', $tool->name(), $risk->label()));
}

// 3. Execute the batch.
$result = $tool->execute(
    [
        'workspace_token' => (string) getenv('SPECTRUM_WORKSPACE_TOKEN'),
        'documents'       => [
            ['id' => 'contract-001', 'path' => '/var/pdf-inbox/contract-001.pdf'],
            ['id' => 'contract-002', 'path' => '/var/pdf-inbox/contract-002.pdf'],
        ],
        'policies'        => ['pdfa', 'pades'],
    ],
    new InMemoryDocumentStore(),
);

echo $result->content[0]['text'] . PHP_EOL;

Beklenen çıktı (sayılar belgelerinizi yansıtır):

Batch compliance check complete: 1 compliant, 1 non-compliant

Uç durumlar ve tuzaklar

Dosya sistemi source yolları varsayılan olarak devre dışıdır. NEXTPDF_MCP_INPUT_DIR ortam değişkeni olmadan, yol biçimli bir source bir hata sonucuyla reddedilir. Bunun yerine document_id, bir data: URI’si veya ham base64 kullanın.
Ham base64 yalnızca 256 karakterin üzerinde tanınır. Daha kısa bir base64 bloğu bir dosya yolu olarak ele alınır ve reddedilir. Küçük yükleri bir data:application/pdf;base64, URI’sine sarın.
Bilinmeyen document_id değerleri yönlendirmeyle başarısız olur. Hata metni Unknown document_id: ... Call create_pdf first. şeklindedir. Bellek içi depodaki belgeler de deponun TTL’sinde sona erer; bu nedenle eski bir kimlik aynı şekilde başarısız olur.
compliance_check, bilinmeyen politika anahtarlarını reddeder ve desteklenen kümeyi hata mesajında listeler.
Batch ve RAG araçları yan bileşene ihtiyaç duyar. batch_compliance_check, batch_forensic_analyze, embed_documents ve search_documents, erişilebilir bir Spectrum uç noktası ve bir workspace_token gerektirir. Fabrika işlem başına bir istemciyi önbelleğe alır; testlerde SpectrumClientFactory::reset() çağırın.
search_documents, top_k değerini 1–100 aralığına sabitler; tamsayı olmayan değerler sunucu varsayılanı olan 10’a döner.
ast_aware_chunk varsayılanları parça başına 1500 karakter ve 150 karakter örtüşmedir.
certify_ai_ready, damgalanmış baytları atlar: return_stamped_pdf false olduğunda veya karar not_certified olduğunda. Mevcut olduğunda, base64 yükü PDF’in kendisinden yaklaşık üçte bir daha büyüktür.
Varsayılan AST denetim izi bellek içidir. Stok sağlayıcı bağlaması aracılığıyla kaydedilen girdiler işlemler arasında kalıcı olmaz; dayanıklı denetim izleri için kalıcı bir AstAuditTrailInterface uygulaması enjekte edin.

Güvenlik notları

Fail-closed kaynak çözümlemesi. MCP çağıranları araç argümanlarını tamamen denetler; bu nedenle çözümleyici bunları düşmanca olarak ele alır. Akış sarmalayıcıları (phar://, php://, file:// ve herhangi bir şema) ve boş baytlar, herhangi bir dosya sistemi çağrısından önce reddedilir. Yol geçişi reddedilir. Ham dosya yolları yalnızca NEXTPDF_MCP_INPUT_DIR ayarlandığında çalışır ve realpath ile kanonikleştirilen hedef, önek karışıklığı kaçışlarını engellemek için bir ayırıcı sınırında karşılaştırılarak kesinlikle o dizinin içinde çözümlenmelidir.
Yan bileşen uç noktasında SSRF koruması. SpectrumClientFactory, yerel yan bileşen modu için localhost’a izin verir ve diğer her SPECTRUM_URL değerini özel, ayrılmış, bağlantı yerel ve bulut meta veri aralıklarına karşı doğrular; engellenen bir adreste InvalidArgumentException fırlatır. Bu, yapılandırılan uç nokta üzerinde yapılandırma zamanı bir geçittir, ağ katmanı denetimi değildir — çıkış politikasını, yönlendirme işlemeyi ve DNS sabitlemeyi ana makine ortamında tutun.
Sırlar ortamda kalır. Yan bileşen taşıyıcı belirteci (SPECTRUM_AUTH_TOKEN) ve HMAC imzalama sırrı (SPECTRUM_APP_SECRET) ortam değişkenlerinden okunur ve araç yüklerinde veya sonuçlarında asla görünmez.
Yansıtıcı olmayan hatalar. Yol reddi mesajları tasarım gereği geneldir (Source path is not permitted.); böylece araştıran bir çağıran ana makine dosya sistemi hakkında hiçbir şey öğrenmez.
Risk geçersiz kılmaları yalnızca yukarı gider. Operatör yapılandırması bir aracın bildirilen risk düzeyini yükseltebilir ancak asla aracın kendi bildiriminin altına düşüremez.

Uygunluk

Destek uygunluk değildir ve uygunluk sertifikasyon değildir. NextPDF hiçbir sertifikasyona sahip değildir ve hiçbirini vermez. Uyumluluk araçları belge yapısını adlandırılmış politika profillerine karşı denetler ve bulguları cümle referanslarıyla raporlar; compliance_check raporu ek olarak motorun kendi feragatnamesini taşır: bunun yasal tavsiye veya bir uyumluluk onayı değil, referans için teknik bir yapı denetimi olduğunu belirtir. ai_ready_certify ve certify_ai_ready kararları ürün tanımlı hazırlık düzeyleridir, herhangi bir standartlar kuruluşunun tasdiki değildir. MCP, bir SDO standardı değil, satıcı yöneticisi tarafından yayımlanan açık bir protokoldür; bu sayfa NextPDF’in uygulama davranışını belgeler ve bağımsız bir protokol uygunluğu veya sertifikasyon iddiasında bulunmaz.

Davranış sözleşmesi

Araç hataları hata sonuçları olarak döndürülür (bir mesajla isError = true); istisnalar asla MCP sınırını geçmez.
Başarılı sonuçlar, tek satırlık insan tarafından okunabilir bir özet ile araç başına kararlı, belgelenmiş bir alan kümesine sahip yapılandırılmış bir JSON yükü taşır.
Her araç tier() = ToolTier::Enterprise ve bildirilen bir RiskLevel raporlar; risk çalışma zamanında düşürülemez.
Salt okunur araçlar readOnlyHint: true bildirir ve belge deposunu, kaynak PDF’i veya herhangi bir koleksiyonu değiştirmez.
certify_ai_ready, girdi belgesini asla yerinde değiştirmez; damga döndürülen bir kopyaya uygulanır.
Uyumluluk ve LTV raporları bir doğrulama zaman damgası ve önem derecesine göre bulgu sayıları içerir; compliance_check yükü ek olarak motorun yasal feragatname dizesini içerir.

Core yedeği

MCP ana makinesinin kendisi Enterprise gerektirmez. NextPDF Connect (nextpdf/server, Apache-2.0), açık Core motoruyla çalışır ve core katmanı araç kataloğunu sunar: belge oluşturma, metin ve içerik işlemleri ve çıkarma. Bkz. araç kataloğu. Core tek başına uyumluluk politikası denetimleri, adli analiz, LTV sağlık denetimleri, AI hazırlık damgalama, AST duyarlı parçalama, mutasyon denetim izleri veya batch ve RAG araçları sağlamaz; o on bir araç yalnızca nextpdf/enterprise kurulu ve lisanslı olduğunda kaydedilir.

Yayın sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilir davranışı ve desteklenen genel API yüzeyini belgeler. Dahili ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, çalıştırma kılavuzu dosya adları ve bilet önekleri kapsam dışıdır.