الانتقال من MCP فقط إلى النقل المتعدد

لمحة سريعة

انقل تكاملاً من نقل بروتوكول سياق النموذج (⁨MCP⁩) عبر ⁨stdio⁩ إلى ⁨REST⁩ أو ⁨gRPC⁩. لا يتغير سلوك المحرك؛ إذ يبقى الفهرس ونموذج المخاطر وبوابة التأكيد كما هي. ما يتغير هو ثلاثة أمور: بروتوكول الاتصال، والمصادقة، ونموذج التزامن.

التثبيت

composer require nextpdf/server
./vendor/bin/rr get-binary

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

كانت الوثائق المبكرة لهذه الحزمة تصف نقلاً واحدًا: ⁨MCP⁩ عبر ⁨stdio⁩. توفر الحزمة الآن سجل الأدوات نفسه عبر ثلاثة أنواع من النقل. للانتقال، اختر نقلاً شبكيًا، ثم اربط استدعاءات ⁨MCP⁩ الخاصة بك به. لا تحتاج إلى إعادة كتابة منطق المستندات لديك.

اختر النقل الذي يناسب نشرك:

• ابقَ على ⁨MCP⁩ لوكيل محلي واحد، أو عند الحاجة إلى أدنى زمن استجابة (من دون قفزة شبكية)، أو لعميل أصلي لـ ⁨MCP⁩، مثل مساعد ⁨IDE⁩ محلي.
• انتقل إلى ⁨REST⁩ للوصول من عملاء متعددين بمفاتيح ⁨API⁩ لكل عميل، أو للنشر عبر الحاويات أو ⁨Kubernetes⁩، أو لتحديد المعدل لكل عميل، أو للمهام غير المتزامنة، أو لدعم عملاء بأي لغة.
• انتقل إلى ⁨gRPC⁩ للعقود محددة الأنواع، وبث ملفات ⁨PDF⁩ الكبيرة من الخادم، وعمليات النشر من خدمة إلى خدمة عبر ⁨TLS⁩ المتبادل.

سطح ⁨API⁩

ما الذي يبقى كما هو

• سجل الأدوات والفهرس المعتمد على وقت التشغيل (انظر /⁨connect/tool-catalog/⁩).
• نموذج المخاطر رباعي المستويات وبوابة التأكيد (انظر /⁨connect/hitl-risk-tiers/⁩).
• نموذج المستند ودلالات المحرك.

ما الذي يتغير

الجانب	⁨MCP⁩ (⁨stdio⁩)	⁨REST⁩	⁨gRPC⁩
تنسيق الاتصال	⁨JSON-RPC 2.0⁩ عبر ⁨stdio⁩	⁨JSON⁩ عبر ⁨HTTP⁩	⁨Protobuf⁩ عبر ⁨gRPC⁩
المصادقة	لا شيء (عملية فرعية محلية)	مفتاح ⁨API⁩ عبر Authorization: Bearer	⁨bearer⁩ ضمن بيانات الاستدعاء الوصفية
التزامن	عملية واحدة، استدعاء واحد	مجمع عمال ⁨RoadRunner⁩	مجمع ⁨gRPC⁩ في ⁨RoadRunner⁩
غير متزامن	لا ينطبق	نقاط نهاية المهام	استدعاءات ⁨RPC⁩ للمهام
البث	لا ينطبق	متن متزامن	استدعاءات ⁨RPC⁩ للبث من الخادم

ربط المفاهيم

التسلسل النموذجي في ⁨MCP⁩ هو create_pdf، ثم أدوات المحتوى، ثم output_pdf. في ⁨REST⁩، يتحول ذلك إلى طلب POST /api/v1/render واحد عديم الحالة يحتوي على مصفوفة operations مرتبة. عندما تحتاج إلى حالة خطوة بخطوة، استخدم نقاط نهاية الجلسات الاختيارية بدلاً من ذلك. في ⁨gRPC⁩، يكافئه استدعاء Render ⁨RPC⁩، أو RenderStream للتسليم المقطّع. للإنشاءات ذات الحالة، استخدم استدعاءات CreateSession وSessionOperation وSessionRender ⁨RPC⁩.

تسلسل أدوات ⁨MCP⁩	⁨REST⁩	⁨gRPC⁩
create_pdf + أدوات المحتوى + output_pdf	POST /api/v1/render	Render / RenderStream
إنشاء ذو حالة عبر الاستدعاءات	POST /api/v1/sessions (+ عمليات الجلسة)	CreateSession (+ SessionOperation)
تصيير طويل الأمد	POST /api/v1/jobs ثم استطلاع النتيجة	SubmitJob ثم GetJobResult
عملية محكومة بالطبقة	POST /api/v1/<operation>	ExecuteCapability

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

