أدوات MCP

نظرة عامة سريعة

تضيف ⁨NextPDF Enterprise⁩ إحدى عشرة أداة ⁨MCP⁩ إلى خادم ⁨NextPDF Connect⁩. تمنح هذه الأدوات مساعدي الذكاء الاصطناعي وأُطر عمل الوكلاء وصولاً مباشراً ومُنمذَجاً إلى محرّك ⁨Enterprise⁩: فحوص سياسات الامتثال، والتحليل الجنائي لملفات ⁨PDF⁩، وفحوص سلامة ⁨LTV⁩، وختم الجاهزية للذكاء الاصطناعي، والتقطيع المدرك لـ ⁨AST⁩، وإدخال ⁨RAG⁩ والبحث فيه. تُعلن كل أداة عن مستوى المخاطر الخاص بها ووضع القراءة فقط، حتى يتمكّن مضيف ⁨MCP⁩ لديك من ضبط نشاط الوكلاء وتسجيله وتدقيقه بثقة. لا تظهر الإخفاقات أبداً على هيئة استثناءات؛ بل يتلقّى الوكلاء دائماً نتيجة منظَّمة قابلة للتحليل.

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

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

التثبيت

composer require nextpdf/enterprise:^3

مضيف ⁨MCP⁩ نفسه هو ⁨NextPDF Connect⁩، المشحون في حزمة nextpdf/server؛ راجِع تثبيت ⁨Connect⁩. عند وجود الحزمتين معاً، يكتشف سجلّ الأدوات في الخادم NextPDF\Enterprise\McpToolProvider تلقائياً ويسجّل أدوات ⁨Enterprise⁩ الإحدى عشرة. لا حاجة إلى أي شيفرة ربط. وإذا غابت nextpdf/server، يعود ملف المزوِّد مبكراً ولا يُحمَّل أي شيء.

