UI Compare MCP

基于算法的 UI 图片精准对比 MCP 服务 - 像素级、结构级、感知级多维度差异检测

特性

• ✅ 精确量化: 像素级、色值级、结构级多维度对比
• ✅ 智能过滤: 自动过滤抗锯齿、渲染差异等误报
• ✅ 可视化输出: 差异热力图、标注图（Base64）
• ✅ 纯内存处理: 默认不保存文件，直接返回 JSON 数据
• ✅ MCP 集成: 无缝集成到 Cursor IDE
• ✅ 批量对比: 支持多组图片批量处理

核心算法

| 算法 | 用途 | 输出 | |------|------|------| | SSIM | 结构相似性检测 | 0-1 分数 | | Pixel Diff | 像素级差异（LAB 色差） | 差异率 + 像素数 | | Color Histogram | 颜色分布对比 | Chi-square 距离 | | Edge Detection | 边缘结构对比 (Canny) | 边缘差异率 | | Anti-aliasing Filter | 抗锯齿过滤 | 过滤误报 |

快速开始

1. 在 Cursor 中配置

编辑 Cursor 配置文件（~/Library/Application Support/Cursor/User/globalStorage/@cursor-server/settings.json）：

{
  "mcpServers": {
    "ui-compare": {
      "command": "npx",
      "args": ["-y", "ui-compare-mcp"]
    }
  }
}

2. 重启 Cursor

配置后重启 Cursor IDE，MCP 服务将自动启动。

3. 使用示例

在 Cursor 中，Agent 可以直接调用 MCP 工具：

// Agent 自动调用
const result = await ui_compare({
  design_image: "/path/to/design.png",
  screenshot_image: "/path/to/screenshot.png",
  threshold: 0.1,
  return_heatmap: true
});

// 查看结果
console.log(`相似度: ${result.metrics.overall_similarity * 100}%`);
console.log(`检测到 ${result.diff_regions.length} 个差异区域`);

// Claude 可以看到 Base64 图片
// result.images.heatmap - 热力图
// result.images.annotated - 标注图

本地开发

1. 安装依赖

npm install
pip install -r requirements.txt

3. 本地测试

node index.js

4. Cursor 本地配置

{
  "mcpServers": {
    "ui-compare": {
      "command": "node",
      "args": ["/path/to/ui-compare-mcp/index.js"]
    }
  }
}

MCP 工具

ui_compare - 单次对比

对比两张图片并返回详细差异分析。

参数:

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | design_image | string | ✅ | - | 设计图路径 | | screenshot_image | string | ✅ | - | 截图路径 | | threshold | number | ❌ | 0.1 | 像素差异阈值 (0-1) | | anti_aliasing | boolean | ❌ | true | 是否启用抗锯齿过滤 | | return_heatmap | boolean | ❌ | true | 是否返回热力图 | | return_annotated | boolean | ❌ | true | 是否返回标注图 | | color_tolerance | number | ❌ | 10 | 颜色容差 (Delta E) |

返回:

{
  "success": true,
  "metrics": {
    "overall_similarity": 0.8745,
    "ssim_score": 0.8923,
    "pixel_diff_rate": 0.1234,
    "color_distance": 23.45,
    "edge_diff_rate": 0.0876,
    "total_diff_pixels": 45678,
    "image_size": [1920, 1080]
  },
  "diff_regions": [
    {
      "region": "region_1",
      "bbox": [100, 50, 400, 100],
      "issues": [
        {
          "type": "color",
          "metric": "color_distance",
          "value": 15.3,
          "severity": "medium",
          "description": "颜色差异 Delta E: 15.30"
        }
      ]
    }
  ],
  "images": {
    "heatmap": "data:image/png;base64,...",
    "annotated": "data:image/png;base64,..."
  }
}

ui_compare_batch - 批量对比

批量对比多组图片。

参数:

{
  "comparisons": [
    {
      "design_image": "/path/to/design1.png",
      "screenshot_image": "/path/to/screenshot1.png",
      "name": "homepage"
    },
    {
      "design_image": "/path/to/design2.png",
      "screenshot_image": "/path/to/screenshot2.png",
      "name": "about"
    }
  ],
  "threshold": 0.1,
  "return_images": false
}