استدعاء ⁨MCP⁩:

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"add_text","arguments":{"text":"Hello"}}}

ويصبح طلب ⁨REST⁩:

curl -sS -X POST http://localhost:8080/api/v1/render \
  -H "Authorization: Bearer $NEXTPDF_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"type":"add_text","text":"Hello"}]}' \
  --output hello.pdf

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

شغّل كلا نوعي النقل أثناء الانتقال المرحلي. يخدم ملف تعريف ⁨RoadRunner⁩ المدمج كلاً من ⁨REST⁩ و⁨gRPC⁩ من مشرف واحد. يمكن للتكامل القديم القائم على ⁨MCP⁩ أن يستمر في العمل محليًا حيثما يظل مناسبًا:

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
./vendor/bin/rr serve -c .rr.full.yaml

ليست هناك حالة مشتركة تحتاج إلى نقلها. أنواع النقل عمليات مستقلة تعمل فوق المحرك نفسه. انقل العملاء تدريجيًا.

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

• أضف المصادقة. لم يكن لنقل ⁨MCP⁩ أي مصادقة لأنه كان عملية فرعية محلية. تتطلب أنواع النقل الشبكية مفتاح ⁨API⁩ صالحًا في كل طلب لا يخص فحص الصحة. جهز المفاتيح قبل التحويل. انظر /⁨connect/security-and-operations/⁩.

• لا تزال بوابة التأكيد تُفعّل. تُفعّل أداة approval_required في ⁨REST⁩ و⁨gRPC⁩ تمامًا كما كانت تُفعّل في ⁨MCP⁩. انقل تدفق التأكيد إلى التكامل الجديد. لا تفترض أن البوابة تخص ⁨MCP⁩ وحده. انظر /⁨connect/hitl-risk-tiers/⁩.

• لم يتغير التحكم بالطبقات. تحتاج عملية ⁨Pro⁩ أو ⁨Enterprise⁩ إلى تثبيت nextpdf/premium ومفتاح مخوّل على النقل الجديد، تمامًا كما كانت الأداة المقابلة تحتاج إلى الحزمة في ⁨MCP⁩.

• الاستقرار التكراري ميزة جديدة ومفيدة. يضيف ⁨REST⁩ تحكمًا بالاستقرار التكراري لم يكن نقل ⁨stdio⁩ يملكه. استخدمه لجعل إرسال المهام آمنًا عند إعادة المحاولة. انظر /⁨connect/production-usage/⁩.

الأداء

⁨MCP⁩ وحيد العملية ويمنح أدنى زمن استجابة لوكيل محلي واحد. تضيف أنواع النقل الشبكية مجمع عمال وقفزة شبكية. في المقابل، تتوسع لخدمة عدد كبير من العملاء المتزامنين. انقل عمليات التصيير الطويلة إلى مسار المهام غير المتزامن على النقل الجديد حتى لا يبقى العمال محجوزين.

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

يؤدي الانتقال من ⁨stdio⁩ إلى انكشاف شبكي. أنهِ أمان طبقة النقل (⁨TLS⁩) أمام ⁨REST⁩، واستخدم ⁨TLS⁩ المتبادل لـ ⁨gRPC⁩ على الشبكات غير الموثوقة، وحدد نطاق المفاتيح لكل عميل، وأبقِ enabled_tools في حدها الأدنى. إن نموذج نقل ⁨MCP⁩ الخالي من بيانات الاعتماد آمن فقط لأنه عملية فرعية محلية. لا تُعد إنتاج ذلك الانكشاف عبر الشبكة. انظر /⁨connect/security-and-operations/⁩.

المطابقة

تقدم هذه الصفحة إرشادات للانتقال. استشهادات البروتوكول والمصادقة مثبّتة في /⁨transports/mcp/⁩ و/⁨transports/rest/⁩ و/⁨transports/grpc/⁩ و/⁨connect/security-and-operations/⁩.

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

تتطلب العمليات المحكومة بالطبقة nextpdf/premium بغض النظر عن النقل. لا يغير الانتقال ما يندرج ضمن ⁨core⁩ مقابل ⁨Premium⁩؛ بل يغير فقط كيفية وصولك إلى الفهرس.

انظر أيضاً

• /⁨transports/mcp/⁩ — النقل الذي تنتقل منه
• /⁨transports/rest/⁩ · /⁨transports/grpc/⁩ — نوعا النقل اللذان تنتقل إليهما
• /⁨connect/tool-catalog/⁩ — الفهرس، وهو متطابق عبر جميع أنواع النقل
• /⁨connect/hitl-risk-tiers/⁩ — البوابة، وهي متطابقة عبر جميع أنواع النقل
• /⁨connect/security-and-operations/⁩ — المصادقة التي يجب أن تضيفها