Applitools

Applitools MCP 服务

Applitools MCP 服务可帮助你使用 Applitools Eyes，通过我们支持的任意 SDK 创建、更新、审核和解决视觉测试。

它通过 Model Context Protocol（MCP）连接 AI 助手，让 Cursor、GitHub Copilot、Cline 和 Claude Code 等工具能够设置测试、添加视觉检查点、配置跨浏览器测试，并调查视觉测试失败（接受、拒绝或调整背后的更改），整个过程无需离开 IDE。

如需了解详情，请访问我们的 MCP 文档。

用途

此服务面向使用 AI 辅助工作流的开发人员、测试人员或 QA。

它可让你的 AI 助手：

• 了解你的项目配置
• 指导 Eyes 设置
• 添加视觉检查点并提出最佳实践建议
• 调查视觉测试失败的批次、场景、会话或步骤，并告知你发生了什么变化、这是否是 Bug，以及原因
• 在将任何更改提交到基准版本之前，征得你的明确批准，然后接受、拒绝或调整检查点的匹配区域

所有操作都无需手动执行易出错的步骤，也无需离开 IDE。

适用对象

• 刚接触 Applitools Eyes，尚未安装或实现 Eyes SDK 的工程师
• 现有 Eyes SDK 用户，他们希望使用 MCP 服务添加 Ultrafast Grid 覆盖范围（跨浏览器和设备测试）、使用 Applitools 视觉 AI 将现有测试转换为视觉测试，或获取并分析视觉测试结果
• 大规模处理视觉测试失败问题的团队
  • 希望 AI 助手调查一批失败测试、收集证据，并准确说明发生了什么变化以及是否需要关注，而不是逐个点击 Eyes 仪表板中的测试

要求与限制

• Node.js 18 或更高版本
• VS Code、Cursor、Claude Code、Cline 或其他 MCP 客户端助手
• 设置和检查点工具（eyes_setup_project、eyes_setup_ufg、eyes_add_checkpoints_to_test）仅支持我们的 Playwright Fixtures SDK。即将支持更多 SDK 框架！
  • 请使用最新版本的 Playwright、Node.js 和我们的 Playwright JavaScript Fixtures SDK
  • 需要能够访问项目的源代码（用于设置和检查点工具）
• 检查、解决和审核工具（eyes_inspect_*, eyes_resolve_*, eyes_review_*）适用于任何 Eyes 测试结果，无论生成结果时使用的是哪种 SDK 或语言，因为它们处理的是已捕获的批次、会话和 DOM 数据
  • 这些工具需要额外的独立读写 API 密钥

安装

推荐：VS Code 扩展或 Cursor MCP 安装

开始使用 Eyes MCP 的最简单方式是安装 Applitools VS Code 扩展，或直接在 Cursor 中安装 MCP 服务。

• 自动运行 MCP 服务
• 将其连接到 Copilot 或 Cursor 的 AI 助手
• 提供上下文感知的代码编辑
• 在 IDE 或你选择的 MCP 客户端 CLI 中显示视觉测试结果

只需点击下方选项，即可安装 MCP 服务：

或者，你也可以按照下方的 Manual Setup 部分手动安装服务。

手动设置

如果您不想使用扩展程序，可以按照以下示例手动安装 MCP 服务。

标准 MCP 配置：

{
  "mcpServers": {
    "applitools-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["--yes", "@applitools/mcp@latest"]
    }
  }
}

{
 "mcpServers": {
   "applitools-mcp": {
     "type": "local",
     "command": "npx",
     "tools": [
       "*"
     ],
     "args": [
       "@applitools/mcp@latest"
     ]
   }
 }
}

{
  "mcpServers": {
    "applitools-mcp": {
      "command": "npx",
      "args": ["--yes", "@applitools/mcp@latest"],
      "disabled": false,
      "type": "stdio",
	   "timeout": 60
    }
  }
}

身份验证

