Vibe Blocks MCP для Roblox Studio

Подключает Roblox Studio к редакторам кода на базе ИИ (например, Cursor, Windsurf, Claude и т. д.) через протокол контекста модели (MCP), что позволяет разрабатывать игры с использованием ИИ в среде Roblox Studio.

Обзор

Этот проект состоит из двух основных частей:

1. Python MCP Server: сервер FastAPI, работающий локально. Он представляет действия Roblox Studio как инструменты через MCP (используя Server-Sent Events - SSE). Он может опционально взаимодействовать с API Roblox Open Cloud, если настроен.

2. Lua Companion Plugin: плагин Roblox Studio ( roblox_mcp_plugin/src/Plugin.server.lua ), который работает внутри Studio. Он опрашивает локальный сервер Python на предмет команд, выполняет их в контексте Studio (манипулируя экземплярами, считывая свойства, выполняя Luau) и отправляет результаты и логи Studio обратно на сервер.

Это позволяет ИИ-агенту, подключенному через MCP, понимать и взаимодействовать с вашим сеансом Roblox Studio в реальном времени.

Related MCP server: Tripo MCP Server

Функции

• Живое взаимодействие в студии:

  • Манипуляции со сценой: создание, удаление, клонирование, перемещение, масштабирование и установка свойств (включая PrimaryPart) объектов (частей, моделей, скриптов и т. д.) непосредственно в сцене Studio.

  • Проверка сцены: получение свойств объекта, вывод списка дочерних объектов, поиск экземпляров по классу или имени в Studio.

  • Скриптинг: Создание, редактирование и удаление скриптов/локальных скриптов. Выполнение произвольного кода Luau непосредственно в среде Studio и захват вывода/ошибок.

  • Окружающая среда: задайте свойства служб «Освещение» или «Рельеф».

  • Анимация: воспроизведение анимации на гуманоидах/контроллерах анимации.

  • NPC: Создавайте NPC, клонируя существующие шаблоны или вставляя их из идентификаторов активов.

  • Изменение дочерних элементов: применение изменений свойств к нескольким дочерним элементам объекта на основе фильтров.

  • Журналы Studio: извлечение последних журналов из окна вывода Studio.

• Интеграция с Roblox Open Cloud (необязательно — требуется ключ API):

  • Выполнение Luau (облако): запуск кода Luau в отдельной облачной среде (полезно для задач, не требующих прямого доступа к Studio).

  • Хранилища данных: список хранилищ, получение, установка и удаление записей «ключ-значение» в стандартных хранилищах данных.

  • Ресурсы: загрузка новых ресурсов (моделей, изображений, аудио) из локальных файлов.

  • Публикация: публикация текущей сохраненной или опубликованной версии места.

  • (Планируется): Получить сведения об активах, составить список активов пользователя.

Настраивать

1. Предварительные условия:

• Питон >= 3.10

• Менеджер пакетов uv ( Установить uv ). Это настоятельно рекомендуется для более быстрого управления зависимостями.

• Студия Роблокс

• (Необязательно) Ключ API Roblox для функций Open Cloud. Получите его из Roblox Creator Dashboard > Credentials . Вам понадобятся разрешения для API, которые вы собираетесь использовать (DataStore, Asset Upload, Publishing, Luau Execution и т. д.).

• (Необязательно) Ваш идентификатор вселенной Roblox и идентификатор целевого места (необходимы для функций Open Cloud).

2. Клонируйте репозиторий:

3. Установите зависимости:

Использование uv (рекомендуется):

Альтернативно, используя pip :

4. Настройте среду (необязательно — для облачных функций):

• Если вы планируете использовать инструменты Open Cloud (DataStores, Asset Upload, Publishing, Cloud Luau), скопируйте пример файла среды:

  cp .env.example .env

• Отредактируйте файл

  • Замените "YOUR_API_KEY_HERE" на ваш ключ API Roblox.

  • Замените 0 вместо ROBLOX_UNIVERSE_ID на идентификатор вашей вселенной.

  • Замените 0 для ROBLOX_PLACE_ID на идентификатор целевого места.

• Если вам не нужны функции Cloud, вы можете пропустить создание файла Сервер все равно будет работать, но инструменты, связанные с Cloud, вернут ошибку.

5. Установите плагин Companion в Roblox Studio:

