Leapfrog MCP

문제점

Playwright MCP는 Hacker News와 같이 콘텐츠가 많은 페이지에 대해 약 14,000개의 토큰을 전송합니다. 대부분은 불필요한 정보입니다. 컨텍스트 창이 가득 차고, 에이전트가 혼란을 겪으며, 비용이 발생합니다.

Leapfrog는 동일한 페이지와 정보에 대해 약 1,400개의 토큰만 전송합니다. 불필요한 정보가 최대 10배 줄어듭니다.

┌─────────────────────────────────────────────────────┐
│  Playwright MCP                                     │
│  ████████████████████████████████████████  ~14,000   │
│                                                     │
│  Leapfrog                                           │
│  █████                                    ~1,400    │
└─────────────────────────────────────────────────────┘
          tokens per page (Hacker News, real test)

절감 효과는 페이지 복잡도에 따라 210배입니다. 콘텐츠가 많은 페이지에서 가장 큰 효과를 보며, 폼이 많은 페이지에서 가장 적은 효과를 봅니다. 실제 사이트에서의 중앙값은 **약 45배**입니다.

빠른 시작

npx leapfrog --doctor          # verify everything works
npx leapfrog --stealth-audit   # test all 19 stealth patches
npx leapfrog --config          # print MCP config to paste

~/.mcp.json(Claude Code) 또는 에디터의 MCP 설정에 추가하세요:

{
  "leapfrog": {
    "command": "npx",
    "args": ["-y", "leapfrog"],
    "env": {
      "LEAP_MAX_SESSIONS": "15",
      "LEAP_TILE": "true",
      "LEAP_HUD": "true",
      "LEAP_SOUND": "true",
      "LEAP_AUTO_CONSENT": "true"
    }
  }
}

Leapfrog는 playwright(1.6GB) 대신 playwright-core(15MB)를 사용하며 브라우저를 번들로 포함하지 않습니다. 다음 중 하나를 수행하세요:

• LEAP_CHANNEL=chrome을 설정하여 설치된 Chrome/Chromium 사용

• 또는 npx playwright-core install chromium을 실행하여 번들된 Chromium 바이너리 설치

기능 매트릭스

스텔스

Leapfrog는 기본적으로 활성화된 19가지 탐지 방지 패치를 제공합니다(LEAP_STEALTH=true). 이는 CreepJS 및 fingerprint-pro와 같은 지문 서비스가 실제로 확인하는 벡터를 다룹니다:

• Client Hints 브랜드 (HeadlessChrome 제거)

• navigator.webdriver를 undefined로 강제 설정

• WebGL 벤더/렌더러 (SwiftShader를 실제 GPU 문자열로 대체)

• 연결 RTT (0이 아님)

• 알림 닫기 타이밍 (인간 속도 지연)

• 창 외부/내부 높이 오프셋

• MIME 타입 배열 채우기

• 사용자 에이전트로부터 플랫폼 추론

• chrome.app 에뮬레이션

• iframe contentWindow 보호

• 미디어 코덱 스푸핑 (canPlayType)

• document.hasFocus() 재정의

• 소스 URL 주석 제거

• 사용자 지정 UA + 스텔스 공존 (사용자 지정 사용자 에이전트가 더 이상 스텔스 컨텍스트를 비활성화하지 않음)

• CDP Runtime.enable 탐지 (Error.prepareStackTrace 필터)

• 권한 API 스푸핑 (20개 이상의 권한 유형)

• AudioContext 지문 노이즈 (getChannelData/getFloatFrequencyData)

• WebRTC IP 유출 방지 (ICE 후보 필터링)

• 폰트 열거 지문 스푸핑

세션별 스텔스 제어: 특정 세션에 대해 비활성화하려면 session_create에서 stealth: false를 전달하세요.

인간화 (실험적)

LEAP_HUMANIZE=true를 설정하여 인간과 유사한 브라우저 상호 작용을 활성화하세요. 이는 선택 사항이며 더 현실적인 동작을 위해 지연 시간이 추가됩니다. 6가지 모듈:

