Ziroom MCP

이것은 自如 주택 임대 MCP 서비스입니다: 상태 저장형 매물 필터링과 세션 없이 단일 상세 페이지 URL을 가져오는 것을 모두 지원합니다. 검색 시 Agent는 동일한 session_id에서 도구를 연속적으로 호출하며, 서버는 브라우저 페이지, 필터 상태, 버전 번호 및 롤백 체크포인트를 유지합니다.

도구

• create_search_session: 도시에 따라 해당 自如 페이지를 엽니다.

• get_filter_schema: 현재 필드, 옵션, 컨트롤 유형 및 선택 상태를 읽습니다.

• search_location: 아파트 단지, 상권 또는 지하철 역을 검색합니다.

• select_filter_option: 단일 선택 또는 다중 선택 태그를 선택합니다.

• set_filter_range: 임대료 범위를 설정합니다.

• set_sort: 가격, 면적 등 정렬을 설정합니다.

• get_results: 매물 이름, URL, 현재 전체 조건 및 검증 결과를 반환합니다.

• get_listing_detail: /x/{listing-id}.html URL을 통해 구조화된 상세 정보와 중국어 Markdown 보고서를 반환합니다.

• restore_checkpoint: 특정 작업 이전의 전체 상태를 복원합니다.

• reset_filter: 지정된 필드를 전체적으로 기본값으로 복원합니다.

• close_search_session: 페이지를 닫고 리소스를 해제합니다.

설치

cd C:\path\to\ziroom-mcp
python -m venv .venv
.venv\Scripts\python.exe -m pip install -e ".[test]"

서비스는 Windows에 이미 설치된 Chrome 또는 Edge를 우선 사용합니다. 사용 가능한 브라우저가 없으면 Playwright Chromium을 설치합니다:

.venv\Scripts\python.exe -m playwright install chromium

상세 정보 가져오기와 검색은 동일한 Playwright 브라우저 프로세스를 공유합니다. get_listing_detail 호출마다 별도의 BrowserContext를 생성하며, 읽기가 완료되면 즉시 닫아 기존 검색 세션을 오염시키지 않습니다. 가격 숫자 스프라이트 이미지는 Playwright 요청 컨텍스트를 통해 다운로드되어 디코딩됩니다.

시작

.venv\Scripts\ziroom-mcp.exe

서비스는 기본적으로 stdio를 사용하며, 로그는 stdout에 기록하면 안 됩니다.

Streamable HTTP 사용:

$env:ZIROOM_TRANSPORT="streamable-http"
$env:ZIROOM_HOST="127.0.0.1"
$env:ZIROOM_PORT="8000"
.venv\Scripts\ziroom-mcp.exe

HTTP MCP 엔드포인트는 http://127.0.0.1:8000/mcp이며, Cloudflare Quick Tunnel과 호환되는 JSON 응답 모드를 사용합니다.

공개 Host를 전달하는 역방향 프록시를 통해 접속하는 경우 $env:ZIROOM_BEHIND_PROXY="1"을 설정하세요. 활성화한 후에는 ZIROOM_HOST=127.0.0.1을 유지해야 하며, 공개 네트워크 인터페이스를 직접 수신하지 않도록 해야 합니다.

自如는 현재 헤드리스 Chrome에 빈 본문을 반환하므로, 서비스는 기본적으로 보이는 브라우저를 시작합니다. 대상 페이지가 지원하는 것이 확인된 경우에만 헤드리스 모드를 활성화하세요:

$env:ZIROOM_HEADLESS="1"
.venv\Scripts\ziroom-mcp.exe

ZIROOM_CHROME_PATH를 통해 Chrome/Edge 실행 파일을 지정할 수도 있습니다.

동일한 검색 세션은 항상 동일한 브라우저 탭을 재사용합니다. 필터 링크 탐색 후 서비스는 기존 쿼리 매개변수를 유지하고 isOpen을 1로 복원한 다음 다음 항목을 다시 찾습니다. 웹사이트가 여전히 대상 링크를 DOM에 숨겨두면 DOM click을 폴백으로 사용합니다.

Agent 호출 규칙

단일 상세 페이지를 가져올 때는 get_listing_detail을 한 번 직접 호출하며, 검색 세션을 생성하거나 닫을 필요가 없습니다:

{
  "url": "https://wh.ziroom.com/x/123456.html",
  "timeout_seconds": 30,
  "retries": 4,
  "include_report": true
}

반환 값에는 listing_id, url, fetched_at, 구조화된 listing, 그리고 선택적인 report_markdown이 포함됩니다.

매물을 필터링할 때는 다음 순서를 따릅니다:

1. create_search_session을 호출합니다.

2. get_filter_schema를 호출하여 페이지가 현재 반환하는 태그만 선택합니다.

3. location, area, metro는 상호 배타적인 집 찾기 방식이므로 하나만 유지합니다. location → area → metro 순서로 폴백 큐를 만들고, 기본 설정 항목이 오류를 반환하거나 유지되지 않거나 결과가 0개이면 페이지가 복원되었는지 확인한 후 다음 항목을 시도합니다.

4. 모든 수정 도구는 동일한 session_id를 사용하며, 이전 단계에서 반환된 state_version을 전달합니다.

5. 각 수정 후 has_results를 확인합니다.

6. false인 경우, 이번에 반환된 checkpoint를 사용하여 restore_checkpoint를 호출하고 reason을 empty_results로 설정합니다.

7. skipped=true 및 reason=page_did_not_retain_option이 반환되면 페이지가 이번 태그를 유지하지 않았고 도구가 원래 상태를 복원했음을 의미합니다. restore_checkpoint를 호출하면 안 되며, 스키마를 새로 고친 후 사용 불가로 기록하거나 비즈니스 규칙에 따라 제한적으로 재시도해야 합니다. 다른 수정 도구는 reason=page_did_not_retain_change를 반환합니다.

8. 마지막으로 get_results를 호출하고 expected_filters를 통해 유지되어야 하는 모든 조건을 검증합니다.

9. 완료 후 close_search_session을 호출합니다.

예상 가능한 필터 충돌은 도구 오류로 반환되지 않습니다. 현재 페이지에 옵션이 없거나, 옵션이 이미 적용되었거나, 페이지가 변경 사항을 유지하지 않았거나, location/area/metro 충돌이 있는 경우 수정 도구는 skipped=true, state_changed=false를 반환하고 원래 state_version과 모든 선택된 조건을 유지합니다. Agent는 이유를 기록하고 다음 항목을 계속 진행해야 합니다. 실제 버전 충돌, 세션 무효화, 사이트 장애 및 내부 오류는 여전히 도구 오류로 반환됩니다.

테스트

모든 MCP 도구에는 오프라인 프로토콜 레이어 테스트가 있습니다:

.venv\Scripts\python.exe -m pytest -m "not live" -v

테스트는 가짜 웹 백엔드를 사용하는 stdio 서버 하위 프로세스도 시작하여 MCP 초기화, 도구 검색 및 도구 호출을 검증합니다. ZIROOM_BACKEND=fake는 자동화 테스트 전용입니다.

실제 웹페이지 스모크 테스트:

$env:ZIROOM_LIVE_TEST="1"
.venv\Scripts\python.exe -m pytest -m live -v