MCP — Derinlemesine başvuru

Bir bakışta

NextPDF\Enterprise\Mcp ad alanı, NextPDF MCP araç kataloğunun Enterprise katmanını sağlar. Genel yüzeyi on bir araç sınıfı, bir istemci fabrikası ve bir tipli istisnadır. Her araç, nextpdf/server çalışma zamanındaki NextPDF\Server\Tools\ToolInterface sözleşmesini uygular ve ToolTier::Enterprise bildirir. Altı araç, süreç içinde tek bir PDF’i çözümler. Dört araç, toplu ve RAG iş yüklerini NextPDF\Enterprise\Mcp\SpectrumClientFactory aracılığıyla Spectrum sidecar’a devreder. Bir araç, PDF baytları yerine kurucuya enjekte edilmiş bir AST mutasyon denetim izini okur. Her araç; kendi MCP adını, JSON Schema girdisini, istemci açıklamalarını, RiskLevel değerini ve kategorisini kendisi tanımlar.

Kullanılabilirlik ve lisanslama

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

Genel API yüzeyi

Sembol	Parametreler	Varsayılan davranış	Döndürür	Şununla hata verir veya başarısız olur	Notlar
ForensicAnalyzeTool::execute	array $arguments, InMemoryDocumentStore $store; argümanlar: document_id veya source	Adli analiz çalıştırır: revizyonlar, artımlı güncellemeler, imzalar	ToolResult (JSON raporu)	Hatalı ToolResult; istisnalar yakalanır, asla yeniden fırlatılmaz	Araç forensic_analyze; RiskLevel::Safe; salt okunur, idempotent; kategori document; since 2.0.0
BatchForensicAnalyzeTool::execute	argümanlar: workspace_token, documents[] (her biri id + path)	Spectrum sidecar üzerinden toplu adli analiz	Belge başına status, başarılı ve başarısız sayılarıyla birlikte ToolResult	Hatalı ToolResult (eksik argümanlar, sidecar hatası)	Araç batch_forensic_analyze; RiskLevel::Safe; kategori document; since 2.1.0
ComplianceCheckTool::execute	argümanlar: policy (12 değerli enum), document_id veya source	PDF’i adlandırılmış tek bir uyumluluk politikasına göre değerlendirir	Bulgular, geçti/kaldı, duration_ms ve bir disclaimer alanı içeren ToolResult	Hatalı ToolResult; bilinmeyen politika, desteklenen anahtarları listeleyen bir hata döndürür	Araç compliance_check; RiskLevel::Review; kategori document; since 2.0.0
BatchComplianceCheckTool::execute	argümanlar: workspace_token, documents[], policies (pdfa, pades, zugferd; varsayılan ["pdfa"])	Spectrum sidecar üzerinden toplu uyumluluk denetimleri	Uyumlu / uyumsuz sayılarıyla ToolResult	Hatalı ToolResult; her documents[] öğesi boş olmayan id ve path için doğrulanır	Araç batch_compliance_check; RiskLevel::Safe; kategori document; since 2.1.0
LtvHealthCheckTool::execute	argümanlar: document_id veya source	İmzalı bir PDF üzerinde LTV sağlık politikasını çalıştırır	Bulgular ve geçti/kaldı ile ToolResult	Hatalı ToolResult	Araç ltv_health_check; RiskLevel::Safe; kategori document; since 2.0.0
AiReadyCertifyTool::execute	argümanlar: document_id veya source	Dört ölçüt üzerinde salt okunur AI’ye hazırlık değerlendirmesi	certification_level (certified, partial, not_certified) ve ölçüt başına boole değerlerle ToolResult	Hatalı ToolResult	Araç ai_ready_certify; RiskLevel::Review; salt okunur; kategori document; since 2.0.0
CertifyAiReadyTool::execute	argümanlar: document_id veya source, return_stamped_pdf (varsayılan true)	Üç ölçütü değerlendirir ve bir XMP köken damgası ekler	ToolResult; devre dışı bırakılmadıkça veya not_certified olmadıkça stamped_pdf_base64 içerir	Hatalı ToolResult	Araç certify_ai_ready; RiskLevel::Review; salt okunur değil; kategori document; since 3.0.0
AstAwareChunkTool::execute	argümanlar: document_id veya source, max_chunk_chars (varsayılan 1500), overlap_chars (varsayılan 150)	AST’yi oluşturur ve köken bilgisiyle alıntı bağlantılı parçalar üretir	chunk_count ile parça başına düğüm ID’si, sayfa dizini, bbox, düğüm türü içeren ToolResult	Hatalı ToolResult	Araç ast_aware_chunk; RiskLevel::Review; kategori extraction; since 3.0.0
AuditAstMutationsTool::__construct	AstAuditTrailInterface $auditTrail	Denetim izi arka ucunu enjekte eder	örnek	—	Kurucuya enjekte edilen bağımlılık; since 3.0.0
AuditAstMutationsTool::execute	argümanlar: document_source_hash (SHA-256 hex, zorunlu)	O belge için kaydedilmiş tüm AST mutasyon olaylarını döndürür	entries[] ve count ile ToolResult	Argüman eksik veya boş olduğunda hatalı ToolResult	Araç audit_ast_mutations; RiskLevel::Review; kategori document; since 3.0.0
EmbedDocumentsTool::execute	argümanlar: collection_id, workspace_token, documents[] (tümü zorunlu)	Spectrum sidecar üzerinden PDF’leri bir RAG koleksiyonuna alır	Başarılı / toplam / başarısız sayılarıyla ToolResult	Hatalı ToolResult	Araç embed_documents; RiskLevel::Caution; salt okunur değil, idempotent değil; kategori extraction; since 2.1.0
SearchDocumentsTool::execute	argümanlar: collection_id, query (zorunlu), top_k (varsayılan 10, 1–100 arasına sıkıştırılır), mode (hybrid, bm25, semantic)	Alınmış bir koleksiyon üzerinde hibrit getirme	Sıralı parçalar ve alaka puanlarıyla ToolResult	Hatalı ToolResult; izin listesi dışındaki bir mode reddedilir	Araç search_documents; RiskLevel::Safe; kategori extraction; since 2.1.0
SpectrumClientFactory::create	yok (SPECTRUM_URL, SPECTRUM_TIMEOUT, SPECTRUM_AUTH_TOKEN, SPECTRUM_APP_SECRET okur)	Süreç genelinde tek bir sidecar istemcisi oluşturur ve önbelleğe alır	SpectrumClient	SPECTRUM_URL bozuk olduğunda veya engellenmiş bir adrese işaret ettiğinde InvalidArgumentException	Varsayılan uç nokta http://127.0.0.1:7800; zaman aşımı 30.0 s; since 2.1.0
SpectrumClientFactory::reset	yok	Önbelleğe alınmış istemci örneğini temizler	void	—	Testler için tasarlanmıştır
SpectrumClientFactory::createRequest	string $method, $uri (string veya UriInterface)	Core HTTP sınıflarından bir PSR-7 isteği oluşturur	RequestInterface	—	PSR-17 RequestFactoryInterface uygulaması
SpectrumClientFactory::createStream	string $content = ''	Bellek içi bir PSR-7 akışı oluşturur	StreamInterface	—	PSR-17 StreamFactoryInterface uygulaması
SpectrumClientFactory::createStreamFromFile	string $filename, string $mode = 'r'	Dosyayı açar ve onu bir akış olarak sarmalar	StreamInterface	Dosya açılamadığında McpStreamException	McpStreamException, RuntimeException sınıfını genişletir
SpectrumClientFactory::createStreamFromResource	$resource (PHP kaynağı)	Mevcut bir kaynağı bir akış olarak sarmalar	StreamInterface	—	PSR-17 StreamFactoryInterface uygulaması
McpStreamException	—	Tipli akış edinme hatası	—	—	final class, RuntimeException sınıfını genişletir; kaynak PSR-17 §1.5 uyumluluğunu belgeler; kaynak onu @since 3.2.0 olarak açıklar (mevcut 3.1.0 takma adlı dev hattında bulunur)

