webability

WebAbility MCP

为编码 Agent 提供可执行操作的无障碍检查：使用两个引擎扫描页面，为每个问题获取结构化修复方案，然后重新检查修复是否已生效。

免费。托管于 https://mcp.webability.io/mcp。扫描无需 API 密钥。MIT。

安装

Claude Code（插件）

/plugin marketplace add snayyar00/webability-mcp
/plugin install webability-accessibility@webability

或运行 claude mcp add --transport http webability https://mcp.webability.io/mcp

Cursor：添加到 Cursor

VS Code：在 VS Code 中安装 · 或运行 code --add-mcp '{"name":"webability","type":"http","url":"https://mcp.webability.io/mcp"}'

Claude.ai / ChatGPT / 任意 MCP 客户端：使用 URL https://mcp.webability.io/mcp 添加自定义连接器。

本地（浏览器在你的机器上运行，因此可直接扫描 localhost）：npx -y -p @webability/mcp webability-mcp

返回内容

实际输出示例：对 https://demo.vercel.store 运行 scan_page（已精简）：

Found 16 high-confidence issue(s): 0 critical, 4 serious, 8 moderate, 4 minor.
20 additional finding(s) need human review — see incomplete[]. Do NOT auto-fix these.

missing_label · serious · WCAG 1.3.1 · input.text-md.w-full.rounded-lg
  fix: { op: "add-attribute", attribute: "aria-label" }   fixability: contextual
missing_table_scope · moderate · WCAG 1.3.1 · thead > tr > th:nth-of-type(1)   (vite.dev/guide)
  fix: { op: "add-attribute", attribute: "scope", value: "col" }   fixability: mechanical

verify_fix input.text-md.w-full.rounded-lg wcag=4.1.2
  NOT RESOLVED: 1 violation still present → "verified": false

• fix.op 是以下值之一：add-attribute、set-attribute、remove-attribute、add-element、remove-element、add-text-content、suggest。
• fixability：mechanical = 按给定方案应用。contextual = 操作已知，但值（替代文本、标签）需要判断。visual = 需要渲染后的输出；提出建议，但不要自动应用。
• incomplete[] 包含需要人工处理的发现（图片上的对比度、营销类替代文本）。Agent 会被告知不要修复这些问题。
• source：在 React ≤18 和 Vue 开发构建中，每个问题都会附带来自实时组件树的 {file, line, column, component}。
• verify_fix：重新扫描单个元素，且验证失败时会拒绝通过。diff_scan 会报告页面的 fixed[]、new[]、remaining[]。

免费

	可用内容
无需账户	使用托管服务上的扫描和检查工具。按 IP 限制合理使用：每小时 30 次浏览器扫描、10 次 AI 修复
免费账户（在客户端中通过 OAuth 提示登录，或在本地运行 npx -y @webability/cli login）	可使用 visual_audit（视觉检查）、start_audit / get_audit（完整报告）和 webability-tunnel（让托管服务扫描你的 localhost）

MCP 无试用、无点数，也没有付费套餐。

不支持的功能

它无法判断替代文本是否有意义，也无法判断自定义小组件是否适合屏幕阅读器。可用它清除源代码中可自动处理的问题，然后使用辅助技术进行测试。

本地与托管

	Lite — 本地 stdio（npx / webability-mcp）	Full — 托管（https://mcp.webability.io/mcp）
账户	无需	扫描工具无需账户；视觉检查和完整审计需免费账户（OAuth 登录）
扫描 / 修复 / 验证	支持（在你的机器上）	支持
find_source	支持	不支持
scan_history / generate_report_pdf	支持	不支持
visual_audit / start_audit / get_audit	列为占位工具 → 连接 Full（仍免费）	支持 — 使用账户即可免费
PostHog / 仪表板分析	仅通过可选环境变量启用	托管服务上默认启用
localhost / 私有地址	支持 — 浏览器在你的机器上运行	通过隧道 — 见下文

扫描本地开发服务器

使用 Lite（stdio）。 它会在你的机器上运行浏览器，因此 http://localhost:3000 就是本机地址：

