GDD (Giggly-Dazzling-Duckling)

GDD — Giggly-Dazzling-Duckling

Fazenda de navegadores controlada por IA na sua máquina
Simule vários usuários reais em 22 tipos de dispositivos — teste seu site como se fosse o dia do lançamento.

Como Funciona

Você: Abra 3 iPhones e um desktop, navegue até myapp.com, teste o formulário de cadastro em todos os dispositivos

Claude Code cria 4 navegadores com emulação de dispositivos, navega cada um até o seu app, preenche o formulário, tira screenshots e verifica o console em busca de erros — tudo em paralelo.

gdd_add_players(3, device="iPhone 15 Pro")    → players [1, 2, 3]
gdd_add_players(1, device="Desktop 1080p")    → player  [4]
gdd_navigate(1, "https://myapp.com")          → all 4 browsers open your app
gdd_tap(1, "#signup-btn")                     → taps signup on iPhone
gdd_screenshot(1)                             → captures the result
gdd_get_console(1, level="error")             → checks for JS errors

O GDD executa N instâncias isoladas de Chromium, cada uma com seu próprio perfil, cookies, emulação de dispositivo, geolocalização e condições de rede. Ele expõe 39 ferramentas MCP via HTTP em localhost:9700.

Instalação

O GDD vem em duas versões. O Server é headless — é apenas o backend MCP, roda em qualquer lugar (inclusive em máquinas sem display) e é tudo que você precisa para automação pura com IA. O app desktop adiciona uma GUI: uma grade ao vivo de miniaturas de navegadores nas quais você pode clicar para assumir uma sessão manualmente. O Server roda na porta 9700 e o app desktop na 9800 — então você pode executar os dois lado a lado.

Server (headless) — o backend MCP:

App desktop (GUI) — uma grade ao vivo de miniaturas de navegadores nas quais você pode clicar:

O app Windows usa WebView2; o app Linux/macOS (construído com Avalonia) controla janelas reais de Chromium posicionadas fora da tela. Binário autossuficiente, ~70 MB. Nenhuma instalação do .NET é necessária. O Chromium é baixado automaticamente no primeiro início.

Comando único (Linux):

curl -sL https://github.com/Cap-of-tea/GDD/releases/latest/download/GDD-Server-Linux.tar.gz | tar xz && chmod +x GDD.Headless && ./GDD.Headless

# Run (headless, port 9700)
docker run -p 9700:9700 ghcr.io/cap-of-tea/gdd

# Or build locally
docker build -t gdd .
docker run -p 9700:9700 gdd

Por padrão, os navegadores iniciam em modo headed (janelas visíveis). Adicione --headless para CI/CD. Outras flags: --stealth e --stealth-max para mascaramento anti-bot, --update para auto-atualização, --version e --help. A seção Configuração abaixo lista todas as flags e variáveis de ambiente.

Conecte-se ao Seu Cliente de IA

Adicione ao .mcp.json e reinicie o seu cliente de IA:

{
  "mcpServers": {
    "gdd": {
      "url": "http://localhost:9700/mcp"
    }
  }
}

Pronto. Inicie o GDD e peça ao Claude ou ao Cursor para testar o seu app.

Usuários do Claude Desktop: Baixe o arquivo .mcpb em Releases e abra-o — o GDD instala como uma extensão de desktop com um clique. Nenhuma configuração manual é necessária.

{
  "servers": {
    "gdd": {
      "type": "http",
      "url": "http://localhost:9700/mcp"
    }
  }
}

{
  "mcp": {
    "servers": {
      "gdd": {
        "type": "http",
        "url": "http://localhost:9700/mcp"
      }
    }
  }
}

{
  "servers": {
    "gdd": {
      "type": "stdio",
      "command": "bash",
      "args": ["/absolute/path/to/Scripts/mcp-proxy.sh"]
    }
  }
}

{
  "permissions": {
    "allow": [
      "mcp__gdd__*"
    ]
  }
}

{
  "mcpServers": {
    "gdd": {
      "command": "powershell",
      "args": ["-ExecutionPolicy", "Bypass", "-File", "C:/path/to/Scripts/mcp-proxy.ps1"]
    }
  }
}

