playwright-trace-decoder-mcp

Servidor MCP para desempaquetar y analizar archivos trace.zip de Playwright

Documentación

Traducción al Español

Preservando todos los tokens y estructura. A continuación el documento traducido:

🎭 playwright-trace-decoder-mcp

Un servidor MCP que desempaqueta y estructura los archivos trace.zip de Playwright para que los agentes de IA puedan realizar análisis de causa raíz en fallos de CI, sin ahogarse en JSON crudo ni reventar la ventana de contexto.

🤔 El Problema

Cuando una prueba de Playwright falla en CI, obtienes un trace.zip. Es un blob binario. Los LLM no pueden leerlo de forma nativa, y volcar el contenido crudo supera la ventana de contexto. Los ingenieros terminan copiando fragmentos de logs a ChatGPT manualmente, como si estuviéramos en 2022.

Este servidor MCP resuelve eso: 16 herramientas enfocadas que exponen exactamente la señal que un agente necesita para diagnosticar un fallo, con paginación y compresión ARIA para mantener los costos de tokens bajos.

🐸 Ejemplo de Investigación de Fallo E2E

Así es como un agente de IA usa las nuevas herramientas en v0.3.0 para encontrar e inspeccionar un fallo al instante:

Localizar el error exacto en el código fuente mediante map_locator_to_source:

// Request arguments
{ "trace_path": "/path/to/trace.zip" }

// Response payload
{
  "action_type": "Click locator('#super-toad-not-found')",
  "locator": "#super-toad-not-found",
  "error": "TimeoutError: locator.click: Timeout 5000ms exceeded.",
  "step_title": "Click locator('#super-toad-not-found')",
  "stack": [
    {
      "file": "/Users/albertdev/Projects/ideas/sample-playwright-project/tests/google-pom.spec.ts",
      "line": 18,
      "column": 17
    }
  ],
  "source_location": {
    "file": "/Users/albertdev/Projects/ideas/sample-playwright-project/tests/google-pom.spec.ts",
    "line": 18,
    "column": 17
  }
}

¡No más suposiciones! El agente sabe exactamente qué archivo, línea y columna causaron el tiempo de espera agotado.

Extraer los fotogramas visuales críticos alrededor del fallo mediante extract_critical_frames:

// Request arguments
{ "trace_path": "/path/to/trace.zip", "limit": 1 }

// Response payload
[
  {
    "timestamp": 1779137404287,
    "mime_type": "image/jpeg",
    "step_title": "Clicking #super-toad-not-found element",
    "data": "/9j/4AAQSkZJRgABAQAAAQABAAD/..." // Base64 JPEG
  }
]

Permite al agente verificar visualmente el estado de la página inmediatamente antes/después del fallo sin tener que arrastrar listas masivas de imágenes.

Recortar la traza para ahorrar costos de almacenamiento/transferencia en CI mediante trim_trace_archive:

// Request arguments
{ "trace_path": "/path/to/trace.zip" }

// Response payload
{
  "original_size_bytes": 2449682,
  "trimmed_size_bytes": 511698,
  "compression_ratio_percent": 79,
  "trimmed_trace_path": "/path/to/trace.trimmed.zip"
}

Reduce trazas grandes eliminando capturas de pantalla fuera de la ventana crítica del fallo. ¡Ahorra un 79% de espacio en disco!

🛠️ Herramientas

Las herramientas se agrupan según cómo un agente debería secuenciarlas al diagnosticar un fallo.

Inspección — leer datos de la traza

Herramienta	Argumentos	Qué devuelve
`get_test_metadata`	`trace_path`	Navegador, plataforma, viewport, título de prueba, hora de inicio en reloj de pared
`get_trace_summary`	`trace_path`	Acción fallida + error de nivel superior + recuento total de acciones
`get_action_timeline`	`trace_path`, `limit`, `offset`	Lista paginada de todas las acciones con nombres de API, localizadores y tiempos
`get_filtered_network_logs`	`trace_path`, `limit`, `offset`	Solo respuestas 4xx/5xx — recursos estáticos (CSS, JS, fuentes, imágenes) eliminados
`get_console_errors`	`trace_path`, `limit`, `offset`	Excepciones JS y advertencias de la consola del navegador
`get_element_state_at_failure`	`trace_path`	Localizador fallido, mensaje de error y metadatos crudos antes/después
`extract_trace_metadata_strict`	`trace_path`	Versión de formato, desglose de sesiones de reintento, modo de carga HAR (embeber/adjuntar/omitir)

Todas las herramientas que devuelven listas admiten limit (1–500, por defecto 50) y paginación offset con una bandera has_more.

trace_path acepta una ruta local absoluta o una URL HTTPS — el servidor descarga el archivo automáticamente y lo cachea para la sesión.

Análisis de DOM / UI

