Claude Code를 활용한 웹 접근성 준수 처리 방법

WebAbility.io를 구축하기 시작했을 때, 저는 빠르게 진행하기 위해 Claude Code에 크게 의존했습니다. 이 도구는 폼(form), 모달(modal) 또는 전체 결제 흐름(checkout flow)을 제가 직접 하는 것보다 훨씬 짧은 시간에 만들어낼 수 있었습니다. 하지만 속도에는 대가가 따랐습니다. 페이지 자체는 괜찮아 보였지만, 스크린 리더나 저시력 사용자는 여전히 장애물에 부딪혔습니다. 저는 누락된 폼 레이블(form labels)과 낮은 대비의 버튼들이 간간이 빠져나가는 것을 발견했습니다.

여기에 WebAbility MCP가 등장합니다. 저는 이 도구를 통해 제 코딩 에이전트에게 추가적인 눈을 제공하도록 만들었습니다. 즉, 렌더링된 페이지를 스캔하고, 접근성 수정 사항을 생성하며, 나아가 그 수정 사항들이 실제로 작동하는지 검증합니다. 본 게시물에서는 코딩 에이전트에 MCP 서버를 설정하는 방법과 이 '스캔-수정-검증(scan-fix-verify)' 루프가 어떻게 작동하는지 보여드리겠습니다.

접근성을 위한 MCP가 필요한 이유

대부분의 접근성 도구는 보고서에서 멈춥니다. 점수를 받고 목록을 받습니다. 그래도 누군가가 각 발견 사항을 읽고, 파일을 찾고, 올바른 프레임워크에서 변경 사항을 작성해야 합니다.

직접적인 도구 접근 권한을 가진 에이전트는 이 격차를 메웁니다. 잘 작동하게 만드는 세 가지 요소가 있습니다:

• 에이전트가 실제 출력을 확인합니다. 스캔은 무엇을 생성할지 추측하는 것이 아니라, 렌더링된 페이지를 대상으로 실행됩니다.
• 출력이 구조화되어 있습니다. 각 문제에는 기계가 읽을 수 있는 수정 사항이 포함되어 있어, 에이전트가 산문(prose)을 구문 분석할 필요가 없습니다.
• 에이전트가 검증할 수 있습니다. 변경 후 재스캔을 통해 문제가 사라졌는지 확인합니다. 작동했다는 에이전트의 주장만을 믿을 필요가 없습니다.

해당 서버는 세 가지 엔진을 실행하고 결과를 하나의 목록으로 중복 제거합니다: WebAbility 디텍터(60개 이상의 규칙), axe-core(104개 규칙), 그리고 HTML_CodeSniffer(200개 이상의 규칙)입니다. 만약 두 개의 엔진이 동일한 요소에 대해 같은 문제를 보고하면, 한 번만 표시됩니다.

60초 설정

호스팅된 서버는 https://mcp.webability.io/mcp (스트리밍 가능한 HTTP)에서 사용할 수 있습니다. 시작하는 데 API 키나 계정이 필요하지 않습니다.

Cursor

원클릭 링크를 사용하세요:

Add to Cursor

또는 MCP 설정에 다음을 붙여넣으세요:

{
  

claude mcp add --transport http webability https://mcp.webability.io/mcp

claude.ai에서 동일한 URL을 사용자 지정 커넥터로 추가하세요.

VS Code

서버를 MCP 구성 파일(.vscode/mcp.json)에 추가합니다:

{
  "servers": {
    "webability": {
...

동일한 URL은 Windsurf, Zed, ChatGPT (커넥터로), Gemini CLI 및 기타 모든 MCP 클라이언트에서 작동합니다. stdio를 통해 로컬에서 실행하는 것을 선호한다면:

npx -y @webability/mcp

그런 다음 에이전트에게 "접근성 문제를 확인하기 위해 https://webability.io/pricing를 스캔해 줘."라고 요청하세요.

스캔(scan), 수정(fix), 검증(verify) 루프

세 가지 도구가 주요 루프인 scan_page, generate_ai_fix, 그리고 verify_fix를 담당합니다.

1. 스캔 (Scan)

scan_page는 세 가지 계층으로 출력을 반환합니다:

• issues: 신뢰도가 높은 위반 사항입니다. 조치해도 안전합니다.
• incomplete: 사람의 판단이 필요한 발견 사항입니다. 예를 들어, 사진에 대한 대비(contrast)나 마케팅 이미지의 alt 텍스트 등이 해당됩니다. 에이전트는 이를 버그가 아닌 질문으로 처리해야 합니다.
• summary: 심각도별 카운트와 미완료 항목의 개수를 포함합니다.

예시 출력 (축약):

# example
summary: 4 issues (2 serious, 2 moderate), 1 incomplete

...

모든 이슈는 폐쇄된 집합(closed set)으로부터 fix.op을 가집니다: add-attribute, set-attribute, remove-attribute, add-element, remove-element, add-text-content, 또는 suggest. 또한 fixability 태그를 가집니다:

• mechanical: 값이 알려져 있습니다. 주어진 대로 적용합니다.
• contextual: 작업은 알지만, alt 텍스트나 레이블과 같이 값에 판단이 필요한 경우입니다. 에이전트는 HTML을 읽고 작성합니다.
• visual: 대비(contrast), 포커스 링(focus rings), 또는 타겟 크기처럼 렌더링된 출력이 필요한 경우입니다. 에이전트가 변경 사항을 제안하고 사용자가 검토합니다.

이 태그가 중요합니다. 이 태그는 에이전트가 자체적으로 적용할 수 있는 수정과 사용자 눈이 필요한 수정을 알려줍니다.

2. 수정 (Fix)

기계적 항목의 경우 에이전트가 파일을 직접 수정합니다. 프레임워크를 고려해야 하는 항목의 경우, generate_ai_fix는 사용자의 스택에 맞는 제안을 생성합니다. 여기서 함께 사용해야 할 도구는 scan_page와 generate_ai_fix의 결과입니다. detect_framework는 수정 생성기에게 Tailwind, MUI, Bootstrap, Next.js, WordPress 또는 일반 CSS 중 어떤 것을 사용하는지 알려줍니다.

3. 검증 (Verify)

verify_fix는 변경한 요소를 다시 스캔하고 true 또는 false를 반환합니다.

# 예시
verify_fix  img.hero__photo  -> verified: true
verify_fix  input#email      -> verified: true
...

세 번째 결과가 유용합니다. 에이전트는 완료되었다고 생각했지만, 검증기가 그렇지 않다고 말한 경우입니다. 이때 에이전트는 더 어두운 색상 토큰으로 다시 시도합니다.

루프 주변의 추가 도구 (More tools around the loop)

• diff_scan: 두 스캔을 비교하여 수정된 문제, 새로 발생한 문제, 그리고 남아 있는 문제를 보고합니다. 이를 사용하여 변경 사항이 회귀(regressions)를 추가하지 않았는지 확인할 수 있습니다.
• flow_scan: 로그인, 대시보드, 결제와 같은 다단계 흐름(multi-step flow)을 따라가며 그 전반에 걸쳐 고유한 문제를 보고합니다.
• visual_audit: 비전 패스입니다. DOM 엔진이 놓칠 수 있는 약한 포커스 가시성이나 버튼처럼 보이지만 실제로는 아닌 요소 등 렌더링된 스크린샷을 확인합니다.
• start_audit와 get_audit: 전체 감사를 실행하고 보고서, Excel 워크북, PDF를 반환합니다.

만약 에이전트의 컨텍스트 창(context window)이 작다면, `format:

React 18 및 이전 버전과 Vue 개발 빌드에서는 각 이슈가 file:line:column과 컴포넌트 이름을 포함합니다. 이 값들은 라이브 컴포넌트 트리에서 가져옵니다. 위 예시에서, label 이슈 옆에 src/components/SignupForm.tsx:18:9를 볼 수 있습니다. 에이전트는 해당 파일을 직접 엽니다.

프로덕션 빌드에는 이러한 데이터가 포함되지 않습니다. 이 경우 로컬의 find_source 도구가 선택자(selector)를 소스 트리 내 파일로 매핑합니다.

무료 모델 및 공정 사용 제한 (Free model and fair-use limits)

MCP는 무료입니다. 크레딧, 체험 기간, 또는 유료 등급이 없습니다.

로그인하려면 클라이언트에서 원클릭 OAuth 프롬프트를 사용하십시오. 로컬 서버의 경우 webability login을 실행하십시오.

자동화가 다루지 못하는 영역 (What automation does not cover)

자동화된 테스트는 WCAG 문제 중 일부만 찾아냅니다. 어떤 스캐너도 대체 텍스트(alt text)가 의미 있는지, 제목 순서가 페이지 로직과 일치하는지, 또는 화면 읽기 프로그램(screen reader)이 사용자 지정 위젯을 유용한 방식으로 발표하는지 알려줄 수 없습니다. MCP를 사용하여 소스 레벨에서 자동화된 계층을 정리한 다음, 나머지 부분은 보조 기술(assistive technology)로 테스트하십시오. incomplete 등급은 에이전트가 사람이 결정해야 할 부분을 추측하지 않도록 존재합니다.

FAQ

API 키가 필요한가요?
아닙니다. 클라이언트를 https://mcp.webability.io/mcp로 지정하고 시작하십시오. 제한을 해제하거나 비전 및 감사 도구를 사용하려면 무료 계정으로 로그인하십시오.

어떤 클라이언트가 작동하나요?
Claude (Claude Code 및 claude.ai 커넥터), Cursor, VS Code, Windsurf, Zed, ChatGPT (커넥터로 사용), Gemini CLI, 그리고 모든 MCP 클라이언트.

에이전트가 변경해서는 안 될 것을 바꿀까요?
그렇지 않습니다. incomplete 등급의 발견 사항은 사람이 검토해야 하며, visual 수정 사항은 제안일 뿐입니다. 어떤 에이전트가 작성한 코드와 마찬가지로, 커밋하기 전에 모든 변경 사항을 직접 검토해야 합니다.

내 로컬 개발 서버를 스캔할 수 있나요?
예. webability-tunnel --port 3000을 실행하면 호스팅된 도구들이 이를 스캔할 수 있습니다. 다른 옵션으로는 로컬의 npx -y @webability/mcp 서버가 있습니다.

수정이 제대로 되었는지 어떻게 알 수 있나요?
요소에 대해 verify_fix를 실행하거나, 페이지 전체에 대해 diff_scan을 실행하세요. 둘 다 재스캔하고 결과를 보고합니다. 에이전트의 자체 요약만 믿을 필요는 없습니다.

사용해 보기

클라이언트에 https://mcp.webability.io/mcp를 추가한 다음, 오늘 작업 중인 페이지를 스캔하도록 에이전트에게 요청하세요. mechanical로 표시된 문제부터 시작하는 것이 좋습니다. 이들이 수정하기 가장 빠르고 검증하기도 가장 쉽습니다.