inspection-mcp

개발 서버 화면 검수 자동화 MCP 서버. 검수 시트(자연어)를 Playwright 스크립트로 변환하고, 이후 반복 검수는 스크립트만 실행합니다.

---

설치

cd /유저경로/inspection-mcp

# 의존성 설치
npm install

# Playwright 브라우저 설치
npx playwright install chromium

# 빌드
npm run build

Node.js 18 이상이 필요합니다.

---

MCP 서버 등록

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json 파일을 편집합니다.

{
  "mcpServers": {
    "inspection-mcp": {
      "command": "/노드설치경로/node",
      "args": ["/유저경로/inspection-mcp/dist/index.js"]
    }
  }
}

Cursor

프로젝트 루트 또는 글로벌 .cursor/mcp.json 파일을 편집합니다.

{
  "mcpServers": {
    "inspection-mcp": {
      "command": "/노드설치경로/node",
      "args": ["/유저경로/inspection-mcp/dist/index.js"]
    }
  }
}

nvm 환경에서 node 경로 찾기

nvm을 사용하는 경우 심볼릭 링크가 아닌 절대 경로를 사용해야 합니다.

# 현재 node 절대 경로 확인
which node
# 예시 결과: /Users/유저이름/.nvm/versions/node/v20.11.0/bin/node

---

환경 설정

.env 파일

프로젝트 루트에 .env 파일을 생성합니다. .env.example을 참고하세요.

cp .env.example .env

사이트 등록

QA_SITE_{사이트키}_URL 패턴으로 자동 인식됩니다. 사이트키는 영문 대문자로 작성합니다.

# 사이트 URL (필수)
QA_SITE_MARKET_URL="https://dev-market.example.com"
QA_SITE_MARKET_NAME=마켓

QA_SITE_BACKOFFICE_URL="https://dev-backoffice.example.com"
QA_SITE_BACKOFFICE_NAME=백오피스

# 외부 SSO 로그인 URL (선택 - SSO 리다이렉트 방식일 때만)
QA_SITE_BACKOFFICE_LOGIN_URL="https://sso.example.com/#/login"

계정 등록

QA_ACCOUNT_{계정키}_ID / _PW 패턴으로 자동 인식됩니다.

QA_ACCOUNT_USER_ID=your-username
QA_ACCOUNT_USER_PW=your-password

QA_ACCOUNT_MANAGER_ID=your-manager-id
QA_ACCOUNT_MANAGER_PW=your-manager-pw

실행 옵션

QA_HEADLESS=true          # true: 백그라운드 실행, false: 브라우저 표시
QA_TIMEOUT=30000          # 스크립트 타임아웃 (ms)
QA_SCREENSHOT_ON_PASS=false  # 성공 항목도 스크린샷 저장 여부
QA_MAX_CONCURRENCY=5      # 최대 동시 실행 수

config.json

사이트별 로그인 셀렉터, 규칙 필터, 뷰포트를 설정합니다.

{
  "sites": {
    "market": {
      "login": {
        "path": "/login",
        "spaWait": 2000,
        "selectors": {
          "idInput": "#loginId",
          "pwInput": "#loginPw",
          "submitButton": "button[type=submit]"
        },
        "successIndicator": "/main"
      }
    }
  },
  "ruleFilter": {
    "maxPageLoadTime": 10000,
    "minPageHeight": 200,
    "ignoreConsolePatterns": ["Warning:", "[HMR]", "Failed to load resource"],
    "ignoreNetworkPatterns": ["google-analytics.com", "googletagmanager.com"]
  },
  "viewport": {
    "width": 1440,
    "height": 900
  }
}

.env의 사이트키와 config.json의 사이트키는 소문자로 일치해야 합니다. (예: QA_SITE_MARKET_URL → config.json에서 "market")

---

사용법

1단계: 검수 시트 준비

먼저 템플릿을 받아 검수 항목을 작성합니다.

"검수 시트 템플릿 받아줘"

AI가 get_qa_template 도구를 호출하여 엑셀 템플릿 경로를 알려줍니다. 템플릿을 복사하여 검수 항목을 작성합니다.

엑셀 컬럼 구조

컬럼	필수	설명	예시
id	O	숫자 고유 ID	1, 2, 3
site	O	.env 사이트키 (소문자)	market, backoffice
path	조건부	시작 페이지 경로	/market, /product/list
group	-	여정 그룹명 (같으면 순차 실행)	purchase_flow
description	O	자연어 검수 내용	상품 검색 시 결과가 정확한지 확인
account	조건부	.env 계정키 (소문자)	user, manager
type	-	full(기본) 또는 rule_only	full
login	-	yes(기본) 또는 no	yes

• 독립 항목 (group 없음): path 필수
• 여정 그룹: 첫 항목만 path 필수, 이후 항목은 이전 스크립트 실행 후 이어서 진행
• login=yes: account 필수
• rule_only: 스크립트 없이 HTTP 상태, 콘솔 에러, 페이지 높이 등만 검사

2단계: 검수 시트 등록

작성한 엑셀 파일을 data/sheets/ 폴더에 넣습니다.

/유저경로/inspection-mcp/data/sheets/검수시트.xlsx

그 다음 AI에게 말합니다:

"검수 항목 조회해줘"

list_qa_items 도구가 data/sheets/ 폴더를 자동 스캔하여 새 파일을 등록하고 결과를 보여줍니다.

여러 엑셀 파일 관리

• 파일 여러 개를 넣어도 됩니다 — 각각 독립적으로 관리됩니다
• 파일 수정 시 자동으로 변경 감지 후 재등록됩니다
• 파일 삭제 시 해당 항목들도 자동으로 삭제됩니다

3단계: 스크립트 생성

"검수 스크립트 만들어줘"

AI가 각 항목에 대해:

1. prepare_qa_item — 대상 페이지의 DOM 구조를 수집
2. DOM 정보를 기반으로 Playwright 스크립트 작성
3. save_qa_script — 스크립트 검증 후 저장

저장된 스크립트는 data/scripts/item-001.ts (+ 컴파일된 .js) 형태입니다.

4단계: 검수 실행

"검수 실행해줘"

전체 실행:     run_qa
특정 항목만:    run_qa (items: [1, 2])
특정 사이트만:  run_qa (sites: ["market"])
단일 디버깅:    run_qa_single (item_id: 1)

실행 결과:

• 성공/실패/에러/스킵 상태
• 실패 항목의 스크린샷 (AI 응답에 이미지로 포함)
• HTML/JSON 리포트: data/reports/{실행ID}/

이후 반복 검수

스크립트가 한 번 생성되면, 이후에는 "검수 실행해줘"만으로 반복 실행 가능합니다. AI 토큰 소모 없이 스크립트만 실행됩니다.

---

탐지 가능한 이슈 유형

이 MCP 서버는 두 가지 방식으로 이슈를 탐지합니다.

자동 규칙 검사 (rule_only / full 모드 공통)

모든 검수 항목에 자동으로 적용되며, 별도 스크립트 작성 없이 탐지됩니다.

검사 항목	판정 기준	탐지 예시
HTTP 상태 코드	400 이상이면 실패	404 Not Found, 500 Internal Server Error
콘솔 에러	console.error 1건 이상 발생	JavaScript 런타임 에러, API 호출 실패 로그
깨진 이미지	<img> 태그 로드 실패	삭제된 상품 이미지, 잘못된 이미지 경로
페이지 높이	200px 미만이면 실패	빈 페이지 렌더링, 데이터 로딩 실패로 컨텐츠 없음
네트워크 에러	Fetch/XHR 요청 실패	API 서버 다운, CORS 에러, 타임아웃
페이지 로드 시간	10초 초과 시 실패	서버 응답 지연, 무거운 리소스 로딩

config.json의 ruleFilter에서 기준값과 무시 패턴을 설정할 수 있습니다. 예: HMR 경고, Google Analytics 에러 등 개발 환경 노이즈는 기본 제외됩니다.

AI 스크립트 검사 (full 모드)

자연어 검수 내용을 기반으로 AI가 Playwright 스크립트를 생성하여 검증합니다. 사용자 관점의 UI/UX 이슈를 탐지할 수 있습니다.

클릭/입력 인터랙션

• 버튼 클릭 후 예상 동작 확인 (팝업 열림, 페이지 이동 등)
• 폼 입력 후 제출 결과 검증
• 탭/메뉴 전환 시 콘텐츠 변경 확인
• 예시: "상품명 클릭 시 상세보기 팝업이 열리는지 확인"

텍스트/콘텐츠 검증

• 특정 텍스트가 페이지에 노출되는지 확인
• 글자 깨짐, 인코딩 오류 탐지
• 데이터가 올바르게 표시되는지 검증
• 예시: "상품정보제공고시 화면에서 모든 속성값에 깨진 글자가 없는지 확인"

검색/필터 기능

• 검색 입력 후 결과 목록 노출 확인
• 필터 조건 적용 후 목록 갱신 검증
• 자동완성/최근 검색어 기능 동작 확인
• 예시: "검색어 입력 후 Like 검색 결과가 정확한지 확인"

상태별 노출 제어

• 특정 상태의 항목이 노출/미노출되는지 확인
• 권한에 따른 메뉴/버튼 표시 검증
• 예시: "판매중지/판매종료 상품이 목록에 미노출되는지 확인"

페이지 네비게이션

• 다음/이전 버튼으로 페이지 이동 확인
• URL 변경 패턴 검증
• 뒤로가기 후 상태 유지 확인
• 예시: "하단 '다음' 버튼을 눌러 다음 단계로 이동하는지 확인"

요소 존재/가시성

• 필수 UI 요소가 페이지에 존재하는지 확인
• 로딩 후 요소가 정상적으로 보이는지 검증
• 예시: "로그인 후 메인 페이지에 사용자 이름이 표시되는지 확인"

검수 유형 선택 가이드

상황	권장 유형	설명
페이지가 정상 로딩되는지만 확인	rule_only	스크립트 없이 HTTP/콘솔/이미지 자동 검사
UI 동작을 구체적으로 검증	full	자동 규칙 검사 + AI 스크립트 검사 모두 적용
배포 후 전체 페이지 헬스체크	rule_only	빠르게 전 페이지 상태 확인
특정 기능의 정상 동작 확인	full	클릭/입력/검증 시나리오 스크립트 생성

---

도구 목록

도구	설명
register_qa_sheet	검수 시트 등록 (data/sheets/ 자동 스캔 또는 파일 경로 지정)
list_qa_items	등록된 항목 조회 (조회 전 자동 동기화)
get_qa_template	엑셀 템플릿 경로 반환
update_qa_item	항목 메타데이터 수정 (sheets 폴더 항목은 엑셀에서 수정 안내)
delete_qa_item	항목 삭제 (sheets 폴더 항목은 엑셀에서 관리)
prepare_qa_item	대상 페이지 DOM 수집
save_qa_script	Playwright 스크립트 검증+저장
run_qa	전체/필터 검수 실행
run_qa_single	단일 항목 디버깅 실행

---

주의사항

검수 시트 관리

• data/sheets/ 폴더에 넣은 엑셀 파일이 단일 진실 원천입니다
• 항목을 삭제하려면 엑셀에서 해당 행을 지운 뒤 저장하세요. delete_qa_item으로는 삭제되지 않습니다
• 항목을 수정하려면 엑셀을 직접 편집하세요. update_qa_item은 시트 관리 항목의 수정을 차단하고 엑셀 수정을 안내합니다
• 항목을 추가하려면 엑셀에 행을 추가하면 됩니다. 다음 도구 호출 시 자동으로 반영됩니다
• 엑셀 파일을 열어둔 상태에서 생기는 ~$ 임시 파일은 자동으로 무시됩니다

