‏⁨MCP⁩ — مرجع متعمّق

لمحة سريعة

يوفّر فضاء الأسماء NextPDF\Enterprise\Mcp فئة ⁨Enterprise⁩ من كتالوج أدوات ⁨MCP⁩ في ⁨NextPDF⁩. يتكوّن سطحه العام من إحدى عشرة فئة أداة، ومصنع عميل واحد، واستثناء واحد ذي نوع. تُنفِّذ كل أداة عقد NextPDF\Server\Tools\ToolInterface من زمن تشغيل nextpdf/server وتُعلن ToolTier::Enterprise. تُحلّل ست أدوات ملف ⁨PDF⁩ واحدًا داخل العملية. تُفوّض أربع أدوات أحمال الدفعات و⁨RAG⁩ إلى ⁨Spectrum sidecar⁩ عبر NextPDF\Enterprise\Mcp\SpectrumClientFactory. تقرأ أداة واحدة أثر تدقيق طفرات ⁨AST⁩ المحقون عبر المُنشئ بدلًا من بايتات ⁨PDF⁩. تصف كل أداة نفسها: اسم ⁨MCP⁩ الخاص بها، ومدخل ⁨JSON Schema⁩، وتعليقات العميل التوضيحية، وRiskLevel، والفئة.

التوفّر والترخيص

تُشحن هذه القدرة ضمن ‏⁨NextPDF Enterprise⁩ (nextpdf/enterprise) وتُفعَّل بحزمة ترخيص من فئة ⁨Enterprise⁩. لا يُحمِّل النشرُ الذي يفتقر إلى ذلك الاستحقاق فئاتِ هذه القدرة. قارن بين الإصدارات واحصل على ترخيص.

سطح واجهة برمجة التطبيقات العامة

