الاتصال بخادم MCP الخاص بـ Roblox Studio | المراجع

تم بناء خادم MCP الخاص بـ Roblox Studio داخل Roblox Studio. يقوم بتنفيذ بروتوكول سياق النموذج (MCP)، وهو معيار مفتوح يتيح للأدوات الذكية التواصل بشكل آمن مع التطبيقات الخارجية. بمجرد الاتصال، يمكن لعميل الذكاء الاصطناعي التفاعل مباشرة مع جلسة Studio المفتوحة الخاصة بك، واستكشاف نموذج البيانات، وكتابة النصوص، وتشغيل تعليمات Luau، واختبار تجربتك في وضع اللعب.

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

المتطلبات الأساسية

قبل أن تتمكن من الاتصال بالخادم، تأكد من أنك قد قمت بتثبيت أحدث إصدار من Roblox Studio و عميل MCP المفضل لديك على جهاز الكمبيوتر الخاص بك.

كيفية عمل خادم MCP الخاص بـ Studio

يعمل الخادم كعملية محلية على جهازك ويتواصل مع عميل الذكاء الاصطناعي باستخدام stdin transport، الذي يستخدم تدفقات الإدخال/الإخراج القياسية. يتم بدء جميع الإجراءات من خلال عميل الذكاء الاصطناعي الخاص بك، الذي يرسل بعد ذلك طلبًا عبر هذا القناة لأداء إجراءات داخل جلسة Studio الخاصة بك.

يوفر الخادم الأدوات التالية:

نصوص
script_read	يقرأ نصًا من اللعبة باستخدام مسارات الترميز النقطي (على سبيل المثال، game.ServerScriptService.MyScript). يدعم قراءة النصوص بالكامل أو نطاقات سطر معينة.
multi_edit	يطبق تعديلات متعددة على نص في عملية واحدة. إذا كان مسار الهدف غير موجود، فإنه ينشئ نصًا جديدًا. يتطلب تحديد datamodel_type (تحرير).
script_search	يبحث عن النصوص حسب الاسم باستخدام المطابقة الناعمة. يُرجع ما يصل إلى 10 نتائج.
script_grep	يبحث عن نمط نصي عبر جميع النصوص في اللعبة. يُرجع ما يصل إلى 50 تطابقًا.
توليد الأصول والمحتوى
generate_mesh	يولد شبكة ثلاثية الأبعاد مزخرفة من موجه نصي باستخدام الذكاء الاصطناعي.
generate_material	يولد نموذج مادة مخصص. يُرجع المادة الأساسية واسم نموذج المادة لتطبيقها على الأجزاء.
generate_procedural_model	يخلق كائنات ثلاثية الأبعاد مبنية من أجزاء بدائية (كتل، كرات، أسطوانات، زوايا) كنموذج إجرائي ذو خصائص قابلة للتكوين. يدعم الصور المرجعية ومخططات الأجزاء المخصصة.
wait_job_finished	ينتظر انتهاء وظيفة توليد نموذج إجرائي ويُرجع الحالة النهائية.
search_asset	يبحث عن الأصول عبر متجر المبدعين (سوق عامة) ومخزون المبدعين (المستخدم، المجموعة، أو الكون). يدعم تصفية حسب نوع الأصل، السعر، العلامات، والنطاق.
insert_asset	يُدخل أصلًا في اللعبة بواسطة معرف الأصول الرقمي الخاص بـ Roblox. يدعم النماذج، والشبكات، والصور، والموسيقى، والفيديو، والرسوم المتحركة، والحزم.
upload_image	يحمّل مجموعة من الصور من عناوين HTTP إلى خادم أصول Roblox، مُرجعًا مسار صورة إلى خريطة معرف الأصل.
store_image	يحمّل صورة من مسار ملف محلي ويُرجع URI صورة يمكن تمريرها إلى أدوات أخرى (على سبيل المثال، كصورة مرجعية لـ generate_procedural_model).
استكشاف نموذج البيانات
subagent	يطلق وكيلًا فرعيًا متخصصًا للتعامل مع المهام المعقدة متعددة الخطوات بشكل مستقل. تشمل الأنواع المتاحة explore (لتحقيق قاعدة الشيفرة واستفسارات حالة اللعبة) و playtest (لتشغيل سيناريوهات اللعب والتحقق من النتائج).
search_game_tree	يستكشف تسلسل الحوادث كصفيف JSON مسطح. يدعم التصفية حسب المسار، نوع الحادث، والكلمات الرئيسية، مع توفر تنظيم العمق.
inspect_instance	يُرجع معلومات مفصلة حول حادث محدد، بما في ذلك جميع الخصائص القابلة للقراءة، والسمات المخصصة، وملخص عن الأطفال والأحفاد.
تنفيذ Luau
execute_luau	تشغيل تعليمات Luau في Studio. يُرجع إما النتيجة أو خطأ. يتطلب تحديد datamodel_type (تحرير، عميل، أو خادم).
اختبار اللعب
get_studio_state	يحصل على الحالة الحالية لـ Studio، بما في ذلك حالة اللعب وأنواع نموذج البيانات المتاحة.
start_stop_play	يبدأ أو يوقف اختبار اللعب.
get_console_output	يسترد الإخراج من سجل إخراج Studio.
screen_capture	يأخذ لقطة شاشة من عرض Studio الحالي ويُرجع بيانات الصورة. يقبل اختيارياً موضع كاميرا مخصص وهدف النظر.
محاكاة إدخال اللاعب
character_navigation	يُنقل شخصية اللاعب إلى موضع أو مسار حادث معين. يدعم مضاعف سرعة قابل للتكوين.
user_keyboard_input	يرسل إجراء واحدة أو أكثر من إجراءات لوحة المفاتيح بالترتيب: الضغط على المفتاح، تحرير المفتاح، ضغط المفتاح، إدخال نص، أو انتظار. يدعم استهداف حوادث واجهة المستخدم المحددة.
user_mouse_input	يرسل إجراء واحدة أو أكثر من إجراءات الماوس بالترتيب: التحرك، النقر، الضغط على الزر/الإفلات، التمرير، أو الانتظار. يدعم استهداف حوادث معينة أو إحداثيات الشاشة.
الوثائق والمهارات
http_get	يسترد المحتوى من عناوين وثائق Roblox المسموح بها (مرجع API للوحة، وثائق المبدعين، واجهة برمجة التطبيقات السحابية، وأدلة تحسين الأداء). يدعم البحث بالكلمات المفتاحية ضمن المحتوى المسترد.
skill	يسترد المعرفة التفصيلية، وأفضل الممارسات، أو المواد المرجعية لمهارات محددة مثل تصحيح الأخطاء، ومحاكاة الأجهزة، وبحث الوثائق.
إدارة الجلسة
list_roblox_studios	يُدرج جميع حالات Studio المتصلة، بما في ذلك اسمها، معرفها، وحالتها النشطة. هذا مفيد عند فتح عدة نوافذ Studio.
set_active_studio	يحدد حالة Studio كحالة نشطة بحيث تستهدف جميع استدعاءات الأدوات لاحقًا تلك الحالة.

تفعيل خادم MCP في Studio

لتمكين خادم MCP في Studio:

افتح مساعد.
انقر على … ⟩ إدارة خوادم MCP.
قم بتشغيل تمكين Studio كخادم MCP.

بمجرد التمكين، يعرض لوحة الإعدادات خيار الاتصال السريع وتعليمات الإعداد للعملاء المختلفين. عند الاتصال بنجاح، تظهر مؤشرات خضراء تبين عدد العملاء المتصلين.

ربط عميلك

يمكنك ربط عميلك بخادم MCP في Studio باستخدام الاتصال السريع، أو تكوين JSON، أو أمر CLI.

استخدم الاتصال السريع إذا كان عميلك مدعومًا.
إذا لم يكن كذلك، استخدم تكوين JSON إذا كان عميلك يدعم ملفات تكوين MCP.
بخلاف ذلك، استخدم أمر CLI.

