MCP 服务器

visual-regression-mcp

Enables AI-assisted visual regression testing by capturing baselines, comparing screenshots, and using AI to judge whether visual differences are bugs or acceptable changes.

README

Visual Regression MCP

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

为什么做这个

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

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

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

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

差异集中在按钮区域，颜色从绿变红 → 可能是真 bug
差异散布全页、每处都是 1-2 像素 → 字体抗锯齿，可忽略
差异在时间戳区域 → 动态内容，应该 mask 掉

工具

工具	说明
`capture_baseline`	截图并保存为基线。支持全页/元素截图、自定义视口、遮盖动态区域
`compare_visual`	对当前页面截图并与基线做像素对比，返回统计数据 + 差异图 + 当前截图
`list_baselines`	列出所有已保存的基线及其截图参数
`delete_baseline`	删除过期基线（页面有意改版后）

降低误报的几个设计

这是项目的核心，不是简单调 pixelmatch 就完事：

冻结动画 — 注入 CSS 把所有 animation-duration 和 transition-duration 归零，同时隐藏光标。CSS 动画是误报的头号来源。
遮盖动态区域 — maskSelectors 参数可以把时间戳、广告位、随机内容用纯色盖住，让这些区域的像素稳定。
参数持久化 — 基线保存时把视口尺寸、选择器、等待时间一起存下来，对比时用完全相同的参数重截。参数不一致的对比是无意义的。
等待网络空闲 — waitUntil: "networkidle" 加可配置的额外等待，避免图片没加载完就截图。
区域定位 — 把画面切成 3×3 网格统计差异分布。"差异集中在顶部导航"和"差异散布全页"含义完全不同，前者可能是布局 bug，后者多半是渲染差异。
尺寸不匹配单独处理 — 页面高度变了说明内容增删，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..."
}