🌐 DOM Explorer MCP Server

Um servidor MCP (Model Context Protocol) e ecossistema de automação inteligente em Python para exploração interativa do Document Object Model (DOM) e geração de seletores e Page Objects resilientes para o Robot Framework (suportando tanto a Browser Library quanto a SeleniumLibrary).

🚀 Funcionalidades

• Inspeção Interativa em Navegador Visível (Headful):

  • Abre uma janela real do Google Chrome / Chromium na URL fornecida.

  • Injeta automaticamente um script de overlay com destaque visual (bounding box), tooltip informativo e barra de controle flutuante.

  • Intercepta cliques de inspeção sem disparar navegações acidentais em botões ou links.

  • Alternância rápida entre Modo Inspeção e Modo Navegação Livre.

• Extração Completa de Metadados do DOM:

  • Tags HTML, IDs, classes, nomes, placeholders, tipos e textos visíveis.

  • Atributos de acessibilidade (role, aria-label) e de teste (data-testid, data-test, data-cy, data-qa).

  • Hierarquia de elementos pais (parent chain) e coordenadas de renderização (bounding box).

• Gerador de Locators & Variáveis para Robot Framework:

  • Converte seletores automaticamente para Browser Library (id=..., role=button[name="..."], text="...", [data-testid="..."]) e SeleniumLibrary (id:..., name:..., xpath:..., css:...).

  • Algoritmo de descarte de IDs dinâmicos de frameworks (como :r0:, ext-gen-123, ember456).

  • Nomenclatura padronizada de variáveis (ex: ${BTN_SUBMIT_LOGIN}, ${INPUT_EMAIL_USUARIO}).

• Varredura Textual e Semântica (scan_elements):

  • Mapeia elementos em lote por tag, role ou texto visível direto pelo Agente sem precisar clicar em cada um manualmente.

• Validação e Destaque Visual (highlight_element):

  • Testa qualquer seletor na página aberta, garantindo unicidade (match_count == 1) e destacando-o na cor vermelha.

• Exportação de Page Objects (export_robot_resource):

  • Gera arquivos .resource completos contendo *** Settings ***, *** Variables *** e *** Keywords *** reutilizáveis.

Related MCP server: LocatorLabs MCP Server

📦 Instalação e Configuração

Pré-requisitos

• Python 3.10 ou superior.

• Ferramenta uv instalada.

Instalação das Dependências

git clone <repo-url> dom-explorer
cd dom-explorer

# Sincronizar dependências do ambiente virtual
uv sync

# Instalar os binários do navegador Playwright
uv run playwright install chromium

⚙️ Configuração nos Clientes MCP

1. Kilo Code

No Kilo Code, os servidores MCP são configurados dentro do arquivo principal de configuração do Kilo (kilo.jsonc ou .kilo/kilo.jsonc), sob a chave raiz "mcp".

Onde configurar:

• Nível de Projeto (Recomendado): Crie ou edite .kilo/kilo.jsonc (ou kilo.jsonc) na raiz do seu projeto.

• Nível Global: ~/.config/kilo/kilo.jsonc (aplica-se a todos os projetos).

Via Interface do Kilo Code (VS Code Extension):

1. Clique no ícone de Configurações (⚙️) na barra lateral do Kilo Code.

2. Clique na aba Agent Behaviour à esquerda.

3. Acesse a sub-aba MCP Servers.

4. Clique em Add Server, selecione Local (stdio) e informe o comando.

Configuração JSON (.kilo/kilo.jsonc ou ~/.config/kilo/kilo.jsonc):

{
  "mcp": {
    "dom-explorer": {
      "type": "local",
      "command": [
        "uv",
        "run",
        "--directory",
        "/home/odoni_r/projects/dom-explorer",
        "dom-explorer"
      ],
      "enabled": true,
      "timeout": 30000
    }
  },
  "permission": {
    "dom-explorer_*": "allow"
  }
}

2. Antigravity IDE / Claude Desktop / Cursor

Adicione a entrada correspondente no seu arquivo de configuração (mcp_config.json ou claude_desktop_config.json):

{
  "mcpServers": {
    "dom-explorer": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/home/odoni_r/projects/dom-explorer",
        "dom-explorer"
      ]
    }
  }
}

🛠️ Ferramentas Disponíveis no MCP (Tools)

🧪 Execução de Testes

Os testes cobrem unitariamente a geração de seletores, detecção de IDs dinâmicos, validação de schemas MCP e ciclo de vida Playwright:

uv run pytest -v

📝 Exemplo de Arquivo .resource Gerado

*** Settings ***
Documentation    Page Object Resource para LoginPage
Library          Browser

*** Variables ***
${INPUT_USER}                     id=user-name
${INPUT_PASSWORD}                 id=password
${BTN_LOGIN}                      [data-testid="login-submit-btn"]

*** Keywords ***
Fill Input User
    [Arguments]    ${value}
    [Documentation]    Preenche o campo Input User com o valor informado
    Fill Text    ${INPUT_USER}    ${value}

Fill Input Password
    [Arguments]    ${value}
    [Documentation]    Preenche o campo Input Password com o valor informado
    Fill Text    ${INPUT_PASSWORD}    ${value}

Click Btn Login
    [Documentation]    Clica no botão Btn Login
    Click    ${BTN_LOGIN}