naverestate-mcp

네이버 부동산 수집을 위한 Playwright + MCP 프로젝트.

목표

• 네이버 부동산 페이지를 실제 브라우저로 열고 public 흐름으로 접근
• UI 상호작용(필터, 스크롤, 중복매물 펼치기)을 Playwright로 수행
• 그 과정에서 발생한 내부 네트워크 응답을 passive capture
• 수집 결과를 정규화하고 MCP tool로 노출

설계 원칙

• 기본 모드는 passive network capture
  • 브라우저가 실제로 발생시킨 요청/응답만 캡처
  • 도구가 내부 API를 새로 직접 때리는 active harvester를 기본으로 두지 않음
• 브라우저 조작과 도메인 로직을 분리
• jipxl의 확장프로그램 구조는 버리고, 재사용 가능한 타입/정규화 로직만 선별 이관
• 로그인 없는 public 흐름을 기본으로 한다
• 캐시는 아파트 이름 전체를 key로 사용하고, 구/동은 metadata로만 저장한다
• 네이버 부동산이 새 Playwright 컨텍스트를 차단할 수 있으므로, 필요하면 기존 Chrome에 CDP attach 하는 경로를 지원한다

패키지 구조

• packages/collector-core
  • 타입, 정규화, 그룹핑, 결과 모델
• packages/playwright-driver
  • persistent context, response capture registry, collector driver
• packages/mcp-server
  • MCP tool spec, server entry skeleton

현재 상태

현재 기본 수집은 실제 동작 확인 완료:

• TypeScript workspace 구조
• collector-core 타입/그룹핑/정규화
• playwright-driver 수집 동작 확인
• mcp-server tool 호출 가능
• 고덕그라시움(complexNo=113907) 기준 검증 완료
  • 대표매물 수집 성공
  • 중복매물 수집 성공
  • JSON 저장 성공

최근 반영 사항

• 새 Playwright Chrome에서 네이버 부동산이 404로 튕기던 문제 수정
  • --disable-blink-features=AutomationControlled
  • navigator.webdriver = false
  • navigator.languages 보정
• overview 응답 패턴 수정
  • /api/complexes/overview/{complexNo} 캡처 지원
• 동일매물 묶기 체크 로직 수정
  • checkbox 직접 클릭 대신 label click / force setChecked fallback
• 중복매물 응답 파싱 수정
  • /api/articles?representativeArticleNo=... 응답의 array payload 지원

현재 기본 수집 전제

• collectDuplicates는 옵션으로 둔다
  • true: 중복매물까지 수집
  • false: 대표매물 목록까지만 수집
• 검색/수집 기본 정렬은 항상 최신순(dateDesc) 으로 고정한다
• 캐시는 아파트 이름 전체 기준으로 저장한다

실행 방법

1) 기본 실행 (권장 시작점)

새 Playwright persistent Chrome 프로필로 실행한다.

cd /Users/hyunsu/.openclaw/workspace/naverestate-mcp
npm run build
node packages/mcp-server/dist/index.js

현재는 anti-detection 보정이 들어가 있어서, 기본 persistent 실행만으로도 네이버 부동산 상세 진입이 가능하다.

2) CDP attach 모드

환경변수로 기존 Chrome 디버깅 엔드포인트를 넘기면, 새 Playwright 프로필 대신 기존 브라우저에 붙을 수 있다.

export NAVER_CDP_ENDPOINT_URL=http://127.0.0.1:9222
node packages/mcp-server/dist/index.js

권장 용도:

• 이미 사람이 열어둔 실제 Chrome 세션을 재사용하고 싶을 때
• Playwright 프로필과 실제 사용자 브라우저 동작 차이를 비교할 때

MCP 도구

현재 stdio MCP 서버에서 제공하는 도구는 아래 4개다.

Tool	설명
naver_search_complex	키워드로 단지 자동완성 후보 검색
naver_resolve_complex	후보를 complexNo로 resolve하고 cache 저장
naver_collect_complex	단지 상세에서 대표매물 + 중복매물 수집
naver_get_last_result	마지막 수집 JSON 다시 가져오기

호출 예시

Search

{
  "name": "naver_search_complex",
  "arguments": {
    "keyword": "고덕그라시움"
  }
}

Resolve

{
  "name": "naver_resolve_complex",
  "arguments": {
    "apartmentName": "고덕그라시움",
    "fullLabel": "고덕동 고덕그라시움"
  }
}

Collect

{
  "name": "naver_collect_complex",
  "arguments": {
    "filter": {
      "complexNo": "113907",
      "tradeTypes": ["A1"]
    },
    "collectDuplicates": true
  }
}

Get last result

{
  "name": "naver_get_last_result",
  "arguments": {}
}

현재 결과 모델 요약

수집 결과 JSON은 아래 필드를 포함한다.

• complex: 단지 개요
• articlePages: 대표매물 목록 원본 응답들
• duplicateResponses: 중복매물 원본 응답들
• articles: 대표매물 정규화 목록
• duplicateGroups: representativeArticleNo 기준 중복매물 묶음
• listingGroups: 대표매물 + duplicates 합친 최종 구조

검증된 샘플

고덕그라시움(complexNo=113907) 기준 최근 검증 결과:

• 대표매물 212
• 중복 묶음 89
• JSON 저장 성공