inspection-mcp

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

설치

cd /유저경로/inspection-mcp

# 의존성 설치
npm install

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

# 빌드
npm run build

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

Related MCP server: Limetest MCP Server

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 도구를 호출하여 엑셀 템플릿 경로를 알려줍니다. 템플릿을 복사하여 검수 항목을 작성합니다.

엑셀 컬럼 구조

• 독립 항목 (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 모드 공통)

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

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

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

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

클릭/입력 인터랙션

• 버튼 클릭 후 예상 동작 확인 (팝업 열림, 페이지 이동 등)

• 폼 입력 후 제출 결과 검증

• 탭/메뉴 전환 시 콘텐츠 변경 확인

• 예시: "상품명 클릭 시 상세보기 팝업이 열리는지 확인"

텍스트/콘텐츠 검증

• 특정 텍스트가 페이지에 노출되는지 확인

• 글자 깨짐, 인코딩 오류 탐지

• 데이터가 올바르게 표시되는지 검증

• 예시: "상품정보제공고시 화면에서 모든 속성값에 깨진 글자가 없는지 확인"

검색/필터 기능

• 검색 입력 후 결과 목록 노출 확인

• 필터 조건 적용 후 목록 갱신 검증

• 자동완성/최근 검색어 기능 동작 확인

• 예시: "검색어 입력 후 Like 검색 결과가 정확한지 확인"

상태별 노출 제어

• 특정 상태의 항목이 노출/미노출되는지 확인

• 권한에 따른 메뉴/버튼 표시 검증

• 예시: "판매중지/판매종료 상품이 목록에 미노출되는지 확인"

페이지 네비게이션

• 다음/이전 버튼으로 페이지 이동 확인

• URL 변경 패턴 검증

• 뒤로가기 후 상태 유지 확인

• 예시: "하단 '다음' 버튼을 눌러 다음 단계로 이동하는지 확인"

요소 존재/가시성

• 필수 UI 요소가 페이지에 존재하는지 확인

• 로딩 후 요소가 정상적으로 보이는지 검증

• 예시: "로그인 후 메인 페이지에 사용자 이름이 표시되는지 확인"

검수 유형 선택 가이드

도구 목록

주의사항

검수 시트 관리

• 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/      # 로그인 세션 파일