使用说明

GitHub可访问性审查员MCP服务器

基于GitHub的MCP辅助功能评审器A. 生产准备就绪 使用可定制的模型上下文协议（MCP）将自动可访问性代码审查工作流集成到GitHub管道中。该系统使用混合分析引擎（快速正则表达式+精确AST解析）对所有拉取请求执行WCAG 2.2 AA标准。这减少了人工审查的工作量，防止了可访问性回归，并为未来的人工智能辅助执法奠定了可扩展的基础。

🎯 项目状态

✅ 生产就绪v2.0.0 -具有全面WCAG 2.2 AA覆盖的混合架构
下一阶段：LDS组件验证和高级规则自定义
最终目标：通过全面的设计系统集成，人工智能辅助无障碍执行

🌟 特性

核心功能（生产就绪）

混合分析引擎：快速正则表达式（1-5ms）+增强的上下文分析，准确率达到95%以上
多文件类型支持：分析 .js, .jsx, .ts, .tsx, .html, .htm, .css，以及 .scss 文件
WCAG 2.2 AA合规性：15+全面违规检查
GitHub操作集成：自动进行PR检查，并提供详细的违规报告
MCP协议：用于工具集成的标准化JSON-RPC接口
易于集成：为团队设置一个命令（5分钟）
批处理：分析单个请求中的多个文件
修复建议：针对每种违规类型的可操作补救指南

规划功能（路线图）

LDS集成：验证礼来设计系统组件的使用情况，并执行批准的模式
可自定义规则：配置每个存储库的规则严重性、排除和阈值
基于AST的分析：用于复杂违规检测的高级解析
人工智能辅助修复：自动代码建议和PR自动修复

已实施可访问性检查

图片与媒体

缺少Alt文本：检测 <img> 标签无 alt 属性

交互式元素

Div as按钮：旗帜 <div> 元素与 onClick 处理程序（应使用 <button>)
空按钮：检测没有文本内容的按钮或 aria-label
通用链接文本：查找包含非描述性文本的链接（“单击此处”、“阅读更多”）

表单

无标签输入：标识缺少关联的表单输入 <label> 元素

文档结构

缺少语言：检测没有以下内容的HTML文档 lang 属性
缺少页面标题：标识没有的HTML <title> 元素
没有标题的Iframes：旗帜 <iframe> 元素没有 title 属性

焦点和键盘（CSS）

缺少焦点样式：检测缺失的CSS :focus 样式
大纲已删除，无其他选择：旗帜 outline: none 没有其他焦点指示器
字体太小：检测低于可读最小值的字体大小
触摸目标太小：标记最小44x44px以下的交互元素
在交互界面上不显示任何内容：警告 display: none 隐藏交互式内容
透明文本颜色：检测 color: transparent 使文本不可见
指针事件已禁用：旗帜 pointer-events: none 论互动要素

MCP工具可用

服务器提供 3个MCP工具 通过JSON-RPC：

check_accessibility：分析单个文件中的违规行为
check_accessibility_batch：在一个请求中分析多个文件
suggest_fix：获取违规行为的详细补救指南

🚀 快速开始

先决条件

Node.js 18+ (点击此处下载)
npm （附带Node.js）
GitHub 仓库 具有管理员访问权限（用于GitHub Actions集成）

安装

克隆仓库

git clone https://github.com/berucha-lilly/a11y-mcp.git
cd a11y-mcp

安装依赖项

npm install

测试MCP服务器

# List available MCP tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node src/mcp-server.js

预期输出：JSON响应列出了3个可用工具

使用CLI扫描程序进行本地测试

# Test a single file
node cli-scanner.js path/to/your-file.jsx

# Test all files in a directory
./run.sh path/to/directory

# View results in JSON format
node cli-scanner.js path/to/your-file.jsx --json

GitHub操作集成

请参阅 完整的初学者指南 有关详细的分步设置说明。

� MCP工具参考

服务器实现了模型上下文协议，并提供了3个可通过JSON-RPC访问的工具：

工具1： `check_accessibility`

分析单个文件的可访问性违规。

输入架构：

{
  "filePath": "src/components/Button.jsx",
  "content": "<button></button>"
}

请求示例：

cat << 'EOF' | node src/mcp-server.js
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "check_accessibility",
    "arguments": {
      "filePath": "test.jsx",
      "content": "<img src='logo.png' />"
    }
  }
}
EOF

退货：

违规次数
带有行号的违规行为列表
严重性级别（错误/警告）
WCAG标准参考
修复建议

工具2： `check_accessibility_batch`

在单个请求中分析多个文件。

输入架构：

{
  "files": [
    {
      "path": "src/App.jsx",
      "content": "..."
    },
    {
      "path": "src/styles.css",
      "content": "..."
    }
  ]
}

退货：

每个文件的结果
汇总统计
总体通过/失败状态

工具3： `suggest_fix`

获取特定违规类型的详细补救指南。

输入架构：

{
  "violationType": "img-missing-alt",
  "context": {
    "line": 42,
    "code": "<img src='logo.png' />"
  }
}

退货：

逐步修复说明
代码示例（之前/之后）
WCAG文档链接
最佳实践

🔗 GitHub操作集成

自动检查每个拉取请求是否存在可访问性违规。

安装程序（快速版本）

将MCP服务器复制到您的存储库：

mkdir -p .github/a11y-mcp
cp src/mcp-server.js .github/a11y-mcp/
cp package.json package-lock.json .github/a11y-mcp/
cd .github/a11y-mcp && npm ci && cd ../..

添加工作流文件：

mkdir -p .github/workflows
cp github-actions/accessibility-review.yml .github/workflows/

承诺并推动：

git add .github/
git commit -m "Add MCP accessibility checks"
git push

每个PR都会发生什么

触发：工作流在每个更改的PR上运行 .js, .jsx, .ts, .tsx, .html, .css，或 .scss 文件
分析：MCP服务器通过JSON-RPC检查所有更改的文件
报告：Bot对PR的评论：
- 发现的违规行为总数
- 按文件细分
- 行号和描述
- 修复建议
- WCAG标准参考
状态检查：可以阻止合并的通过/失败检查

PR评论示例

## 🔍 Accessibility Review Results (via MCP)

**Files Checked:** 3
**Total Violations:** 5 (4 errors, 1 warning)

### ❌ src/components/Button.jsx
- **Line 12**: [ERROR] Image missing alt attribute
  - Fix: Add alt="description" to image
  - WCAG: 1.1.1 (Level A)

- **Line 24**: [ERROR] Div used as button
  - Fix: Use <button> element instead
  - WCAG: 4.1.2 (Level A)

需要进行检查

到 块合并 当发现违规行为时：

首选 存储库设置 → 分支
添加/编辑分支保护规则 main
启用“合并前要求状态检查通过”
选择“通过MCP检查可访问性”
保存更改

请参阅新手指南有关截图的详细分步说明。

📖 使用示例

示例1：在本地测试单个文件

# Create a test file with violations
cat > test.jsx << 'EOF'
export const MyComponent = () => {
  return (
    <div>
      <img src="logo.png" />
      <div onClick={() => alert('hi')}>Click me</div>
    </div>
  );
};
EOF

# Run the CLI scanner
node cli-scanner.js test.jsx

输出：

📄 File: test.jsx
❌ Result: Found 2 accessibility violation(s):

1. [ERROR] Image missing alt attribute
   📍 Line: 4
   💡 Fix: Add alt="description" to the image tag
   📚 WCAG: 1.1.1 (Level A)

2. [ERROR] Div used as button
   📍 Line: 5
   💡 Fix: Use <button> element instead of div with onClick
   📚 WCAG: 4.1.2 (Level A)

示例2：直接使用MCP协议

# Check a file via JSON-RPC
cat << 'EOF' | node src/mcp-server.js 2>/dev/null | jq
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "check_accessibility",
    "arguments": {
      "filePath": "Button.jsx",
      "content": "<button></button>"
    }
  }
}
EOF

退货： 带有违规详细信息的JSON

示例3：批量检查多个文件

# Use the batch tool
cat << 'EOF' | node src/mcp-server.js 2>/dev/null | jq
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "check_accessibility_batch",
    "arguments": {
      "files": [
        {
          "path": "App.jsx",
          "content": "<div onClick={...}>Click</div>"
        },
        {
          "path": "styles.css",
          "content": ":focus { outline: none; }"
        }
      ]
    }
  }
}
EOF

示例4：获取修复建议

# Request fix suggestions for a violation type
cat << 'EOF' | node src/mcp-server.js 2>/dev/null | jq
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "suggest_fix",
    "arguments": {
      "violationType": "img-missing-alt",
      "context": {
        "code": "<img src='logo.png' />",
        "line": 10
      }
    }
  }
}
EOF

退货： 详细的补救步骤和代码示例

🏗️ 建筑