يعمل خادم MCP في Studio مع أي عميل يدعم stdio transport. بعد إضافة التكوين، اتبع وثائق عميلك لإكمال الإعداد، ثم أعد تشغيل العميل لتطبيق التغييرات.

يمكن أن تقرأ وتعدل عملاء MCP المحتوى في أماكن Roblox المفتوحة لديك. تأكد من الاتصال فقط بالعملاء الذين تثق بهم.

الاتصال السريع

يدعم الاتصال السريع العملاء التالية:

Antigravity
Codex CLI
Claude Code
Claude Desktop
Cursor
Gemini CLI
Visual Studio Code

للاتصال باستخدام الاتصال السريع:

انتقل إلى إعدادات المساعد ⟩ خوادم MCP.
قم بتوسيع قائمة الاتصال السريع لعرض العملاء المدعومين المثبتين على جهاز الكمبيوتر الخاص بك.
قم بتشغيل العميل الذي اخترته.

إذا لم يظهر العميل الذي تريده في قائمة الاتصال السريع، قم بتثبيته وأعد تشغيل Roblox Studio.

تكوين JSON

تدعم معظم عملاء MCP ملفات تكوين JSON. توضح الأمثلة التالية التكوينات الكاملة التي يمكنك استخدامها.

إذا كانت Roblox Studio هي خادم MCP الوحيد لديك، استخدم هذه التكوينات كما هي. إذا كنت تستخدم عدة خوادم MCP، انسخ إدخال Roblox_Studio وأضفه إلى القاموس mcpServers الموجود لديك.

قد تحتوي ملف mcp.json على إدخالات أخرى بالفعل. عند إضافة تكوين Roblox_Studio، تأكد من فصل كل إدخال بفاصلة. ستؤدي الفواصل المفقودة إلى JSON غير صالح وتمنع تحميل التكوين.

تختلف التكوينات حسب نظام التشغيل:

Windows
{
  "mcpServers": {
    "Roblox_Studio": {
      "command": "cmd.exe",
      "args": [
        "/c",
        "%LOCALAPPDATA%\\Roblox\\mcp.bat"
      ]
    }
  }
}

macOS
{
  "mcpServers": {
    "Roblox_Studio": {
      "command": "/Applications/RobloxStudio.app/Contents/MacOS/StudioMCP"
    }
  }
}

أمر CLI

تتطلب بعض عملاء MCP استخدام أمر CLI بدلاً من تكوين JSON. استخدم الأمر المناسب لنظام التشغيل الخاص بك:

Windows
cmd.exe /c %LOCALAPPDATA%\Roblox\mcp.bat

macOS
/Applications/RobloxStudio.app/Contents/MacOS/StudioMCP

استخدام عدة حالات من Studio

يمكنك ربط عميل MCP واحد بعدة حالات تعمل من Studio في نفس الوقت. يحدد الخادم تلقائيًا أي حالة يجب استخدامها بناءً على السياق (على سبيل المثال، إذا كنت تشير إلى تجربة محددة أو كائن يوجد فقط في تلك الحالة).

يمكنك تبديل الحالات يدويًا باستخدام list_roblox_studios و set_active_studio.

تحقق من اتصالك

بعد إعداد عميلك، تحقق من أن الاتصال يعمل في Roblox Studio:

افتح مساعد.
انقر على … ⟩ إدارة خوادم MCP.
تحت تمكين Studio كخادم MCP، تحقق من المؤشر الأخضر للتأكد من أن العميل قد اتصل بنجاح.

استكشاف الأخطاء

إذا لم يظهر الخادم، أو إذا كانت الأدوات غير متاحة:

أعد تشغيل كل من Roblox Studio وعميل MCP الخاص بك.
تحقق من أن الأمر أو مسار الثنائي صحيح وأن الملف موجود.
تحقق من بناء الجملة JSON الخاص بك. حتى الفاصلة أو القوس المفقود يمكن أن يمنع تحميل التكوين.