스크립트 규약

AI가 생성하는 스크립트는 이 프로젝트만의 규약을 따릅니다:

• module.exports = async (page) => { ... } 형태 (CommonJS)
• page 객체 하나만 인자로 받음 — ({ page, expect }) 구조분해 사용 불가
• { pass: boolean, message: string } 객체를 반드시 반환
• @playwright/test, require() 등 외부 모듈 사용 불가
• 첫 페이지 이동은 실행기가 처리하므로, 스크립트는 추가 조작만 작성

환경 설정

• .env에 민감한 정보(계정 비밀번호 등)가 포함됩니다. git에 커밋하지 마세요 (gitignore 적용됨)
• config.json의 사이트키는 .env의 QA_SITE_{키}_URL에서 {키}를 소문자로 변환한 값과 일치해야 합니다
• nvm 환경에서는 MCP 등록 시 which node로 확인한 절대 경로를 사용하세요. node만 쓰면 PATH 문제로 실행이 안 될 수 있습니다

세션 및 인증

• 로그인 세션은 data/auth-states/에 저장됩니다. 세션 만료 시 자동으로 재로그인합니다
• WEHAGO 팝업 로그인 시 팝업 URL이 wehago.com을 포함하는지 검증합니다
• data/auth-states/ 디렉토리는 0700 권한으로 생성됩니다

실행 관련

• QA_HEADLESS=false로 설정하면 브라우저가 화면에 표시됩니다. 디버깅에 유용합니다
• scriptStatus가 ready가 아닌 항목은 실행 시 자동으로 건너뜁니다 (skip)
• 여정 그룹은 같은 브라우저 페이지에서 순차 실행됩니다. 중간 항목의 선행 스크립트가 모두 ready여야 합니다
• 실행 결과 폴더명은 날짜_시분초 형식으로 생성됩니다:
  • run_qa → data/screenshots/run-20260306_143025/
  • run_qa_single → data/screenshots/single-20260306_143025/
  • 리포트도 동일한 ID: data/reports/run-20260306_143025/
• run_qa 결과에는 스크린샷 이미지가 포함되지 않습니다 (용량 초과 방지). 실패 항목의 스크린샷을 확인하려면 run_qa_single로 해당 항목을 재실행하세요

---

폴더 구조

inspection-mcp/
├── .env                  # 사이트 URL, 계정 정보 (git 제외)
├── .env.example          # 환경변수 템플릿
├── config.json           # 사이트별 로그인 셀렉터 설정
├── package.json
├── tsconfig.json
├── src/                  # 소스 코드
│   ├── index.ts          # MCP 서버 진입점
│   ├── types/index.ts    # 타입 정의
│   ├── core/             # 핵심 모듈
│   │   ├── config-loader.ts    # 환경변수/설정 로딩
│   │   ├── excel-parser.ts     # 엑셀 파싱
│   │   ├── script-generator.ts # 스크립트 생성/저장
│   │   ├── script-runner.ts    # 스크립트 실행
│   │   ├── rule-filter.ts      # 규칙 필터 (HTTP, 콘솔, 이미지 등)
│   │   ├── report-generator.ts # HTML/JSON 리포트
│   │   └── auth-manager.ts     # 로그인/세션 관리
│   ├── store/            # 데이터 저장소
│   │   ├── qa-store.ts         # qa-items.json CRUD
│   │   └── sheet-registry.ts   # 엑셀↔항목 매핑 + 동기화
│   └── tools/            # MCP 도구 핸들러 (9개)
├── dist/                 # 빌드 결과물 (git 제외)
└── data/                 # 런타임 데이터 (git 제외, 자동 생성)
    ├── sheets/           # 검수 시트 엑셀 파일 배치 폴더
    ├── scripts/          # 생성된 Playwright 스크립트
    ├── reports/          # 실행 리포트
    ├── screenshots/      # 실패 스크린샷
    └── auth-states/      # 로그인 세션 파일