playwright-mcp — 사내 화면을 Claude 에게 시키기

사내 웹화면(회의실 예약, 근태, 결재…)을 말로 시켜서 처리한다. 사람이 어려운 앞부분을 한 번 시연해 저장해두면, 그 구간은 도구가 그대로 재생하고 LLM 은 남은 작은 부분만 판단한다. 그래서 사내 LLM 처럼 작은 모델로도 안정적으로 돈다.

WSL / 리눅스 기준이다. 명령은 전부 bash 문법 — PowerShell 문법($env:...)은 command not found 가 난다. 브라우저도 리눅스 크로미움이 필요하다. 설치·실행 전부 WSL 안에서 한다.

1. 지금 되는 일

Related MCP server: Playwright MCP

2. 회의실 예약 시켜보기

준비(§4)가 끝났으면 이 폴더에서 claude 를 켜고 이렇게 말하면 된다.

회의실예약 경로로 1703호를 31일 09:00~10:00 예약해줘

Claude 가 하는 일:

route_run {"values":{"day":"31"}}          ← 로그인 → 예약페이지 → 날짜까지 (도구가 재생)
route_assist {"reason":"회의실·시간 지정"}   ← 여기부터 LLM
  route_row {"rowText":"1703호","action":"click"}          → 예약 창이 열린다
  route_set_period {"watch":"시간 선택","start":"09:00","end":"10:00"}
  회의명 입력 → #btnAction 클릭
route_done

경로에 다음에 할 일 메모가 들어 있어서 LLM 이 셀렉터를 새로 찾지 않는다. 날짜만 day 값으로 바뀌고 나머지는 고정이다.

알아두면 좋은 것

• 음영으로 표시된 시간대는 남이 이미 예약한 곳이다. 그쪽으로는 시간을 늘릴 수 없고, 못 맞추면 도구가 "09:30 까지만 가능" 이라고 알려주고 거기서 멈춘다. 요청한 시간이 아닌 채로 예약이 잡히는 일은 없다.

• 회의실 이름을 누르면 위치 안내 팝업만 뜬다. 예약 창은 이름 오른쪽 시간표를 눌러야 열리고, route_row 가 그걸 눌러준다.

• 달력의 월 이동은 아직 도구가 못 한다. 다음 달 날짜는 LLM 이 직접 달력을 넘겨야 한다.

3. 처음 한 번만 — 준비

git clone https://github.com/kay8244/playwright-mcp.git
cd playwright-mcp

npm run setup     # ① 설치 + 검증 (최초 1회, 크로미움 내려받음)
npm run corp      # ② 사내망 설정 (프록시·인증서) — 사내에서는 필수
npm run login -- --route 회의실예약   # ③ 로그인 세션 만들기
cp .env.example .env                  # ④ 아이디/비밀번호가 필요한 경로가 있으면

npm run doctor    # 무엇이 준비됐고 무엇이 남았는지
claude            # 이 폴더 안에서 켠다 → /mcp 에 playwright connected

npm run doctor 가 준비물을 한 번에 짚어준다. 이상하면 일단 이걸 돌리면 된다(읽기만 한다).

=== 업무 준비물 ===
✅ 로그인 세션 — 쿠키 12개, 가장 이른 만료 2026-08-05 09:12 (onspace.sk.com)
⚠️  .env 없음 — 아이디/비밀번호가 필요한 경로는 로그인 단계에서 멈춥니다. → cp .env.example .env
✅ 사내망 설정 — 프록시 http://proxy.corp:8080 (계정 ●●●)
✅ 저장된 경로 2개 — 회의실예약, 샘플-미니샵검색
✅ 경로가 요구하는 비밀값이 모두 .env 에 있습니다

② 사내망 — 화면이 스타일 없이 맨 HTML 로 뜨면

사내 프록시가 HTTPS 를 가로채는데(SSL inspection) 브라우저가 사내 루트 인증서를 몰라서다. 쿠키 문제가 아니다.

npm run corp                                  # 프록시 자동 감지 + 인증서 무시
npm run corp -- --proxy http://주소:포트        # 직접 지정
npm run corp -- --user 사번 --pass 비밀번호      # 인증이 필요한 프록시
npm run corp -- --check auth.sk.com           # 프록시가 정말 필요한지 판별
# claude 껐다 켜기 ← 안 하면 옛 브라우저 설정이 그대로 산다

프록시 주소는 HTTPS_PROXY → 윈도우 설정(WSL 에서 reg.exe/netsh.exe 로 조회) → npm config 순으로 자동으로 찾는다. 사내 프록시가 윈도우에만 잡혀 있고 WSL 환경변수엔 없는 경우가 흔하다. 셸의 curl 은 되는데 브라우저만 안 되는 이유가 이것이다 — 크로미움은 이 환경변수를 자동으로 쓰지 않는다.

설정은 .corp-config.json 에 저장되고 gitignore 된다(프록시 계정이 들어가므로).

③ 로그인 세션 (auth.json)

경로 재생은 저장된 세션을 쓴다. 없으면 로그인 화면부터 시작해 경로와 어긋난다.

npm run login -- --route 회의실예약   # 경로의 시작 주소로 연다
npm run login -- --url https://...    # 주소를 직접

브라우저가 뜨면 평소처럼 로그인하고 창을 닫는다(닫아야 저장된다). 그다음 저장한 세션으로 다시 열어보고, 로그인 화면이면 실패로 알려준다.

세션은 만료된다. 재생이 갑자기 로그인 화면부터 시작하면 만료된 것이다 — npm run doctor 가 만료 시각을 알려주고, npm run login 을 다시 돌리면 된다.

④ 아이디·비밀번호 (.env)

로그인 단계를 자동화해야 하는 경로에만 필요하다. SSO 라면 ③ 세션만으로 충분한 경우가 많다.

cp .env.example .env

ROUTE_SECRET_아이디=k12345@sk.com
ROUTE_SECRET_비밀번호=●●●●●●
# 시스템마다 계정이 다르면 경로별로 덮어쓴다
# ROUTE_SECRET_회의실예약_아이디=...

값은 래퍼만 안다. 툴 응답·대화·로그 어디에도 나오지 않는다(섞여도 •••••• 로 가린다).

⚠ .env 는 gitignore 되지만 디스크에는 평문이다. 그리고 Claude Code 는 파일 읽기 도구로 이걸 열 수 있다 — MCP 경계 밖이라 래퍼가 막지 못한다. 곤란하면 레포 밖 ~/.playwright-mcp.env 에 두거나(이것도 자동으로 읽는다), ③ 세션만 쓴다.

npm run install-global 은 쓰지 마세요. 이 폴더 안에서 claude 를 켜면 .mcp.json 으로 그냥 붙는다. 전역까지 켜면 중복돼 /mcp 에 failed 가 뜬다. 다른 폴더에서도 쓰고 싶을 때만 §8 참고.

4. 업데이트

cd playwright-mcp     # ← 레포 폴더 안에서
npm run update

  [1/10] git pull … 받음
  [2/10] npm install … ok (0.8초)
  ...
✔ 업데이트 완료 — 10단계 전부 통과 (9.6초)
  코드 debac8b → e4f5a6b   검증 7종 통과   전역 등록: 미사용
  ⚠ 실행 중이던  claude  는 껐다 켜야 새 설정이 붙습니다.

git pull 만으로는 부족하다 — 전역 등록은 pull 로 안 바뀌어서, 옛 경로로 계속 붙은 채 겉보기엔 멀쩡한데 새 기능만 빠진 상태가 된다. 제일 알아채기 어려운 실패다.

문제가 생기면 그 단계 출력이 통째로 나온다. 전부 보려면 npm run update -- --verbose.

5. 내 업무 경로 녹화하기

