استكشاف أخطاء اتصال Cocos MCP: لا يظهر cocos-creator في Cursor

أولاً: أي طبقة فشلت؟

إذا كان وصفك «Cursor تعطّل / لا يتصل»، ابدأ بأعراض Cursor: تعطّل Cursor بعد Cocos Creator MCP.

إن لم يتضح بعد ماذا يفعل MCP وكيف يختلف عن «Cocos Creator AI»، اقرأ أولاً ما هو Cocos Creator MCP.

عند ربط Cocos MCP بـ Cursor (أو عميل MCP آخر)، فإن العائق المعتاد ليس “الطلبات السيئة”—بل الجسر لا يتصل أبداً: خادم المحرر متوقف، أو IDE الذكي لا يسرد cocos-creator.

يتبع هذا الدليل العرض → السبب → الإصلاح لـ Creator 2.x و 3.x. خطوات التثبيت الكاملة:

• تثبيت Cocos Creator 3.x MCP
• تثبيت Cocos Creator 2.x MCP

الأمثلة تستخدم Cursor؛ Claude Code و Codex والعملاء المماثلون يتبعون نفس فحوصات إعادة التحميل / التكوين.

أولاً: أي طبقة فشلت؟

مسار MCP يحتوي على أربع طبقات. الفشل في أي طبقة يبدو مثل “لا يمكن الاتصال”:

1. الامتداد مثبت ومفعّل
        ↓
2. اللوحة مفعلة (الحساب / رمز الترخيص)
        ↓
3. خادم MCP يعرض Running (localhost)
        ↓
4. تكوين IDE الذكي مكتوب وقائمة MCP تعرض متصلاً

ما تراه	تحقق أولاً
لا توجد قائمة Extension → Cocos MCP Server / MCP Server	الطبقة 1: إصدار الحزمة، مسار الاستيراد، إعادة التشغيل
اللوحة تفتح ولكن لا يمكن بدءها / تبقى غير مفعلة	الطبقة 2: الحساب والترخيص
نقرت Start ولكن لا تصل أبداً إلى Running	الطبقة 3: المنفذ، جدار الحماية، التفعيل
Creator يعرض Running، Cursor لا يحتوي على cocos-creator	الطبقة 4: التكوين السريع، إعادة تحميل MCP، ملف التكوين
Cursor يعرض متصلاً ولكن لا يمكنه سرد عقد المشهد	موجه التحقق، مفاتيح الأدوات، فتح المشروع الصحيح

العرض أ: لا يوجد امتداد MCP في القائمة

الأسباب المحتملة

1. حزم 2.x / 3.x مختلطة
2. 3.x: غير مستورد في مدير الامتدادات، أو ما زال معطلاً
3. 2.x: ليس تحت packages/<plugin-name>/، أو مستوى تداخل إضافي من فك الضغط
4. 2.x: تم وضع الملفات ولكن Creator لم يُعد تشغيله بالكامل

الإصلاحات

Creator 3.x:

1. قم بالتنزيل من Cocos MCP 3.x—وليس حزمة 2.x
2. افتح المشروع → Extension → Extension Manager → Import → حدد ملف zip الخاص بـ 3.x
3. تأكد من أن cocos-mcp-server مفعّل؛ قم بتفعيله إذا كان معطلاً
4. إذا كانت القائمة ما زالت مفقودة: أغلق Creator وأعد فتح نفس المشروع

Creator 2.x:

1. قم بالتنزيل من Cocos MCP 2.x
2. بعد فك الضغط، يجب أن يبدو الهيكل هكذا:

your-project-root/
  packages/
    <plugin-name>/          ← ملفات الإضافة هنا مباشرة
      package.json          ← يجب أن يكون موجوداً في هذا المسار (الاسم حسب الحزمة)

3. مثال على تداخل خاطئ:

packages/
  xxx-mcp-unzip/
    <plugin-name>/
      package.json

4. أصلح المسار، ثم أغلق وأعد تشغيل Creator (وليس مجرد تحديث المشهد). تحقق من Extension → MCP Server.

العرض ب: اللوحة تفتح، لكن التفعيل يفشل أو الخدمة لا تبدأ

الأسباب المحتملة

• الحساب يفتقر إلى صلاحية Pro المطابقة
• رمز الترخيص منتهي أو البريد الإلكتروني غير مطابق
• نقرت Start قبل التفعيل

الإصلاحات

1. افتح لوحة MCP (3.x: Extension → Cocos MCP Server → Open Mcp Panel؛ 2.x: Extension → MCP Server)
2. قم بالتفعيل باستخدام أحد الخيارين:
   • حساب VberAI + كلمة المرور
   • البريد الإلكتروني + رمز الترخيص
3. تأكد من الخطة / الرمز في مركز الحساب الرسمي، ثم أعد المحاولة في اللوحة
4. فقط بعد التفعيل افتح إعدادات خادم MCP وانقر Start

بدون التفعيل، عادةً لا يصل الخادم أبداً إلى Running. أصلح جانب المحرر قبل إلقاء اللوم على Cursor.

العرض ج: نقرت Start، ولكن لا يصل أبداً إلى Running

الأسباب المحتملة

1. لم يتم التفعيل بعد (انظر العرض ب)
2. المنفذ قيد الاستخدام (غالباً ما يكون الافتراضي 3000 في 3.x؛ 2.x يتبع اللوحة)
3. جدار الحماية / برنامج الأمان يمنع الاستماع على localhost

الإصلاحات

1. لاحظ المنفذ في صفحة إعدادات خادم MCP (الأمثلة أدناه تستخدم 3000—استبدله بقيمة اللوحة الخاصة بك)
2. تحقق مما إذا كان هناك شيء يستمع بالفعل:

macOS / Linux:

lsof -iTCP:3000 -sTCP:LISTEN

Windows (PowerShell):

netstat -ano | findstr :3000

3. إذا كانت عملية أخرى تشغل المنفذ:
   • أوقف تلك العملية، أو
   • اختر منفذاً حراً في لوحة MCP، ثم Start مرة أخرى
4. تأكد من أن جدار الحماية يسمح بـ 127.0.0.1 (لا تكشف MCP للإنترنت العام)
5. عندما تعرض اللوحة Running، قم بتكوين IDE الذكي

العرض د: Creator يعمل، لكن Cursor لا يحتوي على cocos-creator

معظم تقارير “فشل الاتصال” تصل إلى هنا: المحرر جيد، العميل لم يستوعب التكوين أبداً.

الإصلاحات (بالترتيب)

1. في Creator، تأكد من أن لوحة MCP ما زالت Running (تغييرات المنفذ أو إعادة تشغيل المحرر قد توقفها)
2. افتح Tool Manager وقم بتمكين الأدوات التي تحتاجها
3. افتح Quick Config → اختر Cursor → Auto Config حتى تعرض الواجهة Configured
4. في Cursor → قائمة MCP / الأدوات:
   • يجب أن ترى cocos-creator (أو الاسم المعروض في اللوحة)
   • إذا كان مفقوداً: Reload MCP (أو أعد تشغيل Cursor) وتحقق مرة أخرى
5. إذا ما زال مفقوداً: تحقق من أن تكوين MCP في Cursor يحتوي على الجسر المحلي (127.0.0.1 + منفذ اللوحة)

يختلف مخرج Auto Config حسب إصدار Cursor. عند الفحص يدوياً:

• اسم الخدمة يطابق Cocos MCP (مثل cocos-creator)
• المضيف هو 127.0.0.1 أو localhost، والمنفذ يطابق Creator
• ليس IP شبكة محلية أو عاماً عن طريق الخطأ

بعد أي تعديل على التكوين، أعد تحميل MCP مرة أخرى أو ستبقى الواجهة على الحالة القديمة.

IDEs ذكية أخرى

في Quick Config، اختر Claude Code أو Codex أو Windsurf أو Cline وما إلى ذلك، ثم Auto Config → reload MCP في ذلك العميل. تكوين Cursor لا يربط كل IDE.

العرض هـ: يعرض متصلاً، لكن لا يمكنه سرد المشهد / تعديل العقد

الأسباب المحتملة

1. المشروع / المشهد المفتوح في Creator لا يطابق ما سألت عنه
2. الأدوات المطلوبة غير محددة في Tool Manager
3. تحققت فقط من “الملفات على القرص”، وليس سياق المحرر

التحقق

أرسل طلباً للقراءة فقط في Cursor:

قم بسرد أسماء العقد الجذرية للمشهد المفتوح حالياً في Cocos Creator.

النتيجة	المعنى
تطابق التسلسل الهرمي	الجسر يعمل؛ جرب كتابة صغيرة بعد ذلك
خطأ واضح / لا توجد أدوات	ارجع إلى الأعراض ج/د
أسماء عقد مخترعة	MCP على الأرجح غير مستخدم؛ تحقق من الاتصال ومفاتيح الأدوات

ثم جرب كتابة صغيرة (أنشئ عقدة مؤقتة واحذفها). قم بالالتزام قبل التعديلات الكبيرة.

جدول سريع 2.x مقابل 3.x

العنصر	Creator 3.x	Creator 2.x
صفحة المنتج	cocos (3.x)	cocos2x
التثبيت	Extension Manager → Import	فك الضغط في مشروع packages/
بعد التثبيت	قم بالتمكين في القائمة	يجب إعادة تشغيل Creator
الحزمة	3.x فقط	2.x فقط
الخطوات الكاملة	تثبيت 3.x	تثبيت 2.x

غالباً ما تظهر الحزم المختلطة على أنها “لا توجد قائمة” أو “فشل الاستيراد”—استخدم هذا الجدول أولاً.

الترتيب الموصى به (قائمة تحقق من 5 دقائق)

حدد بالترتيب؛ معظم حالات الفشل تقع في الأربعة الأولى:

1. إصدار Creator الرئيسي يطابق حزمة MCP (2.x ↔ 2.x، 3.x ↔ 3.x)
2. الامتداد مفعل / مسار packages صحيح؛ 2.x أعيد تشغيله
3. تم تفعيل اللوحة بنجاح
4. اللوحة تعرض Running؛ المنفذ حر
5. Quick Config → Auto Config لـ IDE الحالي
6. تم إعادة تحميل MCP في IDE الذكي؛ cocos-creator مدرج
7. طلب للقراءة فقط يسرد جذور المشهد المفتوح حالياً

إذا استمر الفشل، التقط هذا

عند طلب الدعم أو من زميل، قم بتضمين:

• إصدار Creator الدقيق (مثل 3.8.x / 2.4.x)
• نوع حزمة MCP (2.x أو 3.x Pro)
• ما إذا كانت اللوحة Running، والمنفذ
• اسم/إصدار IDE الذكي ولقطة شاشة لقائمة MCP
• الطلب الدقيق للقراءة فقط والرد

أبقِ الجسر على localhost فقط؛ لا تنشر منفذ MCP.

المستندات ذات الصلة

• تثبيت Cocos Creator 3.x MCP
• تثبيت Cocos Creator 2.x MCP
• فيديو إعداد Cocos Creator MCP
• دليل اختيار المحرك: Godot MCP مقابل Unity MCP مقابل Cocos MCP