使用说明

可访问性MCP服务器

MCP（模型上下文协议）服务器，通过Cursor为LLM提供可访问性审计工具。集成axe-core（通过Playwright）、Lighthouse CLI和可选的WAVE API，以提供确定性的、机器可操作的可访问性审计结果。

特征

斧头核心集成：通过Playwright进行自动化无障碍测试，覆盖WCAG 2.1/2.2
Lighthouse CLI：全面的可访问性审计和绩效洞察
WAVE API：可选集成以进行额外的可访问性验证
确定性输出：所有结果均标准化为明确的通过/失败/未知结果
WCAG合规性：每个发现都符合WCAG 2.1/2.2标准，并进行了严重程度分类
机器可操作：结果包括用于补救的选择器和DOM上下文
类型安全：具有严格类型检查的完整TypeScript实现

安装

# Clone the repository
git clone <repository-url>
cd accessibility-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Install Playwright browsers (required for axe-core)
npx playwright install chromium

配置

创建 .env 项目根目录中的文件（请参见 .env.example 模板）：

# WAVE API Configuration (optional)
WAVE_API_KEY=your_wave_api_key_here
WAVE_API_URL=https://wave.webaim.org/api/request

# Lighthouse Configuration (optional)
LIGHTHOUSE_TIMEOUT=60000
LIGHTHOUSE_CHROME_FLAGS=--headless --no-sandbox

# Playwright Configuration (optional)
PLAYWRIGHT_BROWSER=chromium
PLAYWRIGHT_TIMEOUT=30000

用法

作为游标中的MCP服务器

构建项目： npm run build
在Cursor的MCP设置中配置(~/.cursor/mcp.json 或光标设置）：

{
  "mcpServers": {
    "accessibility": {
      "command": "node",
      "args": ["/absolute/path/to/accessibility-mcp/dist/index.js"]
    }
  }
}

重新启动Cursor以加载MCP服务器

可用的MCP工具

`axe_audit`

通过Playwright使用axe-core进行可访问性审计。支持URL、本地文件路径和本地主机URL。

参数：

url （必填）：要审核的URL。可以是：
- HTTP/HTTPS网址： "https://example.com" 或 "http://localhost:3000"
- 本地文件路径： "./index.html" 或 "/path/to/file.html"
- 文件协议URL: "file:///path/to/file.html"
options （可选）：配置对象
- tagsWCAG标签阵列（例如。， ["wcag2a", "wcag2aa"])
- rules：具有规则特定配置的对象
- timeout：超时时间（毫秒）（默认值：30000）
- browser：要使用的浏览器- "chromium", "firefox"，或 "webkit" （默认值： "chromium")

示例：

{
  "name": "axe_audit",
  "arguments": {
    "url": "https://example.com",
    "options": {
      "tags": ["wcag2a", "wcag2aa"],
      "browser": "chromium"
    }
  }
}

{
  "name": "axe_audit",
  "arguments": {
    "url": "./src/index.html"
  }
}

{
  "name": "axe_audit",
  "arguments": {
    "url": "http://localhost:3000"
  }
}

`lighthouse_audit`

使用Lighthouse CLI运行可访问性审核。支持URL、本地文件路径和本地主机URL。

参数：

url （必填）：要审核的URL。可以是：
- HTTP/HTTPS网址： "https://example.com" 或 "http://localhost:3000"
- 本地文件路径： "./index.html" 或 "/path/to/file.html"
- 文件协议URL: "file:///path/to/file.html"
categories （可选）：要包含的灯塔类别数组
options （可选）：配置对象
- onlyCategories：要包含的类别数组
- skipAudits：要跳过的审核ID数组
- timeout：超时时间（毫秒）（默认值：60000）

示例：

{
  "name": "lighthouse_audit",
  "arguments": {
    "url": "https://example.com",
    "categories": ["accessibility"]
  }
}

{
  "name": "lighthouse_audit",
  "arguments": {
    "url": "./dist/index.html"
  }
}

`wave_audit`

使用WAVE API运行可访问性审核（需要API密钥）。支持URL和localhost URL。本地文件通过临时本地服务器自动提供。

参数：

url （必填）：要审核的URL。可以是：
- HTTP/HTTPS网址： "https://example.com" 或 "http://localhost:3000"
- 本地文件路径： "./index.html" （将通过临时服务器提供）
apiKey （可选）：WAVE API密钥（使用 WAVE_API_KEY env-var（如果未提供）