• Установите Rojo: Если у вас не установлен Rojo, следуйте инструкциям на веб-сайте Rojo .

• Создайте плагин (необязательно): Перейдите в каталог roblox_mcp_plugin в терминале и запустите:

  rojo build default.project.json --output VibeBlocksMCP_Companion.rbxm

  Это создаст файл VibeBlocksMCP_Companion.rbxm или вы можете использовать файл, предоставленный в репозитории.

• Установить в студии:

  • Найдите папку плагинов Roblox Studio:

    • Windows: %LOCALAPPDATA%\Roblox\Plugins

    • macOS: ~/Documents/Roblox/Plugins (Возможно, вам придется нажать Cmd+Shift+G в Finder и вставить путь, чтобы перейти туда, или нажать «Папка плагинов» в Roblox Studio).

  • Переместите или скопируйте сгенерированный файл VibeBlocksMCP_Companion.rbxm в эту папку плагинов.

• Перезапустите Roblox Studio: теперь плагин должен загружаться автоматически при открытии Studio.

  • Примечание: плагин опрашивает http://localhost:8000/plugin_command . Если вы измените порт сервера, вам нужно будет обновить переменную SERVER_URL в верхней части скрипта Lua ( roblox_mcp_plugin/src/Plugin.server.lua ) и пересобрать плагин.

6. Запустите сервер Python:

• Откройте терминал в корневом каталоге проекта.

• Сделайте скрипт сервера исполняемым (если вы этого еще не сделали):

  chmod +x server.sh

• Запускаем сервер:

  ./server.sh

• Сервер запустится, при необходимости проверит/установит uvicorn и зарегистрирует, что он работает на http://localhost:8000 .

• Держите это окно терминала открытым во время использования сервиса.

7. Подключитесь из MCP-клиента (например, курсора):

• Эта служба работает с любым клиентом ИИ, который поддерживает протокол контекста модели (MCP) через отправленные сервером события (SSE), например, Cursor, Windsurf или потенциально будущие версии Claude Desktop.

• Пример использования курсора:

  • Перейдите в File > Settings > MCP (или Code > Settings > MCP на Mac).

  • Нажмите «Добавить новый глобальный сервер MCP».

  • Введите URL-адрес SSE: http://localhost:8000/sse (не забудьте включить завершающий /sse ).

  • Возможно, вам придется отредактировать файл mcp.json GXP8

• Теперь клиент должен обнаружить источник инструмента «Vibe Blocks MCP» и его доступные инструменты.

Использование

После запуска сервера, установки плагина в Studio и подключения вашего клиента MCP вы сможете взаимодействовать с сеансом Studio через ИИ.

Обратитесь к агенту (упомянув @-инструменты, если это необходимо вашему клиенту, например, list_children ) и попросите его выполнить действия.

Примеры подсказок:

• «Создайте ярко-красную деталь с именем «Пол» в рабочей области. Задайте ее размер (100, 2, 100) и положение (0, -1, 0). Закрепите ее».

• «Удалить объект с именем 'Workspace.OldPlatform'»

• «Что такое свойство Position у Workspace.SpawnLocation?»

• «Выведите список дочерних элементов ServerScriptService».

• «Найти все экземпляры с className 'Script' в ServerScriptService».

• "Выполнить этот скрипт в Studio: print(game:GetService('Lighting').ClockTime) "

• «Установите свойство ClockTime для Lighting на 14».

• «Клонируйте 'ReplicatedStorage.Templates.EnemyNPC' и назовите клон 'Guard1'. Сделайте его родителем Workspace».

• «Заставьте модель с именем «Workspace.Guard1» воспроизвести анимационный ресурс 123456789».

• «Измените все дочерние элементы Workspace.DecorationFolder с className Part, чтобы задать для них Material значение Neon».

• (Пример облака) «Загрузите './assets/MyCoolModel.fbx' как модель с именем 'Cool Character Model'».

• (Пример облака) «Получить значение для ключа 'player_123_score' из хранилища данных 'PlayerData'».

• (Пример облака) «Опубликовать текущее место».

• «Покажите мне последние логи из Studio».

Доступные инструменты

(Инструменты взаимодействуют либо напрямую с плагином Studio, либо с API Roblox Open Cloud)

Инструменты плагина Studio (интерактивное взаимодействие):

• get_property : извлекает значение определенного свойства из объекта в Studio.

• list_children : Извлекает прямых дочерних элементов объекта в Studio.

• find_instances : находит экземпляры в указанном корне на основе имени класса или имени, содержащего текст в Studio.

• create_instance : создает новый экземпляр (деталь, модель, скрипт и т. д.) в Studio.

• delete_instance : Удаляет объект из сцены Studio.

• set_property : устанавливает определенное свойство объекта в Studio (использует строку JSON в качестве значения).

• set_primary_part : Устанавливает свойство PrimaryPart модели.

• move_instance : Перемещает объект (модель или базовую часть) на новое место в Studio.

• clone_instance : Клонирует существующий объект в Studio.

• create_script : создает новый экземпляр Script или LocalScript с предоставленным кодом в Studio.

• edit_script : Редактирует исходный код существующего скрипта или локального скрипта в Studio.

• delete_script : удаляет существующий экземпляр Script или LocalScript в Studio.

• set_environment : Устанавливает свойства служб окружения (освещение или ландшафт) в Studio.

• spawn_npc : Создает NPC в Studio, либо вставляя модель из идентификатора актива, либо клонируя существующую шаблонную модель.

• play_animation : Загружает и воспроизводит анимацию на Humanoid или AnimationController целевого объекта в Studio.

• execute_luau_in_studio : выполняет произвольный скрипт Luau в сеансе LIVE Studio через плагин и фиксирует выходные/возвращаемые значения/ошибки.

• modify_children : находит прямых потомков родителя, соответствующих необязательным фильтрам (имя/класс), и устанавливает для них указанное свойство.

• get_studio_logs : извлекает последние журналы, полученные из окна вывода Roblox Studio через плагин.

Инструменты Open Cloud API (необязательно — требуется настройка

• execute_luau_in_cloud : выполняет произвольный скрипт Luau через API Roblox Cloud (работает в отдельной облачной среде, а не в Live Studio).

• list_datastores_in_cloud : выводит список стандартных хранилищ данных через Cloud API.

• get_datastore_value_in_cloud : получает значение записи из стандартного хранилища данных через Cloud API.

• set_datastore_value_in_cloud : устанавливает значение для записи в стандартном хранилище данных через Cloud API.

• delete_datastore_value_in_cloud : удаляет запись из стандартного хранилища данных через Cloud API.

• upload_asset_via_cloud : загружает файл из локальной системы как новый актив Roblox через Cloud API.

• publish_place_via_cloud : публикует указанное место через Cloud API.

• get_asset_details_via_cloud : (не реализовано) Получает сведения о конкретном активе через API облака.

• list_user_assets_via_cloud : (не реализовано) Перечисляет активы, принадлежащие аутентифицированному пользователю через API облака.

• send_chat_via_cloud : отправляет сообщение в игровой чат через Cloud API (execute_luau).

• teleport_player_via_cloud : Телепортирует игрока через Cloud API (execute_luau).

Внутренние/очередные инструменты:

• queue_studio_command : (Низкоуровневый) Ставит в очередь один словарь необработанных команд для плагина Studio.

• queue_studio_command_batch : (Низкоуровневый) Ставит в очередь пакет необработанных словарей команд для плагина Studio.

Поиск неисправностей

• Сервер не запускается: Убедитесь, что Python и uv установлены правильно. Проверьте терминал на наличие сообщений об ошибках. Убедитесь, что зависимости установлены ( uv pip sync pyproject.toml ).

• Плагин не подключается: Убедитесь, что сервер Python запущен. Дважды проверьте, что SERVER_URL в скрипте плагина Lua соответствует адресу сервера и порту (по умолчанию http://localhost:8000/plugin_command ). Проверьте окно вывода Studio на наличие ошибок из скрипта плагина.

• Клиент MCP не подключается: убедитесь, что сервер запущен. Убедитесь, что URL-адрес SSE ( http://localhost:8000/sse ) введен правильно в настройках клиента MCP.

• Сбой в работе Cloud Tools: убедитесь, что вы создали файл .env с действительным API Key, Universe ID и Place ID. Убедитесь, что ваш API-ключ имеет необходимые разрешения для конкретных Cloud API, которые вы пытаетесь использовать.

• Разрешения: Для корректной работы сопутствующего плагина требуются разрешения на внедрение скриптов, если вы загружаете его из локального файла вместо его корректной установки.