claude mcp add webability-local -- npx -y -p @webability/mcp webability-mcp

其他客户端：将 npx -y -p @webability/mcp webability-mcp 添加为 stdio 服务。

Full（托管服务）按设计无法直接访问你的机器。 它运行在我们的云端，因此那里的 localhost 指的是我们自己的本机地址。每个 URL 都会在获取内容前进行检查，环回、私有和链路本地地址都会被拒绝：没有这项检查，任何人都可能让服务访问内部服务或云元数据端点。此检查不会对任何人放宽。

需要托管服务时：webability-tunnel

CI、远程 Agent 或由仪表板触发的扫描无法运行 Lite，因为流程中没有笔记本电脑。遇到这种情况，请开启隧道：

WEBABILITY_API_KEY=<your-token> npx -y -p @webability/mcp webability-tunnel --port 3000

它会打印一个 https://tunnel.webability.io/t/<id>/ URL 和一个密钥。将 URL 作为 url，将密钥作为 tunnel_secret 传入：

“使用 tunnel_secret <secret> 扫描 https://tunnel.webability.io/t/abc123.../”

你的机器会主动连接到中继服务，因此该 URL 是普通的公共主机名，上文的 SSRF 检查仍原样适用——不会为了实现这一点而削弱任何安全措施。它的原理与 ngrok 相同，但有三点不同之处：当隧道另一端是你的开发机器时，这些区别很重要：

• URL 不是凭证。 每个请求都必须携带密钥标头；仅有 URL 会返回 401。URL 可能会泄露到 shell 历史记录、CI 日志和屏幕截图中。
• 只有 GET 和 HEAD 请求能到达你的机器，且仅限你指定的一个端口；在任何内容传入之前，Authorization / Cookie 都会被剥除。
• 你停止时，它也会关闭。 30 分钟后、闲置 5 分钟后，或你按下 Ctrl-C 时，隧道都会关闭。

任何同时持有 URL 和密钥的人都可以读取你的开发服务器。请像对待密码一样保管这两者；只要有人在键盘前操作，就优先使用 Lite。

第三方隧道（ngrok、cloudflared）也可使用——托管扫描器会像对待其他公共网站一样处理它们的主机名——但它们会让任何获知 URL 的人访问你的开发服务器。无论如何，Vite 用户都需要将隧道主机名添加到 server.allowedHosts，否则所有请求都会收到 403 Blocked request。

无论使用哪种传输方式，start_audit 都是例外——即使使用 Lite，它的处理流程也会在我们的服务器上运行，因此永远无法访问 localhost URL。

本地选项

可选环境变量：

• WEBABILITY_API_URL（默认值为 https://api.webability.io），用于可自托管的后端。
• POSTHOG_PROJECT_API_KEY 或 POSTHOG_API_KEY，用于启用 PostHog MCP Analytics，记录 MCP initialize、tools/list 和工具调用使用情况事件。
• POSTHOG_HOST（默认值为 https://us.i.posthog.com），用于 EU 或可自托管的 PostHog 数据采集。
• WEBABILITY_POSTHOG_MCP_ANALYTICS=off，即使存在 PostHog 密钥，也会强制禁用 PostHog MCP Analytics。

扫描引擎

scan_page 会并行运行两个引擎并对结果去重：

引擎	规则	覆盖范围
WebAbility 检测器	60+	渐变感知对比度、含义不明确的名称、装饰性图标、地标层级、ARIA 正确性、链接一致性、目标尺寸、键盘陷阱
axe-core	104	行业标准 WCAG 2.2 基线

三层输出（自 v1.2.1 起）

每次扫描都会返回：

• issues — 高置信度违规，可安全地作为缺陷呈现
• incomplete — 需要人工审核的发现（渐变背景上的对比度、营销图片、framer-motion 动画前状态、axe-incomplete）。绝不要自动修复这些问题。
• summary — 按严重程度统计的数量，以及 incomplete 数量

这与 axe-core 的 violations / incomplete / passes 划分一致，可避免 Agent 以破坏性的方式“修复”误报。

结构化修复（自 v1.6.0 起）

