Krds A11y MCP

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 최종 판정 기준은 전문가 심사와 보조기술(스크린리더) 실사용 평가이며, 자동 도구는 이를 대체하지 못한다.

사용 예

화면 흐름 문서 하나를 주고 한 줄로 요청했다. 가상의 도서관 좌석 예약 서비스다.

docs/screen-flow.md의 화면 흐름대로 Next.js로 만들어줘.

AI가 이 서버의 부품·공통부를 받아 Next.js 화면을 만들고, 화면마다 validate_page로 검사했다. 필수 입력을 빠뜨린 부품 요청 5번은 거부됐고 값을 채워 다시 받았다. 끝내기 전에는 gate로 통과를 확인했다. 위반이 남았다면 Stop 훅이 종료를 막는다.

결과는 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 저장소 루트)에서 설정을 설치한다

    npx -y krds-a11y-mcp init

2. 도구가 주는 페이지가 불러올 KRDS 킷을 프로젝트에 설치한다. 킷을 문서루트에 복사해 서빙하는 프로젝트(JSP 등)는 그 경로를 get_page_scaffold의 assetBase로 준다

    npm i krds-uiux@1.1.0

3. 재검사(validate_page·inspect_page)까지 쓰려면 브라우저 검사 스택을 설치한다. 없으면 도구가 이 안내를 그대로 돌려준다

    npm i -D playwright @axe-core/playwright
    npx playwright install chromium

4. 설치 상태를 점검한다

    npx -y krds-a11y-mcp doctor

init이 설치하는 것 (기존 파일은 보존하고 우리 항목만 추가, 재실행해도 중복 없음):

서버와 훅은 설치한 버전(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의 [mcp_servers.krds-a11y] 표, CLAUDE.md·AGENTS.md의 `~end` 구간을 지운다.

수동 설치

claude mcp add krds-a11y -- npx -y krds-a11y-mcp@x.y.z

또는 .mcp.json:

{
  "mcpServers": {
    "krds-a11y": { "command": "npx", "args": ["-y", "krds-a11y-mcp@x.y.z"] }
  }
}

훅은 아래 하네스 절의 설정을 붙인다.

사용 흐름

사용자: "로그인 페이지 만들어줘"
  → AI가 get_page_scaffold(pattern: "login-id", withSiteChrome: true, ...) 호출
  → 필수 입력(페이지 제목 등)이 비면 도구가 거부하고 되물음
  → 접근성 교정이 내장된 완성 마크업 수신, 콘텐츠 교체

AI가 작업을 끝내려 할 때
  → Stop 훅이 검사 기록을 판정
  → 검사가 없거나 위반이 남았으면 종료 거부 + 교정 지시
  → AI가 validate_page로 검사하고 위반 위치·교정 방법대로 고친 뒤 다시 검사

도구 9종

실패·거부 응답(필수 입력 누락, 모르는 id·변형·패턴, 검사 실행 실패)은 isError로 표시되고 다시 부르는 방법을 담는다. 오타로 보이는 이름에는 가까운 이름을 제안한다.

AI에게 주는 세부 사용 규칙은 MCP 연결 시 서버 instructions로 자동 전달된다(원본: src/server/index.ts의 SERVER_INSTRUCTIONS). init이 만드는 CLAUDE.md·AGENTS.md에는 핵심 요약만 마커 구간으로 들어간다.

하네스 — 위반이 남으면 끝내지 못하게

"완성하면 검사하라"는 지시는 따를 때도 건너뛸 때도 있다. 그래서 판정을 훅으로 옮겼다.

gate — 판정 명령

reports/의 검사 기록을 읽어 위반이 남았는지, 검사 뒤에 페이지가 바뀌었는지(낡음)를 판정한다. 판정 로직은 이 명령 한 곳에만 있고 훅과 CI가 같이 쓴다.

npx krds-a11y-mcp gate              # 사람용 요약
npx krds-a11y-mcp gate --json       # 훅·CI용 구조화 출력
npx krds-a11y-mcp gate --only form  # 지정 화면만 (반복 가능)

url 검사는 validate_page에 sourceDir을 넘기면 그 아래 소스 수정 시각으로 낡음을 판정한다. 넘기지 않으면 "판정 불가"로 표기한다(통과로 꾸미지 않는다).

stop-hook — 작업 종료 차단

AI가 작업을 끝내려는 순간 gate를 판정해, 위반·공통부 누락·낡음이 남으면 종료를 거부하고 교정 지시를 모델에게 전달한다. 통과할 때까지 반복하고, 상한(기본 5회)을 넘으면 "자동 교정 실패, 사람 확인 필요"를 남기고 풀어준다. 횟수는 세션 단위로 세고, 풀어 준 세션은 다시 막지 않는다. 위반을 일부러 남겨 둔 작업이면 환경 변수 KRDS_A11Y_GATE=off로 판정을 끈다. 검사 기록이 하나도 없는 프로젝트는 막지 않는다(페이지 작업이 없던 세션의 오탐 방지).

{
  "hooks": {
    "Stop": [{ "hooks": [{ "type": "command", "command": "npx -y krds-a11y-mcp@x.y.z stop-hook", "timeout": 30 }] }]
  }
}

pretool-hook — 금지 행동 사전 차단

파일을 쓰기 직전에 세 가지를 막는다. 실사용 테스트에서 실제로 관찰된 행동들이다.

• 프로젝트 폴더에 임시 검사 스크립트 생성(.axe-check.mjs류) → validate_page·inspect_page가 대체
• 킷 원본(node_modules/krds-uiux) 수정 → 재설치로 사라지고 보증 근거가 훼손된다
• 문서루트로 복사한 킷(webapp/krds-uiux 등) 수정 → npm 킷과 조용히 어긋난다. 교정은 별도 CSS로

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit|NotebookEdit",
        "hooks": [{ "type": "command", "command": "npx -y krds-a11y-mcp@x.y.z pretool-hook", "timeout": 30 }]
      }
    ]
  }
}

