بدء سريع مع NextPDF Connect

لمحة سريعة

توضّح هذه الصفحة أصغر تبادل مفيد عبر كلتا وسيلتي النقل: ⁨Model Context Protocol⁩ (⁨MCP⁩) و⁨Representational State Transfer⁩ (⁨REST⁩). يستخدم كل طلب صيغة النقل الدقيقة كما ينفّذها الخادم. لا تحتاج إلى عُدّة تطوير برمجيات (⁨SDK⁩).

التثبيت

composer require nextpdf/server

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

تستخدم وسيلة نقل ⁨MCP⁩ بروتوكول ⁨JSON-RPC 2.0⁩ عبر الإدخال والإخراج القياسيين. أرسل التسلسل بالترتيب. أرسل أولاً initialize. ثم أرسل إقرار notifications/initialized. ثم أرسل tools/list وtools/call. يقرأ الخادم رسالة ⁨JSON⁩ واحدة لكل سطر. أنهِ كل سطر بسطر جديد. يكتب الخادم استجابة واحدة لكل سطر.

تُتيح وسيلة نقل ⁨REST⁩ قدرات المحرّك نفسها على هيئة عمليات ⁨Hypertext Transfer Protocol⁩ (⁨HTTP⁩). يمثّل التصيير الواحد عديم الحالة طلب POST /api/v1/render واحدًا يحتوي مصفوفة عمليات مرتّبة. جسم الاستجابة هو ملف ⁨Portable Document Format⁩ (⁨PDF⁩).

عيّنة شيفرة — بداية سريعة (⁨MCP⁩ عبر ⁨stdio⁩)

شغّل الخادم، ومرّر المصافحة إليه عبر الأنبوب. تستخدم هذه الطلبات الثلاثة أسماء الطرائق المُتحقَّق منها التي يوجّهها معالج البروتوكول:

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

تعرض استجابة initialize إصدار البروتوكول 2025-06-18، واسم الخادم NextPDF Connect، وكتلة capabilities.nextpdf. تتضمّن تلك الكتلة أعداد الطبقات الحيّة، وقيمة tool_count وقت التشغيل، وإصدار نموذج المخاطر، وhitl_enabled: true. تسرد استجابة tools/list الأدوات الدقيقة المسجّلة لهذا التثبيت. لا ينتج عن سطر الإشعار أي استجابة، وهذا مقصود.

استدعِ الآن أداة آمنة. تجري أداة diagnostic.doctor فحصًا للبيئة للقراءة فقط، ولا تحتاج إلى مستند أو تأكيد:

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

عيّنة شيفرة — بداية سريعة (⁨REST⁩)

شغّل خادم ⁨REST⁩، ثم صيّر ملف ⁨PDF⁩ من سطر واحد. يتطلّب الخادم مفتاح واجهة برمجة التطبيقات (⁨API⁩) على كل نقطة نهاية غير مخصّصة لفحوص الحالة الصحية، لذا عرّف مفتاحًا أولاً:

export NEXTPDF_API_KEYS='npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef:demo:core:default'
./vendor/bin/rr serve -c .rr.yaml

في صدفة ثانية، أرسل طلب تصيير. الجسم هو RenderRequest. يحتوي هذا الطلب على مصفوفة operations مرتّبة من عمليات ذات أنواع محدّدة.

curl -sS -X POST http://localhost:8080/api/v1/render \
  -H 'Authorization: Bearer npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef' \
  -H 'Content-Type: application/json' \
  -d '{
        "page_size": "A4",
        "orientation": "portrait",
        "operations": [
          { "type": "add_text", "text": "Hello from NextPDF Connect" }
        ]
      }' \
  --output hello.pdf

جسم الاستجابة بالحالة 200 هو ملف ⁨PDF⁩ (Content-Type: application/pdf) المكتوب إلى hello.pdf. لا تحتاج فحوص الحالة الصحية إلى مفتاح:

curl -sS http://localhost:8080/healthz

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

• ترتيب المصافحة مهم. يعامل معالج البروتوكول أي رسالة بلا id باعتبارها إشعارًا ولا يُرجع شيئًا. أرسل initialize مع id، ثم إشعار initialized، ثم طلباتك التي تتضمّن id.

• يؤدي تكرار id إلى إزالة تكرار الطلب. يخزّن المعالج الاستجابات الأخيرة مؤقتًا في مخزن دائري سعته 64 مدخلًا. وعند ورود id مكرّر، يُرجع الاستجابة المخزَّنة مؤقتًا دون تشغيل الأداة من جديد. استخدم معرّفات جديدة.

• تستجيب الأداة عالية المخاطر بتحدٍّ، لا بنتيجة. يؤدّي استدعاء output_pdf مع file_path إلى إرجاع تحدّي تأكيد بدلًا من التشغيل. أعد استدعاء الأداة مع _confirmation_token الصادر. أما وضع إخراج ⁨base64⁩، بلا file_path، فلا يتطلّب تأكيدًا. انظر /⁨connect/hitl-risk-tiers/.⁩

• يحصل أي طلب ⁨REST⁩ غير مُصرَّح به على 401. عند غياب ترويسة Authorization: Bearer أو تشوّهها، يُرجع الخادم جسم تفاصيل مشكلة مع ترويسة WWW-Authenticate: Bearer. فحصا /healthz و/readyz هما نقطتا النهاية الوحيدتان المسموح بهما دون مصادقة.

الأداء

يستخدم كل من مساري البداية السريعة طلبًا واحدًا. ويتحمّل مسار ⁨REST⁩ كلفة البدء البارد لمجمّع عاملي ⁨RoadRunner⁩ في أول طلب بعد rr serve. تعيد الطلبات اللاحقة استخدام العاملين الدافئين.

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

مفتاح npk_live_ أعلاه قيمة توضيحية للاستعمال مرة واحدة. ولّد مفاتيح حقيقية بعشوائية كافية، وخزّنها خارج نظام إدارة الشيفرة المصدرية، وفضّل مخزن المفاتيح المبني على الملفات للتدوير. لا تستخدم وسيلة نقل ⁨MCP⁩ عبر ⁨stdio⁩ مفتاح ⁨API⁩ لأنها عملية فرعية محلية يثق بها العميل الذي شغّلها وفق نموذج نقل ⁨MCP.⁩ انظر /⁨connect/security-and-operations/.⁩

التوافق

تطابق صيغ النقل المعروضة مراجعة ⁨MCP⁩ المُنفَّذة 2025-06-18 وعقد ⁨REST⁩ في ⁨OpenAPI 3.1.⁩ الاستشهادات المعيارية للبروتوكول والمصادقة مثبّتة في /⁨transports/mcp/⁩ و/⁨transports/rest/⁩ و/⁨connect/security-and-operations/.⁩

انظر أيضًا

• /⁨transports/mcp/⁩ — مرجع وسيلة نقل ⁨MCP⁩ الكامل
• /⁨transports/rest/⁩ — مرجع وسيلة نقل ⁨REST⁩ الكامل وتصيير ⁨OpenAPI⁩
• /⁨connect/tool-catalog/⁩ — ما الأدوات التي تُرجعها tools/list ولماذا
• /⁨connect/hitl-risk-tiers/⁩ — كيف يبدو تحدّي التأكيد
• /⁨connect/configuration/⁩ — تقييد الكتالوج وضبط الخادم