playwright-trace-decoder-mcp

🎭 playwright-trace-decoder-mcp

一个 MCP 服务，可解包并整理 Playwright trace.zip 归档，让 AI Agent 能够对 CI 失败进行根因分析，而无需淹没在原始 JSON 中，也不会撑爆上下文窗口。

🤔 问题

Playwright 测试在 CI 中失败时，你会得到一个 trace.zip。它是一团二进制数据。大模型无法直接读取，倾倒原始内容又会超出上下文窗口。工程师只能像在 2022 年那样，手动把日志片段复制到 ChatGPT 中。

这个 MCP 服务解决了这个问题：提供 16 个专用工具，只暴露 Agent 诊断失败所需的信号，并通过分页和 ARIA 压缩降低 Token 成本。

🐸 E2E 失败调查示例

下面快速展示 AI Agent 如何使用 v0.3.0 中的新工具，立即查找并检查失败：

1. 通过 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
     }
   }
   

   不再需要猜测！Agent 能准确知道哪个文件、哪一行、哪一列导致了超时。

2. 通过 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
     }
   ]
   

   Agent 可以立即通过视觉验证失败前后的页面状态，无需获取大量图像列表。

3. 通过 trim_trace_archive 精简跟踪归档，以节省 CI 存储和传输成本：

   // 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"
   }
   

   通过删除关键失败时间窗口之外的屏幕截图，缩小大型跟踪文件。节省了 79% 的磁盘空间！

🛠️ 工具

工具按 Agent 诊断失败时的推荐使用顺序分组。

检查 — 读取跟踪数据

工具	参数	返回内容
get_test_metadata	trace_path	浏览器、平台、视口、测试标题、挂钟开始时间
get_trace_summary	trace_path	失败操作 + 顶层错误 + 操作总数
get_action_timeline	trace_path、limit、offset	包含 API 名称、定位器和耗时的全部操作分页列表
get_filtered_network_logs	trace_path、limit、offset	仅包含 4xx/5xx 响应 — 已剔除静态资源（CSS、JS、字体、图像）
get_console_errors	trace_path、limit、offset	浏览器控制台中的 JS 异常和警告
get_element_state_at_failure	trace_path	失败的定位器、错误消息，以及原始的前后状态元数据
extract_trace_metadata_strict	trace_path	格式版本、重试会话明细、HAR 负载模式（嵌入/附加/省略）

所有返回列表的工具都支持 limit（1–500，默认值为 50）和 offset 分页，并提供 has_more 标记。

trace_path 接受绝对本地路径 或 HTTPS URL — 服务会自动下载文件，并为当前会话缓存。

DOM / UI 分析

工具	参数	返回内容
get_aria_accessibility_tree	trace_path, action_index?	以精简 YAML 格式返回 ARIA 无障碍树（比原始 HTML 少约 90% 的 token）。默认使用失败操作时的快照。
get_dom_mutation_delta	trace_path, action_index	对比特定操作前后的 ARIA 行，仅返回新增或移除的元素，而不是两份完整的 DOM 转储。
get_screenshot_at_failure	trace_path, screenshot_index?	返回最接近故障时刻的 Base64 JPEG 截图。当 ARIA 树为空时（如验证码、空白页面）可使用。screenshot_index 可用于查看完整的视觉时间线。
analyze_race_conditions	trace_path	返回交互或断言触发时仍在进行中的网络请求。
correlate_dom_and_network	trace_path	对每个在 ±100ms 内完成 fetch 且 DOM 发生变化的操作，返回触发 URL、响应状态、响应正文片段，以及新增或移除的确切节点。
extract_critical_frames	trace_path, lookback_ms?, lookforward_ms?, limit?	从故障前后的时间窗口中提取关键屏幕录制截图（Base64），并关联步骤标题。

根因分析

工具	参数	返回内容
get_causal_chain_for_failure	trace_path, lookback_ms?	按时间顺序返回导致故障的先前操作、网络错误和控制台错误链（默认窗口：5 s）。
generate_error_signature	trace_path	返回规范化错误的稳定 12 字符 SHA-1 哈希，可用于归组并行 CI 运行中的重复故障。
compare_traces	passing_trace_path, failing_trace_path	返回通过和失败运行之间按 LCS 对齐的操作序列：结构差异、时序异常（>500 ms）、未匹配操作和网络差异。
map_locator_to_source	trace_path, action_index?	通过运行器执行堆栈，将失败的浏览器交互（或指定的操作索引）映射到测试代码中的确切行。

性能分析

工具	参数	返回内容
detect_performance_anomalies	trace_path, slow_action_threshold_ms?, frame_drop_threshold_ms?	按优先级排列的慢操作和丢帧列表，并附带 suspected_cause（主线程阻塞／网络饱和／导航超时）。还会报告操作时长的 p50/p95 和内存泄漏标记。
trim_trace_archive	trace_path, divergence_only?	删除关键故障时间窗口（t_fail - 5s 至 t_fail + 1s）之外的截图，以缩小 trace 压缩包。返回裁剪后的路径和大小变化量。

💬 建议的 Agent 工作流

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

🚀 设置

从源代码构建

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

添加到 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）或 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"]
    }
  }
}

💬 使用示例

基本故障分析

向 Agent 提问：

“CI 运行失败了。这是 trace：/tmp/trace.zip。出了什么问题，原因是什么？”

Agent 会依次调用 get_trace_summary → get_causal_chain_for_failure → get_aria_accessibility_tree，并根据需要深入分析，无需你复制粘贴任何内容。

页面空白或发生重定向时

“ARIA 树为空。能给我看看失败时屏幕上实际显示了什么吗？”

Agent 会调用 get_screenshot_at_failure，获取最接近故障时刻拍摄的 JPEG 图片，有助于发现验证码、错误页面或意外重定向。

间歇性故障诊断

“这个测试在本地通过，但在 CI 中失败了。比较这两个 trace，告诉我有什么不同。”

Agent 会调用 compare_traces，使用 LCS 对齐两个操作序列，并指出首个结构性差异、计时异常，以及仅在失败运行中出现的网络请求。

汇总并行 CI 运行中的重复故障

“这个流水线有 12 个失败的 trace。它们都是同一种故障吗？”

对每个 trace 调用 generate_error_signature——签名相同意味着根本原因相同，无需逐一查看所有 trace。

诊断导致 DOM 变化的 API 调用

“模态框出现了，但我不知道是哪个 fetch 触发的。”

correlate_dom_and_network 会自动关联 HAR 日志和 DOM 快照。输出示例：

{
  "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]" }
      ]
    }
  ]
}

性能超时——不只是元素缺失

“测试在 goto 时超时了，但没有 JS 错误。是什么阻塞了页面？”

detect_performance_anomalies 会检查屏幕录制帧间隔并标记 Long Tasks。输出示例：

{
  "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 用于区分主线程阻塞（main_thread_blocked——存在帧间隔）、并发 fetch 请求造成的瀑布流（network_saturation——≥5 个请求正在进行），以及导航／硬超时（timeout_or_navigation——时长 >3 s 且无其他信号）。

检查跟踪使用的 Playwright 版本和 HAR 模式

“这条跟踪来自一个陌生的 CI 配置。是否能获取响应正文数据？”

extract_trace_metadata_strict 会在你运行任何其他工具之前检查存档：

{
  "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" 表示正文片段内嵌其中。"attach" 表示正文片段位于单独的资源文件中。"omit" 表示仅包含标头——在这种情况下，correlate_dom_and_network 会返回空的 response_body_snippet。

🏗️ 架构

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

解析器逐行流式处理每个文件（不进行完整缓冲区拆分），并使用 LRU 缓存进程内的结果（最多 50 条），缓存键为路径 + 修改时间。重新读取同一份未修改的跟踪无需任何 I/O。

帧快照将 DOM 存储为嵌套数组（["TAG", {attrs}, ...children]）。ARIA 转换器遍历该树并输出精简的 YAML，与原始 HTML 相比，可将令牌开销降低约 90%。

🏗️ 技术栈

• @modelcontextprotocol/sdk — MCP 服务运行时
• adm-zip — zip 解压
• zod v4 — 输入架构验证
• TypeScript、ESLint、Prettier、Husky、GitHub Actions CI

📋 脚本

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

📄 许可证

MIT