Vibe Blocks MCP

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 в реальном времени.

Функции

• Живое взаимодействие в студии:
  • Манипуляции со сценой: создание, удаление, клонирование, перемещение, масштабирование и установка свойств (включая 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
• Отредактируйте файл .env :
  • Замените "YOUR_API_KEY_HERE" на ваш ключ API Roblox.
  • Замените 0 вместо ROBLOX_UNIVERSE_ID на идентификатор вашей вселенной.
  • Замените 0 для ROBLOX_PLACE_ID на идентификатор целевого места.
• Если вам не нужны функции Cloud, вы можете пропустить создание файла .env . Сервер все равно будет работать, но инструменты, связанные с 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 (необязательно — требуется настройка .env ):

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