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 - 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 - 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 Pro que não podem ser contornadas não podem ser executadas no Basic. Se este aviso aparecer repetidamente, considere migrar para o Pro.
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 | Basic | Pro |
|---|---|---|
| Claude Code | ✅ | ✅ |
| Claude Desktop | ✅ | ✅ |
| Cursor | ✅ | ✅ |
| Codex CLI | ✅ | ✅ |
| Codex Desktop | ✅ | ✅ |
| Gemini CLI | ✅ | ✅ |
| Apps com suporte a MCP | ✅ | ✅ |
Comando do servidor: npx -y @weppy/roblox-mcp
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 |
Comparação de Recursos Basic vs Pro
O Basic (gratuito) também permite usar a maior parte do fluxo essencial de codificação com IA. Todas as ferramentas essenciais para instâncias, propriedades, scripts, seleção, câmera e logs estão incluídas, e o Sync unidirecional Studio → Local e o histórico de execução de ferramentas também estão disponíveis. O Pro adiciona Sync bidirecional, operações em massa e um conjunto de ferramentas avançadas como terreno, iluminação, física, áudio e animação.
| Recurso | Basic | Pro |
|---|---|---|
| Pesquisar, criar, excluir, clonar, mover instâncias | ✅ | ✅ |
| Navegar pela árvore/hierarquia de instâncias | ✅ | ✅ |
| Ler/escrever propriedades e tags | ✅ | ✅ |
| Ler, escrever, modificar scripts | ✅ | ✅ |
| Gerenciamento de seleção | ✅ | ✅ |
| Mover/focar câmera | ✅ | ✅ |
| Consultar logs | ✅ | ✅ |
| Informações do sistema e verificação de conexão | ✅ | ✅ |
| Histórico e estatísticas de ferramentas | ✅ | ✅ |
| Sync unidirecional Studio → Local | ✅ | ✅ |
| Sync bidirecional (Local → Studio) | — | ✅ |
| Direction / Apply Mode por tipo | — | ✅ |
| Histórico de alterações Sync | — | ✅ |
| Sync de múltiplos Places (até 3) | — | ✅ |
| Operações em massa (criação/modificação em lote) | — | ✅ |
| Controle de iluminação/atmosfera | — | ✅ |
| Criação/edição de terreno | — | ✅ |
| Controle de tween/animação | — | ✅ |
| Controle de áudio | — | ✅ |
| Partículas/efeitos | — | ✅ |
| Grupos de física/colisão | — | ✅ |
| Spatial query/raycast | — | ✅ |
| Pesquisar, inserir, exportar assets | — | ✅ |
| Captura de screenshot | — | ✅ |
| Execução automática de Playtest e injeção de testes | — | ✅ |
| Execução em lote e código Luau arbitrário | — | ✅ |
Quando você solicita recursos exclusivos Pro no Basic, a IA tenta contornar dentro do possível, mas o consumo de tokens aumenta e alguns recursos não podem ser contornados. Veja mais detalhes no item Aviso “Pro feature required” acima.
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 |
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, envie uma mensagem no GitHub Discussions 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