kim-dongho/krds-a11y-mcp

KRDS(범정부 UI/UX 디자인 시스템) 컴포넌트를 KWCAG 2.2 접근성 조건과 함께 공급하고, 위반이 남으면 AI의 작업 종료를 막는 MCP 서버.
> An MCP server that supplies KRDS (Korea Government Design System) components with KWCAG 2.2 accessibility built in, and keeps AI agents from finishing while accessibility violations remain.
> 설치는 npm i가 아니라 프로젝트 루트에서 npx -y krds-a11y-mcp init 한 줄이다. MCP 등록·훅·지시문을 한 번에 설정한다.
공급 — 접근성 조건을 갖춘 KRDS 부품·템플릿을 준다. 레이블·대체 텍스트 같은 필수 입력을 안 채우면 마크업을 주지 않는다
검사 — 렌더된 페이지를 axe와 자체 실측(명도 대비, 키보드, 화면에 안 그려진 요소)으로 검사해 KWCAG 번호로 보고한다
강제 — Claude Code·Codex 훅이 위반이 남은 채 작업을 끝내지 못하게 막는다
> 정직한 범위: 자동 판정은 접근성 이슈의 3~4할이다. 이 도구는 "심사 통과 보장"이 아니라 심사 전 자가진단 + 증빙 생성 도구다. KWCAG 최종 판정 기준은 전문가 심사와 보조기술(스크린리더) 실사용 평가이며, 자동 도구는 이를 대체하지 못한다.
## 사용 예
화면 흐름 문서 하나를 주고 한 줄로 요청했다. 가상의 도서관 좌석 예약 서비스다.
text
docs/screen-flow.md의 화면 흐름대로 Next.js로 만들어줘.
AI가 이 서버의 부품·공통부를 받아 Next.js 화면을 만들고, 화면마다 validatepage로 검사했다. 필수 입력을 빠뜨린 부품 요청 5번은 거부됐고 값을 채워 다시 받았다. 끝내기 전에는 gate로 통과를 확인했다. 위반이 남았다면 Stop 훅이 종료를 막는다.
| 좌석 현황 조회 | 예약 신청 1단계 (필수 항목을 비우고 다음) |
결과는 5개 화면(상태 화면 포함 7개 기록) 모두 자동 검사 위반 0이다. 사람 확인 항목(배경 위 글자 대비 등)은 화면당 1~4건이 리포트에 남는다.
데모 사이트: https://krds-a11y-mcp-demo.vercel.app/
데모 코드와 흐름 문서: kim-dongho/krds-a11y-mcp-demo
## 왜 만들었나
공공 웹은 KRDS와 KWCAG 2.2(웹 접근성 국가표준, 33개 검사항목)를 함께 지켜야 한다. 그런데
KRDS 공식 패턴 샘플 33종을 전수 검사하면 33종 모두에서 접근성 문제가 나온다. 샘플을 복사하는 것만으로는 준수가 안 된다
axe 같은 자동 검사기는 WCAG 번호로 보고해 KWCAG 기준 심사·보고서와 번호가 맞지 않는다
검사는 보통 개발이 끝난 뒤에 해서 교정 왕복 비용이 크다
그래서 "검사해서 고치는" 대신 처음부터 KWCAG 조건이 들어간 KRDS 마크업을 공급하고, 검사는 조립·변환 과정에서 깨진 것을 잡는 안전망으로 둔다. 안전망은 지시가 아니라 훅으로 강제한다.
## 빠른 시작
요구사항: Node 20 이상. 검사 도구를 쓰려면 Chromium(아래 3번).
1. 프로젝트 루트(git 저장소 루트)에서 설정을 설치한다
sh
npx -y krds-a11y-mcp init
2. 도구가 주는 페이지가 불러올 KRDS 킷을 프로젝트에 설치한다. 킷을 문서루트에 복사해 서빙하는 프로젝트(JSP 등)는 그 경로를 getpagescaffold의 assetBase로 준다
sh
npm i krds-uiux@1.1.0
3. 재검사(validatepage·inspectpage)까지 쓰려면 브라우저 검사 스택을 설치한다. 없으면 도구가 이 안내를 그대로 돌려준다
sh
npm i -D playwright @axe-core/playwright
npx playwright install chromium
4. 설치 상태를 점검한다
sh
npx -y krds-a11y-mcp doctor
init이 설치하는 것 (기존 파일은 보존하고 우리 항목만 추가, 재실행해도 중복 없음):
| 파일 | 내용 |
| .mcp.json | MCP 서버 등록 (도구 9종 + 자동 주입 사용 규칙) |
| .claude/settings.json | Stop 훅(위반이 남으면 작업 종료 차단) + PreToolUse 훅(금지 행동 차단) |
| CLAUDE.md · AGENTS.md | 핵심 사용 규칙 (Codex 등 타 AI 도구 호환) |
| .codex/config.toml · .codex/hooks.json | Codex용 MCP 서버 등록과 같은 두 훅 |
서버와 훅은 설치한 버전(krds-a11y-mcp@x.y.z)으로 고정된다. 세션 중에 새 버전이 나와도 판정 로직이 바뀌지 않고, 훅마다 레지스트리를 조회하지 않는다. Windows에서는 서버를 cmd /c npx로 등록한다.
설치 후 처음 한 번:
Claude Code — 프로젝트를 열고 MCP 서버를 승인한다
Codex — 프로젝트를 신뢰(trust)하고 /hooks에서 krds-a11y 훅 2개를 승인한다. 훅 내용이 바뀌면 다시 승인해야 한다
업그레이드: npx -y krds-a11y-mcp@latest init을 다시 실행하면 고정 버전만 새 버전으로 바뀐다(다른 설정은 보존).
제거: .mcp.json의 krds-a11y 항목, .claude/settings.json·.codex/hooks.json의 krds-a11y-mcp 훅 두 개, .codex/config.toml의 [mcpservers.krds-a11y] 표, CLAUDE.md·AGENTS.md의 ~end 구간을 지운다.
수동 설치
sh
claude mcp add krds-a11y -- npx -y krds-a11y-mcp@x.y.z
또는 .mcp.json:
json
"mcpServers": {
"krds-a11y": { "command": "npx", "args": ["-y", "krds-a11y-mcp@x.y.z"] }
훅은 아래 하네스 절의 설정을 붙인다.
### 사용 흐름
사용자: "로그인 페이지 만들어줘"
→ AI가 getpagescaffold(pattern: "login-id", withSiteChrome: true, ...) 호출
→ 필수 입력(페이지 제목 등)이 비면 도구가 거부하고 되물음
→ 접근성 교정이 내장된 완성 마크업 수신, 콘텐츠 교체
AI가 작업을 끝내려 할 때
→ Stop 훅이 검사 기록을 판정