NextPDF Connect — نقل MCP

لمحة سريعة

يشغّل نقل ⁨Model Context Protocol⁩ (⁨MCP⁩) الأداة bin/nextpdf-mcp كعملية فرعية محلية. ويتواصل باستخدام ⁨JSON-RPC 2.0⁩ عبر الإدخال والإخراج القياسيين. ينفّذ الخادم مراجعة ⁨MCP⁩ ذات الإصدار 2025-06-18.

التثبيت

composer require nextpdf/server

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

في نموذج ⁨stdio⁩ الخاص بـ ⁨MCP⁩، يطلق العميل الخادم كعملية فرعية. يتبادل العميل رسائل ⁨JSON-RPC⁩ مفصولة بأسطر جديدة: رسالة واحدة لكل سطر، دون أسطر جديدة مُضمَّنة، وبترميز ⁨UTF-8.⁩ لا يكتب الخادم إلى الإخراج القياسي إلا رسائل ⁨MCP⁩ الصحيحة، ويرسل السجلات إلى الخطأ القياسي. يوجّه التنفيذ مُسجِّل التدقيق الخاص به إلى الخطأ القياسي حتى لا تُفسد أسطر السجل دفق البروتوكول أبداً. تُعرّف مواصفات ⁨MCP⁩ الرسمية، المراجعة 2025-06-18، هذا التأطير. هذه المواصفات ليست جزءاً من مجموعة المعايير المُقيَّدة، لذلك يُستشهَد بها عبر عنوان ⁨URL⁩: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports.

ينفّذ ⁨NextPDF Connect⁩ نقل ⁨stdio⁩. وتُعرّف مواصفات ⁨MCP⁩ أيضاً نقل ⁨Streamable HTTP.⁩ تنص المواصفات على أن العملاء ينبغي أن يدعموا ⁨stdio⁩ كلما أمكن ذلك، وأن الخادم يمكن أن يكتفي بتنفيذ ⁨stdio⁩. للوصول الشبكي إلى الأدوات نفسها، استخدم نقل ⁨REST⁩ أو ⁨gRPC⁩ بدلاً من ذلك؛ راجع /⁨transports/rest/⁩ و/⁨transports/grpc/.⁩

واجهة ⁨API⁩

الطرق

الطريقة	السلوك
initialize	يعيد إصدار البروتوكول والقدرات ومعلومات الخادم
notifications/initialized	إشعار (بلا id)؛ يُقبَل دون استجابة
tools/list	يسرد الأدوات المُسجَّلة مع مُرشِّح params.category اختياري
tools/call	ينفّذ أداة بحسب params.name مع params.arguments

تعيد أي طريقة أخرى الخطأ ⁨method-not-found⁩ (-32601). وتعيد الرسالة غير الصحيحة وفق ⁨JSON-RPC 2.0⁩ الخطأ ⁨invalid-request⁩ (-32600)؛ أما الإدخال غير القابل للتحليل فيعيد الخطأ ⁨parse-error⁩ (-32700). عند تكرار id الطلب، يعيد الخادم الاستجابة السابقة المُخزَّنة مؤقتاً من مخزن مؤقت سعته 64 إدخالاً دون إعادة التنفيذ.

استجابة ⁨initialize⁩

تعيد نتيجة initialize القيمة protocolVersion 2025-06-18، وserverInfo.name: NextPDF Connect، وكائن capabilities. وبالإضافة إلى قدرة tools القياسية، يضيف الخادم كتلة capabilities.nextpdf:

• tiers — أعداد الأدوات المُسجَّلة المباشرة حسب المستوى (⁨core⁩ / ⁨pro⁩ / ⁨enterprise⁩).
• tool_count — العدد الإجمالي للأدوات المُسجَّلة، المحسوب في وقت التشغيل.
• risk_model_version — إصدار نموذج المخاطر الذي يفرضه الخادم.
• hitl_enabled — true؛ بوابة التأكيد نشطة.

tool_count هو العدد المُعتمَد لـ هذا النشر. وهو عدد يُحسب في وقت التشغيل، وليس قيمة ثابتة موثَّقة؛ راجع /⁨connect/tool-catalog/.⁩

نموذج التعليمات البرمجية — بداية سريعة

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

نموذج التعليمات البرمجية — الإنتاج

يضيّق مُرشِّح الفئة الكتالوج إلى مجال واحد:

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

تأتي قيم الفئة من الفئة المُعلَنة لكل أداة (على سبيل المثال document وdiagnostic).

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

• لا يوجد مفتاح ⁨API.⁩ لا يحتوي نقل ⁨stdio⁩ على مستمع شبكي ولا على رمز ⁨bearer.⁩ تعامَل مع حدود عملية نظام التشغيل على أنها حدود الثقة، وفقاً لنموذج ⁨stdio⁩ الخاص بـ ⁨MCP.⁩ لا تربطه بشبكة.

• تحدِّيات التأكيد ضمن القناة. تعيد أداة ApprovalRequired استجابة ⁨JSON-RPC⁩ ناجحة. محتوى الاستجابة هو نص التحدِّي ورمز للاستخدام مرة واحدة، وليس خطأً. راجع /⁨connect/hitl-risk-tiers/.⁩

• الإشعارات صامتة. الرسالة التي لا تحتوي على id لا تُنتج استجابة. تسلسل المصافحة هو initialize (مع ⁨id⁩)، ثم إشعار initialized، ثم الاستدعاءات التي تحمل ⁨id.⁩

الأداء

يعمل خادم ⁨MCP⁩ كعملية واحدة، ويعالج طلباً واحداً في كل مرة عبر الأنابيب. لا توجد رحلة ذهاب وإياب عبر الشبكة؛ ويهيمن عمل المحرك الأساسي على زمن الاستجابة.

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

يرث النقل ثقة العميل الذي يطلقه. أبقِ العملية الفرعية محلية. لا تزال الأدوات عالية المخاطر تتطلب تأكيداً بشرياً رغم عدم وجود مفتاح ⁨API.⁩ راجع /⁨connect/security-and-operations/.⁩

المطابقة

يتطابق تأطير ⁨stdio⁩ وسلوك ⁨initialize/lifecycle⁩ مع مواصفات ⁨Model Context Protocol⁩ الرسمية، المراجعة 2025-06-18:

• عمليات النقل: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports
• دورة الحياة: https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle

لا تقع مواصفات ⁨MCP⁩ ضمن مجموعة المعايير المُقيَّدة، لذلك ليس لها reference_id؛ وعناوين ⁨URL⁩ الرسمية أعلاه هي الاستشهاد المُعتمَد.

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

تعيد tools/list أدوات ⁨Pro⁩ و⁨Enterprise⁩ فقط عند تثبيت nextpdf/premium إلى جانب الخادم. ويظل النقل نفسه واحداً بغض النظر عن المستويات المُثبَّتة.

انظر أيضاً

• /⁨connect/quickstart/⁩ — المصافحة القابلة للتشغيل
• /⁨connect/tool-catalog/⁩ — ما تعيده tools/list ولماذا تتفاوت الأعداد
• /⁨connect/hitl-risk-tiers/⁩ — صيغة تحدِّي التأكيد
• /⁨transports/rest/⁩ · /⁨transports/grpc/⁩ — بدائل عبر الشبكة
• /⁨connect/migrating-to-multi-transport/⁩ — نقل تكامل يعتمد على ⁨MCP⁩ فقط إلى ⁨REST/gRPC⁩