استكشاف مشكلات NextPDF Connect وإصلاحها

لمحة سريعة

تندرج معظم الإخفاقات ضمن أحد خمسة أنماط: مصافحة ⁨JavaScript Object Notation Remote Procedure Call⁩ (⁨JSON-RPC⁩) مشوَّهة، أو مفتاح ⁨application programming interface⁩ (⁨API⁩) مفقود، أو أداة من هذه الفئة غير مثبَّتة، أو تحدي تأكيد لم يُستجب له، أو مخزن لا تتشاركه العمليات العاملة. لكل نمط علامة مميزة.

التثبيت

composer require nextpdf/server

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

يُرجع ناقل ⁨Model Context Protocol⁩ (⁨MCP⁩) كائنات أخطاء ⁨JSON-RPC 2.0⁩ برموز قياسية. ويُرجع ناقل ⁨Representational State Transfer⁩ (⁨REST⁩) مستندات تفاصيل المشكلات وفق ⁨Request for Comments⁩ (⁨RFC⁩) 7807. يحمل كل مستند عنوان ⁨URL⁩ في حقل type يعرّف الحالة. عند التعامل مع مشكلات البيئة، ابدأ بأدوات التشخيص (diagnostic.doctor، diagnostic.capabilities). هاتان الأداتان متاحتان دائمًا في الكتالوج الأساسي.

واجهة ⁨API⁩

رموز أخطاء ⁨JSON-RPC⁩ في ⁨MCP⁩

الرمز	الاسم	السبب
-32700	خطأ تحليل	السطر ليس ⁨JSON⁩ صالحًا
-32600	طلب غير صالح	ليست الرسالة ⁨JSON-RPC 2.0⁩ (تفتقد jsonrpc/method)
-32601	الأسلوب غير موجود	الأسلوب ليس initialize أو tools/list أو tools/call
-32602	مَعلمات غير صالحة	params.name مفقود في tools/call
-32603	خطأ داخلي	أطلقت الأداة استثناءً أثناء التنفيذ

الأداة التي تُخفق برشاقة لا تستخدم هذه الرموز. بدلاً من ذلك، تُرجع استجابة ⁨JSON-RPC⁩ ناجحة تتضمن isError: true في النتيجة، مع شرح نصي، مثل: أداة غير معروفة، أو أداة مُعطَّلة بموجب السياسة، أو وسائط غير صالحة.

أنواع تفاصيل المشكلات في ⁨REST⁩

⁨HTTP⁩	مُعرّف type	السبب
401	unauthorized	مفتاح ⁨API⁩ مفقود/غير صالح/مُعطَّل/منتهي الصلاحية
403	capability-denied	فئة المفتاح غير مخوَّلة لهذه العملية
413	payload-too-large / tier-payload-exceeded	يتجاوز المحتوى الحد الأقصى العام أو حد الفئة
422	validation-failed	فشل محتوى الطلب في التحقق من المخطط
429	ip-rate-exceeded / client-rate-exceeded	بلغ الطلب حد المعدل
404	not-found	مسار غير معروف أو مُعرّف ⁨job/session⁩
504	(انتهاء مهلة الطلب)	تجاوزت العملية مهلة الفئة

مثال برمجي — بدء سريع

شغّل فحص سلامة البيئة. لا يتطلب مستندًا أو تأكيدًا:

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

مثال برمجي — الإنتاج

قبل تصحيح خطأ “أداة مفقودة”، تأكّد من الأدوات التي يكشفها هذا النشر:

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

أو، مقابل خادم ⁨REST⁩ قيد التشغيل:

curl -sS http://localhost:8080/api/v1/capabilities \
  -H "Authorization: Bearer $NEXTPDF_KEY"

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

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

• أداة ضبطتها في enabled_tools لا تظهر. تتقاطع قائمة السماح مع الأدوات المُكتشَفة. ولا يمكنها إضافة أداة لم يعثر عليها السجل. تحقّق من تثبيت الفئة وأي بوّابات بيئة. على سبيل المثال، تُفعَّل parse_pdf اختياريًا عبر NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED.