• 마우스 — Fitts의 법칙 타이밍과 미세한 떨림(jitter)이 있는 베지에 곡선 경로

• 타이핑 — 로그 정규 분포 키 간 지연(중앙값 200ms), 키 체류 시간, 바이그램 인식 속도, 롤오버 타이핑

• 스크롤 — 가속 및 관성 감쇠가 포함된 관성 시뮬레이션 (터치패드/마우스 휠 물리)

• 일시 정지 — 작업 간 인지적 간격을 시뮬레이션하는 "생각" 지연

• 지문 — 일관된 브라우저 지문 생성 (플랫폼, 장치 메모리, GPU, 시간대)

• 유틸리티 — 공유 수학 기본 요소 (Box-Muller 가우시안, 분포)

페이지 분류

모든 navigate 및 snapshot 호출은 가중치 신호 점수를 사용하여 페이지 유형을 자동으로 분류합니다(LLM 필요 없음). 18가지 유형:

login · search-results · product · product-list · checkout · article · dashboard · form · error · challenge · landing · documentation · profile · media · feed · qa · ecommerce · unknown

분류를 통해 더 스마트한 스냅샷 추출이 가능합니다. 로그인 페이지는 폼 필드를, 기사는 콘텐츠를, 대시보드는 대화형 요소를 표면화합니다.

하네스 지능

하네스는 세션 내의 모든 작업을 추적하고 결과를 분류합니다:

• 작업 결과 분류 — SUCCESS, SILENT_CLICK, NAVIGATION, WRONG_ELEMENT, BLOCKED, ERROR, PENDING

• 봇 리다이렉트 탐지 — 작업 후 사이트가 챌린지 또는 차단 페이지로 리다이렉트되는 경우 탐지

• 루프 탐지 — 에이전트가 동일한 요소를 반복 클릭하거나, URL 간을 핑퐁하거나, 작업을 반복할 때 경고

• 세션 메모리 — session_memory 도구가 컨텍스트 창 압축 후 작업을 회상

쿠키 지속성

지속적인 브라우저 프로필은 이제 storageState() 대신 context.cookies() + addCookies()를 사용합니다. 인증 상태는 세션 전반에 걸쳐 유지됩니다.

적응형 대기 + 스텔스 에스컬레이션

페이지 로드 실패 시 자동으로 대체 전략을 사용하여 재시도합니다:

1. load 시도 (가장 빠름) — 비어 있으면 networkidle(10초 제한)로 재시도

2. networkidle 시간 초과 시 (Amazon, 광고가 많은 사이트), domcontentloaded로 대체

3. 차단/챌린지 발생 시, 스텔스 강화: 무작위 지연 → JS 챌린지 대기 → 새로운 지문으로 세션 교체

4. 프로필 세션(인증됨)은 세션이 절대 파괴되지 않음 — 레벨 2로 엄격히 제한

navigate에서 autoRetry: false로 비활성화할 수 있습니다. maxRetryLevel(0-5, 기본값 3)로 최대 에스컬레이션을 제어하세요.

기록 / 재생

세션의 작업 기록을 재생 가능한 기록으로 내보낸 후 새 세션에서 재생합니다:

• session_export — 세션 기록에서 매개변수화된 JSON 또는 Playwright 스크립트를 생성합니다. @eN 참조는 안정적인 CSS 선택자로 확인됩니다. 이메일, 비밀번호, URL을 {{placeholders}}로 자동 감지합니다.

• session_replay — 매개변수 재정의와 함께 기록을 재생합니다. onError: 'stop' 또는 'skip'을 지원합니다.

일회성 에이전트 워크플로우를 재사용 가능한 자동화로 전환하세요.

페이지네이션 추출

단일 도구 호출로 여러 페이지에 걸쳐 데이터를 추출합니다:

• Click-next — "다음" 버튼, 페이지네이션 링크, "더 보기" 버튼 자동 감지

• 무한 스크롤 — DOM 해시 비교를 통해 스크롤하고 새 콘텐츠를 대기

• URL 패턴 — ?page={page} 또는 사용자 지정 패턴 증가

