OverlayQA

OverlayQA MCP

OverlayQA MCP 是一个 Model Context Protocol 服务，为你的 AI 编码 Agent 提供无障碍审查和设计 QA 超能力。 让 Claude Code、Cursor 或 Windsurf 审查任意 URL 的 WCAG 和颜色对比度问题，然后无需离开编辑器，即可在 OverlayQA 项目中查看、分配、讨论、标记和解决问题。

You:   Scan staging.acme.com for accessibility issues, then open issues for the criticals.
Agent: scan_accessibility → 7 violations (2 critical, 3 high), score 71/100.
       scan_and_create_issues → created 2 issues in "Acme Web":
       - Buttons missing accessible names (WCAG 4.1.2): critical
       - Insufficient text contrast on .cta (WCAG 1.4.3): high
You:   List the open criticals.
Agent: list_issues(status=open, severity=critical) → 2 issues.

安装

一键安装：

• 安装到 Cursor
• 安装到 VS Code

也可以手动将其添加到编辑器的 MCP 配置中：

Claude Code（项目根目录中的 .mcp.json）/ Cursor（~/.cursor/mcp.json）/ Windsurf（~/.codeium/windsurf/mcp_config.json）：

{
  "mcpServers": {
    "overlayqa": { "command": "npx", "args": ["@overlayqa/mcp@latest"] }
  }
}

任何兼容 MCP 的客户端都可以采用相同方式使用。首次运行时会打开浏览器标签页，用于连接你的 OverlayQA 账户（免费，无需银行卡）：选择工作区并授权访问后，连接有效期为 30 天。凭据缓存在 ~/.overlayqa/auth.json 中；访问令牌有效期较短，会在后台自动刷新。你可以随时在控制面板的 Connected AI apps 中断开编辑器连接（app.overlayqa.com/mcp/connect）。

工具

Agent 可以调用的工具。每个工具的说明都旨在帮助模型根据自然语言选择合适的工具。

审计

工具	功能
scan_accessibility	使用 axe-core 对任意 URL 执行 WCAG 审计。返回违规项、严重程度、WCAG 成功标准和总分。
scan_contrast	检查页面各处的颜色对比度。返回未通过检查的前景色/背景色元素对。
audit_tokens	审计实时 URL 的设计系统令牌。返回 0-100 的令牌健康度评分，以及包含严重程度的审计结果（字体大小、文本颜色、间距、字体系列、边框圆角不一致）。仅审计实时页面。

文件与问题管理

工具	功能
scan_and_create_issues	扫描 URL，并为所有严重程度高于阈值的违规项自动创建问题。
create_issue	创建 QA 问题，包含标题、严重程度、类型、描述和可选的受分配人。
list_issues	根据状态、严重程度、类型、标签、受分配人、创建者、页面、创建时间或活跃/已完成/已忽略状态筛选并分页查看问题。每个问题都会注明提交者，以及是否仍需回复。
update_issue	编辑提供的问题字段、分配信息、忽略状态或状态。接受 UUID 或 OQ-12 这样的显示 ID。
create_project	为某个站点 URL 创建项目。
list_projects	列出团队中的所有项目。
list_labels	查看工作区标签库、已分配的标签和你的权限。
create_label	创建可重复使用的工作区标签。
set_issue_label	添加或移除一个标签，不更改问题文本或其他标签。
rename_label	重命名工作区标签（所有者/管理员）。
delete_label	删除工作区标签及其分配记录；保留问题（所有者/管理员）。

AI 审查工作流

工具	功能
run_auto_review	根据项目设置、已忽略的发现项和已提交的问题启动自动审查。
compare_visual	对照 Figma 画框、已保存的设计或上传的图像启动视觉比较，并可选择测量间距。
get_review_result	获取已保存审查的进度、发现项和截图证据。

这两个启动工具都需要 projectId、一个公开的 url 和一个新的 UUID requestId。它们会立即返回 jobId。使用 get_review_result 读取结果，直到任务完成或失败。若响应丢失，请使用相同的请求 ID 和输入重新发起请求；不要仅为读取结果而启动另一次审查。审查会占用你的扫描额度，且不会自动创建问题。视觉比较会按设计创作时的宽度进行截图，并返回 AI 发现项，而非确定性的像素差异 CI 判定。

服务记录的内容

每个工具还接受一个可选的 context 参数：用一句话说明 Agent 调用该工具的原因。OverlayQA 会将这句话、工具名称、你的账户、项目和问题 ID、数量和评分、扫描所用的 URL，以及你的编辑器名称和版本（来自 MCP 握手）记录为产品分析数据。存储前会截断这句话，并删除电子邮件地址和类似凭据的字符串。不会传输任何其他内容：既不会传输你的对话，也不会传输你的代码或工具回复。完整详情：overlayqa.com/privacy。

示例提示词

• “扫描 example.com，查找无障碍问题。”
• “检查我们定价页面的对比度，并告诉我哪些地方未通过检查。”
• “扫描 staging.acme.com，并为所有严重或高严重程度的问题创建问题。”
• “创建一个高严重程度的无障碍问题：登录按钮没有焦点环。”
• “列出 Acme Web 项目中未解决的严重问题。”
• “为 shop.acme.com 创建项目，然后扫描该项目。”

定价

	扫描	创建问题和项目
免费版	每天 3 次，永久有效	否
14 天试用期	每天 30 次	是
付费版	根据套餐每天 10-30 次，Pro 套餐不限次数	是，可导出到 Linear / Jira / Asana / Notion

请参阅 overlayqa.com/pricing。

常见问题

支持哪些编辑器？ Claude Code、Cursor、Windsurf，以及任何兼容 MCP 的客户端（它使用标准 stdio MCP）。

它免费吗？ 可以免费开始：每天可进行 3 次无障碍/对比度扫描，无需银行卡。14 天试用期内每天可扫描 30 次，并解锁问题和项目创建功能。试用期后，创建问题和项目需要付费套餐（Pro 套餐可无限扫描）。

它具体会扫描什么？ 任何公开 URL。无障碍扫描使用映射到 WCAG 成功标准的 axe-core；对比度检查前景色与背景色的比值，并返回未通过检查的元素组合。

我需要账户吗？ 需要一个免费的 OverlayQA 账户。首次运行时会打开浏览器标签页进行连接；连接有效期为 30 天，随时可以从控制面板断开连接。

它能与 OverlayQA Chrome 扩展程序配合使用吗？ 可以。MCP 服务和扩展程序共享相同的项目和问题，因此你在编辑器中提交的任何内容都会显示在扩展程序和控制面板中，反之亦然。

更喜欢点击而不是输入？来认识一下扩展程序

MCP 服务是使用 OverlayQA 的一种方式。Chrome 扩展程序 则是另一种方式：点击实时页面上的任意元素，即可在几秒内捕获屏幕截图以及 CSS、DOM 和元数据，并生成可直接供开发使用的问题，还能直接在页面上运行 AI 无障碍和设计系统审计。项目相同，问题相同，并与此服务共享。

链接

• 网站：overlayqa.com
• Chrome 扩展程序：Chrome 网上应用店
• 免费无障碍检查工具（无需账户）：overlayqa.com/accessibility-checker
• 免费颜色对比度检查工具（无需账户）：overlayqa.com/color-contrast-checker
• 定价：overlayqa.com/pricing
• Model Context Protocol：modelcontextprotocol.io

许可证

MIT

自定义问题标签

使用 list_labels 并提供项目 UUID，即可查看该工作区的标签和你的权限。create_label 可创建可重复使用的标签；set_issue_label 可为单个问题添加或移除标签，而不会更改其其他标签或文本。工作区所有者和管理员可以使用 rename_label 和 delete_label；删除标签会移除其关联项，但不会删除问题。list_issues 接受 labelIds（匹配任意标签），也接受 unlabeled。共享报告会保留共享时的标签名称。

本地验证时可设置 OVERLAYQA_API_BASE 和独立的 OVERLAYQA_AUTH_FILE；两者都不会更改默认生产端点或常规保存的登录信息。

0.3.0 中的问题管理

需要部署匹配的问题一致性 API。现有扫描和状态更新仍与 0.2.0 兼容。

工具	功能
get_issue	读取描述、负责人、标签、忽略状态、屏幕截图、捕获的元素/CSS、视口证据和问题评论。
list_issues	按一个或多个状态、严重性或类型、标签、受派人（me、unassigned 或用户 ID）、创建者以及活跃/已完成/已忽略状态筛选。通过下一页的 page 参数继续获取 hasMore 指示的内容。
list_project_members	查找可读取项目所在工作区中团队成员的用户 ID，以便分配任务和提及成员。
create_issue	选择受派人；使用 null 表示未分配，或省略该字段以分配给自己。默认类型为 General。
update_issue	更改任何提供的标题、描述、严重性、类型、状态、受派人或忽略标记。省略的字段保持不变。忽略问题不会解决问题。设置为已验证只会记录状态，不会运行扫描。
move_issue	使用稳定的问题 UUID，将问题移至同一工作区中的另一个可写项目；保留评论和证据。之后读取返回的显示 ID。
list_comments	读取讨论内容、受众、提及和附件元数据。
create_comment	使用明确的 internal（仅团队可见）或 public（团队和客户可见）受众发布评论，并可添加提及和可选的 PNG/JPG/PDF 文件。
update_comment / delete_comment	编辑或删除你自己的原生评论。编辑会保留受众和文件。
get_comment_attachment	根据问题的访问规则，将原生评论文件作为文件名和 base64 字节读取。

提及成员时，在文本中使用 @[userId]，并在 mentionedUserIds 中包含相同的 ID。创建评论需要 UUID 格式的 requestId：如果因响应丢失而重试同一提交，请重复使用该 ID，以免重复发布。附件使用 base64 字节，并包含文件名和 MIME 类型；每条评论最多可附加 10 个 PNG/JPG/PDF 文件，总计不超过 10 MiB。

为保持兼容，list_issues 默认返回所有状态的问题。使用 state: "active" 获取未忽略的开放/进行中问题。finished 包含未忽略的已解决/已验证/已关闭问题；ignored 按独立的忽略标记筛选。所有提供的筛选条件会取交集。页码从 1 开始，每页最多包含 100 个问题；除非 hasMore 为 false，否则筛选后的空页并不表示项目结果已完整返回。

轮询新反馈时，传入 createdAfter，其值为你已见过的最新问题的 createdAt（带时区的 ISO-8601 时间，例如 2026-10-05T22:00:00Z）；只会返回创建时间晚于该值的问题。pageUrl 会将列表限制为单个页面，并忽略查询字符串。每个列出的问题都带有 source（client 表示审核者通过共享链接提交了问题）、commentCount、lastCommentAt 和 lastCommentBy（reviewer 或 team）；因此，当 source 为 client 且 commentCount 为 0，或 lastCommentBy 为 reviewer 时，问题仍需回复。如果服务器尚未更新以支持某个筛选条件，工具会返回 FILTER_NOT_SUPPORTED，而不是不带筛选条件的列表。

上文列出的标签工具已包含在 0.3.0 中。后续的审核工作流、客户审核工具和定时审核将在下文介绍，并且需要更新对应的服务器。未包含已保存设计的发现功能。

发布前验证

运行 npm test 和 npm run build。实际流程会通过真实的 stdio 协议，使用指定的测试账号，让构建后的客户端连接本地 API 或生产环境；该流程会创建并删除自己的项目，并生成 JSON 和 HTML 证据。

MCP_PARITY_API=http://127.0.0.1:3241 MCP_SERVER_ENV=/path/to/server/.env npm run test:issues-live
MCP_PARITY_API=https://api.overlayqa.com npm run test:issues-live

发布顺序：先部署并验证服务器端点，然后发布 npm 0.3.0 并更新 MCP 注册表。本地构建或版本号升级不代表已发布。

验证已部署的修复

verify_issue({ issueId, requestId }) 会在问题保存的公开 URL 上运行与控制面板相同的修复验证引擎。问题必须处于已解决、已验证或已关闭状态，拥有原始截图证据，并且类型可验证（无法检查「通用」和「改进」类型）。每次检查都使用新的 UUID；仅在响应丢失后重试同一请求时，才重用该 UUID。验证使用工作区现有的权限和验证额度，并遵循服务端的发布设置。

结果包含已保存的检查 ID、判定、说明、置信度、检查后截图 URL、捕获上下文和时间戳。检查结果可以是通过、带有保留意见的通过、失败、无法确定或报告错误。它不会更新问题状态。请先检查证据，再决定是否使用 update_issue 更改状态。私人页面或 localhost 页面需要通过浏览器扩展进行已登录的捕获。

get_issue_verifications({ issueId }) 会读取最新的 50 条已保存检查记录，按时间从新到旧排列，不会运行新的检查。get_issue 也会包含 latestVerification；如果没有检查记录，则为 null。在较旧的服务端上，如果没有此字段，表示此功能尚未部署；并不表示该问题从未经过检查。

list_issues 接受 notDetected: true，用于筛选标记为「不再检测到」的问题；或接受 false，用于筛选没有此标记的问题（包括从未检查过的问题）。此筛选器会与状态、类型、页面及其他筛选条件结合，并在分页前应用。返回的 notDetectedAt 和 lastDetectedAt 时间戳描述的是扫描检测情况，并非修复证明。如果服务端忽略此筛选器，则会拒绝请求并返回 FILTER_NOT_SUPPORTED。

这些新增功能需要在客户端发布前部署匹配的服务端。本地和托管的 MCP 均提供验证和已保存历史记录；托管验证需要扫描和写入权限。此更改不会在生产环境中启用验证。

客户评审链接与进度（下一版本）

发布此客户端前，需要先部署对应的服务。部署该服务前，必须先应用访客选项数据库迁移。这些工具可通过本地和托管 MCP 连接使用，并遵循应用的项目权限。

工具	功能
list_client_reviews	查看项目的客户链接、标题、分享 URL、捕获状态、访问次数、评论、已完成评审的客户，以及每位客户的邀请和提醒状态。
create_client_review	创建实时或快照评审链接；可选添加标题、客户邮箱地址、欢迎说明和访客私密评论。快照捕获会异步完成；请查看列表确认是否就绪。
update_client_review	撤销或恢复链接、更改有效期，或更改响应式预览。
set_client_review_recipients	替换完整的客户邮箱列表。保留的地址会保留其历史记录；移除的地址将不再收到提醒。空列表会移除所有收件人，同时保留链接。

创建公开链接需要用户明确表示分享意图。添加邮箱地址需要用户明确表示邀请这些人的意图。新地址可能会收到邀请，并自动收到第 3、7、10 天的提醒。请查看 invitationsEnabled 和返回的逐地址 invites：如果关闭了投递功能，地址仍会保存，但状态为 sent: false, skipped: true，启用后可以再发送邀请。一次邀请失败不会撤销链接或已成功发送的邀请。

列表会返回包含 email、invitedAt、inviteFailed、lastReminderAt、done、commented 和 unsubscribed 字段的 doneReviewers 和 clients。完成评审表示客户已完成反馈；这不代表问题已修复，也不代表所有人都已完成。只有客户本人可以完成此操作。提醒时间和停止条件仍由现有调度程序管理；没有 MCP 立即发送工具。

如果收件人更新的响应状态不确定，请使用相同的完整列表重试并重新打开评审；保留的地址不会被重复邀请。创建评审没有重试密钥：如果响应丢失，请先使用 list_client_reviews 检查链接是否已保存，再创建另一个评审。项目查看者和只读托管连接可以查看进度，但不能更改链接或邀请他人。

保留的发现、定期审核和跟踪器导出

这些工具需要更新相应的服务。create_review_issues 与自动审核／视觉比较的发布门槛共用。

工具	功能
create_review_issues	将已完成审核中选定的从零开始计数的索引创建为问题，并保留已保存的屏幕截图、页面上下文和修复指导。重复提交相同的任务和索引可找回已有问题。
list_scheduled_reviews、create_scheduled_review、update_scheduled_review、delete_scheduled_review	在仪表板现有的项目权限、计划限制和频率规则下管理定期公开页面审核。
run_scheduled_review、get_scheduled_review_result	使用请求 UUID 启动运行，然后轮询同一 UUID。立即运行不会发送电子邮件。ID／结果会保留 24 小时；如果没有请求 ID，则读取最新保存的基线和可用的完整证据。
list_export_connections、list_export_destinations	查找已连接的跟踪器和明确指定的目标。省略 collection 可查看提供商可用的集合及必需输入。
export_issues、get_issue_export_status	导出已有问题及其证据，并读取已保存的投递／同步状态。检查每项结果；附件不完整或仍有待处理工作都不算成功。

导出功能通过产品现有的适配器支持 Jira、Linear、Asana、Trello、Notion、ClickUp、GitHub 和 Basecamp。必须填写目标字段；客户端不会自行选择第一个项目或列表。Notion 会列出连接时保留的数据库，不支持任意搜索数据库。已导出的问题会保留其原始目标位置。图像、讨论内容和支持的字段同步受与应用相同的提供商限制；已存储的同步时间戳并不能证明刚完成了一次往返同步。

示例：使用 { "provider": "trello" } 调用 list_export_destinations，然后为所选看板列出 boards 和 lists。在 export_issues.destination 中同时传入 boardId 和 listId。安排未来的扫描和分享问题都需要用户提出请求。如果结果不确定，应先读取已保存的状态，再开始新工作。