A11y Feedback MCP

코딩 및 디자인 에이전트에게 “WCAG를 준수하라”는 단순한 주의 환기가 아니라, 실제 접근성 피드백 루프를 제공합니다.

a11y-feedback-mcp는 Chromium에서 인터페이스를 렌더링하고 axe-core를 실행한 뒤, 모든 Model Context Protocol 클라이언트에 실행 가능한 증거(위반된 규칙, 영향, CSS 선택자, DOM 스니펫, 계산된 스타일, 경계 상자, 수정 단계, 수학적으로 통과하는 대비 후보)를 반환합니다.

Codex 및 Claude Code와 직접 작동합니다. Claude Design의 경우, 권장 워크플로는 Claude Code를 Claude Design의 MCP 서버와 이 서버 양쪽에 연결한 다음, 생성된 HTML 또는 라이브 미리보기를 감사하고 수정 사항을 디자인 워크플로로 다시 보내는 것입니다.

이 도구는 WCAG 인증 서비스가 아닌 자동화된 테스트 보조 도구입니다. 의도적으로 검사가 불완전함을 보고하며, 키보드, 포커스, 스크린 리더, 확대/축소, 동작, 인지, 콘텐츠 품질에 대해서는 사람의 테스트가 필요합니다.

“라이브 피드백”의 의미

flowchart TD
    A["Agent creates or changes UI"] --> B["Render at target viewport"]
    B --> C["Run axe + contrast analysis"]
    C --> D["Return evidence and correction"]
    D --> E["Agent proposes or applies code fix"]
    E --> F["Re-run same audit"]
    F --> G["Human checks incomplete behavior"]

이 서버는 읽기 전용입니다. 프로젝트를 조용히 수정하지 않습니다. 연결된 에이전트는 해당 증거를 사용하여 범위가 정해진 변경을 수행한 다음, 감사를 다시 실행해 이를 검증합니다.

Related MCP server: Accessibility MCP Server

도구

모든 도구는 읽기 전용으로 명시됩니다. 서버는 또한 accessibility-fix-loop 프롬프트를 노출합니다.

표준 프로파일

감사 도구는 wcag2a, wcag2aa, wcag2aaa, wcag21aa, wcag21aaa, wcag22aa, wcag22aaa, best-practice를 지원합니다. AA 프로파일은 필수 A 및 AA 기준을 모두 포함하고, AAA 프로파일은 A, AA, AAA를 포함합니다. W3C가 최신 WCAG 버전을 권장하고 일반적인 정책으로 사이트 전체에 AAA를 요구하는 것에 대해 경고하기 때문에 wcag22aa가 기본값으로 유지됩니다. AAA는 명시적인 향상 목표로 사용하고 기준별 진행 상황을 보고하십시오.

axe 매핑은 부분적인 자동 적용 범위를 의미하며, 완전한 성공 기준이 테스트되었음을 의미하지 않습니다. get_wcag_checklist는 자동화가 완료할 수 없는 수동 작업을 포함하여 WCAG 2.2 AA에 필요한 55개 전체 기준 또는 WCAG 2.2 AAA에 필요한 86개 전체 기준을 제공합니다.

요구 사항

• Node.js 20 이상

• Chrome 또는 Edge 권장

• Windows, macOS, 또는 Linux

서버는 먼저 설치된 Chrome/Edge를 찾습니다. 지원되는 Linux 환경에서는 번들된 @sparticuz/chromium을 대신 사용할 수 있습니다. A11Y_MCP_BROWSER_PATH에 명시적인 브라우저 실행 파일을 설정할 수 있습니다. Chromium 샌드박싱은 기본적으로 활성화된 상태로 유지됩니다. A11Y_MCP_NO_SANDBOX=true는 그렇지 않으면 Chrome을 시작할 수 없는 제한된 컨테이너나 Lambda 스타일 런타임에서만 설정하십시오.

Windows에 설치

프로젝트를 보관하는 폴더에서 PowerShell을 엽니다:

git clone https://github.com/aditya-ariosity/a11y-feedback-mcp.git
cd a11y-feedback-mcp
npm install
npm run build

저장소가 아직 GitHub에 없다면 먼저 이 폴더를 다운로드하거나 복사한 다음, 폴더 안에서 마지막 세 개의 명령을 실행하십시오.

Codex 연결

PowerShell에서 빌드된 진입점의 절대 경로를 사용하십시오:

codex mcp add a11y-feedback -- node "C:\full\path\to\a11y-feedback-mcp\dist\index.js"

또는 동일한 구성을 ~/.codex/config.toml에 추가하십시오:

[mcp_servers.a11y_feedback]
command = "node"
args = ["C:\\full\\path\\to\\a11y-feedback-mcp\\dist\\index.js"]
startup_timeout_sec = 30
tool_timeout_sec = 90

[mcp_servers.a11y_feedback.env]
A11Y_MCP_ALLOWED_ROOT = "C:\\full\\path\\to\\your-projects"

Codex를 다시 시작한 다음 요청하십시오:

이 페이지를 1440×900 및 390×844에서 감사하세요. 치명적(critical) 및 심각한(serious) 문제를 수정하고, 두 감사를 다시 실행한 다음, 남은 수동 검사를 나열하세요.

검증 및 문제 해결은 docs/codex.md를 참조하십시오.

Claude Code 연결

claude mcp add --scope user a11y-feedback -- node "C:\full\path\to\a11y-feedback-mcp\dist\index.js"

연결을 확인하려면 claude mcp list를 실행하십시오. Claude Design 브리지 워크플로는 docs/claude-code-and-design.md를 참조하십시오.

개발

npm install
npm run check
npm test
npm run test:e2e
npm run build

npm test는 색상 계산, 네트워크 보호, 수정 및 MCP 계약을 다룹니다. npm run test:e2e는 Chromium을 시작하여 의도적으로 접근할 수 없게 만든 픽스처를 감사합니다.

로컬 stdio 서버를 시작합니다:

npm run dev

선택적 Streamable HTTP 전송을 시작합니다:

npm run build
npm run start:http

엔드포인트는 http://127.0.0.1:3000/mcp이고, 상태 확인은 http://127.0.0.1:3000/health입니다. HTTP는 기본적으로 127.0.0.1에 바인딩됩니다.

환경 변수

참조 HTTP 서버를 공개 인터넷에 직접 노출하지 마십시오. 인증, TLS, 속도 제한, 요청 크기 제한, 테넌트 격리를 그 앞에 배치하십시오. docs/security.md를 참조하십시오.

현재 범위

MVP는 렌더링된 웹 UI와 결정적 대비 계산을 다룹니다. 아직 네이티브 모바일 앱, PDF, 캔버스, 동영상 자막 또는 원시 Claude Design 픽셀은 검사하지 않습니다. 계획된 어댑터는 MCP 계약을 변경하지 않고 프레임워크 인식 패치, 스크린샷/OCR 지원, 디자인 토큰 통합, CI 주석, 일급 디자인 캔버스 커넥터를 추가할 수 있습니다.

프로젝트 문서

• 아키텍처 및 제품 사양

• Codex 설정

• Claude Code 및 Claude Design 설정

• 보안 모델

• W3C WAI 적용 범위 모델

• 보조 에이전트 스킬

• 기여하기

라이선스

MIT