{
  "mcpServers": {
    "gdd": {
      "command": "bash",
      "args": ["/path/to/Scripts/mcp-proxy.sh"]
    }
  }
}

bash Scripts/install-launchd.sh            # headed (default)
bash Scripts/install-launchd.sh --headless  # for CI/CD

mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/gdd.service << 'EOF'
[Unit]
Description=GDD Multi-Browser Testing Server
[Service]
ExecStart=/path/to/GDD.Headless
WorkingDirectory=/path/to/gdd-directory
Restart=on-failure
[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now gdd

curl -X POST http://localhost:9700/mcp -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"gdd_add_players","arguments":{"count":1}}}'

Recursos

• Multi-dispositivo — Execute N instâncias isoladas de Chromium com 22 presets de dispositivos (celulares, tablets, desktops)
• Nativo para IA — 39 ferramentas MCP para Claude Code, Cursor ou qualquer cliente compatível com MCP
• Multiplataforma — GUI nativa com um mural de vídeo ao vivo no Windows, Linux e macOS, além de um servidor headless para CI/CD
• Interação completa — Navegue, toque, digite, pressione teclas e atalhos, arraste, deslize, role, passe o mouse, lide com diálogos e tire screenshots
• Teclado real — Digitar envia pressionamentos de tecla genuínos e confiáveis (a cadeia completa keydown→input), então máscaras de entrada, autocompletar e maxlength se comportam exatamente como para um usuário real, e editores rich-text (contenteditable) funcionam; gdd_press lida com teclas únicas e atalhos como Enter, Tab, Escape e Ctrl+A
• Layouts de teclado físicos — Os pressionamentos de tecla carregam o code/keyCode real do teclado da localidade emulada: o russo ЙЦУКЕН coloca «а» no KeyF físico, o francês AZERTY e o alemão QWERTZ remapeiam suas teclas, acentos de tecla morta e símbolos AltGr funcionam. O layout segue gdd_set_language automaticamente (US, RU, DE, FR)
• Entrada semelhante à humana — humanize=true conduz um caminho contínuo do cursor (Bézier cúbico com easing e micro-variação) que é mantido entre cliques, hovers e arrastos; toques enviam uma única entrada apropriada ao dispositivo (toque ou mouse), nunca ambas
• Furtividade anti-bot — --stealth opcional mascara as marcas usuais de automação (navigator.webdriver, etc.); --stealth-max adiciona evasões de headless/datacenter (client hints de user-agent coerentes, um fornecedor WebGL plausível, métricas de dispositivo realistas) — em um container headless, isso reduziu pela metade a pontuação de headless do CreepJS
• Suporte a proxy — Roteie cada navegador por um proxy upstream com GDD_PROXY (com autenticação opcional)
• Reescrita de cabeçalhos — gdd_set_headers pode remover X-Frame-Options/CSP frame-ancestors para carregar um site em um iframe, ou adicionar/substituir cabeçalhos de resposta
• Emulação de dispositivo — Tamanho de tela, DPR, toque, user-agent, geolocalização, fuso horário, idioma
• Controle de rede — Simule 4G, Fast 3G, Slow 3G ou offline por navegador
• Diagnósticos — Erros de console, tráfego de rede, métricas de desempenho, notificações push
• Sinalizador de erros — Toda resposta de ferramenta avisa sobre erros de JS em todos os navegadores automaticamente
• Pronto para Docker — Imagem oficial no GHCR (ghcr.io/cap-of-tea/gdd), listada no MCP Registry
• Auto-atualização — Verificação de versão integrada e atualização com um comando

Ferramentas MCP (39)

Gerenciamento de Players

Navegação

Interação

Leitura e Screenshots

Emulação

Estado e Diagnósticos

Autenticação e Execução

Armazenamento do Navegador

Ajuda e Atualizações

Arquitetura

Client (AI agent / curl / script)
         │ POST /mcp (JSON-RPC 2.0)
         ▼
    McpServer (:9700)
    Streamable HTTP + SSE
         │
         ▼
    McpToolRegistry (39 tools)
    Player · Navigation · Interaction · Read
    Emulation · Auth · State · Diagnostics
         │
         ▼
    IPlayerManager
    MainViewModel (WPF) / DesktopPlayerManager (Avalonia) / HeadlessPlayerManager
         │
         ▼
    IBrowserEngine Instances
    WebView2 (Win GUI)  |  Playwright (Desktop GUI + headed/headless server)
    Each: own profile, CDP session, emulation

Edições

O GDD é distribuído como três aplicativos sobre um núcleo compartilhado. As duas GUIs diferem apenas no toolkit de desktop (WebView2 no Windows, Avalonia no Linux/macOS); todas as três expõem as mesmas 39 ferramentas MCP.

Pilha de Tecnologias

BrowserXn.sln
├── src/
│   ├── GDD.Core/              ← Shared library (net8.0)
│   │   ├── Abstractions/      ← IBrowserEngine, IPlayerManager, ...
│   │   ├── Mcp/               ← MCP server, tools, protocol
│   │   ├── Models/            ← Device, Location, Network presets
│   │   ├── Services/          ← CDP, Emulation, Monitoring services
│   │   └── Collections/       ← RingBuffer
│   ├── BrowserXn/             ← Windows GUI (WPF + WebView2)
│   │   ├── Engines/           ← WebView2ControlAdapter
│   │   ├── ViewModels/        ← MVVM (MainViewModel : IPlayerManager)
│   │   ├── Views/             ← XAML + VideoWallPanel
│   │   └── ...
│   ├── GDD.Desktop/           ← Linux/macOS GUI (Avalonia + Playwright)
│   │   ├── Engines/           ← PlaywrightHeadedEngine (headed, parked off-screen)
│   │   ├── ViewModels/        ← MainViewModel (DesktopPlayerManager)
│   │   ├── Views/             ← AXAML + VideoWallPanel
│   │   └── Scripts/           ← mcp-proxy.sh, setup-macos.sh, install-deps.sh
│   └── GDD.Headless/          ← Cross-platform server (Playwright)
│       ├── Engines/           ← PlaywrightEngine
│       ├── Platform/          ← HeadlessPlayerManager
│       └── Scripts/           ← mcp-proxy.sh, mcp-proxy.ps1
└── .github/workflows/         ← CI/CD (8 build targets + auto-release)

{
  "GDD": {
    "FrontendUrl": "about:blank",
    "BackendUrl": "http://localhost:8080/api/v1",
    "BotToken": "",
    "McpPort": 9700,
    "DataFolderRoot": "",
    "Stealth": false
  }
}

# Windows GUI (requires Windows 10/11 + WebView2)
dotnet publish src/BrowserXn/BrowserXn.csproj -c Release -p:PublishSingleFile=true -o ./publish/win-gui

# Cross-platform headless
dotnet publish src/GDD.Headless/GDD.Headless.csproj -c Release -r linux-x64 --self-contained -o ./publish/linux-x64
dotnet publish src/GDD.Headless/GDD.Headless.csproj -c Release -r osx-arm64 --self-contained -o ./publish/osx-arm64
dotnet publish src/GDD.Headless/GDD.Headless.csproj -c Release -r win-x64 --self-contained -o ./publish/win-x64

Documentação

• GDD-MANUAL.md — Manual completo de uso com exemplos de fluxos de trabalho
• GDD-ARCHITECTURE.md — Detalhamento da arquitetura
• GDD-PROMPT.md — Instruções de agente Claude para integração MCP
• DEPLOY-RAILWAY.md — Hospede o GDD como um servidor MCP remoto no Railway (atrás de um proxy com autenticação por token)
• CONTRIBUTING.md — Diretrizes de contribuição

Privacidade

Licença

imVS©, livre para uso pessoal.

Código-fonte disponível — Não comercial. Livre para uso pessoal, educacional e pesquisa. Uso comercial requer licença paga. Veja LICENSE para termos completos.

Licenciamento comercial: 2vsmirnov@gmail.com