Herramienta	Argumentos	Qué devuelve
`get_aria_accessibility_tree`	`trace_path`, `action_index?`	Árbol de accesibilidad ARIA como YAML compacto (~90% menos tokens que HTML crudo). Por defecto, la instantánea en la acción fallida.
`get_dom_mutation_delta`	`trace_path`, `action_index`	Diferencia de líneas ARIA antes vs después de una acción específica — solo elementos añadidos/eliminados, no dos dumps completos del DOM
`get_screenshot_at_failure`	`trace_path`, `screenshot_index?`	Captura JPEG en base64 más cercana al momento del fallo. Úsalo cuando el árbol ARIA esté vacío (captcha, página en blanco). `screenshot_index` te permite recorrer toda la línea de tiempo visual.
`analyze_race_conditions`	`trace_path`	Solicitudes de red que estaban en vuelo cuando se disparó una interacción o aserción
`correlate_dom_and_network`	`trace_path`	Para cada acción donde un fetch se completó y el DOM mutó dentro de ±100 ms: URL desencadenante, estado de respuesta, fragmento del cuerpo y nodos exactos añadidos/eliminados
`extract_critical_frames`	`trace_path`, `lookback_ms?`, `lookforward_ms?`, `limit?`	Extrae capturas clave de screencast (base64) de una ventana temporal alrededor del fallo, resueltas con títulos de paso

Análisis de causa raíz

Herramienta	Argumentos	Qué devuelve
`get_causal_chain_for_failure`	`trace_path`, `lookback_ms?`	Cadena cronológica de acciones precedentes, errores de red y errores de consola que llevan al fallo (ventana por defecto: 5 s)
`generate_error_signature`	`trace_path`	Hash SHA-1 estable de 12 caracteres del error normalizado — úsalo para agrupar fallos duplicados en ejecuciones de CI paralelas
`compare_traces`	`passing_trace_path`, `failing_trace_path`	Secuencia de acciones alineada con LCS entre una ejecución exitosa y una fallida: divergencia estructural, anomalías de tiempo (>500 ms), acciones no coincidentes, delta de red
`map_locator_to_source`	`trace_path`, `action_index?`	Mapea una interacción de navegador fallida (o un índice de acción específico) a la línea exacta del código de prueba mediante la pila de ejecución del runner

Análisis de rendimiento

Herramienta	Argumentos	Qué devuelve
`detect_performance_anomalies`	`trace_path`, `slow_action_threshold_ms?`, `frame_drop_threshold_ms?`	Lista clasificada de acciones lentas y caídas de frames con `suspected_cause` (hilo principal bloqueado / saturación de red / tiempo de espera de navegación). También informa duración p50/p95 y un indicador de fuga de memoria.
`trim_trace_archive`	`trace_path`, `divergence_only?`	Reduce el zip de la traza eliminando capturas de pantalla fuera de la ventana crítica del fallo (t_fail - 5s a t_fail + 1s). Devuelve la ruta recortada y el delta de tamaño.

💬 Flujo de trabajo sugerido para el agente

get_trace_summary              ← what failed?
get_causal_chain_for_failure   ← what led up to it?
get_aria_accessibility_tree    ← what did the page look like?
get_screenshot_at_failure      ← ARIA empty? get the actual screenshot
get_dom_mutation_delta         ← what changed right before the failure?
analyze_race_conditions        ← was a network request still pending?
correlate_dom_and_network      ← which fetch caused which DOM change?
compare_traces                 ← flaky? compare to a passing run
detect_performance_anomalies   ← timeout but no JS error? check for Long Tasks

🚀 Configuración

Compilar desde el código fuente

git clone https://github.com/vola-trebla/playwright-trace-decoder-mcp.git
cd playwright-trace-decoder-mcp
npm install
npm run build

