Vibe Blocks MCP

Roblox Studio용 Vibe Blocks MCP

모델 컨텍스트 프로토콜(MCP)을 통해 Roblox Studio를 AI 코딩 편집기(Cursor, Windsurf, Claude 등)에 연결하여 Roblox Studio 환경 내에서 AI 지원 게임 개발을 가능하게 합니다.

개요

이 프로젝트는 두 가지 주요 부분으로 구성됩니다.

1. Python MCP 서버: 로컬에서 실행되는 FastAPI 서버입니다. Roblox Studio 작업을 MCP(서버 전송 이벤트, SSE)를 통해 도구로 노출합니다. 구성된 경우 Roblox Open Cloud API와 선택적으로 상호 작용할 수 있습니다.
2. Lua Companion 플러그인: Studio 내부에서 실행되는 Roblox Studio 플러그인( roblox_mcp_plugin/src/Plugin.server.lua )입니다. 로컬 Python 서버에서 명령을 폴링하여 Studio 컨텍스트에서 실행하고(인스턴스 조작, 속성 읽기, Luau 실행), 결과와 Studio 로그를 서버로 다시 전송합니다.

이를 통해 MCP를 통해 연결된 AI 에이전트가 라이브 Roblox Studio 세션을 이해하고 상호 작용할 수 있습니다.

특징

• 라이브 스튜디오 상호작용:
  • 장면 조작: Studio 장면에서 직접 객체(파트, 모델, 스크립트 등)의 속성(PrimaryPart 포함)을 생성, 삭제, 복제, 이동, 크기 조정 및 설정합니다.
  • 장면 검사: Studio 내에서 객체 속성을 가져오고, 자식 객체를 나열하고, 클래스나 이름으로 인스턴스를 찾습니다.
  • 스크립팅: 스크립트/로컬 스크립트를 생성, 편집 및 삭제합니다. Studio 환경 내에서 임의의 Luau 코드를 직접 실행하고 출력/오류를 캡처합니다.
  • 환경: 조명이나 지형 서비스의 속성을 설정합니다.
  • 애니메이션: Humanoids/AnimationControllers에서 애니메이션을 재생합니다.
  • NPC: 기존 템플릿을 복제하거나 자산 ID에서 삽입하여 NPC를 생성합니다.
  • 자식 수정: 필터를 기반으로 개체의 여러 자식에 속성 변경 사항을 적용합니다.
  • 스튜디오 로그: 스튜디오 출력 창에서 최근 로그를 검색합니다.
• Roblox Open Cloud 통합(선택 사항 - API 키 필요):
  • 루아우 실행(클라우드): 별도의 클라우드 환경에서 루아우 코드를 실행합니다(라이브 Studio 액세스가 필요하지 않은 작업에 유용함).
  • DataStore: 표준 DataStore에서 키-값 항목을 나열하고, 가져오고, 설정하고, 삭제합니다.
  • 자산: 로컬 파일에서 새로운 자산(모델, 이미지, 오디오)을 업로드합니다.
  • 게시: 현재 저장되었거나 게시된 장소 버전을 게시합니다.
  • (계획됨): 자산 세부 정보를 가져오고, 사용자 자산을 나열합니다.

설정

1. 필수 조건:

• 파이썬 >= 3.10
• uv 패키지 관리자( uv 설치 ). 종속성 관리를 더 빠르게 하려면 이 기능을 사용하는 것이 좋습니다.
• 로블록스 스튜디오
• (선택 사항) Open Cloud 기능을 위한 Roblox API 키. Roblox 크리에이터 대시보드 > 사용자 인증 정보 에서 키를 받으세요. 사용하려는 API(데이터 저장소, 애셋 업로드, 게시, 루아우 실행 등)에 대한 권한이 필요합니다.
• (선택 사항) Roblox Universe ID와 대상 장소 ID(Open Cloud 기능에 필요).

2. 저장소 복제:

지엑스피1

3. 종속성 설치:

uv 사용(권장):

또는 pip 사용하면:

4. 환경 구성(선택 사항 - 클라우드 기능의 경우):

• Open Cloud 도구(DataStores, Asset Upload, Publishing, Cloud Luau)를 사용하려는 경우 예제 환경 파일을 복사하세요.
  cp .env.example .env
