Playwright Trace Decoder MCP

🎭 playwright-trace-decoder-mcp

An MCP server that unpacks and structures Playwright trace.zip archives so AI agents can perform root-cause analysis on CI failures — without drowning in raw JSON or blowing up the context window.

🤔 The Problem

When a Playwright test fails in CI, you get a trace.zip. It's a binary blob. LLMs can't read it natively, and dumping the raw contents exceeds the context window. Engineers end up copying log snippets into ChatGPT manually like it's 2022.

This MCP server solves that: 16 focused tools that expose exactly the signal an agent needs to diagnose a failure, with pagination and ARIA compression to keep token costs low.

🐸 E2E Failure Investigation Example

Here is a quick look at how an AI agent uses the new tools in v0.3.0 to instantly find and inspect a failure:

1. Locate the exact source code bug via 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 more guessing! The agent knows exactly which file, line, and column caused the timeout._

1. Extract critical visual frames around the failure via 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 } ]

_Allows the agent to visual-verify page state immediately before/after failure without pulling massive image lists._

1. Trim the trace to save CI storage / transfer costs via 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" }

_Shrinks large traces by deleting screenshots outside the critical failure window. Saved 79% of disk space!_

🛠️ Tools

Tools are grouped by how an agent should sequence them when diagnosing a failure.

Inspection — read trace data

All list-returning tools support limit (1–500, default 50) and offset pagination with a has_more flag.

trace_path accepts either an absolute local path or an HTTPS URL — the server downloads the file automatically and caches it for the session.

DOM / UI analysis

Root-cause analysis

Performance analysis

💬 Suggested agent workflow

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

🚀 Setup

Build from source

git clone https://github.com/vola-trebla/playwright-trace-decoder-mcp.git

cd playwright-trace-decoder-mcp npm install npm run build

Add to your MCP client

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) or 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"] } } }

💬 Example usage

Basic failure analysis

Ask your agent:

_"The CI run failed. Here's the trace: /tmp/trace.zip. What went wrong and why?"_

The agent calls get_trace_summary → get_causal_chain_for_failure → get_aria_accessibility_tree, drilling deeper as needed — without you copy-pasting anything.

When the page was blank or redirected

_"The ARIA tree is empty. Can