시스템 임시 디렉터리의 일회용 스크립트와 .eslintrc.js 같은 정상 설정 파일은 막지 않는다. Bash 경유 수정은 범위 밖이다(파일 쓰기 도구만 본다).

Codex

init이 .codex/hooks.json에 같은 두 훅을 건다. PreToolUse 대상은 apply_patch|Edit|Write이고, 패치 본문의 모든 경로를 뽑아 하나라도 금지 대상이면 패치 전체를 막는다.

• 프로젝트 신뢰와 /hooks 승인 전에는 설정도 훅도 읽히지 않는다
• codex exec(비대화형)에서는 훅이 실행되지 않는다. 자동화로 돌린다면 gate를 CI에서 따로 호출해야 한다

문제 해결

템플릿이 보장하는 것과 지켜야 하는 것

템플릿은 KRDS 공식 패턴 샘플을 전수 검사해 나온 문제를 교정해 만들었다(감사 기록: docs/mapping/pattern-audit.md). 게시판 2종은 공식 샘플이 없어 하위 페이지 틀에 킷 부품을 조립했다. 보장이 유지되는 조건:

1. 구조·클래스·속성(aria 포함)을 유지한 채 렌더된 DOM이 템플릿과 같을 것. React/Vue/JSP 변환은 자유지만 래퍼 요소를 끼우지 않는다
2. 스타일은 킷 CSS와 동봉 CSS를 그대로 로드. Tailwind 등으로 재작성하지 않고 공존만 한다
3. 콘텐츠는 자유, 단 조건부 항목(alt·레이블 등)은 반드시 채운다. 도구가 생성 단계에서 강제한다
4. 시안은 배치·구성만 참고. 색·타이포는 킷 토큰을 쓴다
5. 데모 플레이스홀더(href="#")는 실제 URL로 바꾼다

요약하면 ⑴ 접근성 교정분은 불변 ⑵ 화면 구조는 기본값(명시 요구 시에만 이탈) ⑶ 콘텐츠·문구는 자유.

데이터의 근거

• 매핑표 — KRDS 컴포넌트 43종 × KWCAG 33항목을 자동 충족·조건부·범위 밖으로 분류(docs/mapping/). 근거는 공식 킷(KRDS-uiux)의 실제 파일이며 판정마다 출처(파일·행)를 남긴다. 확신이 없으면 미확정으로 둔다
• KWCAG↔WCAG↔axe 번역표 — 커버리지 완전 1 / 부분 19 / 불가 13. 불가 13항목은 리포트에 수동 체크리스트와 확인 매뉴얼로 내보낸다
• 킷 결함 기록 — 아이콘 경로, 셀렉트 기본색 대비, 탭 role 등 공식 킷의 알려진 결함과 처리는 docs/mapping/kit-bugs.md

개발

pnpm install
pnpm test             # vitest
pnpm typecheck        # tsc --noEmit
pnpm build            # tsup → dist/

pnpm build:previews   # 템플릿 프리뷰 생성 (테스트 전에 한 번 필요)
pnpm scan:axe         # 전 템플릿 axe 전수 (위반 시 exit 1)
pnpm verify:a11y      # 키보드 전수·접근성 트리 검증

검사 기능 테스트에는 Chromium이 필요하다(pnpm exec playwright install chromium).

라이선스

• 이 저장소의 코드: MIT
• KRDS 유래 자료(템플릿의 공식 패턴 교정본·발췌 레이아웃 CSS와 그 안의 패턴 아이콘, 킷 마크업 인용)는 공공누리 제1유형을 따른다. 출처 표기는 NOTICE에 있다