示例：

{
  "name": "wave_audit",
  "arguments": {
    "url": "https://example.com",
    "apiKey": "your_api_key"
  }
}

{
  "name": "wave_audit",
  "arguments": {
    "url": "./src/index.html"
  }
}

注：对于本地文件，MCP服务器会自动创建一个临时HTTP服务器来为文件提供服务，因为WAVE API需要HTTP/HTTPS URL。

输出格式

所有工具均以以下格式返回标准化结果：

{
  url: string;
  tool: 'axe' | 'lighthouse' | 'wave';
  timestamp: string;
  results: Array<{
    rule_id: string;
    wcag_ref: string[];
    severity: 'critical' | 'serious' | 'moderate' | 'minor';
    confidence: 'high' | 'medium' | 'low';
    outcome: 'pass' | 'fail' | 'unknown';
    selector: string;
    dom_context: string;
    message: string;
    reason_code?: string; // Required when outcome is 'unknown'
  }>;
  summary: {
    total: number;
    pass: number;
    fail: number;
    unknown: number;
    by_severity: {
      critical: number;
      serious: number;
      moderate: number;
      minor: number;
    };
  };
}

发展

先决条件

Node.js 18.0.0或更高版本
npm或纱线

脚本

# Development mode (with hot reload)
npm run dev

# Build TypeScript to JavaScript
npm run build

# Run all tests
npm test

# Run unit tests only
npm run test:unit

# Run integration tests only
npm run test:integration

# Type check without building
npm run type-check

# Lint code
npm run lint

项目结构

accessibility-mcp/
├── .cursor/
│   ├── rules/          # Cursor behavioural constraints
│   └── commands/       # Cursor repeatable actions
├── src/
│   ├── adapters/       # External tool adapters (axe, Lighthouse, WAVE)
│   ├── services/       # Business logic (audits, normalisation)
│   ├── tools/          # MCP tool definitions
│   ├── types/          # TypeScript type definitions
│   ├── utils/          # Utility functions (WCAG mappings, selectors)
│   ├── index.ts        # Entry point
│   └── server.ts       # MCP server setup
├── tests/
│   ├── fixtures/       # Test data fixtures
│   ├── unit/           # Unit tests
│   └── integration/    # Integration tests
└── dist/               # Compiled JavaScript output

建筑

服务器遵循干净的架构模式：

工具层 (src/tools/)：暴露审计功能的MCP工具定义
服务层 (src/services/)：审计执行和结果标准化的业务逻辑
适配器层 (src/adapters/)：外部工具（斧头、灯塔、WAVE）的接口层
类型图层 (src/types/)：审计结果和标准化输出的共享类型定义

添加新的审核工具

看 .cursor/commands/add-new-audit-tool.md 有关添加新的可访问性审计工具的详细说明。

测试

# Run all tests
npm test

# Run with coverage
npm test -- --coverage

# Run specific test file
npm test tests/unit/normaliser.test.ts

CI/CD集成

该项目包括用于CI/CD集成的命令。看 .cursor/commands/ci-gate-accessibility.md 有关在CI管道中设置可访问性门的详细信息。

贡献

遵循中定义的架构约束 .cursor/rules/
确保所有代码通过类型检查： npm run type-check
为新功能编写测试
确保确定性输出（参见 .cursor/rules/determinism.md)
将所有发现映射到WCAG标准（参见 .cursor/rules/accessibility.md)

许可证

麻省理工学院

致谢

斧头核心 -可访问性测试引擎
灯塔 -Web性能和可访问性审计
波 -网络可访问性评估工具
剧作家 -浏览器自动化框架
模型上下文协议 -LLM工具集成协议

使用说明

可访问性MCP服务器

特征

安装

配置

用法

作为游标中的MCP服务器

可用的MCP工具

axe_audit

lighthouse_audit

wave_audit

输出格式

发展

先决条件

脚本

项目结构

建筑

添加新的审核工具

测试

CI/CD集成

贡献

许可证

致谢

相关 MCP

网页无障碍扫描器

无障碍代码审查 MCP 服务

自动化测试框架

容器化基础设施语义管理框架

无障碍测试服务

网站质量扫描服务

`axe_audit`

`lighthouse_audit`

`wave_audit`