كتالوج أدوات NextPDF Connect

لمحة سريعة

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

التثبيت

composer require nextpdf/server

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

يبني NextPDF\Server\ToolRegistry الكتالوج أثناء الإقلاع، بالترتيب الآتي:

الطبقة الأساسية. تُسجَّل مجموعة ثابتة من الأدوات الأساسية بلا شروط. ولا تُسجَّل أداتان إضافيتان إلا عند استيفاء شرط مُسبَق.
طبقة ⁨Pro.⁩ تُسجَّل أدوات ⁨Pro⁩ عندما يمكن حلّ صنف موفِّر ⁨Pro⁩، وهو ما يحدث عند تثبيت nextpdf/premium. يتخطى الخادم هذه الخطوة بصمت عندما لا يمكن حلّ الصنف.
طبقة ⁨Enterprise.⁩ يتبع موفِّر ⁨Enterprise⁩ النمط نفسه الذي يتبعه موفِّر ⁨Pro.⁩
الطبقات الممتدة المُرفقة. يُشحَن موفِّرا أداتَي ⁨AST⁩ والتحوير مع حزمة الخادم، ويُسجَّلان ضمن طبقة ⁨Pro.⁩ تتحكم بوابة بيئة في كل موفِّر، ويتراجع كل موفِّر بسلاسة عند غياب دعمه الأساسي.
مرشِّح سياسة الأمان. يتحقق الخادم من كل عملية تسجيل مقابل قائمة السماح enabled_tools. تُسقِط قائمة السماح غير الفارغة أي أداة غير مدرجة فيها. ولا يشمل عدّاد الطبقة إلا الأدوات التي تسمح بها السياسة.

تُبلِغ استجابة initialize الخاصة بـ ⁨Model Context Protocol⁩ (⁨MCP⁩) عن قيمة tool_count الناتجة وعن الأعداد لكل طبقة في الخادم قيد التشغيل. هذه القيمة هي المرجع المعتمد. عامِل أي إجمالي ثابت في النص على أنه متقادم.

سطح الـ ⁨API⁩

الأدوات الأساسية المُتحقَّق منها والمتاحة دائمًا

تُسجَّل هذه الأدوات الاثنتا عشرة دائمًا في الطبقة الأساسية. يقرأ الخادم طبقة المخاطرة وتلميحات سلوك ⁨MCP⁩ لكل أداة من تنفيذها.

اسم الأداة	الفئة	الوصف	المخاطرة
`create_pdf`	مستند	إنشاء مستند ⁨PDF⁩ وإرجاع `document_id`	تنبيه
`add_text`	مستند	إضافة محتوى نصي إلى مستند ⁨PDF⁩	تنبيه
`add_image`	مستند	إضافة صورة من مسار ملف أو بيانات ⁨base64⁩	تنبيه
`add_table`	مستند	إضافة جدول ⁨HTML⁩ إلى مستند ⁨PDF⁩	تنبيه
`set_font`	مستند	تعيين الخط لعمليات النص اللاحقة	تنبيه
`add_page`	مستند	إضافة صفحة جديدة إلى مستند ⁨PDF⁩	تنبيه
`output_pdf`	مستند	إخراج ⁨PDF⁩ النهائي كملف أو ⁨base64⁩	⁨approval_required⁩
`preview_layout`	مستند	إرجاع ملخص تخطيط بصيغة ⁨JSON⁩ من دون تصيير	⁨safe⁩
`diagnostic.doctor`	تشخيص	إجراء فحص سلامة؛ تشخيصات بيئة مُهيكَلة	⁨safe⁩
`diagnostic.capabilities`	تشخيص	سرد القدرات مع الطبقة والحالة	⁨safe⁩
`diagnostic.inspect`	تشخيص	فحص ملف ⁨PDF⁩ وإرجاع بيانات وصفية بنيوية	⁨safe⁩
`diagnostic.verify`	تشخيص	التحقق من سلامة ⁨PDF⁩، مع فحوص ⁨PDF/A⁩ أو ⁨PDF/UA⁩ اختيارية	تنبيه

الأدوات الأساسية المُسجَّلة شرطيًا

اسم الأداة	الشرط
`generate_barcode`	يُسجَّل عندما يتضمن `nextpdf/core` المُثبَّت سجلَّ مُرمِّزات الباركود الأساسي
`parse_pdf`	يُسجَّل فقط عندما تكون `NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED` هي `true` أو `1`

output_pdf هي الأداة الأساسية الوحيدة عند مستوى المخاطرة approval_required. تمرّ كتابة ملف عبر بوابة التدخل البشري في الحلقة؛ أما إخراج ⁨base64⁩ فلا يمر. راجِع /⁨connect/hitl-risk-tiers/.⁩

أدوات تُضاف فقط عند تثبيت حزم إضافية

يفحص الخادم أصناف الموفِّرين باستخدام class_exists():

