Uu Wcag MCP

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"
}

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"
}

check_html_code

分析WCAG可访问性问题的HTML代码片段 部署前。返回可操作的建议。

参数：

{
  "html": "Click me",
  "context": "navigation menu",
  "language": "en"
}

get_wcag_rules

获取W3C WCAG官方指南，为特定标准或主题提供实用指导。

参数：

{
  "topic": "1.4.3",
  "language": "en"
}

可用主题： images, forms, keyboard, aria, color-contrast, focus, headings, links, video, audio, navigation, mobile, touch

suggest_aria

获取HTML元素和组件的ARIA属性建议。

参数：

{
  "element": "modal",
  "context": "confirmation dialog"
}

本地主机测试

要测试本地服务器，请使用 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 empty

Excel报告（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 Allow

Linux防火墙设置

sudo ufw allow 3000/tcp

Docker命令

# 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版本

注： 挪威法律尚未要求WCAG 2.2（2023）。

MCP工具摘要

项目结构

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