• .env 파일을 편집합니다.
  • "YOUR_API_KEY_HERE" Roblox API 키로 바꾸세요.
  • ROBLOX_UNIVERSE_ID 의 0 귀하의 Universe ID로 바꾸세요.
  • ROBLOX_PLACE_ID 의 0 대상 장소 ID로 바꾸세요.
• 클라우드 기능이 필요하지 않으면 .env 파일 생성을 건너뛸 수 있습니다. 서버는 계속 실행되지만 클라우드 관련 도구는 오류를 반환합니다.

5. Roblox Studio에 Companion 플러그인을 설치하세요:

• Rojo 설치: Rojo가 설치되어 있지 않은 경우 Rojo 웹사이트 의 지침을 따르세요.
• 플러그인 빌드(선택 사항): 터미널에서 roblox_mcp_plugin 디렉토리로 이동하여 다음을 실행합니다.
  rojo build default.project.json --output VibeBlocksMCP_Companion.rbxm
  이렇게 하면 VibeBlocksMCP_Companion.rbxm 파일이 생성되거나 저장소에 제공된 파일을 사용할 수 있습니다.
• Studio에 설치:
  • Roblox Studio 플러그인 폴더를 찾으세요.
    • 윈도우: %LOCALAPPDATA%\Roblox\Plugins
    • macOS: ~/Documents/Roblox/Plugins (Finder에서 Cmd+Shift+G 사용하여 경로를 붙여넣어 이동하거나 Roblox Studio에서 플러그인 폴더를 클릭해야 할 수도 있습니다).
  • 생성된 VibeBlocksMCP_Companion.rbxm 파일을 이 플러그인 폴더로 이동하거나 복사합니다.
• Roblox Studio를 다시 시작합니다. 이제 Studio를 열면 플러그인이 자동으로 로드됩니다.
  • 참고: 플러그인은 http://localhost:8000/plugin_command 폴링합니다. 서버 포트를 변경하면 Lua 스크립트 상단의 SERVER_URL 변수( roblox_mcp_plugin/src/Plugin.server.lua )를 업데이트하고 플러그인을 다시 빌드해야 합니다.

6. Python 서버를 실행합니다.

• 프로젝트의 루트 디렉토리에서 터미널을 엽니다.
• 서버 스크립트를 실행 가능하게 만듭니다(아직 실행 가능하게 만들지 않았다면):
  chmod +x server.sh
• 서버를 실행합니다:
  ./server.sh
• 서버가 시작되고, 필요한 경우 uvicorn 확인/설치하고, http://localhost:8000 에서 실행 중임을 기록합니다.
• 서비스를 사용하는 동안 이 터미널 창을 열어 두세요.

7. MCP 클라이언트(예: 커서)에서 연결:

• 이 서비스는 Cursor, Windsurf 또는 Claude Desktop의 향후 버전과 같이 SSE(Server-Sent Events)를 통해 MCP(Model Context Protocol)를 지원하는 모든 AI 클라이언트와 함께 작동합니다.
• 커서를 사용한 예:
  • File > Settings > MCP (Mac에서는 Code > Settings > MCP )로 이동합니다.
  • "새로운 글로벌 MCP 서버 추가"를 클릭합니다.
  • SSE URL을 입력하세요: http://localhost:8000/sse (맨 뒤에 /sse 포함해야 합니다).
  • mcp.json 파일 GXP8을 편집해야 할 수도 있습니다.
• 이제 클라이언트는 "Vibe Blocks MCP" 도구 소스와 사용 가능한 도구를 감지해야 합니다.

용법

서버가 실행 중이고, 플러그인이 Studio에 설치되고, MCP 클라이언트가 연결되면 AI를 통해 Studio 세션과 상호 작용할 수 있습니다.

클라이언트가 도구를 필요로 하는 경우 해당 도구를 언급하면서 에이전트에게 말을 걸고(예: list_children ) 작업을 수행하도록 요청합니다.

예시 프롬프트:

• 작업 공간에 'Floor'라는 이름의 밝은 빨간색 파트를 만듭니다. 크기를 (100, 2, 100)으로 설정하고 위치를 (0, -1, 0)으로 설정합니다. 고정합니다.
• "Workspace.OldPlatform"이라는 이름의 객체를 삭제하세요.
• 'Workspace.SpawnLocation'의 Position 속성은 무엇인가요?
• "ServerScriptService의 자식을 나열합니다."
• "ServerScriptService에서 className이 'Script'인 모든 인스턴스를 찾습니다."
• "Studio에서 이 스크립트를 실행하세요: print(game:GetService('Lighting').ClockTime) "
• "조명의 ClockTime 속성을 14로 설정합니다."
• 'ReplicatedStorage.Templates.EnemyNPC'를 복제하고 복제본의 이름을 'Guard1'로 지정합니다. Workspace를 부모로 지정합니다.
• 'Workspace.Guard1'이라는 모델이 애니메이션 자산 123456789를 재생하도록 합니다.
• 'Workspace.DecorationFolder'의 모든 자식 클래스 이름(className 'Part')을 수정하여 해당 자식 클래스의 Material을 'Neon'으로 설정합니다.
• (클라우드 예시) "'./assets/MyCoolModel.fbx'를 'Cool Character Model'이라는 이름의 모델로 업로드합니다."
• (클라우드 예시) "'PlayerData' 데이터 저장소에서 'player_123_score' 키의 값을 가져옵니다."
• (클라우드 예시) "현재 장소를 게시합니다."
• "Studio 출력의 최신 로그를 보여주세요."

사용 가능한 도구

(도구는 Studio 플러그인 또는 Roblox Open Cloud API와 직접 상호 작용합니다)

스튜디오 플러그인 도구(라이브 상호작용):

• 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에서 객체(모델 또는 BasePart)를 새 위치로 이동합니다.
• clone_instance : Studio에서 기존 객체를 복제합니다.
• create_script : Studio에서 제공된 코드로 새로운 스크립트 또는 LocalScript 인스턴스를 만듭니다.
• edit_script : Studio에서 기존 스크립트나 LocalScript의 소스 코드를 편집합니다.
• delete_script : Studio에서 기존 스크립트나 LocalScript 인스턴스를 삭제합니다.
• set_environment : Studio에서 환경 서비스(조명 또는 지형)의 속성을 설정합니다.
• spawn_npc : 자산 ID에서 모델을 삽입하거나 기존 템플릿 모델을 복제하여 Studio에서 NPC를 생성합니다.
• play_animation : Studio에서 대상 객체의 Humanoid 또는 AnimationController에 애니메이션을 로드하고 재생합니다.
• execute_luau_in_studio : 플러그인을 통해 LIVE Studio 세션에서 임의의 Luau 스크립트를 실행하고 출력/반환 값/오류를 캡처합니다.
• modify_children : 선택적 필터(이름/클래스)와 일치하는 부모 아래의 직계 자식을 찾아 해당 자식에 지정된 속성을 설정합니다.
• get_studio_logs : 플러그인을 통해 Roblox Studio 출력 창에서 캡처된 가장 최근 로그를 검색합니다.

Open Cloud API 도구(선택 사항 - .env 설정 필요):

• execute_luau_in_cloud : Roblox Cloud API를 통해 임의의 Luau 스크립트를 실행합니다(라이브 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 : Cloud API를 통해 로컬 시스템의 파일을 새로운 Roblox 자산으로 업로드합니다.
• publish_place_via_cloud : Cloud API를 통해 지정된 장소를 게시합니다.
• get_asset_details_via_cloud : (구현되지 않음) Cloud API를 통해 특정 자산에 대한 세부 정보를 가져옵니다.
• list_user_assets_via_cloud : (구현되지 않음) 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 서버가 실행 중인지 확인하세요. Lua 플러그인 스크립트의 SERVER_URL 이 서버 주소 및 포트(기본값 http://localhost:8000/plugin_command )와 일치하는지 다시 한 번 확인하세요. Studio의 출력 창에서 플러그인 스크립트의 오류를 확인하세요.
• MCP 클라이언트 연결 안 됨: 서버가 실행 중인지 확인하세요. MCP 클라이언트 설정에 SSE URL( http://localhost:8000/sse )이 올바르게 입력되었는지 확인하세요.
• Cloud Tools 오류: 유효한 API 키, Universe ID, Place ID를 사용하여 .env 파일을 생성했는지 확인하세요. 사용하려는 특정 Cloud API에 필요한 권한이 API 키에 있는지 확인하세요.
• 권한: 동반 플러그인을 제대로 설치하는 대신 로컬 파일에서 로드하는 경우, 해당 플러그인이 제대로 작동하려면 스크립트 주입 권한이 필요합니다.