Her araç ayrıca ToolInterface öz-tanımlama yöntemlerini de sunar: name, description, inputSchema, annotations, riskLevel, tier ve category. Bunların araç başına değerleri yukarıdaki Notlar sütununda görünür.

Kaynaktan aynen alınan giriş noktası imzaları:

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function __construct(private readonly AstAuditTrailInterface $auditTrail)
public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

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

Davranış sözleşmesi

• Her araç NextPDF\Server\Tools\ToolInterface arayüzünü uygular ve ToolTier::Enterprise değerini açıkça bildirir. Katman asla ad alanından veya paketlemeden çıkarsanmaz.
• execute istisna fırlatmaz. Her hata yakalanır ve hata mesajını taşıyan bir hatalı ToolResult olarak döndürülür.
• Tek belgeli araçlar, PDF baytlarını sabit bir öncelikle çözümler. Önce InMemoryDocumentStore içinde bir document_id aranır. Aksi hâlde source, önce bir data: URI’si, ardından ham base64 (256 karakterden fazla), ardından bir dosya yolu olarak yorumlanır.
• Dosya sistemi source yolları varsayılan olarak devre dışıdır. Yalnızca NEXTPDF_MCP_INPUT_DIR ortam değişkeni sınırlandırılmış bir girdi dizini adlandırdığında etkinleşir. Çözümlenen gerçek yol, o dizinin içinde kalmalıdır. Diğer her şey kapalı biçimde başarısız olur.
• Akış sarmalayıcı şemaları (phar://, php://, file:// ve diğer herhangi bir şema) ve bir dosya yolu source içindeki boş baytlar, herhangi bir dosya sistemi çağrısından önce reddedilir. Geçiş ve simgesel bağlantı kaçışları, gerçek yol sınırlandırma denetimine karşı başarısız olur.
• Sidecar destekli araçlar (embed_documents, search_documents, batch_compliance_check, batch_forensic_analyze) istemcilerini SpectrumClientFactory::create üzerinden edinir. Fabrika, localhost olmayan bir SPECTRUM_URL değerini kullanımdan önce özel ve ayrılmış adres aralıklarına karşı doğrular. Yerel sidecar modu için açık localhost’a izin verilir.
• ai_ready_certify, seviyesini dört ölçütten türetir: adli bütünlük, imza varlığı, LTV geçerliliği ve şifreleme yokluğu. Dördünün de geçmesi certified verir; birden üçe kadarı partial; sıfırı not_certified. Adli bütünlük, revizyon zinciri üzerinde yapısal bir sezgisel yöntemdir, kriptografik bir bayt bütünlüğü doğrulaması değildir. Şifreleme denetimi yalnızca fragman (trailer) bölgesini inceler.
• certify_ai_ready, üç ölçütü değerlendirir ve bir XMP köken damgası ekler. Damgalanmış baytlar, return_stamped_pdf false olmadıkça veya seviye not_certified olmadıkça base64 kodlanmış olarak döndürülür.
• compliance_check, tam olarak on iki politika anahtarı kabul eder: pdfa4, pdfa4e, pdfa4f, pades-baseline, ltv-health, eidas-qualified, zugferd, fda-part11, sec-17a4, sec-17a4-compatible, sec-17a4-structural, sec-17a4-pre-sign. Bilinmeyen bir anahtar, desteklenen kümeyi adlandıran bir hata sonucu döndürür.
• audit_ast_mutations, yalnızca enjekte edilen AstAuditTrailInterface’i okur. Kendisi hiçbir şey kaydetmez.

Uç durumlar ve hata modları

• Ne document_id ne de source sağlandı: çağıranı bunlardan birini vermeye yönlendiren hata sonucu.
• Bilinmeyen document_id: ID’yi adlandıran ve create_pdf’e işaret eden hata sonucu.
• NEXTPDF_MCP_INPUT_DIR ayarlanmadan dosya sistemi source: desteklenen kanalları adlandıran bir mesajla reddedilir.
• Yapılandırılan girdi dizininin dışına, simgesel bağlantı yoluyla dâhil, çözümlenen source yolu: reddedilir. Karşılaştırma bir dizin ayırıcı sınırında gerçekleşir, bu nedenle ortak bir ad önekini paylaşan kardeş dizinler geçemez.
• Virgül ayırıcısı olmayan data: URI’si veya geçersiz base64 yükü: hata sonucu.
• search_documents top_k değeri 1–100 dışında: reddedilmez, sıkıştırılır. Tam sayı olmayan bir top_k, yapılandırılan boru hattı varsayılanına geri döner.
• search_documents mode değeri hybrid, bm25, semantic dışında: boru hattı izin listesinden hata sonucu.
• batch_compliance_check documents[] öğesinde id veya path eksik ya da boş dizeler taşıyor: hatalı dizini adlandıran hata sonucu. batch_forensic_analyze yalnızca dış dizi biçimini doğrular; öğe kusurları toplu katmandan yüzeye çıkar.
• Bozuk bir SPECTRUM_URL ile veya özel, bağlantı yerel ya da meta veri adresine işaret eden biriyle SpectrumClientFactory::create: InvalidArgumentException. Bir araç execute içinde bu, bir hata sonucu olarak yüzeye çıkar.
• Okunamayan bir yol üzerinde SpectrumClientFactory::createStreamFromFile: McpStreamException.
• Boş ortam değişkenleri, ayarlanmamış olarak kabul edilir ve varsayılanlara geri döner.

Uygunluk

NextPDF hiçbir sertifika tutmaz ve hiçbirini vermez. MCP araçları yetenek düzeyinde değerlendirmeler bildirir; destek uygunluk değildir ve uygunluk sertifikasyon değildir. ai_ready_certify ve certify_ai_ready tarafından döndürülen certification_level değerleri, araçların kendi bildirdiği sözcük dağarcığıdır. Bunlar üçüncü taraf bir tasdiki oluşturmaz. compliance_check yanıtları, aynı nedenle altta yatan rapor tarafından üretilen bir disclaimer alanı içerir. Ürün kaynağının ISO 32000-2:2020 §12.8.4.3 olarak belirttiği LTV politikası temeli gibi politika madde referansları, araç açıklamalarında ve bulgu başına clause alanlarında taşınır; bu sayfa hiçbir bağımsız standart iddiası eklemez. Denetlenen bir belgenin bir düzenlemeyi karşılayıp karşılamadığı, operatörün ve değerlendiricilerinin bir tespitidir.

Geliştirme notları

• SpectrumClientFactory::create, süreç başına tek bir istemciyi önbelleğe alır. Yeni bir istemciyi zorlamak için test kurulumunda SpectrumClientFactory::reset çağırın.
• Ortam okumaları sırasıyla $_ENV, ardından $_SERVER, ardından getenv değerlerine bakar ve boş dizeleri yok sayılmış olarak ele alır.
• RiskLevel, server çalışma zamanında ana bilgisayar tarafındaki işlemeyi yönlendirir: Safe otomatik çalışır, Caution ve üstü denetim günlüğüne kaydedilir ve ApprovalRequired insan onayı gerektirir. Hiçbir Enterprise MCP aracı ApprovalRequired bildirmez. Operatör geçersiz kılmaları, bildirilen bir seviyeyi yükseltebilir, asla düşüremez.
• annotations değerleri (readOnlyHint, idempotentHint), MCP istemci ipuçlarıdır, zorlama değildir. Sınırlandırma ve doğrulama, ipuçlarından bağımsız olarak server tarafında gerçekleşir.
• Araçlar, tools/list filtrelemesi için document veya extraction category değerlerini bildirir.
• AuditAstMutationsTool, kurucu enjeksiyonu gerektiren tek araçtır; onu somut bir AstAuditTrailInterface uygulamasıyla kaydedin.

Ayrıca bkz.

• MCP (yetenek sayfası)
• Accelerator — Derinlemesine başvuru — Spectrum sidecar istemci yüzeyi.
• Forensics — Derinlemesine başvuru — forensic_analyze arkasındaki çözümleyici.
• Compliance — Derinlemesine başvuru — compliance_check arkasındaki politikalar.
• AST — Derinlemesine başvuru — parçalama ve mutasyon denetim izi.
• Validation — Derinlemesine başvuru

Yayımlama sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilir 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.