الرمز	المعاملات	السلوك الافتراضي	القيمة المُعادة	يرمي أو يفشل بـ	ملاحظات
ForensicAnalyzeTool::execute	array $arguments, InMemoryDocumentStore $store؛ الوسائط: document_id أو source	يُجري تحليلًا جنائيًا: المراجعات، والتحديثات التزايدية، والتواقيع	ToolResult (تقرير ⁨JSON⁩)	ToolResult خطأ؛ تُلتقَط الاستثناءات ولا يُعاد رميها أبدًا	الأداة forensic_analyze؛ RiskLevel::Safe؛ للقراءة فقط، خاملة التكرار؛ الفئة document؛ منذ 2.0.0
BatchForensicAnalyzeTool::execute	الوسائط: workspace_token، documents[] (لكلٍّ id + path)	تحليل جنائي بالدفعات عبر ⁨Spectrum sidecar⁩	ToolResult مع status لكل مستند، وأعداد الناجح والفاشل	ToolResult خطأ (وسائط مفقودة، أو فشل الـsidecar)	الأداة batch_forensic_analyze؛ RiskLevel::Safe؛ الفئة document؛ منذ 2.1.0
ComplianceCheckTool::execute	الوسائط: policy (تعداد من 12 قيمة)، document_id أو source	يقيّم ملف ⁨PDF⁩ مقابل سياسة امتثال مُسمّاة واحدة	ToolResult مع النتائج، ونجاح/فشل، وduration_ms، وحقل disclaimer	ToolResult خطأ؛ تُعيد السياسةُ المجهولة خطأً يسرد المفاتيح المدعومة	الأداة compliance_check؛ RiskLevel::Review؛ الفئة document؛ منذ 2.0.0
BatchComplianceCheckTool::execute	الوسائط: workspace_token، documents[]، policies (pdfa، pades، zugferd؛ الافتراضي ["pdfa"])	فحوصات امتثال بالدفعات عبر ⁨Spectrum sidecar⁩	ToolResult مع أعداد المطابق/غير المطابق	ToolResult خطأ؛ يُتحقَّق من كل عنصر documents[] لضمان id وpath غير فارغين	الأداة batch_compliance_check؛ RiskLevel::Safe؛ الفئة document؛ منذ 2.1.0
LtvHealthCheckTool::execute	الوسائط: document_id أو source	يُطبّق سياسة صحّة ⁨LTV⁩ على ملف ⁨PDF⁩ موقَّع	ToolResult مع النتائج ونجاح/فشل	ToolResult خطأ	الأداة ltv_health_check؛ RiskLevel::Safe؛ الفئة document؛ منذ 2.0.0
AiReadyCertifyTool::execute	الوسائط: document_id أو source	تقييم للجاهزية للذكاء الاصطناعي للقراءة فقط عبر أربعة معايير	ToolResult مع certification_level (certified، partial، not_certified) وقيم منطقية لكل معيار	ToolResult خطأ	الأداة ai_ready_certify؛ RiskLevel::Review؛ للقراءة فقط؛ الفئة document؛ منذ 2.0.0
CertifyAiReadyTool::execute	الوسائط: document_id أو source، return_stamped_pdf (الافتراضي true)	يقيّم ثلاثة معايير ويُلحق ختم مصدر ⁨XMP⁩	ToolResult؛ يتضمّن stamped_pdf_base64 ما لم يُعطَّل أو تكن النتيجة not_certified	ToolResult خطأ	الأداة certify_ai_ready؛ RiskLevel::Review؛ ليست للقراءة فقط؛ الفئة document؛ منذ 3.0.0
AstAwareChunkTool::execute	الوسائط: document_id أو source، max_chunk_chars (الافتراضي 1500)، overlap_chars (الافتراضي 150)	يبني ⁨AST⁩ ويُصدر مقاطع مرتكزة على الاستشهاد مع بيان المصدر	ToolResult مع chunk_count ومعرّف العقدة وفهرس الصفحة و⁨bbox⁩ ونوع العقدة لكل مقطع	ToolResult خطأ	الأداة ast_aware_chunk؛ RiskLevel::Review؛ الفئة extraction؛ منذ 3.0.0
AuditAstMutationsTool::__construct	AstAuditTrailInterface $auditTrail	يحقن الخلفية الخاصة بأثر التدقيق	نسخة	—	تبعية محقونة عبر المُنشئ؛ منذ 3.0.0
AuditAstMutationsTool::execute	الوسائط: document_source_hash (‏⁨SHA-256⁩ ست عشري، مطلوب)	يُعيد كل أحداث طفرات ⁨AST⁩ المُسجَّلة لذلك المستند	ToolResult مع entries[] وcount	ToolResult خطأ عند غياب الوسيط أو كونه فارغًا	الأداة audit_ast_mutations؛ RiskLevel::Review؛ الفئة document؛ منذ 3.0.0
EmbedDocumentsTool::execute	الوسائط: collection_id، workspace_token، documents[] (كلها مطلوبة)	يُدخل ملفات ⁨PDF⁩ إلى مجموعة ⁨RAG⁩ عبر ⁨Spectrum sidecar⁩	ToolResult مع أعداد الناجح/الإجمالي/الفاشل	ToolResult خطأ	الأداة embed_documents؛ RiskLevel::Caution؛ ليست للقراءة فقط، وليست خاملة التكرار؛ الفئة extraction؛ منذ 2.1.0
SearchDocumentsTool::execute	الوسائط: collection_id، query (مطلوب)، top_k (الافتراضي 10، مقيَّد بين 1–100)، mode (hybrid، bm25، semantic)	استرجاع هجين عبر مجموعة مُدخَلة	ToolResult مع مقاطع مرتَّبة ودرجات صِلة	ToolResult خطأ؛ يُرفض أي mode خارج قائمة السماح	الأداة search_documents؛ RiskLevel::Safe؛ الفئة extraction؛ منذ 2.1.0
SpectrumClientFactory::create	لا شيء (تقرأ SPECTRUM_URL، SPECTRUM_TIMEOUT، SPECTRUM_AUTH_TOKEN، SPECTRUM_APP_SECRET)	تبني عميل sidecar واحدًا على مستوى العملية وتخزّنه مؤقتًا	SpectrumClient	InvalidArgumentException عندما يكون SPECTRUM_URL مشوَّهًا أو يستهدف عنوانًا محظورًا	نقطة النهاية الافتراضية http://127.0.0.1:7800؛ المهلة 30.0 ثانية؛ منذ 2.1.0
SpectrumClientFactory::reset	لا شيء	يمسح نسخة العميل المخزَّنة مؤقتًا	void	—	مخصَّصة للاختبارات
SpectrumClientFactory::createRequest	string $method, $uri (string أو UriInterface)	يبني طلب ⁨PSR-7⁩ من فئات ⁨Core HTTP⁩	RequestInterface	—	تنفيذ RequestFactoryInterface وفق ⁨PSR-17⁩
SpectrumClientFactory::createStream	string $content = ''	يبني دفق ⁨PSR-7⁩ في الذاكرة	StreamInterface	—	تنفيذ StreamFactoryInterface وفق ⁨PSR-17⁩
SpectrumClientFactory::createStreamFromFile	string $filename, string $mode = 'r'	يفتح الملف ويغلّفه كدفق	StreamInterface	McpStreamException عند تعذّر فتح الملف	McpStreamException يمتدّ من RuntimeException
SpectrumClientFactory::createStreamFromResource	$resource (مورد ⁨PHP⁩)	يغلّف موردًا قائمًا كدفق	StreamInterface	—	تنفيذ StreamFactoryInterface وفق ⁨PSR-17⁩
McpStreamException	—	فشل مكتوب النوع في الحصول على الدفق	—	—	final class، يمتدّ من RuntimeException؛ يوثّق المصدر توافق ⁨PSR-17 §1.5⁩؛ ويصف المصدر التعليقَ التوضيحي @since 3.2.0 (موجود في خط التطوير الحالي المُلقَّب بـ3.1.0)

