剧作家可访问性测试MCP服务器
一个生产就绪的模型上下文协议（MCP）服务器，用于使用Playwright和axe-core进行全面的可访问性测试。轻松测试web应用程序是否符合WCAG 2.0/2.1。
特性
- 全面的WCAG测试：测试WCAG 2.0/2.1 A级/AA合规性和最佳实践
- 自然语言测试：按可见文本查找元素-不需要CSS选择器
- 自动发现：自动发现和测试所有交互元素
- 交互式组件测试：在不同状态下进行测试（下拉、模态等）
- 电脑屏幕截图工具：测试区域的视觉记录
- 预定义提示：常见测试场景的快速启动模板
- 生产准备就绪：模块化架构、TypeScript、全面的错误处理
安装
npm install
npm run build配置
添加到MCP客户端配置文件中：
克劳德桌面版 (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"playwright-a11y": {
"command": "node",
"args": ["/absolute/path/to/playwright-axe-mcp/dist/server.js"]
}
}
}克劳德代码 (.claude/config.json 在您的项目中）：
{
"mcpServers": {
"playwright-a11y": {
"command": "node",
"args": ["/absolute/path/to/playwright-axe-mcp/dist/server.js"]
}
}
}配置后重新启动MCP客户端。
快速开始
使用预定义提示（最简单！）
最快的测试方法是 综合a11y测试 提示：
Use comprehensive-a11y-test prompt:
- url: https://example.com
- block: Rewards account
- steps: open menu, select provider, input value, click apply参数：
url（必填）：要测试的URLblock（可选）：节名称（例如“导航”、“用户配置文件”）steps（可选）：逗号分隔的交互步骤
它的作用：
- 导航到URL
- 运行完全可访问性审核
- 使用自动发现或自定义步骤测试指定部分
- 生成人类可读的报告，包括：
- 执行摘要 - 关键/严重/中等/次要问题 - 优先修复建议
可用工具
1. a11y_scanUrl
扫描URL以查看是否存在可访问性违规。
参数：
{
url: string; // Required: URL to scan
selector?: string; // Optional: CSS selector to scan specific element
waitForSelector?: string; // Optional: Wait for this element before scanning
captureScreenshot?: boolean; // Optional: Capture screenshot (default: false)
timeout?: number; // Optional: Navigation timeout in ms (default: 30000)
}例子：
{
"url": "https://example.com",
"selector": "header nav",
"captureScreenshot": true
}2. a11y_scanInteractiveByText
使用自然语言测试组件-不需要CSS选择器！
参数：
{
url: string; // Required: URL to navigate to
containerText: string; // Required: Visible text to find section (e.g., "Rewards")
autoDiscover?: boolean; // Optional: Auto-discover interactions (default: true)
customInteractions?: Array;
captureScreenshots?: boolean; // Optional: Screenshot each state
timeout?: number; // Optional: Navigation timeout in ms
}示例：自动发现一切
{
"url": "https://example.com",
"containerText": "User Menu",
"autoDiscover": true,
"captureScreenshots": true
}示例：自定义交互
{
"url": "https://example.com",
"containerText": "Rewards",
"customInteractions": [
{
"stateName": "After opening menu",
"elementText": "View Details",
"action": "click"
}
]
}响应格式
扫描结果
{
"url": "https://example.com",
"timestamp": "2025-01-28T...",
"summary": {
"violations": 3,
"passes": 12,
"incomplete": 1
},
"violations": [
{
"id": "color-contrast",
"impact": "serious",
"description": "Elements must have sufficient color contrast",
"help": "Ensure contrast ratio is at least 4.5:1",
"helpUrl": "https://dequeuniversity.com/rules/axe/4.4/color-contrast",
"tags": ["wcag2aa", "wcag21aa"],
"nodes": [
{
"html": "Submit",
"target": [".btn"],
"failureSummary": "..."
}
]
}
],
"screenshotPath": "/path/to/screenshot.png"
}交互式扫描结果
{
"url": "https://example.com",
"containerText": "Rewards",
"totalStates": 3,
"states": [
{
"stateName": "Initial State",
"summary": {"violations": 0, "passes": 5, "incomplete": 0},
"violations": []
},
{
"stateName": "After interacting with buttons: \"View Details\"",
"action": "click",
"elementText": "View Details",
"summary": {"violations": 2, "passes": 8, "incomplete": 1},
"violations": [...]
}
]
}项目结构
server/
├── constants/ # Configuration and constants
│ ├── config.ts # Application configuration
│ ├── selectors.ts # Interactive element selectors
│ └── wcag-tags.ts # WCAG compliance tags
├── types/ # TypeScript type definitions
│ └── scan-result.ts # Scan result interfaces
├── utils/ # Utility functions
│ ├── axe-scanner.ts # Axe configuration and scanning
│ ├── browser.ts # Browser management
│ ├── container-finder.ts # Find elements by text
│ └── screenshot.ts # Screenshot utilities
├── tools/ # Tool implementations
│ ├── scan-url.ts # URL scanning tool
│ └── scan-interactive-by-text.ts # Interactive testing tool
├── prompts/ # Prompt templates
│ └── comprehensive-a11y-test.ts # Predefined test prompt
└── server.ts # Main MCP server entry pointWCAG合规性
此服务器测试：
- WCAG 2.0 A级 (
wcag2a) - WCAG 2.0 AA级 (
wcag2aa) - WCAG 2.1 A级 (
wcag21a) - WCAG 2.1 AA级 (
wcag21aa) - 最佳实践 (
best-practice)
影响程度
违规行为按严重程度分类：
- 关键的：完全阻止访问-立即修复
- 严肃的：造成重大障碍-发布前修复
- 适度：注意到的问题-很快修复
- 次要的：小改进-可以积压
输出文件
所有截图都保存到： ./accessibility-screenshots/
scan-{timestamp}.png-全页截图{name}-{timestamp}.png-命名截图
使用示例
测试一个简单的页面
User: "Check accessibility of https://example.com"
Claude: → Calls a11y_scanUrl
→ Returns: 3 violations (2 serious, 1 moderate)按名称测试特定部分
User: "Test the Navigation menu on https://example.com"
Claude: → Calls a11y_scanInteractiveByText with containerText="Navigation"
→ Auto-discovers all interactive elements
→ Returns: Issues found in different states使用自定义交互进行测试
User: "Test the Rewards section - click 'View Details' then 'Redeem'"
Claude: → Parses your request
→ Calls a11y_scanInteractiveByText with custom interactions
→ Returns: Accessibility analysis for each state发展
# Build TypeScript
npm run build
# Watch mode for development
npm run watch
# Start server directly (for testing)
npm start添加新工具
- 在中创建工具文件
server/tools/ - 定义模式和执行函数
- 注册
server/server.ts
添加新实用程序
- 在中创建实用程序文件
server/utils/ - 导出函数
- 在需要的地方进口
最佳实践
- 始终使用屏幕截图进行测试 在初始开发阶段：
{"captureScreenshot": true}- 等待动态内容 关于SPA：
{"waitForSelector": ".content-loaded"}- 测试交互式组件 在不同的州：
- 初始状态 - 用户交互后 - 错误状态 - 成功状态
- 使用自然语言测试 当你不知道选择器时：
{"containerText": "User Menu", "autoDiscover": true}故障排除
服务器未启动
npm run build
# Check config path is absolute
# Restart MCP client未找到元素
- 验证页面上是否存在文本
- 尝试更短、更具体的文本
- 检查内容是否已加载（使用
waitForSelector)
超时错误
{"timeout": 60000} // Increase to 60 seconds需求
- Node.js 18+
- Playwright（自动安装浏览器）
许可证
ISC
贡献
- 遵循模块化架构
- 为新功能添加TypeScript类型
- 在README中记录新工具
- 更新常量而不是硬编码值
______________________________________________________________________
采用模块化、可维护的架构，专为生产使用而构建。