⚡ Universal Roblox AI Studio — 자율 멀티 모드 기능 MCP 플랫폼

Universal Roblox AI Studio는 Roblox Studio를 외부 AI 코딩 어시스턴트(Claude Desktop, Cursor, Antigravity, VS Code 등)를 위한 AI-Native, 자율적이고 양방향 개발 플랫폼으로 전환하는 차세대 Model Context Protocol(MCP) 런타임입니다.

📖 목차

• 🌟 핵심 기능

• 🏛️ 아키텍처 및 11개 특화 프로바이더

• 🧱 계층 구조 및 컴포넌트 우선 구축("+ 기호" 패러다임)

• 🛡️ 제한 및 공식 MCP 라우팅 트리(제한 분류 체계)

• 🧠 자가 치유 진단 엔진

• 🛠️ 포괄적인 MCP 도구 목록(63+ 도구)

• 🚀 빠른 설치 및 시작

• 🤖 AI 클라이언트 구성(Claude Desktop / Cursor)

• 📊 실시간 원격 측정 및 Studio 인터페이스

• 🧪 테스트 및 검증

🌟 핵심 기능

1. 63개 이상의 일급 범용 MCP 도구: DataModel 계층 구조, Instance 수명 주기, Luau 스크립트 관리, PBR 머티리얼, Voxel Terrain, Playtest 시뮬레이션, 3D Generative AI 및 가상 하드웨어 입력.

2. 공식 Roblox Studio MCP(StudioMCP.exe) 로컬 통합: Roblox의 공식 MCP 클라이언트(%LOCALAPPDATA%\Roblox\Versions\...\StudioMCP.exe 및 mcp.bat)를 자동으로 탐지하여 제한된 3D/Asset/Playtest 명령을 공식 엔진으로 직접 라우팅합니다.

3. 컴포넌트 및 계층 구조 우선 구축(VisualConstructionEngine): 모든 것을 거대한 스크립트로 생성하는 대신, Studio Explorer의 +(Insert Object) 로직으로 레이어별 물리적 객체, 제약 조건(Constraints), 조명, 파티클 및 사운드를 생성합니다.

4. 고급 애니메이션 및 하드웨어 보정(AnimationAuthoringEngine): R15/R6 리그 포즈(Motor6D), 관절 안전성, KeyframeSequence 생성 및 도구가 캐릭터 손에 올바르게 위치하도록 하는 Tool.Grip 보정.

5. 자가 치유 오류 진단(DiagnosticsEngine): Luau 엔진 오류(C0 is read only, attempt to index nil, HttpDisabled 등)를 즉시 분석하여 AI 어시스턴트에게 준비된 수정 코드(suggestedFix)와 권장 사항을 제공합니다.

6. 4단계 동적 기능 해석(UniversalCapabilityEngine): 명령을 직접 도구, 워크플로 템플릿, 컴파일된 프리미티브 또는 자율 플래너로 해석합니다.

7. 양방향 안전 HTTP/HTTPS 브리지: Studio 플러그인과 Node.js 서버 간 실시간 이벤트 수신(LogService, 오류, 선택 변경) 및 ChangeHistoryService Undo/Redo(Ctrl+Z) 안전성.

🏛️ 아키텍처 및 11개 특화 프로바이더

