A11y Feedback MCP

为编码和设计智能体提供真正的可访问性反馈循环，而不是又一条“遵循 WCAG”的提醒。

a11y-feedback-mcp 在 Chromium 中渲染界面，运行 axe-core，并向任何 Model Context Protocol 客户端返回可操作的证据：违反的规则、影响、CSS 选择器、DOM 片段、计算样式、边界框、修复步骤以及满足数学对比度要求的候选值。

它可直接与 Codex 和 Claude Code 配合使用。对于 Claude Design，可靠的流程是将 Claude Code 同时连接到 Claude Design 的 MCP 服务器和本服务器，然后审计生成的 HTML 或实时预览，并通过设计工作流将更正发送回去。

这是一个自动化测试辅助工具，而非 WCAG 认证服务。它有意报告不完整的检查，并要求人工测试键盘、焦点、屏幕阅读器、缩放、动效、认知和内容质量。

“实时反馈”意味着什么

flowchart TD
    A["Agent creates or changes UI"] --> B["Render at target viewport"]
    B --> C["Run axe + contrast analysis"]
    C --> D["Return evidence and correction"]
    D --> E["Agent proposes or applies code fix"]
    E --> F["Re-run same audit"]
    F --> G["Human checks incomplete behavior"]

该服务器是只读的。它绝不会静默修改项目。连接的智能体会利用这些证据进行局部更改，然后重新运行审计以验证更改。

Related MCP server: Accessibility MCP Server

工具

所有工具都被标注为只读。服务器还提供一个 accessibility-fix-loop 提示词。

标准级别

审计工具支持 wcag2a、wcag2aa、wcag2aaa、wcag21aa、wcag21aaa、wcag22aa、wcag22aaa 和 best-practice。AA 级别包含所有必需的 A 级和 AA 级成功准则；AAA 级别包含 A、AA 和 AAA 级成功准则。wcag22aa 仍是默认值，因为 W3C 推荐使用最新的 WCAG 版本，并提醒不要将整个站点的 AAA 作为通用政策。将 AAA 作为明确的增强目标，并按成功准则级别报告进度。

axe 映射意味着部分自动化覆盖，绝不意味着完整的成功准则已被测试。get_wcag_checklist 公开了 WCAG 2.2 AA 所需的全部 55 项成功准则，或 WCAG 2.2 AAA 所需的全部 86 项成功准则，包括自动化无法完成的人工工作。

要求

• Node.js 20 或更高版本

• 推荐使用 Chrome 或 Edge

• Windows、macOS 或 Linux

服务器会首先查找已安装的 Chrome/Edge。在受支持的 Linux 环境中，它可以回退到捆绑的 @sparticuz/chromium。您可以将 A11Y_MCP_BROWSER_PATH 设置为明确的浏览器可执行文件。默认情况下，Chromium 沙箱保持启用；仅在受限容器或 Lambda 风格的运行时无法以其他方式启动 Chrome 时，才设置 A11Y_MCP_NO_SANDBOX=true。

在 Windows 上安装

在您存放项目的文件夹中打开 PowerShell：

git clone https://github.com/aditya-ariosity/a11y-feedback-mcp.git
cd a11y-feedback-mcp
npm install
npm run build

如果仓库尚未在 GitHub 上，请先下载或复制此文件夹，然后在其中运行最后三条命令。

连接 Codex

在 PowerShell 中，使用构建后的入口点的绝对路径：

codex mcp add a11y-feedback -- node "C:\full\path\to\a11y-feedback-mcp\dist\index.js"

或者将等效配置添加到 ~/.codex/config.toml：

[mcp_servers.a11y_feedback]
command = "node"
args = ["C:\\full\\path\\to\\a11y-feedback-mcp\\dist\\index.js"]
startup_timeout_sec = 30
tool_timeout_sec = 90

[mcp_servers.a11y_feedback.env]
A11Y_MCP_ALLOWED_ROOT = "C:\\full\\path\\to\\your-projects"

重启 Codex，然后询问：

以 1440×900 和 390×844 审计此页面。修复关键和严重问题，重新运行两次审计，并列出剩余的人工检查。

有关验证和故障排除，请参阅 docs/codex.md。

连接 Claude Code

claude mcp add --scope user a11y-feedback -- node "C:\full\path\to\a11y-feedback-mcp\dist\index.js"

运行 claude mcp list 以确认连接。有关 Claude Design 桥接工作流，请参阅 docs/claude-code-and-design.md。

开发

npm install
npm run check
npm test
npm run test:e2e
npm run build

npm test 涵盖颜色数学、网络保护、修复和 MCP 契约。npm run test:e2e 会启动 Chromium 并审计特意设计为不可访问的测试夹具。

启动本地 stdio 服务器：

npm run dev

启动可选的 Streamable HTTP 传输：

npm run build
npm run start:http

端点为 http://127.0.0.1:3000/mcp；健康检查为 http://127.0.0.1:3000/health。HTTP 默认绑定到 127.0.0.1。

环境变量

请勿将参考 HTTP 服务器直接暴露到公共互联网。在其前面设置身份验证、TLS、速率限制、请求大小限制和租户隔离。请阅读 docs/security.md。

当前范围

MVP 涵盖已渲染的 Web UI 和确定性的对比度计算。它尚不检查原生移动应用、PDF、画布、视频字幕或原始 Claude Design 像素。计划中的适配器可以在不更改 MCP 契约的情况下添加框架感知的补丁、截图/OCR 辅助、设计令牌集成、CI 注释和一流的画布连接器。

项目文档

• 架构和产品规范

• Codex 设置

• Claude Code 和 Claude Design 设置

• 安全模型

• W3C WAI 覆盖模型

• 配套智能体技能

• 贡献

许可证

MIT