문제 해결

연결, 권한, Sync, 검증 문제를 단계별로 좁혀 가는 가이드입니다.

플러그인이 연결되지 않을 때

증상: “Connection failed” 또는 Roblox Studio에서 플러그인이 연결 안 됨으로 표시됩니다.

1. MCP 서버가 실행 중인지 확인: npx -y @weppy/roblox-mcp@latest
2. Roblox Studio: Plugins 탭 → WEPPY → Connect 클릭
3. localhost:3002를 차단하는 방화벽, 바이러스 백신, VPN이 없는지 확인
4. Roblox Studio와 MCP 서버를 모두 재시작

AI 클라이언트가 MCP 서버를 인식하지 못할 때

1. AI 클라이언트 설정에서 올바른 명령어가 사용되는지 확인: npx -y @weppy/roblox-mcp@latest
2. Node.js 18 이상이 설치되어 있는지 확인: node --version
3. Windows에서 권한 오류가 발생하면 터미널을 관리자 권한으로 실행해보세요
4. 사용 중인 AI 앱의 설치 가이드를 확인하세요

”Pro feature required” 안내

Basic에서 Pro 전용 액션을 요청하면, 가능한 경우 우회 방법을 찾아 처리합니다. 다만 우회 흐름이 추가 토큰을 소모하고 항상 같은 결과를 보장하지는 않습니다.

또한 우회 자체가 불가능한 일부 Pro 전용 도구는 Basic에서 실행할 수 없습니다. 이 안내가 반복되면 요청한 액션을 현재 플랜에서 사용할 수 있는지 확인하세요.

Sync가 동작하지 않을 때

1. Sync 상태 확인: AI에게 manage_sync status 요청
2. Sync 시작 전에 플러그인이 연결되어 있는지 확인
3. Reverse sync(파일 → Studio)가 안 되면 Pro 티어 활성화 여부 확인
4. 로컬 sync 폴더가 존재하고 쓰기 권한이 있는지 확인

자세한 Sync 설정은 양방향 Sync를 참고하세요.

Multi-Place 작업이 잘못된 Place에 적용될 때

1. Dashboard의 Connection 페이지에서 Studio ID와 Place 이름을 다시 확인합니다.
2. 프롬프트 첫 줄에 studio-1은 Lobby, studio-2는 Game처럼 대상 매핑을 명시합니다.
3. 대상이 없는 요청은 pinned Studio 또는 recent priority로 라우팅될 수 있으므로, 중요한 작업에는 Studio ID를 직접 적습니다.
4. 대량 삭제나 스크립트 일괄 수정 전에는 AI에게 대상 Place와 변경 계획을 먼저 출력하게 합니다.

자세한 패턴은 Multi-Place Work 가이드를 참고하세요.

Assets 업로드 또는 적용이 실패할 때

1. AI에게 manage_open_cloud_assets credential_status로 Open Cloud 설정 상태를 확인하게 합니다.
2. API key 권한, Creator, group/owner 설정이 업로드 대상 asset 종류와 맞는지 확인합니다.
3. 업로드 직후에는 Roblox operation 상태가 완료될 때까지 기다린 뒤 asset URI를 적용합니다.
4. ImageLabel, Decal, Texture처럼 속성 타입에 맞는 rbxassetid://... URI를 적용했는지 확인합니다.

이미지 생성, 업로드, Place 적용 경로는 Assets 가이드에서 자세히 볼 수 있습니다.

호환 AI 클라이언트

서버 명령어: npx -y @weppy/roblox-mcp@latest

시스템 요구 사항

자주 발생하는 오류 메시지

도움이 필요하면

여전히 문제가 해결되지 않으면 GitHub Issue를 열고 다음 정보를 포함하세요:

• 운영 체제 및 Node.js 버전
• AI 클라이언트 및 버전
• 오류 메시지 또는 로그
• 이미 시도한 단계

공개 이슈에는 원본 라이선스 키, 영수증, 이메일 주소, 결제 정보, 비공개 프로젝트 정보를 적지 마세요. 구매, 라이선스, 이메일, 결제, 비공개 프로젝트 정보가 포함된 문의는 [email protected]으로 보내주세요.