以下三个密钥控制服务的功能，可将其设置为全局环境变量、项目中的 .env 文件，或更新 mcp.json 文件中的 applitools-mcp 配置：

• APPLITOOLS_API_KEY：用于测试执行（保持不变；这是您一直用于运行 Eyes 视觉测试的密钥）。请参阅我们的文档，了解如何获取执行密钥。
  • 注意：MCP 服务还会在其他位置查找此密钥。详情请参阅 eyes_verify_api_key 工具。
• APPLITOOLS_READ_KEY：只读密钥。所有 Inspection 工具、所有 Resolution 工具，以及以任一模式运行的 Review 工具都需要此密钥。
• APPLITOOLS_WRITE_KEY：只写密钥。所有 Resolution 工具，以及以 resolve 模式（默认模式）运行的 Review 工具都需要此密钥。

如何获取只读和只写 API 密钥：

请参阅我们的文档，了解 API 密钥管理。

1. 前往 Applitools 管理后台的 API Keys 页面。
2. 创建或复制与您的用户和团队关联的只读 API 密钥。
3. 创建或复制与您的用户和团队关联的只写 API 密钥。
4. 通过项目中的 .env 文件、全局环境变量，或 mcp.json 文件中的 applitools-mcp 配置来设置密钥。

注意：APPLITOOLS_API_KEY（用于测试执行）不同于 APPLITOOLS_READ_KEY 和 APPLITOOLS_WRITE_KEY。Inspection、Resolution 和 Review 工具（eyes_inspect_*, eyes_resolve_*, eyes_review_*）需要这些单独的只读和只写权限密钥，才能查询会话数据、审核/检查并解决测试问题。

设置了全部三个密钥的 applitools-mcp mcp.json 配置示例：

{
  "mcpServers": {
    "applitools-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["--yes", "@applitools/mcp@latest"],
      "env": {
        "APPLITOOLS_API_KEY": "<your execution API key>",
        "APPLITOOLS_READ_KEY": "<your read-only key>",
        "APPLITOOLS_WRITE_KEY": "<your write-only key>"
      }
    }
  }
}

项目中设置了全部三个密钥的 .env 文件示例：

APPLITOOLS_API_KEY=<your execution API key>
APPLITOOLS_READ_KEY=<your read-only key>
APPLITOOLS_WRITE_KEY=<your write-only key>

可用工具

设置与配置

eyes_verify_api_key

验证您的 Applitools API 密钥；如果提供了 Eyes 服务端 URL（例如非公共云），还会验证与该 URL 的连通性。

搜索常见位置：

• APPLITOOLS_API_KEY 环境变量和/或 APPLITOOLS_SERVER_URL（如适用）
• 项目中的 .env 文件
• applitools.config.*
• playwright.config.*
• applitools-mcp mcp.json 配置文件

支持的 Eyes SDK：全部

eyes_setup_project

指导在 Playwright 项目中配置 Applitools Eyes（Fixtures 变体）。

包括：

• Eyes 报告器配置
  • 扩展 Playwright HTML 报告，纳入 Eyes 视觉测试结果。用户无需访问 Eyes 控制面板，即可在报告中批准或拒绝结果。
• 在项目文件中添加 Eyes 设置和依赖项导入
• 推荐的默认设置

支持的 Eyes SDK：Playwright TypeScript/JavaScript Fixtures

eyes_add_checkpoints_to_test

按照最佳实践，在现有 Playwright 测试中添加 Eyes 视觉检查点。

支持的 Eyes SDK：Playwright TypeScript/JavaScript Fixtures

eyes_setup_ufg

配置 Ultrafast Grid（UFG），以进行跨浏览器和跨设备测试。指导你完成 UFG 设置，以便同时在多个浏览器、视口和设备上运行视觉测试。

支持的 Eyes SDK：Playwright TypeScript/JavaScript Fixtures

检查（只读）

需要 APPLITOOLS_READ_KEY。这些工具会查询批次、会话、步骤和 DOM 数据，但不会进行任何更改。通常，助手会在 Review 中代表你调用这些工具（见下文）；你也可以直接提出请求，将它们用于手动或临时调查。

支持的 Eyes SDK：全部

eyes_inspect_sessions

列出批次中的会话和批次范围的统计信息。可筛选出仅未解决或未保存的会话，也可将响应设为完整详情、仅统计信息或去重后的场景名称列表。浏览批次的入口。询问“这个批次中有什么？”或“还有哪些内容需要审核？”时，请先使用此工具。

eyes_inspect_steps

列出会话中的步骤：每个步骤是否匹配，以及基线/检查点图像和 DOM 的 ID、尺寸和解决状态。用于深入查看单个会话。

eyes_inspect_changed_areas

返回某个步骤的差异区域，这些区域由原始像素级差异聚类而成，并已考虑你添加的所有区域。如果某个步骤中有 20 个以上的差异区域，密集的聚类会合并为一个包围区域，这样助手就能专注于有实际意义的差异，而不是像素噪点。

eyes_inspect_image

导出某个步骤的基线或检查点截图，也可选择裁剪到指定区域。

eyes_inspect_image_diff

导出标注了差异区域的检查点截图，让你一眼看出哪些内容发生了移动或变化。

eyes_inspect_dom

将某个步骤的 DOM 捕获结果导出到文件，并为每个元素分配稳定的 ID，让助手可以引用“元素 14”，而无需使用 XPath 或原始坐标。需要在测试运行时启用 DOM 捕获；否则不会返回数据（但不会报错）。

eyes_inspect_dom_diff

返回某个步骤的检查点 DOM 与基线 DOM 之间的结构差异（仅包含实际变化），并自动合并纯位置偏移和大范围变化（例如“下方所有内容都向下移动”），而不是逐个列出元素。

eyes_inspect_dom_search

使用谓词查询语言搜索 DOM 捕获结果。该查询语言作为独立的 MCP 资源提供文档：可组合属性比较、几何和尺寸检查、祖先/后代关系，以及 image 或 button 等快捷关键词，并使用 and/or/not，而无需助手读取整个捕获结果。

eyes_inspect_evidence

一次调用即可返回审核某个步骤的差异区域所需的全部内容：对于你指定的每个区域，返回图像差异以及基线和检查点截图，同时包含该步骤的完整 DOM 差异和当前生效的匹配区域。相比单独调用 eyes_inspect_image_diff、eyes_inspect_image、eyes_inspect_dom_diff 和 eyes_inspect_regions，此工具更为合适；Review 会使用它来收集证据。

eyes_inspect_regions

返回当前对某个步骤生效的匹配区域，并合并测试代码中定义的区域，以及测试运行后新增或更改的区域。添加新区域前会先进行检查，避免助手创建重叠或重复的区域。

eyes_inspect_history

返回某个 DOM 节点在之前运行中的差异历史，作为证据，证明某项更改是反复出现的／动态内容，而非一次性的真实更改。

Review（编排）

始终需要 APPLITOOLS_READ_KEY；在 resolve 模式（默认模式）下运行时，还需要 APPLITOOLS_WRITE_KEY。这是日常使用这些工具的主要方式：让助手检查一个批次、场景、会话或步骤，助手便会为你完成整个调查。

支持的 Eyes SDK：全部

eyes_review_progress

按照你指定的范围（批次、场景、会话或单个步骤）引导调查，并为每个更改区域收集所需证据（图像、DOM 差异、历史记录），然后才能报告发现结果。当你说“检查我的批次”或“检查这个会话”时，助手会调用此工具；它会按正确顺序在内部调用 Inspection 工具，因此你无需操心。

eyes_review_diff_report

为某个更改区域记录结构化发现结果：其分类、是否与周围页面一致、Bug 状态、预期状态，以及（如果属于反复出现的／动态内容）支持证据和建议的遮罩。助手必须先收集相关证据；如果没有这些证据便提交发现结果，系统会拒绝并要求补充缺失的检查调用。

