A Puppeteer-based server for remote debugging, E2E testing, and DOM inspection.
DOM Analyzer MCP Server
Introduzione
Il progetto dom-analyzer-mcp è un DOM Analyzer/E2E server MCP basato su Puppeteer per controllare un'app frontend in un URL configurabile.
- Percorso:
server.ts - Stack: Model Context Protocol (MCP) + Puppeteer
- Obiettivo: fornire comandi remoti di debug, test e ispezione DOM/CSS rete.
Configurazione esterna
File: config.json
Esempio:
{
"targetUrl": "http://localhost:4200",
"headless": true
}
targetUrl: URL dell'app da esplorare (es. server dev locale)headless: booleano per avvio Puppeteer headless
Struttura generale
Variabili di stato globali:
browser: Browser(Puppeteer)page: Page(Puppeteer)networkRequests: {url, method, status?, response?}[]consoleErrors: string[]
Core:
initBrowser(url = 'http://localhost:4200'): inizializza Puppeteer con retry, intercetta request/response.main(): avvia il server MCP, registra console errors e connetteStdioServerTransport.
Tool MCP disponibili
1) `take_screenshot`
Scatta uno screenshot della pagina o elemento selezionato.
Input:
selector(opzionale): CSS selector dell'elemento.navigateTo(opzionale): URL da visitare prima di catturare.
Output:
contentcontexteimage(base64 PNG).
2) `read_dom`
Restituisce l'HTML (outerHTML) del body o elemento specificato.
Input:
selector(opzionale): CSS selector.
Output:
content[0].text= HTML.
3) `get_computed_styles`
Recupera gli stili computati di un elemento.
Input:
selector(required)properties(array di string, opzionale)
Output:
- JSON con proprietà CSS richieste o tutte.
4) `get_network_requests`
Lista chiamate HTTP intercettate.
Input:
filterUrl(opzionale)filterMethod(opzionale, GET/POST/PUT/DELETE/PATCH)limit(opzionale, default 50)
Output:
- JSON array richieste.
5) `execute_js`
Esegue JS nella pagina e ritorna il risultato.
Input:
script(string)
Output:
- JSON value o errore.
6) `navigate_to`
Naviga a URL o route dell'app.
Input:
url(obbligatorio)
Behaviour:
page.goto+ resetnetworkRequests.
7) `get_console_errors`
Recupera console error/warn catturati.
Output:
- lista errori (stringhe) o
Nessun errore in console.
8) `click`
Simula click su elemento.
Input:
selector(obbligatorio)
Behaviour:
page.waitForSelector(selector)+page.click(selector).
9) `type`
Inserisce testo in input.
Input:
selector(obbligatorio)text(obbligatorio)
Behaviour:
page.waitForSelector(selector)+page.type(selector, text).
10) `wait_for_selector`
Attende elemento nel DOM.
Input:
selector(obbligatorio)timeout(opzionale, default 10000ms)
11) `reset_app`
Resetta stato app e ricarica.
Behaviour:
- pulisce localStorage/sessionStorage/cookie
page.goto('http://localhost:4200')- reset
networkRequests
12) `get_storage`
Legge local/sessionStorage.
Input:
type(localStorage|sessionStorage, defaultlocalStorage)key(opzionale)
13) `set_storage`
Scrive local/sessionStorage.
Input:
type(localStorage|sessionStorage, defaultlocalStorage)key(string)value(string)
14) `get_performance_metrics`
Restituisce metriche di performance Puppeteer + window.performance.
Output:
- JSON con
metricseperfTiming.
Comandi consigliati per test e debug
reset_appper stato deterministico.wait_for_selectorprima di click/type su elementi dinamici.get_network_requestsper validare API call.get_console_errorsper errori JS.get_computed_stylesper assertion visuale.
Suggerimenti operativi (migliorie future)
- Aggiungere
assert_*(assertElementVisible, assertText) come tool. - Aggiungere opzione
headless/headfuldinamica. - Implementare
screenshot_diffepage_trace. - Aggiungere supporto per multi-page
targeteframe.
Esempio d'uso rapido (MCP request)
{
"name": "take_screenshot",
"input": {"navigateTo": "http://localhost:4200"}
}
{
"name": "click",
"input": {"selector": "button#submit"}
}
{
"name": "get_network_requests",
"input": {"filterMethod": "GET", "limit": 20}
}
Avvio server
Eseguire da terminale:
cd dom-analyzer-mcp
PUPPETEER_SKIP_DOWNLOAD=true npm i
npm run build
npm start
Il server continua a leggere da stdin/stdout e risponde alle chiamate MCP.
Made by Elia at 01:15am >:)
Tools (14)
take_screenshotCaptures a screenshot of the page or a specific element.read_domReturns the outerHTML of the body or a specified element.get_computed_stylesRetrieves computed CSS styles for an element.get_network_requestsLists intercepted HTTP network calls.execute_jsExecutes JavaScript directly within the browser page.navigate_toNavigates the browser to a specific URL or route.get_console_errorsRetrieves captured console errors and warnings.clickSimulates a mouse click on a specified element.typeTypes text into a specified input element.wait_for_selectorWaits for a specific element to appear in the DOM.reset_appResets the application state, clears storage, and reloads.get_storageReads data from localStorage or sessionStorage.set_storageWrites data to localStorage or sessionStorage.get_performance_metricsReturns Puppeteer and window.performance metrics.Configuration
{"targetUrl": "http://localhost:4200", "headless": true}