a11y-mcp-server

웹 접근성 감사, WCAG 기준 조회 및 수정 가이드를 위한 MCP 서버입니다. 현재는 사용되지 않습니다.

기능

• a11y_lookup_wcag: 번호, 키워드 또는 레벨별로 WCAG 2.2 기준 조회

• a11y_check_pattern: 일반적인 접근성 문제에 대해 HTML 스니펫 분석

• a11y_suggest_fix: 수정 전/후 코드 예시가 포함된 수정 패턴 제공

• a11y_document_component: 18개 이상의 UI 컴포넌트 유형에 대한 접근성 문서 생성

• a11y_audit_summary: 문제 목록을 바탕으로 전문적인 감사 보고서 생성

Related MCP server: @accesslint/mcp

로컬 개발

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start

# Server runs on http://localhost:8080
# Health check: http://localhost:8080/health
# MCP endpoint: http://localhost:8080/mcp

NFSN 배포

개인적인 경로에 대한 사전 요구 사항 (환경에 따라 다를 수 있음):

1. 잔액이 있는 NFSN 계정 (초기 예치금 약 $10)

2. SSH 접근 설정

설정 단계

1. NFSN 사이트 생성

1. NFSN 멤버 인터페이스에 로그인

2. Sites → Create a New Site

3. 사이트 유형: Custom (Node.js 데몬에 필요)

4. 사이트 호스트 이름 기록 (예: yoursite.nfshost.com)

2. 코드 업로드

# From project directory
rsync -avz --exclude node_modules --exclude .git --exclude dist \
  ./ USERNAME_SITENAME@ssh.phx.nearlyfreespeech.net:/home/protected/a11y-mcp-server

3. SSH 설정

ssh USERNAME_SITENAME@ssh.phx.nearlyfreespeech.net

# Navigate to project
cd /home/protected/a11y-mcp-server

# Check Node.js version (should be 18+)
node --version

# Install dependencies
npm install --production

# Build
npm run build

# Make run.sh executable
chmod +x run.sh

# Test locally
./run.sh
# Ctrl+C to stop

4. NFSN 데몬 설정

1. NFSN 사이트 제어판으로 이동

2. Sites → Your Site → Site Information → Daemons

3. 데몬 추가:

   • Tag: node

   • Command Line: /home/protected/a11y-mcp-server/run.sh

   • Working Directory: /home/protected/a11y-mcp-server

5. NFSN 프록시 설정

1. Sites → Your Site → Site Information → Proxies

2. 프록시 추가:

   • Protocol: http

   • Base URI: /mcp

   • Document Root: (비워둠)

   • Target Port: 8080

6. 배포 확인

# Check health endpoint
curl https://yoursite.nfshost.com/health

# Test MCP endpoint
curl -X POST https://yoursite.nfshost.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

문제 해결

데몬 로그 확인:

ssh USERNAME_SITENAME@ssh.phx.nearlyfreespeech.net
cat /home/protected/a11y-mcp-server/daemon.log

데몬 재시작: NFSN 제어판을 통해: Sites → Daemons → Restart

데몬 실행 여부 확인:

ps aux | grep node

Claude Code 설정

~/.config/claude/claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "a11y": {
      "url": "https://yoursite.nfshost.com/mcp"
    }
  }
}

그 후 Claude Code를 재시작합니다.

Claude Code를 이용한 로컬 테스트

NFSN 배포 전 테스트를 위해 서버를 로컬에서 실행하고 Claude Code가 연결되도록 설정합니다:

1. 서버 시작:

npm start

2. ~/.config/claude/claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "a11y-local": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

3. Claude Code 재시작

평가 질문

서버가 올바르게 작동하는지 확인하려면 다음 질문을 사용하세요:

1. WCAG 조회: "키보드 탐색을 다루는 WCAG 기준은 무엇이며 레벨은 어떻게 되나요?"

   • 예상 결과: 2.1.1 Keyboard (Level A)와 전체 세부 정보 반환

2. 수정 패턴: "장식용 이미지에 alt 텍스트가 누락된 경우 수정 패턴은 무엇인가요?"

   • 예상 결과: 빈 alt="" 예시가 포함된 패턴 반환

3. 컴포넌트 문서화: "모달 다이얼로그 컴포넌트에 대한 접근성 문서를 생성해 주세요."

   • 예상 결과: 키보드 상호작용, ARIA 속성, 스크린 리더 기대치 반환

4. WCAG 2.2 검색: "모바일/터치 상호작용과 관련된 WCAG 2.2 기준은 무엇인가요?"

   • 예상 결과: 2.5.x Input Modalities 기준 반환

5. 일반적인 실패 사례: "기준 1.4.3 명도 대비(Contrast)에 대한 일반적인 실패 사례는 무엇인가요?"

   • 예상 결과: F24, F83 실패 기법 반환

사용 예시

WCAG 기준 조회

Query: "What WCAG criterion covers keyboard navigation?"
Tool: a11y_lookup_wcag
Args: { "query": "keyboard" }

HTML 문제 확인

Query: "Check this HTML for accessibility issues"
Tool: a11y_check_pattern
Args: { "html": "<img src='logo.png'><button><svg>...</svg></button>" }

수정 패턴 가져오기

Query: "How do I fix missing alt text on decorative images?"
Tool: a11y_suggest_fix
Args: { "issueType": "missing-alt-decorative" }

컴포넌트 문서 생성

Query: "Generate accessibility documentation for a modal dialog"
Tool: a11y_document_component
Args: { "componentType": "modal" }

WCAG 데이터 업데이트

WCAG 기준은 src/data/wcag-criteria.json에 번들로 포함되어 있습니다. 업데이트 방법:

1. 새로운 기준으로 JSON 파일 수정

2. 재빌드: npm run build

3. NFSN에 재배포

라이선스

MIT