Guia para identificar passo a passo problemas de conexão, permissão, Sync e validação.
Quando o Plugin Não Conecta
Sintoma: “Connection failed” ou o plugin aparece como desconectado no Roblox Studio.
- Verifique se o servidor MCP está em execução:
npx -y @weppy/roblox-mcp@latest - Roblox Studio: aba Plugins → WEPPY → clicar em Connect
- Verifique se não há firewall, antivírus ou VPN bloqueando
localhost:3002 - Reinicie o Roblox Studio e o servidor MCP
Quando o Cliente de IA Não Reconhece o Servidor MCP
- Verifique se o comando correto está sendo usado nas configurações do cliente de IA:
npx -y @weppy/roblox-mcp@latest - Verifique se o Node.js 18 ou superior está instalado:
node --version - No Windows, se ocorrer um erro de permissão, tente executar o terminal como administrador
- Consulte o guia de instalação do app de IA que você está usando
Aviso “Pro feature required”
Quando você solicita uma ação exclusiva Pro no Basic, se possível, é feita uma tentativa de encontrar uma alternativa. No entanto, o fluxo alternativo consome tokens adicionais e nem sempre garante o mesmo resultado.
Além disso, algumas ferramentas exclusivas do Pro não têm alternativa e não podem ser executadas no Basic. Se este aviso aparecer repetidamente, verifique se a ação solicitada está disponível no seu plano atual.
Quando o Sync Não Funciona
- Verificar status do Sync: solicitar
manage_sync statuspara a IA - Verificar se o plugin está conectado antes de iniciar o Sync
- Se o reverse sync (arquivo → Studio) não funcionar, verificar se o tier Pro está ativo
- Verificar se a pasta de sync local existe e tem permissão de escrita
Para configurações detalhadas do Sync, consulte Sync Bidirecional.
Clientes de IA Compatíveis
| Cliente |
|---|
| Claude Code |
| Claude Desktop |
| Cursor |
| Codex CLI |
| Codex Desktop |
| Gemini CLI |
| Apps com suporte a MCP |
Comando do servidor: npx -y @weppy/roblox-mcp@latest
Requisitos do Sistema
| Item | Mínimo |
|---|---|
| Node.js | 18.0.0 ou superior |
| Roblox Studio | Versão mais recente (manter atualização automática) |
| Sistema Operacional | Windows 10+ ou macOS 12+ |
| Rede | localhost:3002 deve estar acessível |
Mensagens de Erro Comuns
| Erro | Causa | Solução |
|---|---|---|
ECONNREFUSED localhost:3002 | Servidor MCP não está em execução | Executar npx -y @weppy/roblox-mcp@latest |
Timeout waiting for plugin | Plugin do Studio não conectado | Clicar em Connect no painel do plugin |
Forbidden path | Tentativa de acesso a CoreGui/CorePackages | Usar somente caminhos de instância válidos |
Place ID mismatch | Place errado conectado | Reconectar na sessão correta do Studio |
Precisa de Ajuda?
Se o problema ainda não foi resolvido, abra uma GitHub Issue com as seguintes informações:
- Sistema operacional e versão do Node.js
- Cliente de IA e versão
- Mensagem de erro ou logs
- Passos já tentados
Não inclua license keys sem ocultar, recibos, emails, dados de pagamento ou informações privadas do projeto em uma issue pública. Escreva para [email protected] se a pergunta incluir compra, licença, email, pagamento ou informações privadas do projeto.