회의실 예약처럼 반복하는 화면이 있으면 한 번 시연해 저장한다. 어려운 앞부분만 녹화하면 된다 — 로그인·메뉴 여러 단계·프레임 진입까지만 담고, 화면이 목적지에 도착한 뒤부터는 LLM 에게 맡기는 방식이 잘 통한다.

npm run record -- --name 주간보고 --url https://사내/report --auth auth.json

1. 브라우저가 뜨면 평소 업무하듯 한 번 시연한다

2. 시연이 끝나면 브라우저 창을 닫는다

3. 각 단계의 의도를 한글로 물어본다 (예: "조회 버튼을 눌러 목록을 띄운다")

4. 위험한 단계(저장·삭제·확정)는 따로 확인한다

5. 저장 전에 실제로 재생해 검증한다 — 재생이 안 되면 저장을 거부한다

핵심은 녹화된 구간에서 LLM 이 아무 판단도 하지 않는다는 점이다. "참고"하는 게 아니라 래퍼가 저장된 셀렉터로 직접 실행한다. 그 구간에서는 모델 성능이 변수가 아니다.

route_run
  ✅ [1/3] 로그인               ← 래퍼가 실행 (LLM 판단 0)
  ✅ [2/3] 메뉴 진입             ← 래퍼가 실행
  ✅ [3/3] 조회                 ← 래퍼가 실행
  🎉 경로를 끝까지 실행했습니다.
route_assist                    ← 여기서부터 LLM (화면은 이미 목적지)
route_done

LLM 이 헤매기 시작하면 그 부분을 추가로 녹화해 경로를 늘리면 된다.

녹화가 잘 안 될 때

⚠ 확정 버튼(저장·예약하기·결재)은 녹화하지 마세요. record 는 저장 전에 녹화분을 다시 재생해 검증하므로, 한 번 녹화에 실제 작업이 2건 일어난다. 확정 단계는 경로에 넣지 말고 LLM 에게 맡기거나, 경로 파일에 손으로 써 넣는다.

⚠ 시간표·달력처럼 클릭 위치로 값이 정해지는 위젯은 녹화로 좌표가 남지 않는다. Playwright 레코더는 <canvas> 가 아니면 좌표를 기록하지 않아서, 재녹화해도 늘 요소 한가운데가 눌린다. 그런 화면은 route_set_period 같은 전용 도구를 쓴다(§8).

6. 경로 파일 공유 규칙

