NICE Scraper — 가맹점 실사 에이전트

PG 가맹점 심사를 위한 자동 사이트 탐색 & 위장 판정 시스템.

프로젝트 개요

• 목표: 가맹점 사이트를 Claude가 직접 탐색하여 신고 업종과 실제 판매 상품 일치 여부 판정
• 방식: Claude API (tool use) + Playwright MCP로 브라우저 자동화
• 배포 형태: 단독 FastAPI 서버 (폐쇄망 배치/API 에서 HTTP 호출)

기술 스택

항목	버전
Python	3.11+
FastAPI	0.104.1
Uvicorn	0.24.0
Pydantic	2.5.0
Anthropic SDK	0.17.0+
Playwright MCP	TBD (2단계)

프로젝트 구조

nice-scraper/
├─ app/
│  ├─ __init__.py
│  ├─ main.py              FastAPI 앱 + 라우팅
│  ├─ config.py            환경 설정
│  ├─ models.py            Request/Response 모델
│  ├─ agent.py             Claude tool-use 루프 (2단계 이후)
│  ├─ mcp_client.py        Playwright MCP 클라이언트 (2단계 이후)
│  └─ prompts.py           시스템 프롬프트 (2단계 이후)
├─ tests/
│  └─ sample_urls.md       테스트 URL 목록
├─ .env.example            환경변수 템플릿
├─ .gitignore
├─ requirements.txt
└─ README.md

설치 & 실행

1. 환경 준비

# 저장소 복제
git clone https://github.com/TBT-AI/NICE_SCRAPER.git
cd nice-scraper

# 가상 환경 생성
python3 -m venv venv
source venv/bin/activate  # macOS/Linux
# venv\Scripts\activate  # Windows

# 의존성 설치
pip install -r requirements.txt

2. 환경변수 설정

cp .env.example .env
# .env 파일을 열어 ANTHROPIC_API_KEY 설정

3. 서버 실행

uvicorn app.main:app --reload

서버가 시작되면: http://localhost:8000

4. API 확인

# 헬스 체크
curl http://localhost:8000/health

# 응답
# {"status":"ok"}

개발 단계

단계	항목	상태
1️⃣	스캐폴딩 + /health	✅ 진행 중
2️⃣	Playwright MCP 연결 + 페이지 로드	⏳ 예정
3️⃣	Claude tool-use 루프 (탐색 로직)	⏳ 예정
4️⃣	시스템 프롬프트 + JSON 파싱	⏳ 예정
5️⃣	안전장치 (스텝·타임아웃·도메인 제한)	⏳ 예정
6️⃣	성능 측정 & 운영 적용 검토	⏳ 예정

API 명세 (완성 예정)

POST /analyze

요청

{
  "url": "https://example-shop.co.kr",
  "declared_category": "의류·패션",
  "biz_name": "럭키기프트몰",
  "ceo_name": "홍길동"
}

응답 (성공)

{
  "status": "SUCCESS",
  "url": "https://example-shop.co.kr",
  "analysis": {
    "site_reachable": true,
    "inferred_category": "의류",
    "category_match": true,
    "prohibited_signals": [],
    "summary": "정상 쇼핑몰"
  },
  "trace": {
    "visited_urls": ["..."],
    "tool_call_count": 8,
    "elapsed_seconds": 23.4,
    "input_tokens": 45000,
    "output_tokens": 1200
  }
}

문서

• 착수지시서: 착수지시서_1단계_스크래핑서버.md (루트)

라이선스

Internal — NICE Sentinel Project

진행 상황

• 2025-09-01: 1단계 스캐폴딩 시작