GitHub - ronantakizawa/a11ymcp at producthunt

A11y MCP(Model Context Protocol) 서버는 LLM(Large Language Model)이 웹 접근성 테스트 API에 접근할 수 있도록 설계된 서비스입니다. 이 서버는 Deque Axe-core API와 Puppeteer를 활용하여 웹 콘텐츠의 WCAG(Web Content Accessibility Guidelines) 준수 여부를 분석하고 접근성 문제를 식별합니다. Deque Labs의 공식 서버는 아니지만, 5000회 이상의 다운로드를 기록하며 널리 사용되고 있습니다.

핵심 방법론 (Core Methodology):
A11y MCP 서버는 LLM과 웹 접근성 테스트 엔진 간의 중개자 역할을 수행합니다. 내부적으로는 크게 두 가지 핵심 기술을 결합하여 작동합니다.

Deque Axe-core API: 이는 웹 접근성 테스트를 위한 핵심 엔진입니다. axe-core는 웹 페이지의 DOM(Document Object Model)을 분석하여 WCAG 지침에 따라 잠재적인 접근성 위반 사항을 식별하는 강력한 오픈 소스 라이브러리입니다. 이 서버는 axe-core의 기능을 래핑하여 LLM이 쉽게 호출할 수 있는 형태로 제공합니다.
Puppeteer: Puppeteer는 Node.js 라이브러리로, Chrome 또는 Chromium을 Headless 모드(UI 없이 백그라운드에서 실행)로 제어할 수 있는 고수준 API를 제공합니다. A11y MCP 서버는 Puppeteer를 사용하여 다음과 같은 작업을 수행합니다:

제공된 URL의 웹 페이지를 실제 브라우저 환경에서 렌더링합니다.
HTML 문자열을 가상 페이지로 로드하여 렌더링합니다.
렌더링된 페이지의 컨텍스트 내부에 axe-core 라이브러리를 주입(inject)합니다.
axe-core를 실행하여 렌더링된 DOM에 대한 접근성 검사를 수행합니다.
검사 결과를 수집하여 LLM이 이해할 수 있는 구조화된 JSON 형식으로 변환하여 반환합니다.

이러한 통합을 통해 A11y MCP는 LLM이 단순한 텍스트 분석을 넘어 실제 브라우저 환경에서 웹 콘텐츠를 "보고" 접근성 문제를 진단할 수 있도록 지원하며, WCAG 표준에 따른 심층적인 검사 기능을 제공합니다.

주요 기능 (Key Features):

Test web pages: 공용 URL의 웹 페이지 접근성 테스트를 수행합니다.
Test HTML snippets: 원시 HTML 문자열의 접근성 문제를 검사합니다.
WCAG compliance testing: WCAG 2.0, 2.1, 2.2 등 다양한 WCAG 표준에 대한 준수 여부를 확인합니다.
Customizable tests: 특정 접근성 태그나 표준을 지정하여 맞춤형 테스트를 실행할 수 있습니다.
Rule exploration: 사용 가능한 접근성 규칙에 대한 정보를 얻습니다.
Color contrast analysis: 전경색과 배경색 조합이 WCAG 명암비 요구 사항을 충족하는지 확인합니다.
ARIA validation: ARIA(Accessible Rich Internet Applications) 속성의 올바른 사용 여부를 검사합니다.
Orientation lock detection: 특정 화면 방향을 강제하는 콘텐츠를 식별합니다.

사용 가능한 도구 (Available Tools):
이 서버는 LLM이 호출할 수 있는 여러 도구를 제공합니다.

test_accessibility:
설명: URL 기반으로 웹 페이지의 접근성 문제를 테스트합니다.
파라미터: url (필수, 테스트할 URL), tags (선택, WCAG 태그 배열 예: ["wcag2aa"]).
예시: {"url": "https://example.com", "tags": ["wcag2aa"]}
test_html_string:
설명: HTML 문자열의 접근성 문제를 테스트합니다.
파라미터: html (필수, 테스트할 HTML 콘텐츠), tags (선택, WCAG 태그 배열).
예시: ${"html": "<div><img src='image.jpg'></div>", "tags": ["wcag2aa"]}$
get_rules:
설명: 사용 가능한 접근성 규칙에 대한 정보를 필터링하여 가져옵니다. (파라미터는 명시되지 않음)
check_color_contrast:
설명: 전경색과 배경색 조합이 WCAG 명암비 요구 사항을 충족하는지 확인합니다.
파라미터: foreground (필수, 헥스(hex) 형식 전경색), background (필수, 헥스 형식 배경색), fontSize (선택, 픽셀 단위 폰트 크기, 기본값 16), isBold (선택, 텍스트 볼드 여부, 기본값 false).
예시: {"foreground": "#777777", "background": "#EEEEEE", "fontSize": 16, "isBold": false}
check_aria_attributes:
설명: HTML 내에서 ARIA 속성이 올바르게 사용되었는지 확인합니다.
파라미터: html (필수, ARIA 속성 사용을 테스트할 HTML 콘텐츠).
예시: ${"html": "<div role='button' aria-pressed='false'>Click me</div>"}$
check_orientation_lock:
설명: 콘텐츠가 특정 화면 방향을 강제하는지 확인합니다.
파라미터: html (필수, 방향 잠금 문제를 테스트할 HTML 콘텐츠).
예시: ${"html": "<html><head><meta name='viewport' content='width=device-width, orientation=portrait'></head><body>Content</body></html>"}$

응답 형식 (Response Format):
서버는 접근성 테스트 결과를 다음과 같은 구조화된 JSON 형식으로 반환합니다.

json{
  "violations": [ // 발견된 위반 사항 목록
    {
      "id": "color-contrast", // 규칙 ID
      "impact": "serious", // 영향도 (예: critical, serious, moderate, minor)
      "description": "Ensure the contrast between foreground and background colors meets WCAG 2 AA minimum contrast ratio thresholds", // 위반 설명
      "help": "Elements must meet minimum color contrast ratio thresholds", // 도움말
      "helpUrl": "https://dequeuniversity.com/rules/axe/4.10/color-contrast", // 상세 도움말 URL
      "affectedNodes": [ // 영향을 받는 노드 목록
        {
          "html": "<div style=\"color: #aaa; background-color: #eee;\">Low contrast text</div>", // 해당 HTML 스니펫
          "target": ["div"], // 해당 요소의 CSS 셀렉터
          "failureSummary": "Fix any of the following: Element has insufficient color contrast of 1.98 (foreground color: #aaa, background color: #eee, font size: 12.0pt, font weight: normal)" // 실패 요약
        }
      ]
    }
  ],
  "passes": 1, // 통과된 검사 수
  "incomplete": 0, // 불완전한 검사 수
  "inapplicable": 2, // 해당 없는 검사 수
  "timestamp": "2025-04-25T16:45:33.655Z", // 테스트 타임스탬프
  "url": "about:blank", // 테스트된 URL
  "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",
    "windowWidth": 800,
    "windowHeight": 600,
    "orientationAngle": 0,
    "orientationType": "portrait-primary"
  }
}

설치 및 사용법 (Installation):
이 서버는 Claude Desktop과 함께 사용하기 위해 MCP 설정 파일(claude_desktop_config.json 또는 claude_mcp_settings.json)을 수정하여 구성할 수 있습니다. 운영체제별로 파일 위치가 다르며, command와 args를 사용하여 서버를 실행하도록 지시합니다.

의존성 (Dependencies):

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

GitHub - ronantakizawa/a11ymcp at producthunt

요약

상세 내용