visualdiff

Name: visualdiff
Author: CloudCorpRecords

本地服务

github.com/CloudCorpRecords开发工具01 周前更新

代码仓库

关于 visualdiff

visualdiff 是面向检查网页 UI 变更的 SnapDiff 视觉测试 CLI 和 MCP 服务。它可按预期验证改动、比较页面与基线，并将网页或 HTML 渲染为图像。

主要功能

01按预期验证 UI 变更
02比较页面和已存基线
03捕获 URL 截图
04将 HTML 和 CSS 渲染为图像

适用场景

01按预期检查暂存环境中的 UI 改动
02将页面与参考页或基线比较
03捕获整页或指定元素截图
04为社交卡片或邮件标题渲染 HTML

MCP 相关

其 stdio MCP 服务提供验证 UI 变更、比较页面、捕获截图和渲染 HTML 图像的工具。调用 SnapDiff API 需要设置 SNAPDIFF_API_KEY。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "cloudcorprecords-visualdiff": {
      "command": "npx",
      "args": [
        "-y",
        "@reneturcios/visualdiff"
      ]
    }
  }
}

启动命令npx -y @reneturcios/visualdiff

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@reneturcios/visualdiff0.1.0stdio

ocighcr.io/cloudcorprecords/visualdiff:0.1.0stdio

工具

收录的工具列表 · 更新于 1 周前

参数	类型	必填	说明
after	string	是	更改后页面的 URL。
branch	string	否	用于比较的分支名称。
intent	string	是	预期 UI 更改的描述。
project	string	是	SnapDiff 项目 slug。
full_page	boolean	否	是否捕获整个页面，而不是仅捕获视口。
page_name	string	是	具有已存储基线的页面名称。
threshold	number	否	视觉差异阈值。
intent_regions	array	否	预期发生更改的区域。
ignore_selectors	array	否	比较时要忽略的元素的 CSS 选择器。
match_tolerance_percent	number	否	以百分比表示的匹配容差。

详细介绍

visualdiff

visualdiff 封装了 SnapDiff 视觉测试 API：验证 UI 更改是否符合预期，比较两个页面（或某个页面与已存储的基线），截取任意 URL 的屏幕截图，并将原始 HTML/CSS 直接渲染为图像。一个二进制文件同时提供命令行界面和 stdio MCP 服务。

需要 API 密钥。将 SNAPDIFF_API_KEY 设置为从 SnapDiff 控制面板获取的密钥；如果未设置，调用会在发出任何请求前失败。可以通过 SNAPDIFF_API_URL 覆盖 API 基础 URL；未设置时，调用将发送到 https://api.snapdiff.ai/v1。

安装

npx @reneturcios/visualdiff screenshot https://example.com

或者运行容器镜像：

docker run -i -e SNAPDIFF_API_KEY=sk_live_... ghcr.io/cloudcorprecords/visualdiff

容器默认启动 MCP 服务（见下文）。传入 CLI 参数即可将其用作 CLI。

CLI

export SNAPDIFF_API_KEY=sk_live_...

visualdiff verify myproj pricing https://staging.example.com/pricing "added a yearly billing toggle"
visualdiff compare https://staging.example.com --before https://www.example.com
visualdiff compare http://localhost:3000 --project myproj --page-name homepage
visualdiff screenshot https://example.com --width 800 --full-page
visualdiff html-to-image "<h1>Hello</h1>" --css "h1 { color: navy; }" --width 1200 --height 630

visualdiff --version

命令会输出上游 JSON 载荷。退出代码：成功时为 0，调用失败时为 1（包括缺少 API 密钥或上游 API 错误），用法错误时为 2。

MCP 服务

一个二进制文件提供两种模式。mcp 子命令会启动 stdio MCP 服务：

npx -y @reneturcios/visualdiff mcp

MCP 客户端配置：

{
  "mcpServers": {
    "visualdiff": {
      "command": "npx",
      "args": ["-y", "@reneturcios/visualdiff", "mcp"],
      "env": { "SNAPDIFF_API_KEY": "sk_live_..." }
    }
  }
}

工具

工具	输入	返回内容
`snapdiff_verify_ui_change`	`project`、`page_name`、`after`、`intent`（均为必填）；可选参数：`intent_regions`、`branch`、`threshold`、`match_tolerance_percent`、`ignore_selectors`、`full_page`	返回判定结果（`pass`、`expected_change_detected`、`unexpected_regression`、`no_change_detected` 或 `needs_human_review`）、`next_action` 和 `review_url`。需要项目中已存储页面基线。
`snapdiff_compare_pages`	必填参数：`after`；以及 `before`，或用于基线模式的 `project` + `page_name`；可选参数：`branch`、`threshold`、`ignore_selectors`、`full_page`	返回差异百分比和突出显示差异的图像。
`snapdiff_capture_screenshot`	必填参数：`url`；可选参数：`full_page`、`dark_mode`、`selector`、`width`	返回页面的屏幕截图。
`snapdiff_html_to_image`	必填参数：`html`；可选参数：`css`、`width`、`height`	返回渲染后的图像（OG 卡片、社交图片、电子邮件页眉）。

每个工具都会向基础 URL 下对应的工具专属端点发送 POST 请求，并使用 API 密钥作为 Bearer 令牌。未提供的可选参数会从请求正文中完全省略。

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx