WCAG报告MCP服务器
用于自动WCAG合规性分析的模型上下文协议（MCP）服务器 pa11y 与官方 UU愿景 Excel模板。使用Node.js 22构建，支持HTTP和stdio传输。
特性
- 行业标准 -由pa11y（HTML代码嗅探器+斧头核心）提供技术支持
- 官方模板 -UU tilsynet WCAG WEB和APP检查表
- WCAG官方数据 -W3C WCAG 2.1规范及实用模板
- 多种格式 -带WCAG标准分组的Markdown或Excel报告
- 多语言 -挪威语和英语支持
- HTTP传输 -VS Code MCP客户端的流式HTTP
- Docker就绪 -使用Google Chrome进行容器化
- 本地主机测试 -测试本地开发服务器
- SPA优化 -React、Vue、Svelte、Angular的特殊配置
- 静态代码分析 -部署前检查HTML代码的可访问性
- i18n支持 -在分析之前等待翻译加载
快速开始
# Clone and start
git clone
cd uu-wcag-mcp
docker compose up -d --build注： 默认配置使用networkidle0等待8秒。对于更简单的网站，减少 PA11Y_WAIT 至5000英寸 docker-compose.yml.
添加到VS代码MCP设置
添加到MCP设置（Ctrl+Shift+P→ “MCP：编辑设置”）：
{
"mcpServers": {
"uu-wcag-mcp": {
"type": "http",
"url": "http://localhost:3100/mcp"
}
}
}替代（标准输入模式）：
{
"mcpServers": {
"uu-wcag-mcp": {
"type": "stdio",
"command": "docker",
"args": ["exec", "-i", "uu-wcag-mcp", "node", "src/index.js"]
}
}
}MCP工具
analyze_wcag
完整的WCAG分析，包括页面爬行和官方UU tilsynet模板。
参数：
{
"url": "https://example.com",
"max_depth": 2,
"max_pages": 10,
"format": "markdown",
"language": "no",
"checklist_type": "WEB",
"standard": "WCAG2AA"
}| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
url | 字符串 | *必需的* | 要分析的网站URL |
max_depth | number | 2 | 最大爬行深度 |
max_pages | number | 10 | 要分析的最大页数 |
format | 字符串 | markdown | 报告格式： markdown 或 excel |
language | 字符串 | no | 报告语言： no 或 en |
checklist_type | 字符串 | WEB | Excel模板： WEB 或 APP |
standard | 字符串 | WCAG2AA | WCAG级别： WCAG2A, WCAG2AA，或 WCAG2AAA |
Excel报表示例：
{
"url": "https://vg.no",
"format": "excel",
"checklist_type": "WEB",
"max_pages": 20,
"language": "no"
}quick_check
快速单页WCAG检查（无爬行）。
参数：
{
"url": "https://example.com",
"language": "en",
"standard": "WCAG2AA"
}| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
url | 字符串 | *必需的* | 要检查的页面URL |
language | 字符串 | no | 报告语言： no 或 en |
standard | 字符串 | WCAG2AA | WCAG级别： WCAG2A, WCAG2AA，或 WCAG2AAA |
check_html_code
分析WCAG可访问性问题的HTML代码片段 部署前。返回可操作的建议。
参数：
{
"html": "Click me",
"context": "navigation menu",
"language": "en"
}| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
html | 字符串 | *必需的* | 要分析的HTML代码 |
context | string | - | 可选上下文（例如“登录表单”） |
language | 字符串 | en | 报告语言： no 或 en |
get_wcag_rules
获取W3C WCAG官方指南，为特定标准或主题提供实用指导。
参数：
{
"topic": "1.4.3",
"language": "en"
}| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
topic | 字符串 | *必需的* | WCAG标准（1.4.3）或主题（图像、表单、键盘） |
language | 字符串 | en | 报告语言： no 或 en |
可用主题： images, forms, keyboard, aria, color-contrast, focus, headings, links, video, audio, navigation, mobile, touch
suggest_aria
获取HTML元素和组件的ARIA属性建议。
参数：
{
"element": "modal",
"context": "confirmation dialog"
}| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
element | 字符串 | *必需的* | 元素类型： modal, dropdown, tabs, accordion, button, navigation, alert, tooltip, combobox, tree |
context | string | - | 有关用例的其他上下文 |
本地主机测试
要测试本地服务器，请使用 host.docker.internal 而不是 localhost:
{
"url": "http://host.docker.internal:3000"
}报表格式
Markdown报告
基于WCAG标准分组的文本报告：
- WCAG成功标准总结（1.1.1、2.4.2等）
- 按标准细分的详细问题
- 严重性计数（严重、严重、中等、轻微）
- 逐页结果
例子：
## WCAG Success Criteria Violations
[ERROR] **2.4.2** - Error (3 issues)
[WARNING] **1.4.3** - Warning (5 issues)
### 2.4.2
[ERROR] Page title is missing or emptyExcel报告（UU tilsynet官方模板）
可下载的 .xlsx 挪威UU tilsynet检查表文件：
- WCAG官方检查表模板
- 颜色编码状态单元格（红色=错误，橙色=警告，绿色=通过）
- 带有违规详细信息的单元格注释
- 关于自动化测试的免责声明
- 选择
WEB或APP模板通过checklist_type
模板：
WCAG-sjekkliste-web.xlsx-Web应用程序（997行）WCAG-sjekkliste-app.xlsx-移动应用程序（993行）
Windows防火墙设置
# Run as Administrator
New-NetFirewallRule -DisplayName "Dev Server 3000" -Direction Inbound -LocalPort 3000 -Protocol TCP -Action AllowLinux防火墙设置
sudo ufw allow 3000/tcpDocker命令
# Start
docker compose up -d
# Rebuild
docker compose down && docker compose build --no-cache && docker compose up -d
# View logs
docker logs --tail 100 uu-wcag-mcp
# Debug
docker exec -it uu-wcag-mcp /bin/bash
# Health check
curl http://localhost:3100/health配置
环境变量（可选 .env 或 docker-compose.yml):
# Logging
LOG_LEVEL=info
# Crawling settings
CRAWL_DELAY=1000
# pa11y configuration
TIMEOUT=60000
WCAG_STANDARD=WCAG2AA
HEADLESS=true
# SPA/i18n support
PA11Y_WAIT=5000 # Wait 5 seconds for JS/translations (increase for slow SPAs)
PA11Y_WAIT_UNTIL=networkidle2 # Wait for network idle (use networkidle0 for stricter wait)
# Viewport
VIEWPORT_WIDTH=1280
VIEWPORT_HEIGHT=720
# User agent
USER_AGENT=WCAG-Analyzer/1.0 (pa11y)默认配置： 适用于大多数网站。对于具有i18n的复杂SPA，增加 PA11Y_WAIT 至8000ms并使用 networkidle0.
重要提示
自动化测试限制
自动化工具仅检测到约30-40%的可访问性问题！
- 使用此工具 快速筛选
- 始终手动验证 发现
- 测试用 真实屏幕阅读器 （NVDA、JAWS、画外音）
- 执行 键盘导航测试
- 进行 用户测试 与残疾人
常见误报：
- 加载JavaScript之前，SPA（React/Svelte/Vue）中的标题为空
- 动态内容尚未呈现
- 慢速网络的时间问题
解决方案： 默认配置已等待8秒 PA11Y_WAIT=8000 和 PA11Y_WAIT_UNTIL=networkidle0，它处理大多数SPA和i18n场景。如果问题仍然存在，请检查应用程序的实际DOM状态。
看 docs/FALSE_POSITIVES.md 获取详细指导
WCAG版本
| 标准 | 说明 |
|---|---|
| WCAG2AA | WCAG 2.1 AA级 （挪威法律要求-默认） |
| WCAG2A | WCAG 2.1 A级（最低） |
| WCAG2AAA | WCAG 2.1 AAA级（严格，可选） |
注： 挪威法律尚未要求WCAG 2.2（2023）。
MCP工具摘要
| 工具 | 说明 |
|---|---|
analyze_wcag | 完整的网站分析，包括爬行和Excel报告 |
quick_check | 单页快速WCAG检查 |
check_html_code | 部署前的静态HTML代码分析 |
get_wcag_rules | W3C WCAG 2.1官方指南+实用技巧 |
suggest_aria | 通用UI组件的ARIA模式 |
项目结构
uu-wcag-mcp/
├── src/
│ ├── index.js # MCP server (HTTP + stdio transport)
│ ├── analyzer.js # pa11y WCAG analysis
│ ├── scraper.js # Web crawling
│ ├── reporter.js # Excel report generation
│ ├── wcag-data.js # W3C WCAG 2.1 data + templates
│ ├── config.js # Configuration
│ ├── logger.js # Winston logging
│ └── contents/ # UU-tilsynet Excel templates
│ ├── WCAG-sjekkliste-web.xlsx
│ └── WCAG-sjekkliste-app.xlsx
├── Dockerfile # Multi-stage Docker build
├── docker-compose.yml # Container configuration
├── package.json # Node.js 22+ dependencies
└── README.md