routes/*.json 은 커밋한다 — 팀 자산이다. 다만 사내 URL 과 입력값이 들어가므로 규칙이 있다.

1. 이름은 업무 이름으로. 공백·시험 번호 없이 — 회의실예약 ○ / 회의실예약3·내테스트 ✗ (claude 안에서 녹화하면 기본 이름이 경로-<날짜> 다. 업무 이름으로 바꿔 주세요)

2. 개인 실험은 임시- 를 붙인다 — routes/임시-*.json 은 gitignore 라 실수로 커밋되지 않는다

3. 커밋 전 확인

   grep -n '"value"' routes/<이름>.json        # fill 단계에 값이 남았나 (없어야 한다)
   grep -nE '/home/|/Users/|@sk\.com' routes/<이름>.json   # 절대경로·개인 식별자
   npm run play -- --route <이름>              # 실제로 재생되나

   녹화는 타이핑한 값을 기본적으로 저장하지 않는다(아이디/비번은 valueFrom:"secret", 나머지는 param). 그래도 커밋 전에 한 번 본다.

4. 리뷰 1인. diff 에서 넷만 본다 — "value" 가 새로 생겼나 / URL 에 개인 식별자 / destructive:true 단계가 들어왔나 / 메모가 실제 도구 사용법과 맞나

5. 남의 경로가 깨졌으면 조용히 재녹화해 덮어쓰지 않는다. 먼저 route_assist → route_resume 로 자가수리하면 repairs 에 이력이 남아 diff 로 보인다. 재녹화했으면 무엇이 왜 바뀌었는지 적는다

7. 막히면

설치·운영 (설치 담당자용)

8. 폐쇄망 반입

브라우저 바이너리는 OS 종속이라 인터넷 되는 WSL(같은 리눅스 x64) PC에서 폴더째 만들어 반입한다. npm run setup 이 크로미움을 node_modules 안에 넣으므로 통째로 압축하면 자체완결 번들이 된다.

# [인터넷 되는 WSL PC]
git clone https://github.com/kay8244/playwright-mcp.git && cd playwright-mcp
npm run setup
cd .. && tar czf playwright-mcp-offline.tgz --exclude=.git playwright-mcp

# [폐쇄망 WSL PC]
tar xzf playwright-mcp-offline.tgz && cd playwright-mcp
npm run verify && npm run verify-route
claude

⚠ 준비 PC 와 폐쇄망 PC 의 OS/CPU 가 같아야 한다(리눅스 x64 등). 폐쇄망 PC 에 Node 18+ 가 없으면 먼저 설치한다.

크로미움은 받았는데 실행이 안 되면(리눅스 라이브러리 부족):

sudo npx playwright install-deps chromium

9. 전역 등록 — 다른 폴더에서도 쓰고 싶을 때만

기본 설치는 이 폴더에서 claude 를 켤 때만 붙는다. 어느 레포에서든 쓰려면:

npm run install-global     # ~/.claude.json 최상위 mcpServers 에 절대경로로 추가
npm run uninstall-global   # 해제

⚠ 이 폴더 안에서는 켜지 마세요. 폴더의 .mcp.json 과 중복돼 /mcp 에 failed 가 난다. 전역을 켰으면 확인은 딴 폴더에서 — cd ~ && claude && /mcp. 이 폴더를 지우거나 옮기면 등록이 깨진다(절대경로다) → 옮겼으면 npm run install-global 다시.

npm run doctor 가 어느 폴더가 실제로 쓰이는지, 중복은 없는지 짚어준다. 최종 확인은 claude 안에서 route_status — 지금 서비스 중인 폴더의 절대경로를 알려준다.

10. 언제 무엇을 실행하나

npm run setup 은 몇 번을 돌려도 안전하다(멱등).

11. 배포 전 검증 — 전부 통과해야 한다

npm run update 가 한 번에 돌린다. 개별로 돌리려면:

npm run verify           # 브라우저 조작 (번들 크로미움을 쓰는지까지)
npm run verify-route     # 모드 게이트 10항목
npm run verify-readtime  # 시간 위젯 읽기 14항목
npm run verify-steps     # 경로 단계 스키마 25항목
npm run verify-row       # 행 찾기 4항목
npm run verify-clicktext # 달력·라벨 찾기 8항목
npm run verify-auth      # 로그인 세션 판정 12항목
npm run verify-docs      # 문서가 안내하는 명령·경로·링크가 실재하는가

12. 모드 게이트 — 왜 매번 묻나

브라우저를 만지기 전에 경로 지정과 LLM 자율 중 하나를 반드시 고르게 되어 있다. 프롬프트 규칙이 아니라 래퍼가 물리적으로 막는다 — 고르기 전에는 browser_* 가 전부 거부된다.

작업 단위로만 다시 묻는다. 한 작업 안에서는 추가 질문이 없고, 같은 사이트 안 이동도 재질문하지 않는다. route_done·다른 사이트로 이동·호출 60회/유휴 15분 초과일 때만 다시 잠긴다.

이 레포는 --no-auto 가 기본이다(.mcp.json 에 커밋돼 있다). LLM 이 자율 모드를 스스로 켤 수 없고, 사람이 시연해 만든 경로로만 브라우저가 열린다. 이유는 DECISIONS.md §3. 새 화면이 필요하면 claude 안에서 "🔴 지금 녹화하기" 를 고르면 된다 — 이건 --no-auto 와 무관하게 항상 열려 있다.

⚠ npm run no-auto 는 쓰지 마세요. tracked 파일인 .mcp.json 을 수정해서 git pull 이 막히고 npm run update 가 계속 실패한다. 이미 기본값이라 쓸 일도 없다.

13. 옵션 (.mcp.json 의 args)

14. 개발·디버깅

npm run play — LLM 없이 직접 돌린다

래퍼를 그대로 띄우므로 claude 에서 도는 것과 완전히 같은 경로를 탄다.

npm run play -- --route 샘플-미니샵검색                 # 재생만
npm run play -- --route 샘플-미니샵검색 --headed --repl  # 브라우저 띄운 채 이어서 시험 (권장)
npm run play -- --route 회의실예약 --values '{"day":"31"}'

--repl 이 실전에서 제일 쓸모 있다. 셀렉터를 맞춰가는 일은 시행착오가 필수인데, 매번 처음부터 다시 열면 시간이 다 간다.

play> sel 시간 선택      ← 그 텍스트 요소의 셀렉터를 알아낸다 (라벨이면 옆 입력창까지)
play> row {"rowText":"1703호","action":"click"}
play> period {"watch":"시간 선택","start":"09:00","end":"10:00"}
play> try {"target":".jqs-day","watch":"시간 선택","x":150}
play> probe             ← 프레임·프레임워크 진단
play> quit

--keep 은 Ctrl+C 로 나가면 브라우저도 닫힌다. 이어서 시험하려면 --repl.

시간 블록 드래그 — route_set_period

회의실 예약처럼 선택한 시간대가 막대로 표시되고 그걸 끌어 옮기는 화면(jQuery UI draggable/resizable)용.

route_set_period {"watch":"시간 선택","start":"09:00","end":"10:00"}

✅ 시간대를 맞췄습니다 — 시간 선택 09:00 ~ 10:00
   이전: 07:30 ~ 08:00   (시간당 약 54px 로 계산)
   이동: +81px / 길이조절: +27px

좌표를 알 필요가 없다. 지금 표시된 시각과 막대 폭에서 "시간당 몇 px" 가 바로 나오기 때문이다. 창 크기가 바뀌어도 매번 다시 잰다. 시각이 <input> value 나 ::before 에 있어도 읽고, 물결표가 전각(～)이어도 읽는다.

• block 기본 .myPeriod, handle 기본 .ui-resizable-e — 대개 안 줘도 된다

• end 생략하면 길이는 두고 시작만 옮긴다

• 요청 구간이 남의 예약에 막히면 어디까지 가능한지 알려주고 실패로 끝낸다

사내 그리드(가상 스크롤)

사내 표는 대개 보이는 몇 줄만 실제로 존재한다(597행짜리 표인데 DOM 에는 12행). 그래서 셀렉터를 잘 잡아도 "없는 요소"를 찾게 된다.

⚠ 위치로 행을 잡으면 위험하다. 녹화가 만드는 div:nth-child(12) 는 "화면상 12번째"라 스크롤 위치에 따라 다른 행을 건드린다. 근태·예약에서는 에러도 안 나는 조용한 오작동이다.

반복 작업 굳히기 — crawl.mjs

매일 똑같은 작업이면 LLM 분석을 아예 없애고 고정 셀렉터로 재생하면 수 초에 끝난다.

npm run crawl                                # 동봉 픽스처 → crawl-result.json
node crawl.mjs --url "https://..." --out out.json --auth auth.json

흐름은 MCP 로 한 번 탐색하고, 그 셀렉터를 crawl.mjs 의 crawl(page) 함수에 박는다.

15. 파일

16. 이어서 개발하려면

DECISIONS.md 를 먼저 읽으세요. 왜 이렇게 만들었는지(되돌리면 안 되는 결정), 사내 환경 특성, 회의실 예약 실측값, 다음 할 일이 있다. README 는 사용법, DECISIONS.md 는 설계 근거다.