scan_page、flow_scan、diff_scan 和 scan_html 返回的每个问题都带有机器可读的修复建议和可修复性层级，因此 Agent 无需解析文字描述即可采取操作：

{
  "id": "wa-missing_button_type-a1b2c3",
  "fixability": "mechanical",
  "fix": { "op": "add-attribute", "attribute": "type", "value": "button", "currentValue": "", "needsManualReview": false }
}

字段	值
fix.op	add-attribute · set-attribute · remove-attribute · add-element · remove-element · add-text-content · suggest
fixability	mechanical — 值已知，可按原样应用 · contextual — 操作已知，值需判断（替代文本、标签） · visual — 需要渲染结果（对比度、焦点环、目标尺寸）；可提出建议，但绝不要自动应用

仅当引擎已知 fix.value 时才会提供该字段。旧版 fix.attribute / currentValue / suggestedValue / needsManualReview 字段保持不变。get_rules 会列出每条规则的层级，方便你预先选出可自动修复的规则。

源码位置指引（自 v1.6.0 起）

在 React ≤18 或 Vue 开发版中，scan_page、flow_scan 和 diff_scan 会读取实时页面的组件树，并为每条发现附加 JSX 调用位置：

{ "selector": "img#hero", "source": { "framework": "react", "file": "/app/src/Hero.tsx", "line": 12, "column": 5, "component": "Hero" } }

打开该文件即可，无需通过 find_source 往返查询。React 19 移除了 _debugSource；在该版本中，你仍可获取 component。生产构建没有组件树；传入 sourceRoot（仅限 Lite），没有指针的问题会通过对选择器进行令牌 grep，获得 sourceCandidates[]。

输出控制（自 v1.6.0 起）

scan_page、flow_scan、scan_html 和 diff_scan 接受：

参数	作用
minImpact	minor · moderate · serious · critical — 忽略低于此级别的问题
rules[]	仅保留这些规则 ID（missing_alt、image-alt，……）
wcag[]	仅保留这些标准；像 1.4 这样的前缀也会匹配 1.4.3
format: "compact"	每个元素占一行，仅打印一次规则元数据 — JSON 令牌数量可减少一部分

筛选会在 50 项上限生效前进行，因此，minImpact: "serious" 会返回一个含 300 个问题的页面上的所有严重问题。scan_history 存档会保留未筛选的结果。

进程内 scan_html（自 v1.6.0 起）

scan_html 默认不再启动浏览器。它会在 MCP 进程内的 jsdom 中运行 WebAbility 检测器和 axe-core — 耗时毫秒级，无需网络 — 并返回与 scan_page 相同的三层 issues / incomplete / summary 结构，每条发现都带有 fix.op。片段会自动包装成文档。jsdom 没有布局，因此会跳过视觉层级规则（对比度、目标尺寸、焦点环），并计入 skippedVisual；传入 engine: "browser" 即可使用之前的无头 Chromium axe 路径。

工具