تكشف كل أداة أيضًا عن دوال التوصيف الذاتي في ToolInterface: name، وdescription، وinputSchema، وannotations، وriskLevel، وtier، وcategory. وتظهر قيمها لكل أداة في عمود «ملاحظات» أعلاه.

توقيعات نقاط الدخول، حرفيًّا من المصدر:

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

عقد السلوك

• تُنفِّذ كل أداة NextPDF\Server\Tools\ToolInterface وتُعلن ToolTier::Enterprise صراحةً. ولا تُستنتَج الفئة أبدًا من فضاء الأسماء أو التحزيم.
• لا ترمي execute استثناءً. يُلتقَط كل فشل ويُعاد بوصفه ToolResult خطأ يحمل رسالة الفشل.
• تحلّ أدوات المستند الواحد بايتات ⁨PDF⁩ وفق أولوية ثابتة. يُبحَث عن document_id أولًا في InMemoryDocumentStore. وإلا فيُفسَّر source بوصفه ⁨URI⁩ من نوع data:، ثم بوصفه ⁨base64⁩ خامًا (أكثر من 256 حرفًا)، ثم بوصفه مسار ملف.
• تُعطَّل مسارات source الخاصة بنظام الملفات افتراضيًا. ولا تُفعَّل إلا عندما يُسمّي متغيّر البيئة NEXTPDF_MCP_INPUT_DIR دليل إدخال محصورًا. ويجب أن يبقى المسار الحقيقي المحلول داخل ذلك الدليل. وكل ما عدا ذلك يفشل مغلقًا.
• تُرفَض مخطَّطات مغلِّف الدفق (phar://، php://، file://، وأي مخطَّط آخر) وبايتات ⁨null⁩ في source من نوع مسار ملف قبل أي استدعاء لنظام الملفات. ويفشل التنقّل عبر الأدلّة والهروب عبر الروابط الرمزية أمام فحص حصر المسار الحقيقي.
• تحصل الأدوات المدعومة بالـsidecar (embed_documents، search_documents، batch_compliance_check، batch_forensic_analyze) على عميلها من SpectrumClientFactory::create. ويتحقّق المصنع من SPECTRUM_URL غير المحلي مقابل نطاقات العناوين الخاصة والمحجوزة قبل الاستخدام. ويُسمح بـlocalhost الصريح لوضع الـsidecar المحلي.
• تشتقّ ai_ready_certify مستواها من أربعة معايير: السلامة الجنائية، ووجود التوقيع، وصلاحية ⁨LTV⁩، وغياب التعمية. نجاح الأربعة جميعًا يُنتج certified؛ ونجاح واحد إلى ثلاثة يُنتج partial؛ وصفر يُنتج not_certified. والسلامة الجنائية استدلال بنيوي على سلسلة المراجعات، لا تحقّق تعمويّ من سلامة البايتات. ويفحص فحص التعمية منطقة الـtrailer فقط.
• تقيّم certify_ai_ready ثلاثة معايير وتُلحق ختم مصدر ⁨XMP⁩. وتُعاد البايتات المختومة مُرمَّزة بـ⁨base64⁩ ما لم يكن return_stamped_pdf بقيمة false أو يكن المستوى not_certified.
• تقبل compliance_check اثني عشر مفتاح سياسة بالضبط: pdfa4، pdfa4e، pdfa4f، pades-baseline، ltv-health، eidas-qualified، zugferd، fda-part11، sec-17a4، sec-17a4-compatible، sec-17a4-structural، sec-17a4-pre-sign. ويُعيد أي مفتاح مجهول نتيجة خطأ تُسمّي المجموعة المدعومة.
• تقرأ audit_ast_mutations فقط AstAuditTrailInterface المحقون. ولا تسجّل هي نفسها شيئًا.

الحالات الحدّية وأنماط الفشل

• عدم توفير document_id ولا source: نتيجة خطأ توجّه المستدعي إلى تزويد أحدهما.
• document_id مجهول: نتيجة خطأ تُسمّي المعرّف وتشير إلى create_pdf.
• source خاص بنظام الملفات مع عدم ضبط NEXTPDF_MCP_INPUT_DIR: يُرفَض برسالة تُسمّي القنوات المدعومة.
• مسار source الذي يُحَلّ خارج دليل الإدخال المُهيّأ، بما في ذلك عبر رابط رمزي: يُرفَض. وتقع المقارنة على حدّ فاصل الأدلّة، فلا تستطيع الأدلّة الشقيقة التي تتشارك بادئة اسم أن تجتاز.
• ‏⁨URI⁩ من نوع data: دون فاصلة، أو حمولة ⁨base64⁩ غير صالحة: نتيجة خطأ.
• top_k الخاص بـsearch_documents خارج 1–100: يُقيَّد، لا يُرفَض. ويرتدّ top_k غير الصحيح إلى الافتراضي المُهيّأ في خطّ الأنابيب.
• mode الخاص بـsearch_documents خارج hybrid، bm25، semantic: نتيجة خطأ من قائمة سماح خطّ الأنابيب.
• عنصر documents[] في batch_compliance_check يفتقر إلى id أو path، أو يحمل سلاسل فارغة: نتيجة خطأ تُسمّي الفهرس المخالف. أما batch_forensic_analyze فيتحقّق من شكل المصفوفة الخارجية فقط؛ وتظهر عيوب العناصر من طبقة الدفعات.
• SpectrumClientFactory::create مع SPECTRUM_URL مشوَّه، أو مع واحد يستهدف عنوانًا خاصًا أو محليّ الرابط أو عنوان بيانات وصفية: InvalidArgumentException. وداخل execute أداةٍ ما يظهر هذا بوصفه نتيجة خطأ.
• SpectrumClientFactory::createStreamFromFile على مسار غير قابل للقراءة: McpStreamException.
• تُعامَل متغيّرات البيئة الفارغة على أنها غير مضبوطة وترتدّ إلى القيم الافتراضية.

المطابقة

لا تحمل ⁨NextPDF⁩ أي شهادة ولا تمنح أيًا منها. تُبلّغ أدوات ⁨MCP⁩ عن تقييمات على مستوى القدرة؛ فالدعم ليس مطابقةً، والمطابقة ليست شهادةً. وقيم certification_level التي تُعيدها ai_ready_certify وcertify_ai_ready هي مفردات الأدوات المُبلَّغة ذاتيًا. وهي لا تشكّل توثيقًا من طرف ثالث. وتتضمّن استجابات compliance_check حقل disclaimer يُنتجه التقرير الأساسي للسبب ذاته. أما مراجع بنود السياسات، مثل أساس سياسة ⁨LTV⁩ الذي يذكره مصدر المنتج بأنه ⁨ISO 32000-2:2020 §12.8.4.3⁩، فتُحمَل في أوصاف الأدوات وحقول clause لكل نتيجة؛ ولا تضيف هذه الصفحة أي ادّعاءات معايير مستقلّة. وأما ما إذا كان مستند مفحوص يستوفي لائحةً تنظيمية فهو قرار يعود إلى المشغّل ومقيّميه.

ملاحظات التطوير

• تخزّن SpectrumClientFactory::create عميلًا واحدًا لكل عملية. استدعِ SpectrumClientFactory::reset في إعداد الاختبار لفرض عميل جديد.
• تستشير قراءات البيئة $_ENV، ثم $_SERVER، ثم getenv، وتُعامل السلاسل الفارغة على أنها غائبة.
• يقود RiskLevel المعالجة على جانب المضيف في زمن تشغيل الخادم: Safe يُنفَّذ تلقائيًا، وCaution وما فوقها يُسجَّل في سجل التدقيق، وApprovalRequired يستلزم تأكيدًا بشريًا. ولا تُعلن أي أداة ⁨MCP⁩ من فئة ⁨Enterprise⁩ عن ApprovalRequired. وتستطيع تجاوزات المشغّل رفع مستوى مُعلَن، لا خفضه أبدًا.
• قيم annotations (readOnlyHint، idempotentHint) هي تلميحات لعميل ⁨MCP⁩، لا إنفاذ. ويحدث الحصر والتحقّق على جانب الخادم بغضّ النظر عن التلميحات.
• تُبلّغ الأدوات عن قيم category وهي document أو extraction لغرض تصفية tools/list.
• AuditAstMutationsTool هي الأداة الوحيدة التي تتطلّب الحقن عبر المُنشئ؛ سجّلها بتنفيذ محسوس لـAstAuditTrailInterface.

انظر أيضًا

• ‏⁨MCP⁩ (صفحة القدرة)
• ‏⁨Accelerator⁩ — مرجع متعمّق — سطح عميل ⁨Spectrum sidecar⁩.
• ‏⁨Forensics⁩ — مرجع متعمّق — المحلّل خلف forensic_analyze.
• ‏⁨Compliance⁩ — مرجع متعمّق — السياسات خلف compliance_check.
• ‏⁨AST⁩ — مرجع متعمّق — التقطيع وأثر تدقيق الطفرات.
• ‏⁨Validation⁩ — مرجع متعمّق

حدود النشر

توثّق هذه الصفحة السلوك القابل للملاحظة خارجيًا وسطح واجهة برمجة التطبيقات العامة المدعوم فقط. أما مسارات فضاء الأسماء الداخلية، والفئات المساعِدة، وجداول الآليات، وأسماء ملفات كتيّبات التشغيل، وبادئات التذاكر فخارج النطاق.