系统概述

┌─────────────────────┐
│  GitHub Actions     │  Triggers on PR
└──────────┬──────────┘
           │ (JSON-RPC)
           ▼
┌─────────────────────┐
│  MCP Server         │  src/mcp-server.js (production)
│  - check_a11y       │  Uses hybrid analyzer (regex + enhanced context)
│  - batch_check      │  Returns violations + suggestions
│  - suggest_fix      │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  GitHub API         │  Posts results to PR
└─────────────────────┘

Future: LDS Storybook integration →

核心组件

1.生产MCP服务器 (src/mcp-server.js)

实现模型上下文协议（JSON-RPC 2.0）
使用混合分析器（快速正则表达式+增强上下文）
提供3个可访问性检查工具
返回结构化JSON结果

2.CLI扫描程序 (cli-scanner.js)

独立命令行界面
与MCP服务器相同的分析逻辑
用于本地测试的人类可读输出
CI/CD的JSON输出模式

3.GitHub操作工作流 (github-actions/accessibility-review.yml)

检测PR中更改的文件
通过stdio/JSON-RPC调用MCP服务器
将结果格式化为PR评论
上传工件（请求/响应日志）

4.批处理运行器 (run.sh)

用于测试多个文件的Shell脚本
容错（故障时继续）
生成带时间戳的摘要报告

分析方法

混合分析 （当前实施）：

基于正则表达式的简单模式快速检测（1-5ms）
在需要时加强对复杂违规行为的背景分析
智能路由自动选择最佳方法
涵盖15+WCAG 2.2 AA违规

未来增强-LDS集成:

查询LDS Storybook API以获取组件规格
根据批准的模式验证组件使用情况
为非标准元件提出LDS替代方案
轨道设计系统采用指标

未来增强-AST解析:

基于AST的Babel/PostCSS解析
更复杂的规则引擎
WCAG标准覆盖范围

🛠️ 发展

项目结构

a11y-mcp/
├── src/
│   ├── mcp-server.js           # Production MCP server (hybrid analyzer)
│   └── core/
│       ├── hybrid-analyzer.js  # Hybrid analyzer (regex + AST)
│       └── regex-analyzer.js   # Fast regex-based analyzer
├── cli-scanner.js              # CLI testing tool
├── run.sh                      # Batch file scanner
├── package.json                # Dependencies
├── mcp-server.json             # MCP configuration
├── github-actions/
│   └── accessibility-review.yml  # GitHub Actions workflow
├── docs/
│   ├── BEGINNERS_GUIDE.md              # Step-by-step setup guide
│   └── MCP_GITHUB_ACTIONS_SETUP.md     # Technical reference
├── examples/                   # Test files with violations
└── README.md                   # This file

添加新的辅助功能检查

编辑 src/core/regex-analyzer.js 并添加到 analyzeFile() 功能：