eyes_review_end

汇总并结束指定范围内的调查，将所有子级发现结果去重，生成完整且无遗漏、无重复计数的清晰摘要。在步骤级别，此处还会确定该步骤的接受／拒绝／未解决结果（在 resolve 模式下）。

两种 Review 模式：

• inspect：只读。生成更改摘要，不进行任何修改。适合初步查看，或在决定如何处理之前先查看发现结果。
• resolve（默认模式）：还会为已确认的动态差异应用遮罩，并在发现结果出现时自动确定每个步骤的接受／拒绝／未解决结果。助手无需单独调用 Resolution 工具即可完成这些操作。

两种模式都可以应用于整个批次，也可以缩小到单个场景、会话或步骤。inspect 模式的 Review 完成后，可在不重复调查的情况下转为 resolve 模式；系统只需将缓存的发现结果重新通过 resolve 模式的决策逻辑处理即可。保存基线更改或重置基线不属于 Review 的操作；如需执行这些操作，请另行请求 eyes_resolve_save（或 eyes_resolve_reset），且仍需获得你的明确批准。

Resolution（会修改数据）

同时需要 APPLITOOLS_READ_KEY 和 APPLITOOLS_WRITE_KEY。通常情况下，你无需直接调用这些工具。Review 会在检查批次的过程中自动应用等效决策。只有在 Review 之外需要进行一次性手动处理时，才直接使用这些工具，例如：不运行完整调查，直接接受一个已了解情况的步骤。

支持的 Eyes SDK：全部

eyes_resolve_checkpoint

将步骤的检查点标记为已接受或已拒绝。接受的检查点会在保存后替换基线；拒绝的检查点则保留现有基线。默认情况下，会将相同决策应用于共享完全相同差异的所有步骤，包括同一会话内的步骤，以及场景名称相同的其他会话中的步骤。

eyes_resolve_regions

添加、移除或更新步骤的匹配区域；可根据基线图像／DOM 或检查点图像／DOM 进行对照。传播方式与 eyes_resolve_checkpoint 相同。

注意：运行此工具前始终需要获得你的明确批准

eyes_resolve_save

将整个批次中每个已接受或拒绝的步骤，以及每个区域变更提交到基线——包括批次中的所有测试，而不只是你指定的会话。运行此工具之前，解决决策会一直处于待处理状态，基线也不会更改。

注意：运行此工具始终需要你的明确批准。

eyes_resolve_reset

将会话或批次的基线恢复到测试最初运行时所依据的版本，并清除所有待处理的解决决策。

注意：运行此工具始终需要你的明确批准。

开始使用和使用示例

向你的 AI 助手咨询 Applitools：

• “使用 Applitools MCP 服务执行以下任务”
  • 此提示词前缀为可选内容，可引导你的助手更好地使用 MCP 服务。
• “验证我的 Applitools API 密钥”
• “为我的 Playwright 项目设置 Applitools Eyes”
  • 适用于 Playwright TypeScript/JavaScript
• “在我的 login.spec 测试中添加 Eyes 视觉检查点”
  • 适用于 Playwright TypeScript/JavaScript
• “使用 Applitools UFG 配置跨浏览器测试”
  • 适用于 Playwright TypeScript/JavaScript
• “向我显示上次测试结果的批次 URL”
• “分析并总结我的批次结果”
• “查看我上一个批次，并告诉我有哪些变化”
• “只显示此批次中的变化，暂时不要解决任何问题”
• “看起来都没问题。现在就解决吧”
• “接受此场景中所有会话里的结账按钮差异”
• “时间戳元素上的这个差异是动态变化，还是实际变更？”
• “将此批次的基线重置为测试最初运行时所依据的版本”

实用链接

• Applitools MCP 文档
• 联系支持团队

由 Applitools 倾心打造 ❤️