Skip to main content
Glama
visual-regression-mcp

visual-regression-mcp

by noGarne

Visual Regression MCP

AI 辅助的视觉回归测试 MCP Server。像素对比找出差异,AI 判断这个差异是真 bug 还是可接受的变化。

为什么做这个

视觉回归测试不是新技术,但传统方案有个致命问题:误报太多。

字体渲染差异、动画时序、随机数据、时间戳——这些都会导致像素差异,但都不是 bug。团队引入视觉回归测试后,往往因为每次 CI 都红、但 90% 是误报,最后干脆关掉。

这个项目的思路是:像素对比只负责"找出哪里不一样",判断"这是不是 bug"交给 AI。

工具返回的不只是差异百分比,而是差异图 + 当前截图 + 区域定位。AI 看到图之后可以判断:

  • 差异集中在按钮区域,颜色从绿变红 → 可能是真 bug

  • 差异散布全页、每处都是 1-2 像素 → 字体抗锯齿,可忽略

  • 差异在时间戳区域 → 动态内容,应该 mask 掉

Related MCP server: UI Screenshot Comparison MCP

工具

工具

说明

capture_baseline

截图并保存为基线。支持全页/元素截图、自定义视口、遮盖动态区域

compare_visual

对当前页面截图并与基线做像素对比,返回统计数据 + 差异图 + 当前截图

list_baselines

列出所有已保存的基线及其截图参数

delete_baseline

删除过期基线(页面有意改版后)

降低误报的几个设计

这是项目的核心,不是简单调 pixelmatch 就完事:

  1. 冻结动画 — 注入 CSS 把所有 animation-duration 和 transition-duration 归零,同时隐藏光标。CSS 动画是误报的头号来源。

  2. 遮盖动态区域 — maskSelectors 参数可以把时间戳、广告位、随机内容用纯色盖住,让这些区域的像素稳定。

  3. 参数持久化 — 基线保存时把视口尺寸、选择器、等待时间一起存下来,对比时用完全相同的参数重截。参数不一致的对比是无意义的。

  4. 等待网络空闲 — waitUntil: "networkidle" 加可配置的额外等待,避免图片没加载完就截图。

  5. 区域定位 — 把画面切成 3×3 网格统计差异分布。"差异集中在顶部导航"和"差异散布全页"含义完全不同,前者可能是布局 bug,后者多半是渲染差异。

  6. 尺寸不匹配单独处理 — 页面高度变了说明内容增删,pixelmatch 无法对比,此时直接报告尺寸变化而不是崩溃。

安装

git clone <repo-url>/visual-regression-mcp.git
cd visual-regression-mcp
npm install
npx playwright install chromium
npm run build

配置

在 Claude Code 的 MCP 配置中添加:

{
  "mcpServers": {
    "visual-regression": {
      "command": "node",
      "args": ["/path/to/visual-regression-mcp/build/index.js"],
      "env": {
        "VISUAL_BASELINE_DIR": "/path/to/your/baselines"
      }
    }
  }
}

VISUAL_BASELINE_DIR 可选,默认存在 ~/.visual-regression-mcp/baselines/。

使用

配置后重启 Claude Code,直接用自然语言:

帮我给 http://localhost:3000/dashboard 建一个视觉基线,命名 dashboard

(改了代码之后)
对比一下 dashboard 有没有视觉回归

把时间戳区域 .timestamp 遮盖掉再建基线

AI 会调用工具、看差异图、然后告诉你这个差异是不是问题。

输出示例

{
  "status": "differences_found",
  "name": "dashboard",
  "diffPixels": 5107,
  "totalPixels": 480000,
  "diffPercent": 1.064,
  "diffRegions": [
    { "region": "middle-left", "diffPixels": 5107, "percentOfRegion": 9.58 }
  ],
  "note": "Pixel diff found. Inspect the diff image below..."
}

外加两张图:差异图(品红高亮变化像素)和当前截图,供 AI 视觉判断。

技术栈

  • @modelcontextprotocol/sdk — MCP 协议

  • playwright — 无头浏览器截图

  • pixelmatch + pngjs — 像素级图像对比

  • TypeScript + ESM

License

MIT

Available Tools

4 tools
capture_baselineA

Capture a screenshot of a URL and save it as the visual baseline under a given name. Run this once on a known-good version of the page. Later use compare_visual against the same name to detect regressions.

Inputs: url (required), name (required), width, height, +4 more.

compare_visualA

Capture the current state of a URL and compare it pixel-by-pixel against a saved baseline. Returns diff statistics AND the diff image, so you (the AI) can visually judge whether the changes are real regressions or acceptable variations (font rendering, dynamic content, intentional redesign). Pixel diff alone produces many false positives — your visual judgment is the point of this tool.

Inputs: name (required), url, threshold, includeDiffImage.

delete_baselineA

Delete a saved baseline by name. Use when a page has intentionally changed and the old baseline is obsolete.

Inputs: name (required).

list_baselinesA

List all saved visual baselines with their URLs and capture settings.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: capture creates a baseline, compare evaluates a current page against a baseline, list enumerates baselines, and delete removes one. There is no overlap or ambiguity between the tools.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern: capture_baseline, compare_visual, list_baselines, delete_baseline. The verbs (capture, compare, list, delete) are all distinct and describe the action clearly.

    Tool Count5/5

    Four tools is an appropriate scope for visual regression testing, covering the essential operations of create, compare, list, and delete. Each tool earns its place without unnecessary bloat or missing core functionality.

    Completeness5/5

    The tool set covers the complete baseline lifecycle: capture (create/update), compare (use), list (read), and delete. The compare tool provides both statistics and visual output, enabling the agent to make informed judgments. No obvious gaps exist.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables automated end-to-end testing powered by Playwright where test cases are defined in natural language and executed by AI. Uses lightweight snapshot analysis with vision mode fallback for sophisticated testing scenarios.
      3
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to see, analyze, and visually verify web page changes through pixel-perfect diffing, theme extraction, layout analysis, and interactive element detection.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI-driven UI inspection and optimization by scanning websites with configurable viewports, capturing screenshots, running deterministic accessibility and layout checks, and generating prioritized reports with fix prompts.
      2
      MIT