Universal Roblox MCP는 단일 정적 도구 목록 대신 11개의 특화 프로바이더(IProvider)와 중앙 기능 라우터(CapabilityRouter) 를 통해 작동합니다:

                      ┌────────────────────────────────────────────────────────┐
                      │             AI Client (Claude / Cursor)                │
                      └──────────────────────────┬─────────────────────────────┘
                                                 │ MCP (JSON-RPC)
                                                 ▼
                      ┌────────────────────────────────────────────────────────┐
                      │         Universal Roblox Studio MCP Router             │
                      │           (UniversalCapabilityEngine)                  │
                      └───────┬──────────────────┬───────────────────┬─────────┘
                              │                  │                   │
         ┌────────────────────┴───┐     ┌────────┴────────┐   ┌──────┴────────────────┐
         │ 1. Embedded Plugin     │     │ 2. Official MCP │   │ 3-11. Specialized     │
         │    (HTTP/HTTPS Bridge) │     │ (StudioMCP.exe) │   │       Domain Engines  │
         └────────────┬───────────┘     └────────┬────────┘   └──────┬────────────────┘
                      │                          │                   │
                      │ Polling RPC              │ Stdio / WS        │ Logic & Templates
                      ▼                          ▼                   ▼
    ┌──────────────────────────────────────────────────────────────────────────────────┐
    │                               Roblox Studio Session                              │
    │  • DataModel Tree    • Luau ScriptEditor    • Viewport Framebuffer  • Simulation │
    └──────────────────────────────────────────────────────────────────────────────────┘

11개 프로바이더 레이어:

1. EmbeddedPluginProvider: Roblox Studio 내부의 로컬 플러그인과 통신하여 36개의 핵심 프리미티브를 관리합니다.

2. OfficialRobloxMCPProvider: Roblox의 공식 StudioMCP.exe 바이너리에 연결하여 제한된 3D, Asset 및 Playtest 명령을 실행합니다.

3. ModelingProvider: 3D 메시, PBR 머티리얼 및 절차적 파트 조립을 조정합니다.

4. AnimationProvider: 애니메이션 파트, 플레이어 컨트롤 및 리그 포즈를 관리합니다.

5. LuauProvider: Luau 정적 분석, 구문 검증 및 안전한 코드 실행을 제공합니다.

6. WorkflowProvider: 복합 게임 시스템(낮/밤, Leaderstats, 섬 생성기 등)을 템플릿으로 적용합니다.

7. AssetProvider: Creator Store 및 Cloud 인벤토리에서 모델, 사운드 및 시각적 에셋을 가져오거나 추가합니다.

8. TestingProvider: 자동 시나리오 테스트, 가상 키보드/마우스 입력 및 검증 프로세스를 관리합니다.

9. DiagnosticsProvider: Studio 출력을 모니터링하고, 근본 원인 분석을 수행하며 안전한 수리를 제안합니다.

10. ObservationProvider: Viewport 화면 캡처 및 시각적 검사를 관리합니다.

11. DesignProvider: 공간 미학, 색상 조화 및 디자인 규칙을 감독합니다.

🧱 계층 구조 및 컴포넌트 우선 구축("+ 기호" 패러다임)

Roblox Studio의 숙련된 개발자는 모든 것을 하나의 거대한 Luau 스크립트로 절차적으로 생성하지 않습니다. 대신 컴포넌트 및 계층 구조 기반(Component-Driven) 개발을 수행합니다. 우리 시스템은 5단계 산업 표준 레이어로 객체를 생성합니다:

[Katman 1: Mekansal İskelet]  ───▶ Model / Folder / Frame / Parts / Meshes / PrimaryPart
            ↓
[Katman 2: Görsel & Duyusal]  ───▶ PBR Materials / PointLight / Particles / Sounds / SurfaceGui
            ↓
[Katman 3: Etkileşim & Fizik] ───▶ ProximityPrompt / HingeConstraint / WeldConstraint / Attachments
            ↓
[Katman 4: Animasyon & Donanım]──▶ KeyframeSequence / Motor6D Poses / Tool Grip Calibration
            ↓
[Katman 5: Ayrık Mantık]      ───▶ Sadece sinyalleri dinleyen hafif ve modüler Luau Controller

준비된 컴포넌트 템플릿(component_compose):

• interactive_door: 나무 프레임(Frame), 힌지(HingePart), 도어 패널(DoorPanel), ProximityPrompt, 개방 사운드(Sound), TweenService 컨트롤러 및 사용자 지정 Attributes(IsOpen, OpenAngle).