工具	版本	功能说明
scan_page	Lite + Full	扫描 URL，查找 WCAG 无障碍问题（2 种引擎）。开发版本会提供 source 指针；可通过 minImpact / rules / wcag / format 控制输出
flow_scan	Lite + Full	扫描多页面用户旅程，并去重汇总各页面的问题
scan_html	Lite + Full	在进程内扫描原始 HTML 代码片段或片段内容（jsdom，毫秒级，无需浏览器）；对比度检查可使用 engine: "browser"
detect_framework	Lite + Full	检测 Tailwind / MUI / Bootstrap / Next.js / WP / 纯 CSS
generate_ai_fix	Lite + Full	提供感知框架的修复方案。遇到对比度问题时，会自动从实时 URL 提取品牌配色。
verify_fix	Lite + Full	重新扫描已修复的元素，确认违规问题已消失 — verified: true/false。完成从发现 → 修复 → 验证的闭环。
diff_scan	Lite + Full	基线与当前结果对比 → fixed[] / new[] / remaining[]。页面级回归检查；基线来自 scan_history（Lite）或实时 URL。
check_color_contrast	Lite + Full	检查一组颜色是否符合 WCAG 对比度要求；传入 url 可获取与实时页面品牌配色一致的建议
check_aria	Lite + Full	验证 HTML 代码片段中的 ARIA 属性
get_rules	Lite + Full	列出 axe-core + WebAbility 规则，包含 fixability 和 fix 操作模板；可按标签、层级或引擎筛选
find_source	仅 Lite	将 CSS 选择器映射回本地源文件（当页面没有框架 source 指针时的备用方案）
scan_history	仅 Lite	浏览 ~/.webability/scans/ 下以前的本地扫描记录
generate_report_pdf	仅 Lite	将扫描结果生成为品牌化的 WebAbility 无障碍报告 PDF，并保存到项目目录旁 — 免费，无需账户。传入 scan_page 返回的 issues[]。如需完整的审计交付物（Excel + 证据），请使用 start_audit。
visual_audit	Full（有账户时免费；Lite 为存根）	通过视觉分析进行像素级审计（图标对比度、焦点可见性、看起来像按钮但实际并非按钮的元素）
start_audit	Full（有账户时免费；Lite 为存根）	启动完整的服务端审计交付流程（报告 + Excel 工作簿）。返回一个可用于轮询的 ID。
get_audit	Full（有账户时免费；Lite 为存根）	查看审计进度；完成后获取严重程度摘要 + 报告/工作簿下载 URL。

何时使用此 MCP

• 构建新组件，并希望从一开始就确保其具备无障碍性
• 推送前审计 localhost / staging 构建
• 分析 Lighthouse / axe 报告 — scan_page 会汇总两种引擎的结果
• 生成与你当前使用的框架相匹配的修复建议
• 根据用户的实际品牌配色（而非通用建议）检查颜色对比度

示例

在 Cursor / Claude Code 中：

“扫描 localhost:3000，查找无障碍问题”

“依次访问登录页 → 仪表盘 → 结账页，并报告整个流程中不重复的问题”

“为 https://example.com 上 .btn-primary 的对比度问题推荐修复方案，并匹配其品牌配色”

“WCAG 1.4.11 检查什么内容？”

“将你刚刚在 localhost:3000 上发现的问题整理成一份品牌化 PDF 报告”

隐私、扫描日志与遥测

每次扫描都会在本地记录到 ~/.webability/scans/——一个每次扫描占一行的 index.jsonl 账本，以及最近 500 次扫描的完整结果。使用 scan_history 工具（“之前扫描了什么？”）或普通的 jq 查看。设置 WEBABILITY_SCAN_LOG=off 可禁用日志，设置 WEBABILITY_SCAN_LOG_DIR 可更改存储位置。

此外，每次工具调用（所有工具，不仅是扫描）都会向 WebAbility API 发送一条简短的遥测事件：工具名称、简短的目标标签（URL、选择器、问题类型，不包含页面内容）、通过/失败状态、耗时、问题数量，以及持久化的匿名安装 ID。完整扫描结果、HTML 和生成的修复代码绝不会通过遥测离开你的设备。设置 WEBABILITY_SCAN_TELEMETRY=off 可选择退出。

如果配置了 POSTHOG_PROJECT_API_KEY 或 POSTHOG_API_KEY，服务器还会启用 PostHog MCP Analytics。此功能会收集 MCP 使用元数据，例如初始化、tools/list、工具名称、耗时、客户端名称/版本以及成功/失败状态。WebAbility 会在发送前移除 PostHog 的 $mcp_parameters 和 $mcp_response 字段，因此此集成不会向 PostHog 发送原始 HTML 片段、屏幕截图、扫描响应或生成的代码。

其中两个工具——generate_ai_fix 和 visual_audit——还会向 WebAbility API 发送页面内容（HTML 片段或屏幕截图），以便 WebAbility 代表你调用第三方大模型；WebAbility 不会存储这些内容，但大模型提供商在传输过程中会看到这些内容。请参阅 PRIVACY.md，了解各工具的完整说明以及 WebAbility 的隐私政策。

链接

• WebAbility — 平台、小组件、仪表板
• 文档
• GitHub

许可证

MIT