تتطلّب أدوات المعالجة الدفعية و⁨RAG⁩ إضافةً إلى ذلك مُرافِق ⁨Spectrum⁩. اضبطه عبر متغيّرات البيئة التي يقرؤها NextPDF\Enterprise\Mcp\SpectrumClientFactory: SPECTRUM_URL (الافتراضي http://127.0.0.1:7800)، وSPECTRUM_TIMEOUT (الافتراضي 30.0 ثانية)، وSPECTRUM_AUTH_TOKEN، وSPECTRUM_APP_SECRET.

نظرة عامة مفاهيمية

⁨Model Context Protocol⁩ (⁨MCP⁩) بروتوكول مفتوح يتيح لمساعدي الذكاء الاصطناعي وأُطر عمل الوكلاء استدعاء أدوات مُنمذَجة يعرضها خادم. فبدلاً من لصق بايتات ⁨PDF⁩ في مُحفِّز والتعويل على الحظ، يستدعي الوكيل أداةً مُسمّاة بحمولة مُتحقَّق منها بمخطط ⁨JSON⁩ ويتلقّى نتيجة حتمية منظَّمة. ⁨NextPDF Connect⁩ هو ذلك الخادم لملفات ⁨PDF⁩؛ وتوسّع حزمة ⁨Enterprise⁩ فهرسه بالأدوات أدناه. كل أداة غلاف رفيع فوق واجهات ⁨Enterprise⁩ البرمجية ذاتها التي تستدعيها شيفرة ⁨PHP⁩ لديك مباشرةً، بحيث يُنتج فحصٌ يجريه وكيل وفحصٌ تجريه الشيفرة الحُكمَ نفسه.

فهرس الأدوات

أداة MCP	الصنف	ما تفعله	المخاطر	القراءة فقط
compliance_check	ComplianceCheckTool	يتحقّق من ملف PDF واحد مقابل سياسة مُسمّاة: pdfa4، pdfa4e، pdfa4f، pades-baseline، ltv-health، eidas-qualified، zugferd، fda-part11، وأربع صيَغ من sec-17a4.	Review	نعم
batch_compliance_check	BatchComplianceCheckTool	يفحص ملفات PDF متعددة مقابل سياسات pdfa أو pades أو zugferd في دفعة واحدة عبر مُرافِق Spectrum.	Safe	نعم
forensic_analyze	ForensicAnalyzeTool	يُبلّغ عن سجلّ المراجعات والتحديثات التزايدية وأحداث التعديل لكشف العبث.	Safe	نعم
batch_forensic_analyze	BatchForensicAnalyzeTool	يُجري تحليلاً جنائياً على ملفات PDF متعددة في دفعة واحدة عبر المُرافِق.	Safe	نعم
ltv_health_check	LtvHealthCheckTool	يفحص ملف PDF موقَّعاً بحثاً عن مواد التحقق طويل الأمد: قاموس DSS واستجابات OCSP ومدخلات CRL ومدخلات VRI ومخازن الشهادات.	Safe	نعم
ai_ready_certify	AiReadyCertifyTool	حُكم جاهزية للذكاء الاصطناعي مُعرَّف من المنتج وبالقراءة فقط وفق أربعة معايير: السلامة الجنائية، ووجود توقيع، وصلاحية LTV، وعدم وجود تشفير.	Review	نعم
certify_ai_ready	CertifyAiReadyTool	حُكم جاهزية مُعرَّف من المنتج وفق ثلاثة معايير (أربعة معايير الأداة بالقراءة فقط ناقص السلامة الجنائية - بحكم التصميم، لأن هذه الأداة تعيد كتابة الملف الذي تختمه) ويُلحِق ختم مصدرية XMP؛ ويُعيد ملف PDF المختوم بترميز base64.	Review	لا
ast_aware_chunk	AstAwareChunkTool	يقسّم ملف PDF إلى مقاطع مُثبَّتة للاستشهاد على حدود العناوين، مع مُعرِّف عقدة وفهرس صفحة ومربع إحاطة لكل مقطع.	Review	نعم
audit_ast_mutations	AuditAstMutationsTool	يسترجع أثر تدقيق طفرات AST لمستند عبر تجزئة المصدر SHA-256.	Review	نعم
embed_documents	EmbedDocumentsTool	يُدخِل ملفات PDF إلى مجموعة RAG: تحليل، وتقطيع، وتضمين، وفهرسة. يعدّل حالة المجموعة.	Caution	لا
search_documents	SearchDocumentsTool	استرجاع هجين (كلمات مفتاحية BM25 بالإضافة إلى الدلالي) على مجموعة مُدخَلة، مع مقاطع مُرتَّبة ومُسجَّلة النقاط.	Safe	نعم

تُصدِر أدوات «⁨certify⁩» حُكم جاهزية مُعرَّفاً من المنتج (certified أو partial أو not_certified). هذا الحُكم نتيجة فحص تقني، وليس اعتماداً من أي هيئة اعتماد.

ضبط الموافقة ووضع التدقيق

تُعلن كل أداة عن مستوى مخاطر ضمن نموذج ⁨Connect⁩ رباعي الفئات. أدوات Safe تُنفَّذ تلقائياً. أدوات Caution تُنفَّذ تلقائياً مع مدخلة في سجلّ التدقيق. أدوات Review تحمل تحذيراً ضمن تعليمات الوكيل المُستدعي. أدوات ApprovalRequired تتطلّب تأكيداً بشرياً؛ ولا تُعلن حالياً أي أداة ⁨MCP⁩ في ⁨Enterprise⁩ عن هذا المستوى، لأن أياً منها ليست مُدمِّرة. لا يمكن لتهيئة التشغيل إلا رفع مستوى مخاطر الأداة، لا خفضه أبداً. تنشر الأدوات أيضاً تعليقات سلوك ⁨MCP⁩ التوضيحية (readOnlyHint، idempotentHint)، بحيث يمكن لعميل مُطابِق تطبيق ضبطه الخاص فوقها. راجِع فئات مخاطر HITL للنموذج الكامل.

لماذا يعمل بهذه الطريقة

القرار الحامل هو أن الأدوات أغلفة رفيعة حتمية ذات حوكمة ذاتية الإعلان: تُصرّح كل أداة بمستوى مخاطرها وفئتها بوصفها ثابتاً في المجال، ولا يُستنتَج ذلك أبداً من مساحة الأسماء أو التغليف. يُبقي هذا قرار الضبط قابلاً للتدقيق عند المضيف دون الوثوق بطبقة النقل. لا تحوي الأدوات أي ذكاء مستندي خاص بها؛ بل تُفوِّض إلى واجهات ⁨Enterprise⁩ البرمجية ذاتها التي تستدعيها شيفرتك، فيوجد سلوك واحد بالضبط لاختباره وحُكم واحد للوثوق به. تعود الأخطاء على قناة أخطاء ⁨MCP⁩ بدلاً من الإفلات على هيئة استثناءات، لأن الوكيل لا يستطيع التقاط استثناء ⁨PHP⁩ لكنه يستطيع دائماً التفرّع بناءً على isError. أي مُدخَل قد يلامس نظام الملفات مُغلَق-عند-الفشل افتراضياً، لأن وسائط ⁨MCP⁩ قابلة لوصول المهاجم بحكم التعريف.

خلفية التصميم: واجهة برمجية ترفض التخمين.

سطح الـ ⁨API⁩

تُنفّذ الأدوات الإحدى عشرة جميعها عقد NextPDF\Server\Tools\ToolInterface من nextpdf/server وتتشارك السطح العام نفسه. التواقيع أدناه معروضة مرة واحدة على NextPDF\Enterprise\Mcp\ComplianceCheckTool بوصفها المُمثِّل:

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

يرمي أو يفشل بـ: execute() لا يرمي أبداً. يلتقط Throwable داخلياً ويُعيد ToolResult::error() مع isError = true. تظهر الوسائط غير الصالحة (غياب workspace_token، أو مدخلات documents مُشوَّهة، أو document_id مجهول، أو source غير آمن) على هيئة رسائل InvalidArgumentException على قناة الأخطاء تلك.

تأخذ أداة أثر التدقيق خلفية تخزينها عبر حقن المُنشئ:

public function __construct(private readonly AstAuditTrailInterface $auditTrail)

المزوِّد الذي يسجّل الفهرس:

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

يُعيد getTier() القيمة 'enterprise'. ويُعيد getTools() نُسخ الأدوات الإحدى عشرة؛ وتُوصَّل audit_ast_mutations بـ NextPDF\Enterprise\Ast\InMemoryAstAuditTrail افتراضياً.

مصنع عميل مُرافِق ⁨Spectrum⁩، وهو أيضاً مصنع طلبات وتدفّقات ⁨PSR-17⁩:

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

يرمي أو يفشل بـ: يرمي create() استثناء InvalidArgumentException عندما يكون SPECTRUM_URL مُشوَّهاً أو عندما تستهدف نقطة النهاية المُهيَّأة عنواناً خاصاً أو محجوزاً معروفاً (باستثناء localhost). هذه بوابة زمن-التهيئة، وليست ضابطاً على مستوى الشبكة: لا يزال يلزمك فرض سياسة الخروج، ومعالجة إعادة التوجيه، وتثبيت ⁨DNS⁩ في بيئة المضيف. ويرمي createStreamFromFile() استثناء NextPDF\Enterprise\Mcp\McpStreamException (صنف فرعي من RuntimeException، وفق عقد ⁨PSR-17⁩) عندما يتعذّر فتح الملف.

عيّنة شيفرة — بداية سريعة

شغّل فحص امتثال ⁨PDF/A-4⁩ تماماً كما يفعل الوكيل، باستخدام قناة معرّف data: في الذاكرة:

quick-compliance-check.php

<?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;

الخرج المتوقَّع لملف مُطابِق (تختلف أعداد النتائج حسب المستند):

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

التقرير الكامل القابل للقراءة آلياً، بما في ذلك شدّة كل نتيجة ومُعرِّف القاعدة والبند والاقتراح، متاح على $result->structured.

عيّنة شيفرة — إنتاج

افحص المُرافِق مُسبقاً، وافرض وضع المخاطر المُعلَن، ثم شغّل فحص امتثال دفعياً:

gated-batch-compliance.php

<?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;

الخرج المتوقَّع (تعكس الأعداد مستنداتك):

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

الحالات الحدّية والمزالق

• مسارات source لنظام الملفات مُعطَّلة افتراضياً. بدون متغيّر البيئة NEXTPDF_MCP_INPUT_DIR، يُرفَض أي source على هيئة مسار بنتيجة خطأ. استخدم document_id أو معرّف data: أو base64 خاماً بدلاً من ذلك.
• لا يُتعرَّف على base64 الخام إلا فوق 256 محرفاً. تُعامَل كتلة base64 أقصر بوصفها مسار ملف وتُرفَض. لُفّ الحمولات الصغيرة في معرّف data:application/pdf;base64,.
• قيم document_id المجهولة تفشل مع إرشاد. نص الخطأ هو Unknown document_id: ... Call create_pdf first. كما تنتهي صلاحية المستندات في المخزن داخل الذاكرة وفق ⁨TTL⁩ الخاص بالمخزن، فيفشل المُعرِّف القديم بالطريقة نفسها.
• compliance_check يرفض مفاتيح السياسات المجهولة ويسرد المجموعة المدعومة في رسالة الخطأ.
• أدوات المعالجة الدفعية و⁨RAG⁩ تحتاج المُرافِق. تتطلّب batch_compliance_check وbatch_forensic_analyze وembed_documents وsearch_documents نقطة نهاية Spectrum قابلة للوصول وworkspace_token. يُخبّئ المصنع عميلاً واحداً لكل عملية؛ استدعِ SpectrumClientFactory::reset() في الاختبارات.
• search_documents يقصر top_k على 1–100؛ وترتد القيم غير الصحيحة إلى القيمة الافتراضية للخادم وهي 10.
• القيم الافتراضية لـ ast_aware_chunk هي 1500 محرف لكل مقطع مع تداخل 150 محرفاً.
• certify_ai_ready يحذف البايتات المختومة عندما تكون return_stamped_pdf بقيمة false أو يكون الحُكم not_certified. وعند وجودها، تكون حمولة base64 أكبر بنحو الثُلث من ملف ⁨PDF⁩ نفسه.
• أثر تدقيق AST الافتراضي في الذاكرة. المدخلات المُسجَّلة عبر توصيل المزوِّد القياسي لا تدوم عبر العمليات؛ احقِن تنفيذاً دائماً لـ AstAuditTrailInterface للحصول على آثار تدقيق مُعمَّرة.

ملاحظات أمنية

• حلّ المصدر مُغلَق-عند-الفشل. يتحكّم مستدعو ⁨MCP⁩ تحكّماً كاملاً في وسائط الأداة، لذا يعاملها المُحلِّل بوصفها عدائية. تُرفَض أغلفة التدفّق (phar://، php://، file://، وأي مخطط) والبايتات الصفرية قبل أي استدعاء لنظام الملفات. ويُرفَض اجتياز المسارات. ولا تعمل مسارات الملفات الخام إلا عند ضبط NEXTPDF_MCP_INPUT_DIR، ويجب أن يُحلّ الهدف المُقنَّن بـ realpath داخل ذلك الدليل حصراً، مع المقارنة على حدّ فاصل لمنع هروب الخلط بالبادئة.
• حارس SSRF على نقطة نهاية المُرافِق. يسمح SpectrumClientFactory بـ localhost لوضع المُرافِق المحلي ويتحقّق من كل SPECTRUM_URL آخر مقابل النطاقات الخاصة والمحجوزة والمحلية-للوصلة ونطاقات بيانات السحابة الوصفية، رامياً InvalidArgumentException على عنوان محظور. هذه بوابة زمن-التهيئة على نقطة النهاية المُهيَّأة، وليست ضابطاً على مستوى الشبكة - أبقِ سياسة الخروج ومعالجة إعادة التوجيه وتثبيت ⁨DNS⁩ في بيئة المضيف.
• الأسرار تبقى في البيئة. يُقرَأ الرمز الحامل للمُرافِق (SPECTRUM_AUTH_TOKEN) وسرّ توقيع HMAC (SPECTRUM_APP_SECRET) من متغيّرات البيئة ولا يظهران أبداً في حمولات الأدوات أو نتائجها.
• أخطاء غير عاكسة. رسائل رفض المسار عامة بحكم التصميم (Source path is not permitted.)، فلا يتعلّم المستدعي المُتحسِّس شيئاً عن نظام ملفات المضيف.
• تجاوزات المخاطر تتجه صعوداً فقط. يمكن لتهيئة المُشغِّل رفع مستوى مخاطر الأداة المُعلَن لكنها لا تستطيع أبداً خفضه دون إعلان الأداة نفسها.

المطابقة

الدعم ليس مطابقة، والمطابقة ليست اعتماداً. لا تملك ⁨NextPDF⁩ أي اعتماد ولا تمنح أياً منه. تفحص أدوات الامتثال بنية المستند مقابل ملامح السياسات المُسمّاة وتُبلّغ عن النتائج مع مراجع البنود؛ ويحمل تقرير compliance_check إضافةً إلى ذلك إخلاء المحرّك الخاص بأنه فحص بنية تقني للاستئناس، لا مشورة قانونية ولا مصادقة امتثال. وحُكما ai_ready_certify وcertify_ai_ready مستويا جاهزية مُعرَّفان من المنتج، لا شهادة من أي هيئة معايير. و⁨MCP⁩ بروتوكول مفتوح ينشره الوصيّ البائع له، وليس معياراً من منظمة تطوير معايير؛ توثّق هذه الصفحة سلوك تنفيذ ⁨NextPDF⁩ ولا تُقدِّم أي ادعاء مستقل بمطابقة البروتوكول أو الاعتماد.

عقد السلوك

• تُعاد إخفاقات الأدوات على هيئة نتائج خطأ (isError = true مع رسالة)؛ ولا تعبر الاستثناءات أبداً حدّ ⁨MCP⁩.
• تحمل النتائج الناجحة ملخصاً من سطر واحد قابلاً للقراءة البشرية بالإضافة إلى حمولة ⁨JSON⁩ منظَّمة بمجموعة حقول ثابتة وموثَّقة لكل أداة.
• تُبلّغ كل أداة عن tier() = ToolTier::Enterprise وRiskLevel مُعلَن؛ ولا يمكن خفض المخاطر في زمن التشغيل.
• تُعلن أدوات القراءة فقط عن readOnlyHint: true ولا تعدّل مخزن المستندات ولا ملف ⁨PDF⁩ المصدر ولا أي مجموعة.
• certify_ai_ready لا يغيّر أبداً مستند الإدخال في مكانه؛ بل يُطبَّق الختم على نسخة مُعادة.
• تتضمّن تقارير الامتثال و⁨LTV⁩ طابعاً زمنياً للتحقق وأعداد النتائج حسب الشدّة؛ وتتضمّن حمولة compliance_check إضافةً إلى ذلك سلسلة إخلاء المسؤولية القانوني للمحرّك.

الرجوع إلى ⁨Core⁩

مضيف ⁨MCP⁩ نفسه لا يتطلّب ⁨Enterprise⁩. يعمل ⁨NextPDF Connect⁩ (nextpdf/server، ⁨Apache-2.0⁩) مع محرّك ⁨Core⁩ المفتوح ويقدّم فهرس أدواته من فئة ⁨Core⁩: إنشاء المستندات، وعمليات النص والمحتوى، والاستخراج. راجِع فهرس الأدوات. لا يوفّر ⁨Core⁩ وحده فحوص سياسات الامتثال ولا التحليل الجنائي ولا فحوص سلامة ⁨LTV⁩ ولا ختم الجاهزية للذكاء الاصطناعي ولا التقطيع المدرك لـ ⁨AST⁩ ولا آثار تدقيق الطفرات ولا أدوات المعالجة الدفعية و⁨RAG⁩؛ إذ لا تُسجَّل تلك الأدوات الإحدى عشرة إلا مع تثبيت nextpdf/enterprise وترخيصه.

حدود النشر

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

اطّلع أيضاً

• MCP — المرجع العميق
• نظرة عامة على ⁨NextPDF Connect⁩
• فئات مخاطر HITL
• التحقق من الامتثال
• التحليل الجنائي
• المُسرِّع — مُرافِق GPU
• واجهة برمجية ترفض التخمين