// Example: Check for missing form labels
const formLabelPattern = /<input[^>]+type=["'](?:text|email|password)[^>]*>/gi;
let match;
while ((match = formLabelPattern.exec(content)) !== null) {
  const lineNum = content.substring(0, match.index).split('\n').length;
  const inputTag = match[0];
  
  // Check if input has associated label
  const hasId = /id=["'][^"']+["']/.test(inputTag);
  const hasAriaLabel = /aria-label=["'][^"']+["']/.test(inputTag);
  
  if (!hasId && !hasAriaLabel) {
    violations.push({
      type: 'error',
      rule: 'input-missing-label',
      message: 'Form input missing associated label',
      line: lineNum,
      wcagCriteria: '3.3.2',
      wcagLevel: 'A',
      suggestions: [
        'Add a <label> element with for="inputId"',
        'Add aria-label="description" to the input'
      ]
    });
  }
}

自定义严重性级别

改变 type: 'error' 到 type: 'warning' 用于非阻塞检查。

本地测试更改

# Test your changes on example files
node cli-scanner.js examples/accessibility-violations.jsx

# Test via MCP protocol
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node src/mcp-server.js

# Test batch processing
./run.sh examples/

🆘 故障排除

常见问题

Q： MCP服务器未启动

# Check Node.js version (must be 18+)
node --version

# Verify dependencies are installed
npm list @modelcontextprotocol/sdk

Q：没有发现违规行为，但我在代码中看到了问题

检查是否支持文件扩展名(.js, .jsx, .ts, .tsx, .html, .css, .scss)
违规类型可能不在当前的15+次检查中
一些复杂的违规行为可能需要AST解析（在需要时自动使用）

Q： GitHub操作工作流未运行

# Verify workflow file exists
ls .github/workflows/accessibility-check.yml

# Check YAML syntax is valid
cat .github/workflows/accessibility-check.yml

Q： GitHub操作中出现“找不到模块”错误

确保 package.json 和 package-lock.json 在 .github/a11y-mcp/
检查 npm ci 步骤在调用MCP服务器之前运行

Q：结果中的假阳性

查看匹配的特定模式
考虑违规行为是否真的有效
如果需要，添加到忽略的文件/模式

先在本地测试

在推送到GitHub之前，始终在本地测试更改：

# 1. Test MCP server starts
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node src/mcp-server.js

# 2. Test on a known file with violations
node cli-scanner.js examples/accessibility-violations.jsx

# 3. Test batch processing
./run.sh examples/

# 4. If all pass, commit and push
git add .
git commit -m "Update accessibility checks"
git push

📚 文档

快速入门指南 -5分钟后开始
新手指南 -完成分步设置（建议首次使用）
集成指南 -详细的集成说明
PowerShell安装程序 -Windows用户指南
建筑 -系统设计和组件
演示 -团队演示材料
例子 -测试中存在可访问性违规的示例文件
WCAG 2.2指南 -WCAG官方文件

🔄 路线图

✅ 第1阶段-MVP（当前）

✅ 15+可访问性检查（WCAG 2.2 AA）
✅ 混合分析（快速正则表达式+AST解析）
✅ MCP协议实现
✅ GitHub操作集成
✅ 用于本地测试的CLI扫描程序
✅ 批处理文件
✅ 带有违规详细信息的公关评论

🚧 第2阶段-LDS集成（下）

🔲 礼来设计系统（LDS）验证：强制使用批准的LDS组件
🔲 组件规格：查询LDS故事书以了解可访问性要求
🔲 备选建议：为非标准元件推荐LDS组件
🔲 设计系统合规性评分：跟踪存储库中LDS的采用情况

🔮 第3阶段-高级功能（未来）

🔲 附加WCAG标准（颜色对比度计算、标题层次验证）
🔲 可配置规则引擎（每个仓库 .a11y/config.json -文件已创建但尚未运行）
🔲 运行时检查的HTML渲染（检测动态违规）
🔲 人工智能辅助代码修复（自动PR建议）
🔲 用于内联检查的VS代码扩展
🔲 合规仪表板和分析

🎯 最终目标

人工智能辅助无障碍执行：一个综合系统，结合了：

实时WCAG 2.2 AA验证
LDS组件执行
通过AI自动生成修复
历史合规性跟踪
团队教育和最佳实践

📄 许可证

MIT许可证-请参阅许可证文件以获取详细信息。

🙏 致谢

W3C网络无障碍倡议 WCAG 2.2指南
模型上下文协议 标准化工具接口社区
GitHub操作 用于CI/CD自动化功能

使用说明

GitHub可访问性审查员MCP服务器

🎯 项目状态

🌟 特性

核心功能（生产就绪）

规划功能（路线图）

已实施可访问性检查

图片与媒体

交互式元素

表单

文档结构

焦点和键盘（CSS）

MCP工具可用

🚀 快速开始

先决条件

安装

使用CLI扫描程序进行本地测试

GitHub操作集成

� MCP工具参考

工具1： check_accessibility

工具2： check_accessibility_batch

工具3： suggest_fix

🔗 GitHub操作集成

安装程序（快速版本）

每个PR都会发生什么

PR评论示例

需要进行检查

📖 使用示例

示例1：在本地测试单个文件

示例2：直接使用MCP协议

示例3：批量检查多个文件

示例4：获取修复建议

🏗️ 建筑

系统概述

核心组件

分析方法

🛠️ 发展

项目结构

添加新的辅助功能检查

自定义严重性级别

本地测试更改

🆘 故障排除

常见问题

先在本地测试

📚 文档

🔄 路线图

✅ 第1阶段-MVP（当前）

🚧 第2阶段-LDS集成（下）

🔮 第3阶段-高级功能（未来）

🎯 最终目标

📄 许可证

🙏 致谢

相关 MCP

网页无障碍扫描器

无障碍代码审查 MCP 服务

SonarCloud问题获取服务

无障碍测试服务

代码审查服务器

AI应用生产就绪扫描器

工具1： `check_accessibility`

工具2： `check_accessibility_batch`

工具3： `suggest_fix`