🎮 Roblox Studio Ultimate MCP 서버

English | 日本語

Roblox Studio를 위한 가장 포괄적인 MCP(Model Context Protocol) 서버입니다. Claude Code나 모든 MCP 호환 AI 어시스턴트에서 Studio를 완벽하게 제어할 수 있는 41개의 도구를 제공합니다.

✨ 이 서버가 필요한 이유

기본 Roblox Studio MCP는 run_code만 제공하므로 문자열 작업(gsub)을 통해 스크립트 소스를 조작해야 합니다. 이로 인해 다음과 같은 문제가 발생합니다:

❌ 패턴 매칭 실패
❌ end) 문 깨짐
❌ 스크립트가 되돌려질 때 발생하는 자동 롤백
❌ 쓰기 전 구문 검사 부재
❌ 단순 편집에 낭비되는 시간

이 MCP는 이 모든 문제를 해결합니다.

🚀 기능

스크립트 작업 (게임 체인저)

도구	설명
`getScript`	전체 소스 코드 가져오기
`setScript`	전체 소스 교체 (구문 검사 + 자동 백업 포함)
`editScript`	특정 줄 범위 편집 (부분 편집!)
`insertCode`	특정 줄 뒤에 코드 삽입
`removeLines`	특정 줄 제거
`replaceInScript`	텍스트 찾기 및 바꾸기 (일반 텍스트, 안전함)
`getLines`	특정 줄 범위만 가져오기 (가벼움)
`getFunctionList`	줄 번호와 함께 모든 함수 나열
`getScriptSummary`	개요: 함수, require, 전역 변수
`listScripts`	게임 내 모든 스크립트 나열
`getAllScripts`	모든 스크립트 소스를 한 번에 가져오기
`searchInScripts`	모든 스크립트에서 키워드 검색
`getReferences`	변수/함수의 모든 사용처 찾기
`getModuleDependencies`	require() 의존성 나열

안전 메커니즘

기능	설명
🔒 구문 검사	쓰기 전 자동 검증. 잘못된 코드는 거부합니다.
💾 자동 백업	모든 편집 전 이전 버전을 저장합니다 (10세대)
🛑 플레이 모드 보호	플레이 모드 중 쓰기를 차단합니다 (자동 롤백 방지)
📝 UpdateSourceAsync	충돌 없는 쓰기를 위해 ScriptEditorService를 사용합니다

백업 및 복원

도구	설명
`restoreBackup`	자동 저장된 백업에서 복원
`listBackups`	사용 가능한 백업 나열

검증

도구	설명
`checkSyntax`	쓰기 없이 구문 검사
`verifyScript`	줄 수 / 소스 길이 검증
`validateAllScripts`	모든 스크립트 일괄 구문 검사

인스턴스 작업

도구	설명
`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 Plugins 폴더에 복사하세요:

Mac:

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

Windows:

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

또는 소스에서 생성하세요:

bash generate-plugin.sh

3. Studio에서 HTTP 활성화

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 서버 (src/index.ts): MCP 도구 호출을 HTTP 명령으로 변환
Studio 플러그인 (plugin/RobloxMCP.lua): 서버를 폴링하여 Studio 내에서 명령 실행
통신: HTTP 폴링 (300ms 간격)

🔧 다른 MCP 서버와 함께 사용하기

이 서버는 공식 Roblox Studio MCP와 함께 작동하도록 설계되었습니다:

사용 사례	사용할 MCP
스크립트 읽기/쓰기	Ultimate (getScript/setScript)
플레이 테스트	공식 (start_stop_play)
콘솔 출력	공식 (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