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 connette StdioServerTransport.

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:

• content con text e image (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 + reset networkRequests.

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, default localStorage)

• key (opzionale)

13) set_storage

Scrive local/sessionStorage.

Input:

• type (localStorage|sessionStorage, default localStorage)

• key (string)

• value (string)

14) get_performance_metrics

Restituisce metriche di performance Puppeteer + window.performance.

Output:

• JSON con metrics e perfTiming.

Comandi consigliati per test e debug

• reset_app per stato deterministico.

• wait_for_selector prima di click/type su elementi dinamici.

• get_network_requests per validare API call.

• get_console_errors per errori JS.

• get_computed_styles per assertion visuale.

Suggerimenti operativi (migliorie future)

• Aggiungere assert_* (assertElementVisible, assertText) come tool.

• Aggiungere opzione headless/headful dinamica.

• Implementare screenshot_diff e page_trace.

• Aggiungere supporto per multi-page target e frame.

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 >:)