Añadir a tu cliente MCP

Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`)

{
  "mcpServers": {
    "playwright-trace-decoder": {
      "command": "node",
      "args": ["/absolute/path/to/playwright-trace-decoder-mcp/dist/index.js"]
    }
  }
}

Cursor (`.cursor/mcp.json`) o VS Code (`.vscode/mcp.json`)

{
  "mcpServers": {
    "playwright-trace-decoder": {
      "command": "node",
      "args": ["/absolute/path/to/playwright-trace-decoder-mcp/dist/index.js"]
    }
  }
}

Claude Code

claude mcp add playwright-trace-decoder \
  node /absolute/path/to/playwright-trace-decoder-mcp/dist/index.js

Docker

docker build -t playwright-trace-decoder-mcp .

{
  "mcpServers": {
    "playwright-trace-decoder": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-v", "/path/to/traces:/traces", "playwright-trace-decoder-mcp"]
    }
  }
}

💬 Ejemplo de uso

Análisis básico de fallos

Pregunta a tu agente:

"La ejecución de CI falló. Aquí está la traza: /tmp/trace.zip. ¿Qué salió mal y por qué?"

El agente llama a get_trace_summary → get_causal_chain_for_failure → get_aria_accessibility_tree, profundizando según sea necesario — sin que tengas que copiar y pegar nada.

Cuando la página estaba en blanco o redirigida

"El árbol ARIA está vacío. ¿Puedes mostrarme qué había realmente en pantalla cuando falló?"

El agente llama a get_screenshot_at_failure y obtiene el JPEG tomado más cercano al momento del fallo — útil para detectar captchas, páginas de error o redirecciones inesperadas.

Diagnóstico de flakiness

"Esta prueba pasa localmente pero falla en CI. Compara estas dos trazas y dime qué fue diferente."

El agente llama a compare_traces, que alinea con LCS ambas secuencias de acciones y saca a la superficie la primera divergencia estructural, anomalías de tiempo y solicitudes de red que solo aparecieron en la ejecución fallida.

Agrupar fallos duplicados en ejecuciones de CI paralelas

"Tenemos 12 trazas fallidas de este pipeline. ¿Son todas el mismo fallo?"

Llama a generate_error_signature en cada una — firmas idénticas significan causa raíz idéntica, sin necesidad de leer cada traza.

Diagnosticar qué llamada API causó un cambio de DOM

"El modal apareció pero no sé qué fetch lo desencadenó."

correlate_dom_and_network une el registro HAR y las instantáneas de DOM automáticamente. Ejemplo de salida:

{
  "total_correlations": 1,
  "correlations": [
    {
      "action_id": "4:Locator.click",
      "triggering_request_url": "https://api.example.com/cart/items",
      "response_status_code": 200,
      "response_body_snippet": "{\"items\":[{\"id\":\"abc\",\"qty\":1}]}",
      "time_to_dom_mutation_ms": 38,
      "resulting_dom_mutations": [
        { "type": "added", "selector": "heading \"Cart (1 item)\"" },
        { "type": "removed", "selector": "button \"Add to cart\" [disabled]" }
      ]
    }
  ]
}

Tiempos de espera por rendimiento — no solo elementos faltantes

"La prueba agota el tiempo en goto, pero no hay error de JS. ¿Qué está bloqueando la página?"

detect_performance_anomalies inspecciona las brechas de fotogramas del screencast y marca Long Tasks. Ejemplo de salida:

{
  "anomalies": [
    {
      "kind": "slow_action",
      "blocked_action_id": "2:Frame.goto",
      "task_duration_ms": 4200,
      "threshold_ms": 500,
      "concurrent_network_load": 9,
      "frame_drop_count": 0,
      "worst_frame_gap_ms": 0,
      "suspected_cause": "network_saturation"
    }
  ],
  "suspected_memory_leak_flag": false,
  "p50_action_duration_ms": 95,
  "p95_action_duration_ms": 780,
  "total_frame_drop_count": 0
}

suspected_cause distingue un hilo principal bloqueado (main_thread_blocked — hay brechas de fotogramas), una cascada de fetchs concurrentes (network_saturation — ≥5 en vuelo) y un tiempo de espera de navegación/duro (timeout_or_navigation — duración >3 s sin otras señales).

Comprobar qué versión de Playwright y modo HAR usa una traza

"La traza proviene de una configuración de CI desconocida. ¿Están disponibles los datos del cuerpo de la respuesta?"

extract_trace_metadata_strict inspecciona el archivo antes de que ejecutes cualquier otra herramienta:

{
  "format_version": 6,
  "har_mode": "embed",
  "retry_sessions": [
    { "session_id": "s1", "failed": false },
    { "session_id": "s2", "failed": true }
  ],
  "failed_session_id": "s2"
}

har_mode: "embed" significa que los fragmentos del cuerpo están en línea. "attach" significa que están en archivos de recursos separados. "omit" significa solo cabeceras — correlate_dom_and_network devolverá response_body_snippet vacíos en ese caso.

🏗️ Arquitectura

trace.zip
  ├── *.trace          → JSONL: before/after action pairs, console events, frame snapshots
  ├── *.network        → JSONL: HAR resource-snapshot entries
  └── resources/
      ├── page@*.jpeg  → screenshots taken during the run
      └── ...          → fonts, stylesheets, other captured resources

El analizador transmite cada archivo línea por línea (sin división completa del buffer) y cachea los resultados en proceso con un LRU (máx. 50 entradas), claveado por ruta + mtime. Releer la misma traza no modificada cuesta cero I/O.

Las instantáneas de fotogramas almacenan el DOM como arrays anidados (["TAG", {attrs}, ...children]). El traductor ARIA recorre este árbol y genera YAML compacto, reduciendo el costo de tokens en ~90% frente al HTML crudo.

🏗️ Stack tecnológico

@modelcontextprotocol/sdk — runtime del servidor MCP
adm-zip — extracción de zip
zod v4 — validación de esquema de entrada
TypeScript, ESLint, Prettier, Husky, GitHub Actions CI

📋 Scripts

npm run build        # compile TypeScript → dist/
npm run lint         # ESLint
npm run format       # Prettier --write
npm run format:check # Prettier check (used in CI)

📄 Licencia

MIT