• collectible_coin: 회전하는 원통형 코인, 금속 머티리얼, 황금 PointLight, Sparkles, 수집 사운드 및 CollectionService 태그.

• equippable_weapon: 보정된 Tool.Grip, RightGripAttachment, Handle, 휘두르는 사운드, 타격 흔적(Trail) 및 활성화 스크립트.

• interactive_chest: 고정된 상자 본체, 열리는 뚜껑(ChestLid), HingeConstraint, ProximityPrompt, 황금 광채 및 LootTable 속성.

• streetlamp_fixture: 금속 기둥, 유리 램프 헤드, PointLight, SpotLight, Neon 머티리얼 및 낮/밤 자동 조명 센서.

• teleporter_pad: 순간이동 플랫폼, 파티클 빔(ParticleEmitter & Beam), 텔레포트 사운드 및 목표 좌표.

• dialogue_npc: 포즈가 적용된 R15/R6 캐릭터, BillboardGui 이름 라벨, 대화 ProximityPrompt 및 대화 트리.

🛡️ 제한 및 공식 MCP 라우팅 트리(제한 분류 체계)

Roblox 엔진은 보안상의 이유로 타사 플러그인에 일부 API(RobloxSecurity, RobloxScriptSecurity, SensitiveInput, Capture)를 제한합니다. 우리 시스템은 RestrictedCapabilityRegistry 를 통해 이러한 제한을 자동으로 인식하고 공식 StudioMCP.exe 프록시로 직접 라우팅합니다:

RESTRICTED / OFFICIAL-ONLY (12 Kategori)
├── 1. RobloxSecurity                   ──▶ official-roblox-mcp (execute_luau / search_game_tree)
├── 2. RobloxScriptSecurity             ──▶ official-roblox-mcp (script_grep / execute_luau)
├── 3. Internal Studio APIs             ──▶ official-roblox-mcp (get_studio_state, list_roblox_studios)
├── 4. Internal Engine APIs             ──▶ official-roblox-mcp (generate_mesh / get_console_output)
├── 5. Internal Plugin APIs             ──▶ official-roblox-mcp (internal plugin manager)
├── 6. Protected Debug APIs             ──▶ official-roblox-mcp (get_console_output)
├── 7. Protected Studio Control APIs    ──▶ official-roblox-mcp (start_stop_play [Play/Run/Stop])
├── 8. Missing Sandbox Capabilities     ──▶ official-roblox-mcp (screen_capture, keyboard/mouse input)
├── 9. Restricted Asset APIs            ──▶ official-roblox-mcp (generate_mesh, generate_material, search_asset)
├── 10. Restricted HTTP APIs            ──▶ official-roblox-mcp (Cloud Auth HTTP)
├── 11. Internal Network APIs           ──▶ official-roblox-mcp (Replication diagnostics)
└── 12. Provider-Specific Capabilities  ──▶ official-roblox-mcp (subagent, execute_luau)

🧠 자가 치유 진단 엔진

AI 모델은 코드를 실행할 때 일반적인 Roblox API 오류에 부딪힐 수 있습니다. DiagnosticsEngine은 이러한 오류를 포착하여 AI에게 바로 작동하는 솔루션을 제공합니다:

🛠️ 포괄적인 MCP 도구 목록(63+ 도구)

1. 시각적 구축 및 애니메이션 도구

• component_compose: 준비된 템플릿으로 완전한 컴포넌트(문, 상자, 코인, NPC 등)를 구축합니다.

• component_template_list: 사용 가능한 모든 컴포넌트 템플릿과 계층 구조 트리를 나열합니다.

• hierarchy_scaffold: Studio 프로젝트를 전문적인 산업 표준 폴더로 구성합니다.

• tool_grip_calibrate: 무기와 아이템의 캐릭터 손 쥐는 각도(Tool.Grip)를 자동으로 보정합니다.

