🎮 Roblox Studio Ultimate MCP Server

English | 日本語

Самый полный MCP-сервер (Model Context Protocol) для Roblox Studio. 41 инструмент для полного управления Studio из Claude Code или любого AI-ассистента с поддержкой MCP.

✨ Зачем это нужно

Стандартный MCP для Roblox Studio предоставляет только run_code, вынуждая вас манипулировать исходным кодом скриптов через строковые операции (gsub). Это приводит к:

❌ Ошибкам при сопоставлении с шаблоном
❌ Поврежденным операторам end)
❌ «Тихим» откатам при возврате скриптов к предыдущему состоянию
❌ Отсутствию проверки синтаксиса перед записью
❌ Часам, потраченным на простые правки

Этот MCP решает все эти проблемы.

🚀 Функции

Операции со скриптами (Меняют правила игры)

Инструмент	Описание
`getScript`	Получить полный исходный код
`setScript`	Заменить весь исходный код (с проверкой синтаксиса + авто-резервной копией)
`editScript`	Редактировать определенный диапазон строк (частичное редактирование!)
`insertCode`	Вставить код после определенной строки
`removeLines`	Удалить определенные строки
`replaceInScript`	Найти и заменить текст (обычный текст, безопасно)
`getLines`	Получить только определенный диапазон строк (легковесно)
`getFunctionList`	Список всех функций с номерами строк
`getScriptSummary`	Обзор: функции, зависимости, глобальные переменные
`listScripts`	Список всех скриптов в игре
`getAllScripts`	Получить все исходные коды скриптов сразу
`searchInScripts`	Поиск ключевого слова во всех скриптах
`getReferences`	Найти все использования переменной/функции
`getModuleDependencies`	Список зависимостей `require()`

Механизмы безопасности

Функция	Описание
🔒 Проверка синтаксиса	Автоматическая проверка перед записью. Отклоняет некорректный код.
💾 Авто-резервное копирование	Сохраняет предыдущую версию перед каждым редактированием (10 поколений)
🛑 Защита режима Play	Блокирует запись во время режима Play (предотвращает «тихие» откаты)
📝 UpdateSourceAsync	Использует ScriptEditorService для записи без конфликтов

Резервное копирование и восстановление

Инструмент	Описание
`restoreBackup`	Восстановить из авто-сохраненной резервной копии
`listBackups`	Список доступных резервных копий

Валидация

Инструмент	Описание
`checkSyntax`	Проверить синтаксис без записи
`verifyScript`	Проверить количество строк / длину исходного кода
`validateAllScripts`	Пакетная проверка синтаксиса всех скриптов

Операции с объектами (Instances)

Инструмент	Описание
`getTree`	Получить иерархию объектов
`getChildren`	Список дочерних элементов (легковесно)
`getProperty` / `setProperty`	Получить/установить свойства
`createInstance`	Создать новый объект
`deleteInstance`	Удалить объект
`cloneInstance`	Клонировать объект
`renameInstance`	Переименовать объект
`moveInstance`	Переместить к другому родителю
`findInstances`	Поиск объектов по имени/классу

Прочее

Инструмент	Описание
`runCode`	Выполнить код Luau (с захватом вывода)
`batch`	Выполнить несколько команд сразу
`getAttribute` / `setAttribute`	Операции с атрибутами
`getErrors` / `clearErrors`	Управление журналом ошибок
`undo` / `redo`	Операции отмены/повтора
`getSelection`	Получить текущее выделение
`getStudioInfo`	Получить информацию о Studio

📦 Установка

1. Клонирование и сборка

git clone https://github.com/YOUR_USERNAME/roblox-studio-ultimate-mcp.git
cd roblox-studio-ultimate-mcp
npm install
npm run build

2. Установка плагина для Studio

Скопируйте файл плагина в папку плагинов Roblox:

Mac:

cp plugin/UltimateMCP.rbxmx ~/Documents/Roblox/Plugins/

Windows:

copy plugin\UltimateMCP.rbxmx %LOCALAPPDATA%\Roblox\Plugins\

Или сгенерируйте его из исходного кода:

bash generate-plugin.sh

3. Включение HTTP в Studio

Откройте Roblox Studio, затем в командной строке (View → Command Bar):

game:GetService("HttpService").HttpEnabled = true

4. Регистрация в Claude Code

Добавьте в ваш ~/.claude.json в соответствующий проект:

{
  "mcpServers": {
    "roblox_ultimate": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/roblox-studio-ultimate-mcp/dist/index.js"],
      "env": {}
    }
  }
}

5. Перезапуск

Перезапустите Roblox Studio (чтобы загрузить плагин)
Перезапустите Claude Code (чтобы подключиться к MCP)

🏗️ Архитектура

Claude Code ←(stdio)→ MCP Server (Node.js) ←(HTTP)→ Studio Plugin (Luau)
                         Port 3002

MCP Server (src/index.ts): Преобразует вызовы инструментов MCP в HTTP-команды
Studio Plugin (plugin/RobloxMCP.lua): Опрашивает сервер, выполняет команды внутри Studio
Связь: HTTP-опрос (интервал 300 мс)

🔧 Использование с другими MCP-серверами

Этот сервер разработан для работы вместе с официальным MCP для Roblox Studio:

Вариант использования	Какой MCP
Чтение/запись скриптов	Ultimate (getScript/setScript)
Тестирование в игре	Official (start_stop_play)
Вывод консоли	Official (get_console_output)
Манипуляция объектами	Ultimate
Изменение свойств	Ultimate

📝 Реальный эффект

До появления этого MCP простое исправление одной строки в скрипте из 260 строк требовало:

run_code для получения исходного кода
gsub для сопоставления с шаблоном (часто не срабатывает)
run_code для записи обратно
Молитвы, чтобы все заработало
Повторения 3-5 раз

Теперь: editScript(path, 103, 103, "new code") → Готово. С первой попытки.

🤝 Участие в разработке

PR приветствуются! Особенно для:

Новых инструментов
Улучшенной обработки ошибок
Повышения производительности
Документации

📄 Лицензия

MIT

Roblox Studio Ultimate MCP Server