نظرة عامة على خادم NextPDF Connect

لمحة سريعة

⁨NextPDF Connect⁩ هو حزمة nextpdf/server: خدمة طويلة العمر تعرض محرك ⁨NextPDF⁩ الخاص بـ ⁨PDF 2.0⁩ لوكلاء الذكاء الاصطناعي وعملاء ⁨HTTP.⁩ يدعم ثلاث وسائل نقل: ⁨Model Context Protocol⁩ ‏(⁨MCP⁩) عبر ⁨stdio⁩، وواجهة ⁨REST API⁩، و⁨gRPC.⁩ وتشترك وسائل النقل الثلاث في سجل أدوات واحد وبوابة تأكيد واحدة تتضمن تدخّلًا بشريًا ‏(⁨HITL⁩).

التثبيت

composer require nextpdf/server

قيد ⁨Composer⁩ هو nextpdf/core: ^3.0 مع php: >=8.4 <9.0. للاطّلاع على الإجراء الكامل، راجع /⁨connect/install/.⁩ وتتناول تلك الصفحة أيضًا إضافتين اختياريتين: امتداد ext-redis وحزمة nextpdf/premium.

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

يكيّف nextpdf/server نواة ⁨NextPDF⁩ المستقلة عن أُطر العمل لتصبح سطح خدمة. ولا يعيد تنفيذ توليد ⁨PDF.⁩ بل يغلّف كل قدرة من قدرات المحرك بوصفها أداة مُسمّاة لها مخطّطها الخاص، ثم يقدّم ذلك الكتالوج عبر عدة بروتوكولات اتصال.

يرتكز التصميم بأكمله على ثلاثة مفاهيم:

• سجل الأدوات. يعثر NextPDF\Server\ToolRegistry على الأدوات ويسجّلها عند الإقلاع. تُشحن مجموعة أساسية مع الحزمة، وهذه المجموعة متاحة دائمًا. يسجّل مزوّدا ⁨Pro⁩ و⁨Enterprise⁩ مزيدًا من الأدوات، ولكن فقط عند تثبيت الحزم المطابقة. عدد الأدوات المكشوفة خاصية وقت تشغيل تخصّ النشر، وليس قيمة ثابتة. راجع /⁨connect/tool-catalog/.⁩

• وسائل النقل. يُقدَّم السجل نفسه بثلاث طرائق. يعمل ⁨MCP⁩ عبر ⁨stdio⁩ لعملاء الذكاء الاصطناعي المحليين. ويعمل ⁨REST⁩ عبر مسار وسائط ⁨PSR-15⁩ على تجمّع عمّال ⁨RoadRunner⁩ للعملاء المتصلين بالشبكة. ويعمل ⁨gRPC⁩ على عامل ⁨gRPC⁩ من ⁨Spiral RoadRunner⁩ للعملاء محددي الأنواع والمتدفقين. كل وسيلة نقل عملية مستقلة لها نقطة دخولها الخاصة. راجع /⁨transports/mcp/⁩ و/⁨transports/rest/⁩ و/⁨transports/grpc/.⁩

• بوابة التأكيد. تعلن كل أداة عن مستوى مخاطرتها. تتطلّب الأدوات الواقعة عند أعلى مستوى تأكيدًا بشريًا صريحًا قبل تشغيلها. تُصدر البوابة رمز تحدٍّ مميّزًا للاستخدام مرة واحدة. يجب أن يمرّر الوكيل ذلك الرمز إلى إنسان، ثم يستدعي الأداة مرة أخرى مع الرمز. راجع /⁨connect/hitl-risk-tiers/.⁩

يوضح الرسم التخطيطي أدناه كيف يصل سجل واحد إلى ثلاث وسائل نقل، ويوضح كذلك موضع بوابة التأكيد على مسار الطلب.

NextPDF Connect component architecture

الحزمة مرخّصة بموجب Apache-2.0، بما يطابق nextpdf/core. إصدار بروتوكول ⁨MCP⁩ المُنفَّذ هو المراجعة المؤرَّخة 2025-06-18. يصف مستند ⁨OpenAPI 3.1⁩ سطح ⁨REST.⁩ وتصف حزمة ⁨Protocol Buffers⁩ المسمّاة nextpdf.connect.v1 سطح ⁨gRPC.⁩

سطح ⁨API⁩

نقاط الدخول العامة هي فئات الخادم الثلاث، ولكل واحدة منها غلاف واجهة سطر أوامر ‏(⁨CLI⁩):

نقطة الدخول	الفئة	وسيلة النقل
bin/nextpdf-mcp	NextPDF\Server\Mcp\McpServer	⁨MCP⁩ عبر ⁨stdio⁩
bin/nextpdf-server	NextPDF\Server\Http\HttpServer	⁨REST⁩ عبر ⁨RoadRunner HTTP⁩
bin/nextpdf-grpc	NextPDF\Server\Grpc\GrpcServer	⁨gRPC⁩ عبر ⁨RoadRunner gRPC⁩
bin/generate-skills	NextPDF\Server\Skills\SkillsDumper	تصدير كتالوج الأدوات

تُنشئ كل من McpServer::create() وHttpServer::create() وGrpcServer::create() خادمًا مُهيّأً بالكامل من مدخلات البيئة والتهيئة. وتشترك الخوادم الثلاثة جميعها في مفاهيم السجل ومخزن المستندات وسياسة الأمان وبوابة التأكيد.

عيّنة برمجية — بدء سريع

لا يتطلّب الحد الأدنى من خادم ⁨MCP⁩ إلا أمرًا واحدًا. لا تكتب أي شيفرة ربط بلغة ⁨PHP⁩:

./vendor/bin/nextpdf-mcp