• rig_pose_and_animate: R15/R6 캐릭터 관절(Motor6D)을 안전하게 포즈합니다.

2. 공식 Roblox MCP 도구(StudioMCP.exe 통합)

• generate_mesh: 자연어 프롬프트에서 Roblox Cloud AI 3D 메시를 생성합니다.

• generate_material: 자연어 프롬프트에서 PBR 머티리얼과 텍스처를 생성합니다.

• generate_procedural_model: 절차적 파트 조립을 생성합니다.

• search_asset 및 insert_asset: Creator Store 및 Cloud 라이브러리에서 에셋을 검색하고 배치합니다.

• screen_capture: Studio 3D Viewport에서 고해상도 스크린샷을 캡처합니다.

• start_stop_play: 게임을 물리적으로 시작(Play/Run)하거나 편집 모드로 복귀(Stop)합니다.

• get_studio_state: Studio 세션, 열린 문서 및 활성 시뮬레이션 모드를 조회합니다.

• list_roblox_studios 및 set_active_studio: 실행 중인 Studio 창을 나열하고 활성 창을 선택합니다.

• character_navigation: 시뮬레이션 중 캐릭터를 3D 세계 좌표로 이동시킵니다.

• user_keyboard_input 및 user_mouse_input: 시뮬레이션에 하드웨어 수준의 키 및 마우스 클릭을 주입합니다.

• script_read, multi_edit, script_search, script_grep: Studio Script Editor를 통한 로컬 다중 파일 편집 및 검색.

• subagent 및 execute_luau: Roblox의 로컬 하위 에이전트와 Luau 코드 실행 엔진을 실행합니다.

3. 핵심 DataModel 및 프리미티브 도구

• studio_info, studio_get_tree, studio_search, studio_inspect: DataModel 계층 구조 스캔 및 심층 속성 검사.

• instance_create, instance_delete, instance_clone, instance_reparent, instance_rename, instance_move: 객체 수명 주기 및 3D 위치 지정.

• property_get, property_set, property_get_all: 자동 Luau 타입 변환 속성 읽기/쓰기.

• attribute_get, attribute_set, attribute_delete, attribute_get_all: 속성(Attribute) 관리.

• script_get_source, script_set_source, script_patch_source, script_search_code: 스크립트 소스 읽기, 줄 단위 패치 및 코드 검색.

• selection_get, selection_set, selection_add, selection_clear: Studio Explorer 선택 제어.

• output_get, output_get_errors, output_clear: 출력 로그 및 오류 캡처.

• terrain_fill_block, terrain_fill_ball, terrain_clear: Voxel Terrain 생성 및 정리.

• batch_execute: 단일 작업에서 원자적 다중 명령 실행(Undo/Redo 웨이포인트 지원).

🚀 빠른 설치 및 시작

1. 요구 사항

• Node.js: v18.0.0 이상(v20+ / v24 권장).

• Roblox Studio: Windows 또는 macOS에 설치.

2. 저장소 클론 및 빌드

git clone <repo-url>
cd "Roblox Studio MCP"
npm install
npm run build

3. Roblox Studio 플러그인 설치

다음 두 가지 방법 중 하나로 플러그인을 설치할 수 있습니다:

방법 A: 준비된 플러그인 파일 복사 (권장)

npm run bundle:plugin 및 node scripts/build-rbxmx.js 명령을 실행하세요 (또는 컴파일된 파일을 복사하세요):

• Windows: plugin-build\RobloxUniversalMCP.rbxmx 파일을 %LOCALAPPDATA%\Roblox\Plugins\ 디렉터리에 복사하세요.

• macOS: plugin-build/RobloxUniversalMCP.rbxmx 파일을 ~/Library/Application Support/Roblox/Plugins/ 디렉터리에 복사하세요.

방법 B: Studio 내에서 수동 설치

1. Roblox Studio에서 아무 Place나 엽니다.

