MCP-Web-无障碍服务

Name: MCP-Web-无障碍服务
Author: bilhasry-deriv

作者：bilhasry-deriv4 星标更新：2025-05-05

安装使用来源：spider==github.com

项目介绍

Web 可访问性 MCP 服务器

这是一个使用 axe-core 和 Puppeteer 提供网页可访问性分析能力的 MCP（模型上下文协议）服务器。

功能

使用 axe-core 分析任何 URL 的网页可访问性
使用颜色矩阵模拟色盲（红绿色盲、蓝黄色盲）
详细的可访问性违规报告
支持自定义用户代理和选择器
调试日志用于故障排除
基于 WCAG 指南的全面可访问性检查

先决条件

Node.js（v14 或更高版本）
npm

安装

通过 Smithery 安装

要通过 Smithery 自动安装 Web 可访问性 MCP 服务器到 Claude Desktop：

npx -y @smithery/cli install @bilhasry-deriv/mcp-web-a11y --client claude

手动安装

克隆仓库：

git clone [repository-url]
cd mcp-web-a11y

安装依赖项：

npm install

构建服务器：

npm run build

配置

将服务器添加到您的 MCP 设置文件中（通常位于 ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json）：

{
  "mcpServers": {
    "web-a11y": {
      "command": "node",
      "args": ["/path/to/mcp-web-a11y/build/index.js"],
      "disabled": false,
      "autoApprove": [],
      "env": {
        "MCP_OUTPUT_DIR": "/path/to/output/directory"
      }
    }
  }
}

环境变量

MCP_OUTPUT_DIR：截图输出保存的目录
- 对于 simulate_colorblind 工具是必需的
- 如果未指定，默认为当前工作目录下的 ./output
- 在 MCP 设置中配置时必须是绝对路径

使用

该服务器提供了两个工具：check_accessibility 用于分析网页可访问性，simulate_colorblind 用于模拟色盲。

工具：check_accessibility

使用 axe-core 检查给定 URL 的可访问性。

参数

url（必需）：要分析的 URL
waitForSelector（可选）：在分析之前等待的 CSS 选择器
userAgent（可选）：请求的自定义用户代理字符串

示例用法

<use_mcp_tool>
<server_name>mcp-web-a11y</server_name>
<tool_name>check_accessibility</tool_name>
<arguments>
{
  "url": "https://example.com",
  "waitForSelector": ".main-content",
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
}
</arguments>
</use_mcp_tool>

工具：simulate_colorblind

使用颜色矩阵变换模拟网页对不同类型的色盲用户的显示效果。

色盲类型

该工具支持三种类型的色盲模拟：

红绿色盲（红盲） - 使用矩阵：

0.567, 0.433, 0
0.558, 0.442, 0
0, 0.242, 0.758

绿黄色盲（绿盲） - 使用矩阵：
```
0.625, 0.375, 0
0.7, 0.3, 0
0, 0.3, 0.7
```

蓝黄色盲（蓝盲） - 使用矩阵：

0.95, 0.05, 0
0, 0.433, 0.567
0, 0.475, 0.525

参数

url（必需）：要捕获的 URL
type（必需）：要模拟的色盲类型（'protanopia'、'deuteranopia' 或 'tritanopia'）
outputPath（可选）：截图输出的自定义路径
userAgent（可选）：请求的自定义用户代理字符串

示例用法

<use_mcp_tool>
<server_name>mcp-web-a11y</server_name>
<tool_name>simulate_colorblind</tool_name>
<arguments>
{
  "url": "https://example.com",
  "type": "deuteranopia",
  "outputPath": "colorblind_simulation.png"
}
</arguments>
</use_mcp_tool>

响应格式

check_accessibility 响应

{
  "url": "analyzed-url",
  "timestamp": "ISO-timestamp",
  "violations": [
    {
      "impact": "serious|critical|moderate|minor",
      "description": "违规描述",
      "help": "解释问题的帮助文本",
      "helpUrl": "详细文档的 URL",
      "nodes": [
        {
          "html": "受影响元素的 HTML",
          "failureSummary": "需要修复的总结"
        }
      ]
    }
  ],
  "passes": 42,
  "inapplicable": 45,
  "incomplete": 3
}

simulate_colorblind 响应

{
  "url": "analyzed-url",
  "type": "colorblind-type",
  "outputPath": "path/to/screenshot.png",
  "timestamp": "ISO-timestamp",
  "message": "[type] 模拟的截图已保存"
}

错误处理

该服务器包括针对常见情况的全面错误处理：

网络错误
无效的 URL
超时问题
DNS 解析问题

错误响应将包含详细的诊断信息。

开发

项目结构

mcp-web-a11y/
├── src/
│   └── index.ts    # 主服务器实现
├── build/          # 编译后的 JavaScript
├── output/         # 生成的截图
├── package.json    # 项目依赖项和脚本
└── tsconfig.json   # TypeScript 配置

构建

npm run build

这将：

将 TypeScript 编译为 JavaScript
使输出文件可执行
将编译后的文件放置在 build 目录中

调试

该服务器包括可以在控制台输出中观察到的详细调试日志。这包括：

网络请求和响应
页面加载状态
选择器等待状态
来自分析页面的任何控制台消息
颜色模拟进度

常见问题及解决方案

超时错误
- 在代码中增加超时值
- 检查网络连接
- 验证 URL 是否可访问
DNS 解析错误
- 验证 URL 是否正确
- 检查网络连接
- 尝试使用 www 子域
选择器未找到
- 验证选择器是否存在于页面上
- 等待动态内容加载
- 检查页面源以获取正确的选择器
颜色模拟问题
- 确保页面的颜色是以受支持的格式（RGB、RGBA 或 HEX）指定的
- 检查页面是否使用了动态颜色变化（可能需要额外的等待时间）
- 验证截图输出目录是否存在且可写

贡献

分叉仓库
创建一个功能分支
提交更改
推送到分支
创建拉取请求

许可证

此项目根据 MIT 许可证发布 - 查看 LICENSE 文件以获取详细信息。