a11y-toolkit MCP

作为 MCP 服务器（Model Context Protocol）提供给 AI 代理的 WCAG 2.2 无障碍套件——外加一个统一的 CLI。核心零依赖；所有计算均在本地完成且结果精确（采用官方相对亮度公式）。

完整流程——审计 → 修复 → 文档化 → 回归监控——装进同一个工具包：

1. 审计：对任意 URL 进行快速 WCAG 审计（结果按严重程度排序）

2. 修复：精确的对比度检查——颜色对*以及* 图像上的文字（对真实背景做像素级采样）——并提供最接近的可用颜色建议

3. 文档：生成欧盟法定无障碍声明，输出为无障碍 HTML

4. 回归监控：对比构建之间的快照和 diff，在生产环境前拦下无障碍回归

所有工具均支持多语言 es/en（英文声明采用 Directive (EU) 2016/2102 与 Directive (EU) 2019/882 —— 欧洲无障碍法案的措辞，在整个欧盟范围内可用）。

MCP 工具（9 个）

Related MCP server: Accessibility MCP Server

以 MCP 方式安装

{
  "mcpServers": {
    "a11y-toolkit": {
      "command": "python3",
      "args": ["/path/to/a11y-toolkit/server.py"]
    }
  }
}

或者使用 uv，无需克隆仓库：

{
  "mcpServers": {
    "a11y-toolkit": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/kinti/a11y-toolkit", "a11y-toolkit-mcp"]
    }
  }
}

如果你打算用到 a11y_snapshot（需要启动浏览器），请加上 "timeoutMs": 60000。

统一 CLI——一条命令搞定一切

a11y pair "#1f2328" "#fbfaf7"                     # contrast, per-criterion verdicts
a11y image hero.jpg --text "#ffffff" --region 120,40,420,90
a11y audit --url https://example.com              # express WCAG audit
a11y declaration --entidad "Acme" --url https://acme.example \
       --estado parcial --marco eaa --lang en --output decl.html
a11y snapshot https://mysite --out before.json    # before deploy (needs Playwright)
a11y diff before.json after.json                  # after deploy

在仓库目录下运行：python3 a11y.py <sub命令>。

理解图像模式

• ratio_peor（最差）——对你文字颜色最不利的位置。

• area_pasa_aa_texto_normal_4_5——隐私安全面积的占比。如果文本所在地 < 100%：加遮罩/覆盖层、剪裁或移动文字。

• zona_peor——在 3×3 网格中失败最严重的格子，同时给出精确坐标。

安全性与范围

本地工具：它在你的机器上以你的身份运行。path（图像）和 output_path（声明）参数会读写本地路径——请在你信任的 MCP 客户端中使用。除你明确审计的 URL 外，不会有任何内容发送到网络。

技术细节

• 图片解码：优先 Pillow，否则用 macOS 的 sips；始终可用 PPM（这正是 CI 不需要依赖的原因）。

• aria-live 监视器自带设计教训：它的面板故意不是动态区域，并将自己排除在 observer 之外——一个 role="log" 面板会匹配到自身的 selector，从而陷入无限自观察循环。我们之所以知道，是因为我们已被坑过。

• 已用自己的真实生产站点测试过（毕竟它得通过自己的审计）。

• Web 版供真实人类（同样一套计算）：jquin.net/lab —— 对比度（pair + image）、声明生成器、aria-live 监视器、构建 diff。

Español

一套于 MCP 服务器 + 统一 CLI 形态的 WCAG 2.2 无障碍套件。核心零依赖（可选 Pillow；macOS 可用 sips；PPM 始终可用）。整个闭环同一个 toolchain：audit（a11y_audit_url）→ 修复（颜色对以及图像上的文字，像素级采样 + 困难区域检测；提供无障碍颜色建议）→ 生成声明（RD 1112/2018 第 10 条或 Ley 11/2023/EAA 的无障碍 HTML）→ 持续监测（build 之间的 snapshot 与 diff：添加/移除/重命名，焦点顺序）。9 个 MCP 工具（见上方表格）· 多语言 es/en（EN 声明采用欧盟指令 (EU) 2016/2102 和 2019/882 的措辞）· 统一 CLI a11y，子命令 pair、image、audit、declaration、snapshot、diff。

{ "mcpServers": { "a11y-toolkit": {
    "command": "python3", "args": ["/ruta/al/repo/server.py"] } } }

本地工具：path 和 output_path 参数只读写本地路径；除明确审查的 URL 外，没有任何内容走网络。aria-live 监视器附带它的一个设计教训： 面板刻意不是 live region，并且把自己排除在 observer 之外（role="log" 面板会匹配自身的 selector，形成无限自观察循环——我们踩过这个坑）。人类面向网页版： jquin.net/lab。

作者

. Jesús Quintana Fernández（jquin.net）——自 2003 年起担任 SEO/GEO 顾问以及 web 无障碍开发实践者。MIT © 2026。