@weppy/roblox-mcp 2.5.1 → 2.6.0

package/docs/pt-br/installation/ai-apps/codex-cli.md

@@ -1,67 +0,0 @@
-# Configuracao do Codex CLI
-
-Como usar o Roblox MCP no [OpenAI Codex CLI](https://github.com/openai/codex) (ferramenta de codificacao com IA baseada em terminal).
-
-## Pre-requisitos
-
-- **Node.js** (v18.0.0 ou superior)
-- **Plugin do Roblox Studio** instalado
-
-## Instalacao
-
-```bash
-npm install -g @openai/codex
-```
-
-## Registrar o Servidor MCP
-
-### Metodo 1: Comando CLI (Recomendado)
-
-```bash
-codex mcp add weppy-roblox-mcp -- npx -y @weppy/roblox-mcp
-```
-
-### Metodo 2: Editar Arquivo de Configuracao Diretamente
-
-Adicione o seguinte conteudo ao arquivo `~/.codex/config.toml`:
-
-```toml
-[mcp_servers.weppy-roblox-mcp]
-command = "npx"
-args = ["-y", "@weppy/roblox-mcp"]
-```
-
-**Localizacao do arquivo de configuracao:**
-
-| SO | Caminho |
-|----|---------|
-| macOS/Linux | `~/.codex/config.toml` |
-| Windows | `%USERPROFILE%\.codex\config.toml` |
-
-## Teste de Conexao
-
-1. Inicie o **Roblox Studio** → Aba Plugins → **WEPPY** → **Connect**
-2. Inicie o **Codex CLI** e digite:
-   ```
-   Diga-me o que esta selecionado atualmente no Roblox Studio
-   ```
-
-## Solucao de Problemas
-
-### O servidor nao inicia
-
-Execute o servidor MCP diretamente para verificar erros:
-```bash
-npx -y @weppy/roblox-mcp
-```
-
-### Falha na conexao
-
-- Verifique se o plugin do Roblox Studio esta no estado **Connected**
-- Verifique se a porta 3002 nao esta bloqueada pelo firewall
-
-## Referencias
-
-- [GitHub do Codex CLI](https://github.com/openai/codex)
-- [Documentacao Oficial de MCP do Codex](https://developers.openai.com/codex/mcp/)
-- [Referencia de Configuracao do Codex](https://developers.openai.com/codex/config-reference/)

package/docs/pt-br/installation/ai-apps/cursor.md

@@ -1,77 +0,0 @@
-# Configuração do Cursor
-
-Como usar o Roblox MCP com [Cursor](https://cursor.com/).
-
-## Pré-requisitos
-
-- **Cursor** instalado
-- **Node.js** (v18.0.0 ou superior)
-- **Plugin do Roblox Studio** instalado
-
-## Registrar o servidor MCP
-
-### Método 1: Configuração do projeto
-
-Adicione o seguinte em `.cursor/mcp.json` dentro do seu projeto:
-
-```json
-{
-  "mcpServers": {
-    "weppy-roblox-mcp": {
-      "command": "npx",
-      "args": ["-y", "@weppy/roblox-mcp"]
-    }
-  }
-}
-```
-
-### Método 2: Configuração global
-
-Adicione o mesmo conteúdo ao arquivo global de configuração do Cursor.
-
-**Locais do arquivo de configuração:**
-
-| Escopo | Caminho |
-|--------|---------|
-| Projeto | `<projeto>/.cursor/mcp.json` |
-| Global (macOS/Linux) | `~/.cursor/mcp.json` |
-| Global (Windows) | `%USERPROFILE%\\.cursor\\mcp.json` |
-
-> Se o arquivo já existir, mescle a entrada `weppy-roblox-mcp` dentro do objeto `mcpServers`.
-
-### Aplicar alterações
-
-Depois de editar a configuração, recarregue a janela do Cursor ou reinicie o aplicativo.
-
-## Teste de conexão
-
-1. Abra o **Roblox Studio** → aba Plugins → **WEPPY** → **Connect**
-2. No **Cursor**, digite:
-   ```
-   Tell me what's currently selected in Roblox Studio
-   ```
-
-## Solução de problemas
-
-### O servidor MCP não aparece
-
-- Verifique se o caminho do arquivo de configuração está correto
-- Confirme que a sintaxe JSON está válida
-- Recarregue o Cursor após editar a configuração
-
-### O servidor não inicia
-
-Execute o servidor MCP diretamente para verificar erros:
-
-```bash
-npx -y @weppy/roblox-mcp
-```
-
-### Falha na conexão
-
-- Verifique se o plugin do Roblox Studio está no estado **Connected**
-- Confira se a porta 3002 está bloqueada pelo firewall
-
-## Referência
-
-- [Documentação do Cursor MCP](https://docs.cursor.com/context/model-context-protocol)

package/docs/pt-br/installation/ai-apps/gemini-cli.md

@@ -1,120 +0,0 @@
-# Configuração do Gemini CLI
-
-Como usar o Roblox MCP com [Google Gemini CLI](https://github.com/google-gemini/gemini-cli).
-
-## Pré-requisitos
-
-1. **Node.js** (v18.0.0 ou superior)
-   ```bash
-   node --version
-   ```
-
-2. **Gemini CLI** instalado
-   ```bash
-   npm install -g @google/gemini-cli
-   ```
-
-3. **Plugin do Roblox Studio** instalado
-
-## Registrar servidor MCP
-
-### Método 1: Comando CLI (Recomendado)
-
-Registre com um único comando no terminal:
-
-```bash
-gemini mcp add weppy-roblox-mcp npx --trust -- -y @weppy/roblox-mcp
-```
-
-> A flag `--trust` ignora as solicitações de confirmação para cada chamada de ferramenta.
-
-Para registrar globalmente, adicione `-s user`:
-
-```bash
-gemini mcp add weppy-roblox-mcp npx -s user --trust -- -y @weppy/roblox-mcp
-```
-
-### Método 2: Editar arquivo de configuração
-
-Adicione o seguinte conteúdo ao arquivo `.gemini/settings.json`:
-
-```json
-{
-  "mcpServers": {
-    "weppy-roblox-mcp": {
-      "command": "npx",
-      "args": ["-y", "@weppy/roblox-mcp"]
-    }
-  }
-}
-```
-
-**Localizações do arquivo de configuração:**
-| Escopo | Caminho |
-|--------|---------|
-| Projeto | `<projeto>/.gemini/settings.json` |
-| Global | `~/.gemini/settings.json` |
-
-### Método 3: Usando variáveis de ambiente
-
-Se variáveis de ambiente específicas forem necessárias:
-
-**CLI:**
-```bash
-gemini mcp add weppy-roblox-mcp npx --trust -e HTTP_PORT=3002 -- -y @weppy/roblox-mcp
-```
-
-**Arquivo de configuração:**
-```json
-{
-  "mcpServers": {
-    "weppy-roblox-mcp": {
-      "command": "npx",
-      "args": ["-y", "@weppy/roblox-mcp"],
-      "env": {
-        "HTTP_PORT": "3002"
-      }
-    }
-  }
-}
-```
-
-## Teste de conexão
-
-1. Abra o **Roblox Studio** → aba Plugins → **WEPPY** → **Connect**
-2. Execute o **Gemini CLI** e digite:
-   ```
-   Me diga o que está selecionado atualmente no Roblox Studio
-   ```
-
-## Verificar status do servidor MCP
-
-Você pode verificar o status dos servidores conectados com o comando `/mcp` no Gemini CLI:
-
-```
-/mcp
-```
-
-## Solução de problemas
-
-### Servidor não inicia
-
-Execute o servidor MCP diretamente para verificar erros:
-```bash
-npx -y @weppy/roblox-mcp
-```
-
-### Falha na conexão
-
-- Verifique se o plugin do Roblox Studio está no estado **Connected**
-- Verifique se a porta 3002 está bloqueada por um firewall
-- Verifique o status do servidor com o comando `/mcp`
-
-### Conflitos de ferramentas
-
-Se vários servidores MCP tiverem ferramentas com o mesmo nome, elas receberão o prefixo no formato `serverAlias__toolName`.
-
-## Referências
-
-- [Documentação oficial do Gemini CLI MCP](https://geminicli.com/docs/tools/mcp-server/)
-- [Guia de configuração do Gemini CLI](https://geminicli.com/docs/get-started/configuration/)

package/docs/pt-br/installation/roblox-explorer.md

@@ -1,58 +0,0 @@
-# WEPPY Roblox Explorer (Extensão VSCode)
-
-Visualização em árvore de instâncias similar ao Explorer do Roblox Studio, dentro do VSCode. Navegue por instâncias sincronizadas, abra scripts diretamente e acompanhe o status de sincronização sem sair do editor.
-Esta é uma extensao complementar do WEPPY, e não uma integração Roblox independente.
-
-![WEPPY Roblox Explorer](../../assets/screenshots/roblox-explorer/roblox-explorer-screen.png)
-
-## Requisitos
-
-- VSCode 1.85+
-- [Roblox MCP](../../../README.md) instalado com Sync habilitado (Basic ou Pro)
-- O Sync ja gerou `weppy-project-sync/place_*/.sync-meta.json` na raiz do projeto
-
-## Instalação
-
-Pesquise **WEPPY Roblox Explorer** na barra lateral de Extensões do VSCode (`Ctrl+Shift+X` / `Cmd+Shift+X`) e clique em **Install**.
-
-Ou instale diretamente por um destes marketplaces:
-
-- [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=weppy.weppy-roblox-explorer)
-- [Open VSX](https://open-vsx.org/extension/weppy/weppy-roblox-explorer)
-
-A navegação basica da arvore funciona a partir dos arquivos sincronizados em disco. Status sync ao vivo, indicadores de direction e envio de telemetria do Explorer ficam disponiveis quando o servidor MCP local está acessivel.
-
-## Funcionalidades
-
-- **Árvore de instâncias**: Hierarquia de serviços/instâncias idêntica ao Roblox Studio
-- **Ícones de classes Roblox**: Mais de 200 ícones com suporte a temas escuro/claro
-- **Multi-Place**: Raízes de árvore separadas por Place sincronizado
-- **Abrir ao clicar**: Abre arquivos de suporte (`.server.luau`, `.client.luau`, `.module.luau`, `.props.json`)
-- **Pesquisa de instâncias**: Pesquisa QuickPick em todos os serviços
-- **Badges de status Sync**: Visualize os estados `modified`, `studio`, `conflict` de relance
-- **Atualização automática**: A árvore é atualizada automaticamente quando os arquivos Sync mudam (debounce 500ms)
-- **Copiar caminho de instância**: Clique com o botão direito para copiar caminhos no formato `game.Workspace.Part`
-
-## Configurações
-
-| Configuração | Padrão | Descrição |
-|--------------|--------|-----------|
-| `robloxExplorer.syncRoot` | `""` | Caminho absoluto para a raiz do `weppy-project-sync`. Se estiver vazio, e detectado automaticamente. O WEPPY usa `{projectRoot}/weppy-project-sync`. |
-| `robloxExplorer.hidePropsFiles` | `false` | Oculta arquivos de Sync (`.props.json`, `_tree.json`, `.value.json`) no explorador padrão do VSCode. |
-| `robloxExplorer.autoRefresh` | `true` | Atualiza automaticamente a árvore quando os arquivos Sync mudam. |
-| `robloxExplorer.showSyncStatus` | `true` | Exibe decorações de status Sync nos itens da árvore. |
-
-## Comandos
-
-| Comando | Descrição |
-|---------|-----------|
-| `WEPPY Explorer: Refresh` | Atualizar manualmente a árvore de instâncias |
-| `WEPPY Explorer: Search Instances` | Pesquisar instâncias em todos os serviços |
-| `WEPPY Explorer: Open Backing File` | Abrir o arquivo de suporte de uma instância selecionada |
-| `WEPPY Explorer: Copy Instance Path` | Copiar o caminho completo da instância (ex. `game.Workspace.Part`) |
-| `WEPPY Explorer: Reveal in Explorer` | Mostrar o arquivo no explorador padrão do VSCode |
-
-## Relacionado
-
-- [Guia detalhado de Sync](../sync/overview.md)
-- [Guia de instalação](README.md)

package/docs/pt-br/installation/roblox-plugin.md

@@ -1,85 +0,0 @@
-# Instalacao do Plugin Roblox
-
-Como instalar o plugin para conectar agentes de IA no Roblox Studio.
-
-## 1. Baixar o Plugin
-
-1. Abra [GitHub Releases](https://github.com/hope1026/weppy-roblox-mcp/releases/latest)
-2. Baixe `weppy-roblox-mcp-v{version}.zip`
-3. Extraia o ZIP - voce encontrara `roblox-plugin/WeppyRobloxMCP.rbxm` e guias de instalacao
-
-Nota:
-- Basic usa o mesmo pacote com politica Basic (Studio -> Local, unidirecional)
-- Com licenca Pro por assinatura, sync bidirecional e recursos avancados mais amplos sao liberados
-
-## 2. Instalar o Plugin
-
-1. Inicie o **Roblox Studio**
-2. Clique na aba **Plugins**
-3. Clique em **Plugins Folder**
-
-![Abrir Plugins Folder](../../assets/screenshots/plugin/installation/plugins-menu.png)
-
-4. **Copie** `WeppyRobloxMCP.rbxm` para a pasta de Plugins
-5. **Reinicie o Roblox Studio**
-
-## 3. Verificar a Instalacao
-
-Apos reiniciar, o botao **WEPPY** aparecera na aba Plugins.
-
-![Botao WEPPY](../../assets/screenshots/plugin/installation/toolbar-button.png)
-
-## 4. Conectar ao Agente de IA
-
-### Pre-requisitos
-
-O servidor MCP deve estar instalado. Complete primeiro o guia do seu app de IA:
-
-| Aplicativo de IA | Guia de Instalacao |
-|------------------|---------------------|
-| Claude Code | [Como Configurar](ai-apps/claude-code.md) |
-| Claude Desktop | [Como Configurar](ai-apps/claude-app.md) |
-| Cursor | [Como Configurar](ai-apps/cursor.md) |
-| Codex CLI | [Como Configurar](ai-apps/codex-cli.md) |
-| Codex Desktop | [Como Configurar](ai-apps/codex-app.md) |
-| Gemini CLI | [Como Configurar](ai-apps/gemini-cli.md) |
-| Antigravity | [Como Configurar](ai-apps/antigravity.md) |
-
-### Conectar
-
-1. Abra qualquer projeto no **Roblox Studio**
-2. Aba **Plugins** -> **WEPPY**
-3. Clique em **Connect**
-4. Quando aparecer **"Connected"**, esta pronto
-
-![Tela Principal do Plugin](../../assets/screenshots/plugin/installation/main-screen.png)
-
-## 5. Configuracoes (Opcional)
-
-Use o botao de configuracoes no canto superior direito.
-
-![Tela de Configuracoes](../../assets/screenshots/plugin/installation/settings-screen.png)
-
-- **Conexao Automatica**
-- **Reconexao Automatica**
-- **Foco Automatico da Camera**
-- **Idioma**
-
-## Solucao de Problemas
-
-### O plugin nao aparece
-
-- Reinicie o Roblox Studio por completo
-- Verifique se o arquivo foi copiado corretamente
-- Verifique se `.rbxm` nao esta corrompido
-
-### Nao consigo conectar
-
-- Verifique se o servidor MCP esta em execucao
-- Clique em **Connect** novamente
-- Verifique conflito na porta 3002
-
-### A conexao cai frequentemente
-
-- Ative **Reconexao Automatica**
-- Reinicie o app de IA

package/docs/pt-br/pro-upgrade.md

@@ -1,96 +0,0 @@
-# Guia de Upgrade para Pro
-
-## Por que Pro?
-
-### Sync bidirecional para fluxos de desenvolvimento reais
-
-O Sync do Pro vai além do simples export. Edite scripts localmente e envie para o Studio. Faça mudanças no Studio e traga de volta para o disco. Pro mantém os dois lados sincronizados.
-
-- **Sync bidirecional** — Mudanças fluem em ambas as direções entre Studio e arquivos locais.
-- **Direction por tipo** — Configure a direção independentemente para Scripts, Values, Containers, Data e Services.
-- **Apply Mode por tipo** — Escolha Auto ou Manual por tipo para equilibrar velocidade e controle.
-- **Full Sync / Resync** — Reconstrua o estado limpo do projeto após grandes mudanças ou reconexões.
-- **Histórico de mudanças** — Rastreie o que mudou, quando e em qual direção antes de aplicar.
-- **Sync multi-place** — Sincronize até 3 Roblox Places simultaneamente, cada um com armazenamento isolado e histórico próprio.
-
-### Economize tokens de IA com workflows de alto impacto
-
-Ações em massa e avançadas reduzem chamadas repetitivas — faça mais por prompt.
-
-### IA que controla playtests diretamente
-
-A IA pode controlar os playtests do Roblox Studio diretamente. Ela pode iniciar e parar Play (F5) ou Run (F8), injetar scripts de teste, coletar logs e gerar relatórios automaticamente.
-
-- "Inicia um playtest no modo Run e verifica se o NPC chega ao alvo."
-- "Escreve um teste que verifica se o SpawnLocation está acima do chão e executa."
-- "Valida que o script que acabei de mudar funciona sem erros no playtest."
-
-### Mais recursos exclusivos do Pro
-
-O Pro desbloqueia recursos adicionais além do fluxo de trabalho principal.
-
-- **Operações em massa** — Criar, modificar ou excluir múltiplas instâncias em uma única solicitação
-- **Geração de terrain** — Preencher com bloco, esfera, cilindro, cunha e substituir materiais
-- **Busca/inserção de assets** — Pesquisar no marketplace do Roblox e inserir assets diretamente
-- **Análise espacial** — Raycast, encontrar chão, busca de área plana, detecção de colisão
-- **Controle de ambiente** — Iluminação, atmosfera, céu e hora do dia
-- **Áudio/Animação** — Reprodução de som e carregar/reproduzir animações
-
-## Comprar e ativar
-
-### Passo 1: Compre uma licença de assinatura Pro no Gumroad
-
-1. Acesse [Gumroad - Weppy Roblox Plugin](https://gumroad.com/l/faccjs?utm_source=github&utm_medium=repo&utm_campaign=pro_upgrade_md)
-2. Conclua a compra da licença de assinatura Pro
-3. Copie a chave de licença que você recebe após a compra
-
-Você só precisa ativar a licença uma vez, no plugin ou no dashboard. As duas superfícies compartilham o mesmo estado local de licença do MCP, então a ativação feita em um lugar aparece no outro.
-
-### Ativar no plugin
-
-1. Abra o **WEPPY** no Roblox Studio e conecte ao servidor MCP.
-2. Abra a seção **Settings > License** no plugin.
-3. Cole a chave comprada no campo `License key`.
-4. Clique em **Activate** para ativar a licença.
-5. Se o status não atualizar imediatamente, clique em **Refresh**.
-6. Quando a ativação terminar, o status muda de Basic para Pro e os recursos Pro ficam disponíveis.
-
-![Tela de ativação de licença no plugin](../assets/screenshots/plugin/license/plugin-license-screen.png)
-
-### Ativar no dashboard
-
-1. Inicie o servidor MCP e abra **Settings > License** no dashboard.
-2. Confirme que o provider está definido como `gumroad`.
-3. Cole a chave comprada no campo `License Key`.
-4. Clique em **Activate License** para ativar a licença.
-5. Se necessário, use **Refresh License** para buscar o status mais recente.
-
-![Tela de ativação de licença no dashboard](../assets/screenshots/plugin/license/dashboard-license-screen.png)
-
-### Depois da ativação
-
-- Se o status da licença aparecer como `active` ou `grace`, os recursos Pro já estão disponíveis.
-- O plugin e o dashboard compartilham o mesmo estado de licença, então a ativação feita em um deles aparece no outro.
-- Use **Refresh** ou **Refresh License** sempre que quiser verificar o status mais recente novamente.
-
-## Comparação de Recursos
-
-| Recurso | Basic | Pro |
-|---------|:-----:|:---:|
-| Criação/edição de scripts | ✅ | ✅ |
-| Criar/excluir/mover instâncias | ✅ | ✅ + operações em massa |
-| Ler/modificar propriedades | ✅ | ✅ + alterações em massa |
-| Seleção, tags, busca | ✅ | ✅ |
-| Controle de câmera | ✅ | ✅ |
-| Monitoramento de logs | ✅ | ✅ |
-| Execução de código Luau | ✅ | ✅ |
-| Sincronização de projeto | Studio → Local unidirecional | Bidirecional + direção/modo por tipo |
-| Sync multi-place | — | Até 3 Places simultaneamente |
-| Histórico de mudanças | — | Rastrear mudanças antes de aplicar |
-| Controle de playtest | — | Reproduzir / parar / pausar / retomar + testes automáticos |
-| Geração/edição de terrain | — | Bloco, esfera, cilindro, cunha, substituição de material |
-| Busca/inserção de assets | — | Pesquisar no marketplace do Roblox e inserir diretamente |
-| Análise espacial | — | Raycast, encontrar chão, detecção de colisão |
-| Controle de ambiente | — | Iluminação, atmosfera, céu, hora do dia |
-| Áudio / Animação | — | Reprodução de som, carregar/reproduzir animações |
-| Eficiência de tokens IA | Ações individuais | Menos chamadas com ações em massa |

package/docs/pt-br/sync/luau-lsp.md

@@ -1,41 +0,0 @@
-# Usar `luau-lsp` com WEPPY Sync
-
-O WEPPY Sync pode gerar automaticamente os arquivos sourcemap que o `luau-lsp` precisa, para que voce habilite recursos de editor com contexto de Roblox sem montar um projeto Rojo separado.
-
-## O que o WEPPY grava
-
-Depois que o Full Sync termina, o WEPPY grava:
-
-- Place sourcemap: `weppy-project-sync/place_<id>/sourcemap.json`
-- Arquivo representativo da raiz: `weppy-project-sync/sourcemap.json`
-
-Para a maioria dos usuarios, o caminho recomendado e `weppy-project-sync/sourcemap.json`.
-
-## O que melhora
-
-Quando o `luau-lsp` usa o sourcemap do WEPPY, melhora:
-
-- Autocomplete de `game.*`
-- Navegacao entre scripts sincronizados
-- Resolucao de `require` entre scripts sincronizados
-
-## Configuracao recomendada
-
-1. Execute o Full Sync uma vez para que o WEPPY crie `weppy-project-sync/sourcemap.json`.
-2. Aponte a configuracao de sourcemap do `luau-lsp` no seu editor para `weppy-project-sync/sourcemap.json`.
-3. Se o seu cliente puder desativar a geracao automatica com Rojo, defina `luau-lsp.sourcemap.autogenerate` como `false`.
-
-Exemplo de configuracao no VSCode:
-
-```json
-{
-  "luau-lsp.sourcemap.enabled": true,
-  "luau-lsp.sourcemap.autogenerate": false,
-  "luau-lsp.sourcemap.sourcemapFile": "weppy-project-sync/sourcemap.json"
-}
-```
-
-## Observacao sobre Multi-place
-
-`weppy-project-sync/sourcemap.json` acompanha o place representativo atual do projeto.
-Se voce precisar fixar um place especifico, aponte o `luau-lsp` diretamente para `weppy-project-sync/place_<id>/sourcemap.json`.