2. plugin-build/RobloxUniversalMCP.luau 파일의 내용을 Script 안에 붙여넣습니다.

3. Script를 마우스 오른쪽 버튼으로 클릭하고 "Save as Local Plugin..." 옵션을 선택합니다.

4. Home > Game Settings > Security 섹션에서 "Allow HTTP Requests" 옵션을 활성화합니다.

🤖 AI 클라이언트 구성 (모든 컴퓨터에서의 범용 설치)

어떤 컴퓨터에서든 고정적이고 휴대 가능하게 실행하기 위해 3가지 범용 방법을 제공합니다:

🌟 방법 1: 글로벌 CLI 등록 (권장 — 모든 컴퓨터에서 한 줄로!)

프로젝트 폴더에서 한 번 npm link를 실행하여 시스템을 글로벌 명령으로 등록하세요:

npm run build
npm link

이제 Claude Desktop, Cursor 또는 모든 MCP 클라이언트에서 파일 경로를 입력할 필요가 없습니다:

Claude Desktop (claude_desktop_config.json)

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "roblox-universal-studio": {
      "command": "roblox-studio-mcp"
    }
  }
}

🚀 방법 2: Cursor / VS Code 범용 작업 영역 (${workspaceFolder})

프로젝트를 Cursor 또는 VS Code에서 열면 .cursor/mcp.json 또는 .vscode/mcp.json 파일에 추가하세요. 어떤 컴퓨터에서 열든 ${workspaceFolder}가 자동으로 감지됩니다:

{
  "mcpServers": {
    "roblox-universal-studio": {
      "command": "node",
      "args": [
        "${workspaceFolder}/dist/index.js"
      ]
    }
  }
}

📁 방법 3: 직접 파일 경로를 지정하여 실행

글로벌 CLI 대신 컴파일된 dist/index.js 파일을 직접 호출하려면:

{
  "mcpServers": {
    "roblox-universal-studio": {
      "command": "node",
      "args": [
        "<PROJE_KLASORUNUZ_TAM_YOLU>/dist/index.js"
      ]
    }
  }
}

(예: Windows: C:\\Projects\\Roblox-Studio-MCP\\dist\\index.js | macOS: /Users/username/Projects/Roblox-Studio-MCP/dist/index.js)

📊 실시간 원격 측정 및 Studio 인터페이스

플러그인이 설치되면 Roblox Studio 내에 전용 **DockWidget (DiagnosticsView)**이 열립니다:

• Plugin Runtime: ONLINE / STANDALONE

• MCP Bridge: CONNECTED (녹색) / DISCONNECTED (빨간색)

• Capabilities Discovered: 80+ Live Capabilities (모든 제공자 및 하위 시스템)

• Low-Level Tools: 57 Primitive Tools

• High-Level Workflows: 19 Composite Workflows

• Total Universal Tools: 76 Universal Tools

• Active Mode: CHAT | OBSERVE | BUILD | PLAYTEST | AUTONOMOUS

🧪 테스트 및 검증

전체 테스트 패키지를 실행하려면:

npm test

테스트 출력:

✔ Tool Registry contains all universal tools
✔ HTTP Bridge Status returns disconnected when no session is active
✔ HTTP Bridge Handshake registers studio session
✔ Executing a command dispatches over polling RPC and resolves with response
✔ 11 Providers are registered and operational in ProviderRegistry
✔ Universal Capability Engine resolves across 4-tier hierarchy
✔ MultiModeEngine handles operating mode transitions and permissions
✔ Live Dashboard endpoint returns comprehensive real-time telemetry
✔ Visual Construction Engine lists rich archetypes and templates
✔ Animation Authoring Engine calibrates tool grips and keyframe sequences

📄 라이선스

이 프로젝트는 MIT 라이선스 하에 라이선스가 부여되었습니다. Roblox Studio와 함께하는 AI 네이티브 게임 개발 경험을 즐기세요! 🎮⚡