أدوات ⁨Pro⁩ تُسجَّل عند تثبيت nextpdf/premium وعندما يمكن حلّ صنف موفِّر ⁨Pro.⁩
أدوات ⁨Enterprise⁩ تُسجَّل عند تثبيت nextpdf/premium وعندما يمكن حلّ صنف موفِّر ⁨Enterprise.⁩ تغلِّف أدوات الخصوصية (التنقيح وإزالة التعريف وتنقيح المناطق) أصناف ⁨Enterprise.⁩ ولا تُسجَّل ضمن طبقة ⁨Enterprise⁩ إلا عندما تكون تلك الأصناف قابلة للتحميل التلقائي.
أدوات ⁨AST⁩ والتحوير تُشحَن مع الخادم، وتُسجَّل ضمن طبقة ⁨Pro.⁩ تتحكم بهما بوابتا NEXTPDF_AST_TOOLS_ENABLED وNEXTPDF_MUTATION_TOOLS_ENABLED، وكلتا البوابتين مُفعَّلتان افتراضيًا.

حزمة ⁨Premium⁩، لا الخادم، هي التي تحدد قوائم أدوات ⁨Pro⁩ و⁨Enterprise⁩ الدقيقة وتوثّقها مع تلك الحزمة. العقد الذي يقدّمه الخادم هو آلية التسجيل، وليس قائمة ⁨Premium⁩ ثابتة.

عينة شيفرة — بدء سريع

اطبع الأدوات التي يكشفها هذا التثبيت من دون تشغيل خادم:

./vendor/bin/generate-skills --dry-run --list-tools

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

استعلِم الخادم قيد التشغيل عن العدد المرجعي المعتمد عبر ⁨MCP⁩:

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"c","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
EOF

يحسب الخادم capabilities.nextpdf.tool_count وtiers ضمن نتيجة initialize للعملية قيد التشغيل. وعبر ⁨REST⁩، يُرجِع GET /api/v1/capabilities بيانات استبطان مكافئة.

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

لا يوجد رقم ثابت هو “33 أداة” — ولا يوجد أي إجمالي ثابت. تورد المواد الأقدم رقمًا واحدًا، لكن ذلك الرقم ليس عقدًا. يتغير العدد بحسب الحزم المُثبَّتة وقائمة السماح enabled_tools وبوابات بيئة parse_pdf و⁨AST⁩ والتحوير. اقرأ العدد دائمًا من الخادم قيد التشغيل.
قائمة السماح تستبعد، ولا تضيف أبدًا. إدراج أداة ⁨Pro⁩ في enabled_tools لا يُسجِّلها عند غياب nextpdf/premium.
غياب طبقة أمر صامت ومتوقَّع. يقدّم التثبيت مفتوح المصدر فقط المجموعة الأساسية، ويبلّغ عن صفر أداة ⁨Pro⁩ وصفر أداة ⁨Enterprise.⁩ تلك النتيجة تشغيل صحيح، وليست عطلًا.
الطبقة المُعلَنة في الكتالوج ثابتة. تُعلِن كل أداة طبقتها ومخاطرتها بنفسها في الشيفرة. لا يستنتج السجلّ أي طبقة على الإطلاق من فضاء الأسماء أو الحزمة.

الأداء

يحدث مسح السجلّ واكتشاف الطبقة مرة واحدة عند الإقلاع، وتحدّهما performance_budget الخاصة بالصفحة. أما تكلفة كل أداة فتأتي من عملية المحرك الأساسية، لا من بحث الكتالوج؛ إذ يكون البحث ⁨O⁩(1) باسم الأداة.

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

استخدم enabled_tools ضابطًا لأقل الامتيازات: اكشف فقط الأدوات التي يحتاجها التكامل. لا يدرج الكتالوج أي أداة رفضتها سياسة الأمان، ولا يعكس عدّاد الطبقة إلا الأدوات المسموح بها. تبقى الأدوات عالية المخاطرة خاضعة لتأكيد بشري بصرف النظر عن عضويتها في الكتالوج. راجِع /⁨connect/security-and-operations/.⁩

المطابقة

تصف هذه الصفحة آلية السجلّ. تُثبَّت استشهادات البروتوكول الخاصة بسطحَي tools/list وinitialize على /⁨transports/mcp/.⁩ ويُحدَّد نموذج المخاطرة على /⁨connect/hitl-risk-tiers/.⁩

السياق التجاري

يغطي الكتالوج الأساسي الإنشاء والفحص والتشخيصات. لا تظهر أدوات التوقيع والتنقيح والامتثال والتحليل الجنائي إلا عند تثبيت nextpdf/premium إلى جانب الخادم. يُطبَّق هذا الحدّ الفاصل للحزمة في وقت composer require، لا عبر مُطالبة في وقت التشغيل أبدًا.

انظر أيضًا

/⁨connect/hitl-risk-tiers/⁩ — معنى عمود المخاطرة وكيف يعمل الإنفاذ
/⁨connect/boot-and-discovery/⁩ — تسلسل الإقلاع والاكتشاف الكامل
/⁨connect/configuration/⁩ — enabled_tools وبوابات البيئة
/⁨transports/mcp/⁩ — صيغتا النقل عبر السلك tools/list وinitialize
/⁨connect/overview/⁩ — لماذا يعتمد الكتالوج على وقت التشغيل بحكم التصميم