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

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

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

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

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

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

يعمل الخادم كعملية محلية على جهازك ويتواصل مع عميل الذكاء الاصطناعي باستخدام نقل stdio، الذي يستخدم تدفقات الإدخال/الإخراج القياسية. يتم بدء جميع الإجراءات من خلال عميل الذكاء الاصطناعي الخاص بك، الذي يرسل بعد ذلك طلبًا عبر هذه القناة لتنفيذ الإجراءات داخل جلسة 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 للمحرك، توثيق المبدعين، API السحابي، أدلة تحسين الأداء). يدعم البحث عن الكلمات الرئيسية داخل المحتوى المسترجع.
skill	يسترجع المعرفة التفصيلية، وأفضل الممارسات، أو المواد المرجعية لمهارات معينة مثل تصحيح الأخطاء، محاكاة الأجهزة، والبحث في التوثيق.
إدارة الجلسات
list_roblox_studios	يسرد جميع مثيلات Studio المتصلة، بما في ذلك اسمها، معرف مثيل Studio، ومعرف المكان. يتم سرد الأماكن المحلية التي لا تحتوي على معرف مكان بالاسم فقط. مفيد عندما تكون هناك نوافذ Studio متعددة مفتوحة؛ إذا كانت هناك مثيلتان مفتوحتان من Studio تشتركان في نفس الاسم، فإن معرف المكان يساعدك على التمييز.

كل استدعاء أداة يأخذ معلمة studio_id التي تحدد مثيل Studio المستهدف، لذا تتوجه الوكلاء إلى مثيلات Studio بشكل صريح بدلاً من الاعتماد على حالة الجلسة. استخدم list_roblox_studios للبحث عن معرف المثيل الذي تريده.

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

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

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

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

ربط عميلك

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

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

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

يمكن لعملاء 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 في نفس الوقت. يتضمن كل استدعاء أداة studio_id الذي يحدد مثيل Studio المستهدف، مما يجعل سير العمل مع عدة مثيلات من Studio ووكالات أو عملاء متعددة موثوقًا.

استخدم list_roblox_studios لسرد المثيلات المتصلة بأسمائها، ومعرفات مثيل Studio، ومعرفات الأماكن. ثم مرر معرف المثيل الذي تريده كـ studio_id في الاستدعاءات اللاحقة.

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

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

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

استكشاف الأخطاء وإصلاحها

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

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