HyperCrawl

셀프 호스팅 방식의 쿠키 인식 웹 자동화 엔진입니다. 모든 웹사이트를 호출 가능한 MCP 도구(DOM 선택자 기반)로 바꾸고, 자체 서버에서 스텔스 모드로 헤드리스 실행하며, 실제 로그인된 브라우저에서 라이브 인증 쿠키를 온디맨드로 가져옵니다. 내부 NEB 도구 — Apify와 함께 작동합니다.

상태: hypercrawl-vm GCE VM에서 프로덕션 운영 중입니다(Caddy 자동 TLS + Firebase-Auth 게이트, hypercrawl.service). 기능: acquire() 기능 사다리(hypercrawl_acquire — API 재생/하이드레이션 → 학습된 도구 → DOM 에이전트 → set-of-marks → 비전 → 전문가), 다중 페이지 발견(hypercrawl_map, hypercrawl_crawl_site), 크롤 간 변경 추적(상태 비저장 previousHashes 또는 DB 기반 track 스트림, 두 인텐트 모두), 웹 검색(hypercrawl_search), 그리고 HTTP MCP 전송, ProxyPool, Apify 폴백 어댑터. docs/USAGE.md(도구) 및 deploy/gcp/README.md(배포/업데이트 — 필수 npm install + npx playwright install 단계 포함)를 참조하세요.

브라우저 세션

일회성 획득 외에도 HyperCrawl은 상태 저장 브라우저 표면을 노출합니다. 즉, 15개의 hypercrawl_browser_* MCP 도구가 여러 호출에 걸쳐 단일 라이브 페이지를 구동하므로 에이전트는 페이지를 읽고, 클릭하고, 양식을 작성하고, 제출할 수 있습니다. 각 단계는 동일한 탭에 머물게 됩니다. hypercrawl_browser_open은 다른 모든 도구가 사용하는 sessionId를 반환합니다.

세션은 제한된 리소스입니다. 각 세션은 실제 Chromium 컨텍스트를 고정하므로, 서버는 동시성을 제한하고(HYPERCRAWL_MAX_SESSIONS, 기본값 4) 5분 이상 유휴 상태인 세션을 정리합니다. 작업이 끝나면 세션을 닫으세요. 알 수 없는 sessionId는 조용히 새 페이지가 아니라 명백한 오류입니다.

그 외에도: hypercrawl_analyze / hypercrawl_quality(페이지 구조, 그리고 저장된 템플릿의 선택자가 라이브 페이지에 대해 여전히 해석되는지 여부 — 리디자인이 이를 깨뜨렸다는 신호), hypercrawl_auth_save / _auth_list, 그리고 프로세스 내 관측성을 위한 hypercrawl_metrics / _events / _speed / _setup이 있습니다. 도구 참조 및 모든 환경 변수: docs/USAGE.md.

두 가지 기능은 서버가 hypercrawl serve를 통해 시작될 때만 연결됩니다 — 인증 쌍과 hypercrawl_setup — 그 구현이 CLI 패키지에 있기 때문입니다. 연결되지 않은 경우에는 "구성된 항목 없음"으로 읽힐 빈 결과를 반환하는 대신 그렇다고 알려줍니다.

GCP에 배포

Caddy 자동 TLS와 Firebase Auth 토큰 게이트를 갖춘 전용 GCE VM에서 전체 엔진(인증된 쿠키 가져오기 스크래핑 포함)을 실행하려면 deploy/gcp/README.md에 있는 멱등 프로비저닝 스크립트와 운영자 런북을 사용하세요. 설계: docs/superpowers/specs/2026-05-29-hypercrawl-gcp-deploy-design.md.