# 계획서: task-134.1 — MCP 브라우저 자동화 도구 세팅

## 목표
Claude Code에서 웹 브라우저를 조작할 수 있도록 Playwright MCP 서버를 설치 및 설정한다.

## 기술 결정
- **선택**: `@playwright/mcp@0.0.68` (Playwright 공식 MCP 서버)
- **기각**: `@modelcontextprotocol/server-puppeteer` — npm에서 DEPRECATED 상태, 더 이상 유지보수 안 됨
- **기각 사유**: Playwright MCP가 활발히 유지보수되고 (2주 전 릴리즈), headless 모드 지원, 더 풍부한 API 제공

## 서브태스크 분해

### ST-1: 불칸 (백엔드) — Playwright MCP 서버 설치 및 설정
- `@playwright/mcp` npm 패키지 설치 (로컬)
- Playwright 브라우저 바이너리 설치 (chromium)
- Claude Code settings.json에 MCP 서버 등록
- 설치 검증 스크립트 작성

### ST-2: 아르고스 (테스터) — 설치 검증 및 동작 테스트
- Playwright MCP 서버 프로세스 기동 확인
- MCP 프로토콜 핸드셰이크(initialize) 테스트
- tools/list 응답 확인
- 간단한 브라우저 자동화 도구 호출 테스트 (navigate)

## 실행 순서
1. ST-1 (불칸): 설치 및 설정 → 2. ST-2 (아르고스): 검증 (순차)

## 팀원 미배정 사유
- 이리스(프론트엔드): UI 작업 없음 — 인프라/설정 작업
- 아테나(UX/UI): 디자인 요소 없음

## 예상 위험 및 대안
1. **headless 브라우저 미설치 시 Playwright 실행 불가** → `npx playwright install chromium`으로 브라우저 설치
2. **시스템 라이브러리 누락** → `npx playwright install-deps chromium`으로 의존성 설치, 또는 수동 apt 설치
3. **Node.js 버전 호환성** → v24.14.0 확인 완료, 호환 가능

## 실패 시나리오 체크리스트

### 1. 비정상 입력/상태
- MCP settings.json이 손상되어 있는 경우 → 백업 후 덮어쓰기
- npm 패키지 다운로드 실패 → 네트워크 확인 후 재시도
- 기존 MCP 서버 설정이 충돌하는 경우 → 기존 설정 보존하며 추가만 수행

### 2. 동시성/경쟁 조건
- 다른 프로세스가 settings.json 수정 중일 수 있음 → 현재 단일 사용자 환경이므로 위험 낮음
- 해당 없음 (설치 작업은 일회성)

### 3. 비정상 종료/타임아웃
- npm install 중간에 중단 → node_modules 정리 후 재설치
- Playwright 브라우저 다운로드 타임아웃 → 재시도
- MCP 서버 프로세스 크래시 → 로그 확인, headless 모드 강제 설정

### 4. 스테일 데이터
- 해당 없음 (설치 설정이므로 캐시/TTL 이슈 없음)

### 5. 통합 시 충돌
- 기존 openclaw MCP 서버 설정 보존 필수 — mcpServers 오브젝트에 새 키만 추가
- 다른 팀 디렉토리 건드리지 않음