JinDaGe - accessibilitymcp MCP Details

article

README

🚀 网络可访问性测试 MCP 服务器（A11y MCP）

Web 可访问性测试 MCP 服务器（A11y MCP） 是一款用于 Web 应用程序可访问性测试的工具。它支持通过 Model Context Protocol (MCP) 进行交互，基于 @modelcontextprotocol/sdk 搭建，结合 puppeteer 和 axe-core 等库，提供全面的可访问性测试功能。

🚀 快速开始

Web 可访问性测试 MCP 服务器（A11y MCP）能帮助你对 Web 应用进行可访问性测试。以下将为你介绍安装、配置及使用的相关内容。

✨ 主要特性

核心功能

可访问性测试：借助 axe-core 分析网页内容，检测不符合 WCAG 2.1 级别 AAA 的问题。
DOM 操作：利用 Puppeteer 提供的 API 进行元素定位、点击、输入等操作。
报告生成：返回详细的可访问性测试结果，涵盖违规项、通过项和不适用项。

支持的功能

颜色对比检测：确保文本与背景之间的对比度符合 WCAG 标准。
表单验证：检查表单元素是否符合可访问性规范，如标签关联、输入提示等。
屏幕阅读器支持：验证网页内容是否能够被屏幕阅读器正确解析和朗读。
键盘导航测试：确保用户可以通过键盘完成所有交互操作。

📦 安装指南

依赖项

@modelcontextprotocol/sdk
puppeteer
@axe-core/puppeteer
axe-core

安装步骤

使用 Node.js 包管理器 (npm) 或 yarn 下载所有依赖：

npm install @modelcontextprotocol/sdk puppeteer @axe-core/puppeteer axe-core

配置环境变量或在代码中指定 Puppeteer 的浏览器执行模式（如 headless 或 non-headless）。

💻 使用示例

基础用法

const { createMcpServer } = require('@modelcontextprotocol/sdk');
const puppeteer = require('puppeteer');
const axe = require('axe-core');

// 初始化 Puppeteer 浏览器实例
let browser;
async function initBrowser() {
  browser = await puppeteer.launch({
    headless: true,
    width: 1200,
    height: 800,
  });
}

// 创建 MCP 服务器
const server = createMcpServer({
  async getBrowser() {
    if (!browser) await initBrowser();
    return browser;
  },
});

// 示例测试用例：检测颜色对比
async function testContrast(url) {
  const page = await browser.newPage();
  await page.goto(url);
  const result = await axe.run(page);
  return result;
}

// 启动服务器并开始测试
server.start(3000);

📚 详细文档

响应格式

MCP 服务器返回的可访问性测试结果采用 JSON 格式：

{
  "violations": [
    {
      "id": "color-contrast",
      "impact": "serious",
      "description": "确保文本与背景之间的对比度符合 WCAG 2 AA 最低要求。",
      "help": "元素必须满足最低颜色对比度阈值。",
      "helpUrl": "https://dequeuniversity.com/rules/axe/4.10/color-contrast",
      "affectedNodes": [
        {
          "html": "<div style=\"color: #aaa; background-color: #eee;\">低对比度文本</div>",
          "target": ["div"],
          "failureSummary": "修复以下任一问题：元素的对比度为 1.98（前景色：#aaa，背景色：#eee，字体大小：12.0pt，字体重量：正常）未达到最低要求。"
        }
      ]
    }
  ],
  "passes": 1,
  "incomplete": 0,
  "inapplicable": 2,
  "timestamp": "2025-04-25T16:45:33.655Z",
  "url": "about:blank",
  "testEngine": {
    "name": "axe-core",
    "version": "4.10.3"
  },
  "testRunner": {
    "name": "axe"
  },
  "testEnvironment": {
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) HeadlessChrome/135.0.0.0 Safari/537.36",
    "width": 1200,
    "height": 800
  }
}

其他资源

官方文档：Model Context Protocol
Puppeteer 文档：Puppeteer 官方文档
axe-core 文档：axe-core 官方文档

accessibilitymcp