يقرأ الخادم طلبات ⁨JSON-RPC⁩ من المدخل القياسي ويكتب الاستجابات إلى المخرج القياسي. للاطّلاع على تبادل قابل للتشغيل لـ initialize وtools/list وطلب ⁨REST⁩ المطابق، راجع /⁨connect/quickstart/.⁩

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

• عدد الأدوات ليس 33، ولا أي رقم ثابت آخر. يحصي الخادم الأدوات في وقت التشغيل عبر count(ToolRegistry::all())، بعد تطبيق تصفية السياسة واكتشاف المستوى. التوثيق الذي يذكر إجماليًّا ثابتًا أصبح قديمًا ولم يعد صالحًا. للحصول على العدد المرجعي، استعلم من الخادم العامل. استخدم استجابة initialize الخاصة بـ ⁨MCP⁩، أو نقطة نهاية /api/v1/capabilities الخاصة بـ ⁨REST.⁩

  لا تثبّت عدد الأدوات في الشيفرة

  يعتمد عدد الأدوات المكشوفة على الحزم المثبّتة وعلى السياسة الفعّالة. اقرأه من الخادم العامل في وقت التشغيل. أي رقم ثابت في شيفرتك أو توثيقك سيصبح قديمًا وغير صالح.

• غياب حزمة ⁨Pro⁩ أو ⁨Enterprise⁩ ليس خطأ. يتحقّق السجل من فئات المزوّد عبر class_exists()، ثم يتخطّى بصمت أي مستوى غائب. يُقلع النشر المفتوح المصدر فقط ويقدّم كتالوجه الأساسي بصورة طبيعية.

• وسائل النقل الثلاث لا تتشارك عملية واحدة. تشغيل خادم ⁨MCP⁩ لا يبدأ خادم ⁨REST⁩ ولا خادم ⁨gRPC.⁩ والعكس صحيح أيضًا. يشغّل النشر المُدمج مشرف ⁨RoadRunner⁩ بتهيئة تبدأ كلا تجمّعَي العمّال: تجمّع ⁨HTTP⁩ وتجمّع ⁨gRPC.⁩ راجع /⁨connect/deployment/.⁩

الأداء

تعتمد كل وسيلة نقل على العمّال. يعالج العامل طلبًا واحدًا في كل مرة. يعمل خادما ⁨REST⁩ و⁨gRPC⁩ على تجمّعات عمّال ⁨RoadRunner⁩، وتحدّد التهيئة حجم التجمّع. القيمة الافتراضية هي أربعة عمّال ⁨HTTP.⁩ يحدّ مشرف ⁨RoadRunner⁩ من ذاكرة كل عامل. يصف عنصر performance_budget الموجود في الترويسة الأمامية لهذه الصفحة حدًّا للإقلاع البارد والاكتشاف. وهو ليس هدفًا لكل طلب. تمثّل عملية المحرك الأساسية معظم تكلفة الطلب.

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

تُجرى المصادقة في جميع وسائل النقل المتصلة بالشبكة باستخدام رمز حامل لمفتاح واجهة برمجة التطبيقات ‏(⁨API⁩). وسيلة نقل ⁨MCP⁩ عبر ⁨stdio⁩ عملية فرعية محلية يثق بها العميل المُطلِق، وفقًا لنموذج نقل ⁨MCP.⁩ تبقى الأدوات عالية المخاطرة مقيّدة خلف تأكيد بشري في كل وسيلة نقل. للاطّلاع على نموذج التهديد الكامل، ونموذج المصادقة، وتهيئة أمان النقل، راجع /⁨connect/security-and-operations/.⁩

تعتمد وسيلة نقل ⁨MCP⁩ عبر ⁨stdio⁩ على الثقة المحلية

لا تحمل وسيلة نقل ⁨MCP⁩ عبر ⁨stdio⁩ أي رمز حامل. تعمل بوصفها عملية فرعية محلية، ويقع حدّ الثقة عند العميل المُطلِق. طبّق نموذج المصادقة الشبكية على وسيلتَي نقل ⁨REST⁩ و⁨gRPC⁩ فقط.

المطابقة

تقدّم هذه الصفحة ادّعاءات معمارية فقط. أمّا الاستشهادات المعيارية الخاصة بالبروتوكول والأمان، فهي مثبّتة في الصفحات التي تحدّد السلوك: /⁨connect/security-and-operations/⁩ و/⁨transports/mcp/⁩ و/⁨transports/rest/⁩ و/⁨transports/grpc/.⁩ المرجع المعتمد لدورة حياة ⁨MCP⁩ هو المواصفة الرسمية على modelcontextprotocol.io ‏(المراجعة 2025-06-18). تسجّل صفحات النقل ذلك المرجع مع عنوان ⁨URL⁩ الخاص به، لأن مواصفة ⁨MCP⁩ ليست جزءًا من مجموعة المعايير المقيّدة.

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

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

انظر أيضًا

• /⁨connect/install/⁩ — التثبيت والحزم الاختيارية
• /⁨connect/quickstart/⁩ — أول تبادل قابل للتشغيل لـ ⁨MCP⁩ و⁨REST⁩
• /⁨connect/tool-catalog/⁩ — مجموعة الأدوات الأساسية المُتحقَّق منها وكيف يعتمد العدد على وقت التشغيل
• /⁨connect/hitl-risk-tiers/⁩ — بوابة التأكيد ونموذج المخاطرة
• /⁨transports/mcp/⁩ و/⁨transports/rest/⁩ و/⁨transports/grpc/⁩ — الإعداد لكل وسيلة نقل
• /⁨connect/security-and-operations/⁩ — المصادقة وأمان النقل ونموذج التهديد
• /⁨connect/deployment/⁩ — ⁨RoadRunner⁩ و⁨Docker⁩ والنشر متعدّد وسائل النقل المُدمج