返回:

{
  "success": true,
  "results": [
    {
      "name": "homepage",
      "metrics": {...},
      "diff_regions": [...]
    }
  ],
  "summary": {
    "total": 2,
    "passed": 2,
    "failed": 0,
    "avg_similarity": 0.89
  }
}

指标解读

整体相似度 (overall_similarity)

综合评分 (0-1)：

• > 0.95: 高度相似
• 0.85-0.95: 基本相似
• 0.70-0.85: 中等差异
• < 0.70: 明显差异

SSIM 分数 (ssim_score)

结构相似性指数 (0-1)：

• 衡量布局和结构的相似程度
• 对光照、对比度变化不敏感

像素差异率 (pixel_diff_rate)

差异像素占比 (0-1)：

• < 0.05: 几乎无差异
• 0.05-0.15: 轻微差异
• > 0.15: 明显差异

颜色距离 (color_distance)

颜色分布差异（Chi-square 距离）：

• < 10: 颜色分布一致
• 10-50: 颜色有差异
• > 50: 颜色分布明显不同

边缘差异率 (edge_diff_rate)

结构轮廓差异 (0-1)：

• 反映布局和形状的差异

使用场景

1. UI 还原验收

// 截取页面
const screenshot = await browser_take_screenshot({
  filename: "current_page.png"
});

// 对比设计稿
const result = await ui_compare({
  design_image: "designs/homepage.png",
  screenshot_image: screenshot.path
});

// Claude 分析差异并生成修复建议

2. 视觉回归测试

// 批量对比多个页面
const result = await ui_compare_batch({
  comparisons: [
    { design_image: "baseline/home.png", screenshot_image: "current/home.png", name: "home" },
    { design_image: "baseline/about.png", screenshot_image: "current/about.png", name: "about" }
  ]
});

// 检查是否有回归
if (result.summary.failed > 0) {
  console.log("发现视觉回归！");
}

3. 设计稿走查

// 精确对比细节
const result = await ui_compare({
  design_image: "design.png",
  screenshot_image: "impl.png",
  threshold: 0.05,  // 更严格
  color_tolerance: 5
});

// 输出差异报告
for (const region of result.diff_regions) {
  console.log(`区域 ${region.region}:`);
  for (const issue of region.issues) {
    console.log(`- ${issue.description}`);
  }
}

阈值调优

| 场景 | threshold | color_tolerance | 说明 | |------|-----------|-----------------|------| | 图标/Logo 对比 | 0.05 | 5 | 要求严格 | | 文本页面对比 | 0.15 | 12 | 字体渲染容差 | | 色彩设计对比 | 0.08 | 8 | 色彩准确性 | | 布局结构对比 | 0.12 | 15 | 关注结构而非色彩 | | 整页对比 | 0.10 | 10 | 平衡准确性和效率 |

系统要求

• Node.js: >= 14.0.0
• Python: >= 3.8
• 操作系统: macOS, Linux, Windows

Python 依赖

自动安装以下依赖：

• mcp>=0.9.0
• opencv-python>=4.8.0
• numpy>=1.24.0
• scikit-image>=0.21.0
• Pillow>=10.0.0

故障排查

Q: 提示 "未找到 Python 3"？

A: 确保已安装 Python 3.8+:

python3 --version

Q: 依赖安装失败？

A: 手动安装依赖:

pip3 install -r requirements.txt

Q: 图片读取失败？

A: 检查文件路径是否正确，支持绝对路径和相对路径。

Q: MCP 服务启动失败？

A: 查看 Cursor 的 MCP 日志:

cat ~/Library/Application\ Support/Cursor/logs/mcp-*.log

开发

运行测试

npm test

构建

npm run build

发布

npm publish

许可证

MIT License - 详见 LICENSE 文件

贡献

欢迎提交 Issue 和 Pull Request！

致谢

算法实现参考了以下开源项目：

• Pixelmatch
• scikit-image
• OpenCV