• أعادت tools/call نصًا يطلب رمزًا مميزًا. هذا تحدي تأكيد، وليس خطأً. استدعِ الأداة مرة أخرى خلال 300 ثانية مع تعيين _confirmation_token على الرمز المميز الصادر. راجع /⁨connect/hitl-risk-tiers/.⁩

• لم يُنتج سطر الإشعار أي مُخرَج. هذا صحيح. رسالة ⁨JSON-RPC⁩ التي لا تتضمن id هي إشعار، ولا يُعيد المُعالِج شيئًا. أرسل الطلبات مع id للحصول على استجابات.

• أعاد مُعرّف طلب مكرر استجابة قديمة. يزيل المُعالِج التكرارات بحسب مُعرّف الطلب في مخزن مؤقت سعته 64 مُدخَلاً. استخدم مُعرّفًا جديدًا لكل طلب منطقي.

• تتصرف حدود المعدل على نحو غير متوقع عبر العمليات العاملة. المخزن في الذاكرة خاص بكل عملية عاملة. لمشاركة العدّ، عيّن NEXTPDF_REDIS_HOST وثبّت ext-redis. راجع /⁨connect/deployment/.⁩

• تختفي المستندات بين الطلبات. مخزن المستندات في الذاكرة خاص بكل عملية عاملة ومقيَّد بمدة بقاء (document_ttl، القيمة الافتراضية 1800 ⁨s⁩). لاستمرار المستند عبر العمليات العاملة، استخدم المخزن المدعوم بـ ⁨Redis⁩، أو استخدم نقاط نهاية الجلسة، أو أبقِ مجموعة العمليات كاملة ضمن عملية تصيير متزامنة واحدة.

• عاد الخادم إلى التخزين في الذاكرة رغم تهيئة ⁨Redis.⁩ يعود خادم ⁨REST⁩ تلقائيًا إلى التخزين في الذاكرة إذا فشل اتصال ⁨Redis⁩ عند الإقلاع. تحقّق من إمكانية الوصول إلى ⁨Redis⁩، وتأكّد من وجود ext-redis في الصورة قيد التشغيل. لا تفترض أن ⁨Redis⁩ قيد الاستخدام دون التحقق.

• يرفض الخادم الإقلاع مع خطأ تهيئة. حاول مُدخَل في risk_level_overrides خفض مستوى أداة ApprovalRequired. يرفض المُحمِّل هذا عمدًا. أزِل الخفض؛ إذ لا يجوز للتجاوزات سوى رفع المخاطرة.

الأداء

إذا كان التصيير بطيئًا تحت الحمل، فتأكّد من أن مجمّع العمليات العاملة غير مُشبَع. تحقّق من نقطة نهاية مقاييس ⁨RoadRunner.⁩ ثم انقل عمليات التصيير الطويلة إلى مسار المهام غير المتزامنة حتى لا تحتجز العمليات العاملة. راجع /⁨connect/production-usage/.⁩

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

لا تتحايل على 401 بكشف ناقل ⁨MCP⁩ غير المُصادَق عبر شبكة؛ فهذا يزيل المصادقة بالكامل. أصلِح مفتاح ⁨API⁩ بدلاً من ذلك. لا ترفع مستوى تفصيل السجل لفحص وسائط الأداة في بيئة مشتركة؛ فقد تكون حمولات الوسائط حساسة. راجع /⁨connect/security-and-operations/.⁩

المطابقة

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

انظر أيضًا

• /⁨connect/tool-catalog/⁩ — محتويات الكتالوج الأساسي وسبب تفاوت العدد
• /⁨connect/hitl-risk-tiers/⁩ — تحديات التأكيد بالتفصيل
• /⁨connect/deployment/⁩ — ⁨Redis⁩، ومجمّعات العمليات العاملة، ومشاركة المخزن
• /⁨connect/security-and-operations/⁩ — إخفاقات المصادقة والوضع الأمني