페이지당 3-4개의 도구 호출을 대체합니다. 제한: 50페이지, 총 10만 자. 다음 버튼 없음, 빈 페이지, 중복 콘텐츠 또는 봇 탐지 시 중지됩니다.

증분 스냅샷

diff 도구는 마지막 스냅샷 이후 변경된 내용(추가, 제거, 변경)만 반환합니다. 모니터링 및 폴링 워크플로우를 위한 엄청난 토큰 절감 효과를 제공합니다.

HUD 오버레이 (LEAP_HUD=true)

헤드 모드 실행 시, Leapfrog는 모든 세션에 시각적 피드백을 오버레이합니다:

• 클릭 리플 — 클릭 좌표에 녹색 원 확장 (에이전트 작업만)

• 타겟 줌 — 클릭된 요소로 브라우저가 잠시 1.15배 확대되어 에이전트(및 인간)가 타일 창에서 무슨 일이 일어나는지 시각적으로 추적 가능

• 타겟 스크롤 — 클릭 전 scrollIntoView를 수행하여 에이전트가 무엇을 클릭하려는지 확인 가능

설계상 최소화되어 있습니다. 테두리, 상태 표시줄, 커서 오버레이가 없으며 중요한 피드백만 제공합니다.

멀티 터미널 타일링 (LEAP_TILE=true)

여러 Leapfrog 인스턴스가 파일 기반 조정을 통해 화면을 공유합니다. 각 인스턴스는 자신의 창을 추적하고 TilesCoordinator가 전역 그리드 슬롯을 할당합니다. 겹침이나 수동 정렬이 필요 없습니다. LEAP_TILE=true(또는 기본 인스턴스의 경우 LEAP_TILE=master)를 설정하세요. 타일 간 간격은 LEAP_TILE_PADDING(기본값 8px)으로 구성 가능합니다.

인간 개입

Leapfrog는 CAPTCHA, 로그인 폼, OAuth 리다이렉트, Cloudflare 챌린지 등 인간의 도움이 필요한 상황을 자동으로 감지하고 일시 중지하기 전에 스스로 해결을 시도합니다.

• 우선 자동 해결: reCAPTCHA 체크박스, Cloudflare 확인 버튼, 일반 확인/계속 버튼을 클릭하고 두 번째 재시도를 수행합니다. 모두 도움을 요청하기 전에 수행됩니다.

• 외부 해결사: CapSolver, 2Captcha 또는 NopeCHA 통합을 위해 LEAP_CAPTCHA_PROVIDER + LEAP_CAPTCHA_API_KEY를 설정하세요.

• 학습: 도메인별로 어떤 해결 방법이 성공했는지 기억하고 재방문 시 알려진 좋은 방법을 먼저 시도합니다.

• reCAPTCHA, hCaptcha, Turnstile, 로그인 폼, OAuth 리다이렉트, Cloudflare 챌린지 탐지

• 개입이 필요할 때 탭 제목이 "NEEDS HUMAN"으로 변경됨

• wait_for_human 도구 — 에이전트가 막혔을 때 호출하며, 사용자가 해결하거나 탐색을 완료할 때까지 차단

쿠키 동의 자동 닫기 (LEAP_AUTO_CONSENT=true)

10개 프레임워크(OneTrust, CookieBot, TrustArc, Quantcast, Didomi, Cookielaw, Osano, Usercentrics 등)와 텍스트 일치 대체 기능을 통해 쿠키 동의 배너를 자동으로 닫습니다. 재방문 시 즉각적인 재생을 위한 도메인별 선택자 캐싱을 지원합니다.

추적 (LEAP_TRACE=true)

스크린샷 + DOM 스냅샷이 포함된 세션별 Playwright 추적입니다. session_export_trace 도구를 통해 trace.playwright.dev에서 볼 수 있는 ZIP 파일을 내보냅니다. 세션 파괴 시 자동 저장됩니다.

자가 개선

Leapfrog는 모든 방문에서 학습합니다. 도메인별 지식은 ~/.leapfrog/domains/{domain}.json에 유지되며 9가지 차원이 모두 자동으로 관리됩니다: