dom-explorer
Launches and controls a visible Google Chrome/Chromium browser for interactive DOM inspection, with visual overlays, highlighted elements, and click-to-select handling.
Generates Robot Framework Page Object resources with variables and reusable keywords, supporting both Browser Library and SeleniumLibrary locator syntax.
Creates SeleniumLibrary-compatible locators and Page Object resource files for the inspected DOM elements to be used in automated Robot Framework tests.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@dom-explorer Open https://example.com/login and generate a resilient Robot Framework locator for the email input"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
🌐 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
.resourcecompletos 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(oukilo.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):
Clique no ícone de Configurações (⚙️) na barra lateral do Kilo Code.
Clique na aba Agent Behaviour à esquerda.
Acesse a sub-aba MCP Servers.
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"
}
}Formato de comando: O campo
"command"deve ser uma lista com o executável e seus argumentos.Permissões automáticas: A chave
"permission": { "dom-explorer_*": "allow" }permite que o Kilo Code execute as ferramentas do DOM Explorer sem abrir caixas de diálogo para confirmação manual a cada inspeção de elemento.Verificação via CLI do Kilo: Você pode listar e depurar a conexão executando:
kilo mcp list kilo mcp debug dom-explorer
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)
Ferramenta | Parâmetros | Descrição |
|
| Abre o navegador na URL indicada e ativa o inspetor visual. |
| nenhum | Retorna os dados detalhados do último elemento clicado/selecionado pelo usuário. |
| nenhum | Lista o histórico de todos os elementos inspecionados durante a sessão atual. |
|
| Varre o DOM buscando elementos interativos por critérios textuais ou semânticos. |
|
| Destaca visualmente um elemento na página e valida se o seletor é único. |
|
| Gera o conteúdo completo de um arquivo |
| nenhum | Encerra o navegador e finaliza a sessão. |
🧪 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}Available Tools
7 toolsclose_browserA
Encerra a sessão do navegador e limpa os recursos.
Inputs: no named parameters. Returns: result
export_robot_resourceA
Gera um arquivo de recurso (.resource) completo para o Robot Framework baseado nos elementos inspecionados até o momento, contendo a seção *** Variables *** e *** Keywords *** (Page Object Pattern).
Args: page_name: Nome da página ou componente (ex: 'LoginPage', 'DashboardHeader'). library: Biblioteca alvo do Robot Framework ('Browser' para Playwright ou 'SeleniumLibrary'). include_children: Inclui o componente selecionado e seus descendentes. only_interactive: Limita descendentes a elementos interativos. max_depth: Profundidade máxima dos descendentes incluídos. output_path: Caminho opcional onde o arquivo .resource será gravado.
Inputs: page_name (required), library, max_depth, output_path, +2 more. Returns: result
get_selected_elementA
Recupera o último elemento selecionado/clicado pelo usuário no navegador. Retorna metadados completos (tag, id, classes, atributos, texto), além de locators ranqueados para Robot Framework (Browser Library e SeleniumLibrary) e keywords prontas.
Inputs: no named parameters. Returns: result
get_selection_historyA
Retorna o histórico de todos os elementos selecionados/inspecionados na sessão atual.
Inputs: no named parameters. Returns: result
highlight_elementA
Destaca visualmente um elemento na página do navegador através de um seletor e valida se ele é único.
Args: selector: Seletor CSS ou ID a validar e destacar (ex: '#login-btn' ou '[data-testid="submit"]').
Inputs: selector (required). Returns: result
launch_browserA
Abre um navegador visível (headful por padrão) na URL informada e injeta o inspetor do DOM Explorer.
Args: url: O endereço web para navegar (ex: 'https://exemplo.com.br' ou 'localhost:3000'). headless: Se True, roda em segundo plano. Padrão False (abre janela visível para o usuário interagir). browser_type: Tipo de navegador ('chromium', 'firefox', 'webkit'). Padrão 'chromium'.
Inputs: url (required), headless, browser_type. Returns: result
scan_elementsA
Varre o DOM da página atual procurando elementos interativos por critérios textuais ou semânticos. Útil para mapear formulários ou botões sem necessidade de clicar em cada um manualmente.
Args: selector: Seletor CSS específico para buscar (ex: 'form.login input'). tag: Filtrar por tag HTML (ex: 'button', 'input', 'select', 'a'). role: Filtrar por ARIA role (ex: 'button', 'checkbox', 'tab'). text: Filtrar por texto visível parcial (case-insensitive, ex: 'Salvar' ou 'Entrar'). limit: Quantidade máxima de elementos a retornar (padrão 25).
Inputs: tag, role, text, limit, +1 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Most tools target distinct actions: browser lifecycle, element selection retrieval, scanning, highlighting, and export. The main potential confusion is between get_selected_element and get_selection_history, but the current-element vs history distinction is clear enough.
All tool names follow a consistent verb_noun pattern in English (get_selected_element, launch_browser, scan_elements, highlight_element, export_robot_resource, close_browser). No mixed casing or stylistic deviations.
Seven tools is a well-scoped size for a DOM exploration and Robot Framework export server. Each tool contributes to a clear workflow without redundancy or bloat.
The set covers browser lifecycle, element discovery/inspection, highlighting, history, and resource file generation. Minor gaps include no navigation/refresh tool and no direct single-element fetch by selector, but these can be worked around.
Maintenance
Related MCP Connectors
Playwright selector risk checks with healing suggestions and receipts.
Write, run and check natural-language browser tests of your web app from your AI assistant.
Browser-based QA for AI-built software. Test pages with real browsers via agents.
Give your AI agent a QA wingman. Find UX bugs and verify fixes.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables AI assistants to inspect, debug, and test web pages using Playwright. Provides comprehensive DOM inspection, visibility debugging, layout validation, and element finding capabilities in real browser environments.3454 npm5MIT
- AlicenseAqualityDmaintenanceGenerates intelligent Playwright locators with reliability rankings, creates Page Object Models, and runs test automation scripts directly from your IDE or AI assistant.510 npm1MIT
- AlicenseNot gradedqualityDmaintenanceEnables generating Robot Framework test cases with SeleniumLibrary, creating page object models, and performing performance monitoring through natural language.MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to drive Robot Framework through natural language, discovering keywords, running live test steps across web, mobile, API, database, and desktop targets, and generating clean .robot test suites from plain-English instructions.Apache 2.0