jjx-js-reverse-mcp

English README

통합 JavaScript 역공학 MCP: 전체 Hook / 중단점 / 스크립트 디버깅 + 브라우저 조작 링크 + CDP 반감지.

하나의 프로세스는 하나의 브라우저에만 연결되며, js-reverse-mcp와 chrome-devtools-mcp를 동시에 사용할 때 두 개의 창이 열리는 문제를 해결합니다.

모드는 대화 프롬프트가 아닌 시작 매개변수로 결정됩니다. 프롬프트로 MCP가 ATTACH / LAUNCH를 '자동 인식'할 수 없습니다. 모드를 변경하려면 mcp.json을 수정한 후 Reload하거나, 두 세트의 MCP 항목을 등록하여 선택하세요.

빠른 선택

이중 모드 브라우저 생명주기

• ATTACH와 LAUNCH 매개변수는 상호 배타적입니다 (--remoteDebuggingPort와 --executablePath를 동시에 작성 불가).

• ATTACH 실패 시 은밀히 새 브라우저를 열지 않음 ('인계한 줄 알았는데 또 열렸다' 방지).

• 실행 중에는 attach_browser 도구로 동적 인계 가능; 대칭적인 '동적 launch' 도구는 없음 — 실제로 자체 시작하려면 반드시 LAUNCH 시작 매개변수를 사용해야 함.

도구: get_browser_mode / attach_browser / check_browser_health

ATTACH: CLI 예시

# 1) 手动启动（桌面 bat 常用 9333；也可 9222）
"你的chrome.exe路径" ^
  --remote-debugging-port=9333 --remote-allow-origins=*

# 2) 在浏览器里打开目标站并登录

# 3) MCP 接管（端口必须一致）
node build/src/index.js --remoteDebuggingPort 9333 --toolProfile slim
# 或
node build/src/index.js --browserUrl http://127.0.0.1:9333 --toolProfile slim

LAUNCH: CLI 예시

node build/src/index.js ^
  --executablePath "你的chrome.exe路径" ^
  --isolated ^
  --toolProfile slim

Cursor mcp.json: 시나리오별 복사

전역 설정 경로는 일반적으로: %USERPROFILE%\..cursor\mcp.json 수정 후 반드시: Settings → Tools & MCP → Reload 해당 server.

경로는 본인 기기에 맞게 수정: 당신의 jjx-js-reverse-mcp 경로, 당신의 chrome.exe 경로.

시나리오 1 — ATTACH 일상 역공학 (권장)

적합: 로그인 상태 유지, 새 창 적게 열기, Cloak Browser.bat과 함께 사용.

{
  "mcpServers": {
    "jjx-js-reverse-mcp": {
      "command": "cmd",
      "args": [
        "/c",
        "node",
        "你的jjx-js-reverse-mcp路径/build/src/index.js",
        "--remoteDebuggingPort",
        "9333",
        "--toolProfile",
        "slim"
      ]
    }
  }
}

절차: bat 먼저 열기 → 수동으로 대상 사이트 접속 → MCP Reload (로드되지 않은 경우) → 대화에서 "new_page 금지 / launch 금지, 먼저 list_pages" 요청.

시나리오 2 — ATTACH 클래식 9222

브라우저를 --remote-debugging-port=9222로 시작한 경우:

{
  "mcpServers": {
    "jjx-js-reverse-mcp": {
      "command": "cmd",
      "args": [
        "/c",
        "node",
        "你的jjx-js-reverse-mcp路径/build/src/index.js",
        "--remoteDebuggingPort",
        "9222",
        "--toolProfile",
        "slim"
      ]
    }
  }
}

시나리오 3 — LAUNCH 자체 실행 Cloak (자동화/재로그인 가능)

적합: 기존 로그인 상태 불필요; 'Chrome이 자동화된 테스트 소프트웨어에 의해 제어되고 있습니다' 노란색 바가 나타날 수 있음.

{
  "mcpServers": {
    "jjx-js-reverse-mcp": {
      "command": "cmd",
      "args": [
        "/c",
        "node",
        "你的jjx-js-reverse-mcp路径/build/src/index.js",
        "--executablePath",
        "你的chrome.exe路径",
        "--isolated",
        "--toolProfile",
        "slim"
      ]
    }
  }
}

• --isolated: 임시 프로필, 'browser already running / profile 사용 중' 문제 감소.

• 동일 프로필을 사용하는 bat 인스턴스와 디렉토리 충돌 금지; 충돌 시 여분 브라우저를 먼저 닫거나 ATTACH로 변경.

시나리오 4 — 두 세트 병존 (ATTACH + LAUNCH, 대화 중 선택)

설정을 반복해서 수정하고 싶지 않을 때, 두 server를 등록하고 Cursor에서 해당 항목을 활성화/선택:

{
  "mcpServers": {
    "jjx-attach": {
      "command": "cmd",
      "args": [
        "/c",
        "node",
        "你的jjx-js-reverse-mcp路径/build/src/index.js",
        "--remoteDebuggingPort",
        "9333",
        "--toolProfile",
        "slim"
      ]
    },
    "jjx-launch": {
      "command": "cmd",
      "args": [
        "/c",
        "node",
        "你的jjx-js-reverse-mcp路径/build/src/index.js",
        "--executablePath",
        "你的chrome.exe路径",
        "--isolated",
        "--toolProfile",
        "slim"
      ]
    }
  }
}

참고: 둘 다 활성화하면 Agent가 '잘못된' 것을 호출할 수 있음; 프롬프트에 jjx-attach 또는 jjx-launch를 명시하거나, 하나만 활성화.

시나리오 5 — 도구 범위 축소 (observe / hook)

--toolProfile만 변경, 모드 매개변수는 그대로.

정찰 (도구 적음, 결정 빠름):

--toolProfile observe

Hook / 중단점 위주:

--toolProfile hook

전체 (performance / heapsnapshot / 중형 AI / 심층 Wasm 포함):

--toolProfile full

시나리오 6 — Stealth 비활성화 (순수 디버깅)

ATTACH 또는 LAUNCH의 args 끝에 추가:

"--no-stealth"

강력한 리스크 관리 사이트 역공학 시 일반적으로 Stealth 기본값 유지 (이 항목 추가 금지).

시나리오 7 — ATTACH 자동 포트 감지

로컬 포트 9222–9225 감지; 찾지 못하면 오류 발생 후 launch 안 함:

{
  "mcpServers": {
    "jjx-js-reverse-mcp": {
      "command": "cmd",
      "args": [
        "/c",
        "node",
        "你的jjx-js-reverse-mcp路径/build/src/index.js",
        "--autoConnect",
        "--toolProfile",
        "slim"
      ]
    }
  }
}

데스크톱 bat이 9333으로 고정되어 있고 9222–9225 범위 밖이면 시나리오 1의 명시적 포트를 사용하고 --autoConnect에 의존하지 마십시오.

프롬프트와 설정의 관계

로컬에서 참고할 수 있는 프롬프트 템플릿:

• 당신의 ATTACH 모드 프롬프트 템플릿 경로

• 당신의 LAUNCH 모드 프롬프트 템플릿 경로

더 많은 설명: docs/guides/browser-modes.md, docs/guides/anti-detect.md

CDP 반감지 (간략)

기본적으로 기본 CDP leak guard 활성화 (--no-stealth로 비활성화 가능):

1. CdpLeakGuard: cdc_* / selenium 전역 정리, navigator.webdriver 패치, 최소 chrome.*, Error stack 비식별화; 새 문서에 사전 주입 + 탐색 후 재주입

2. evaluate_script / 주입 경로: CDP Runtime.evaluate 우선, __puppeteer_evaluation_script__ 누출 감소

3. 제거됨: StealthScripts2025 (Chrome 131 UA / Canvas / WebGL / Audio 등 지문 위장) — 구식이며 실제 커널과 충돌 가능

도구: enable_cdp_guard / inject_stealth (기본 guard와 동일) / stealth_status 수동 UA: set_user_agent (Client Hints 변경 안 함)

강력한 리스크 관리 시 CloakBrowser 기본 지문 + 실제 로그인 상태 ATTACH 사용. 본 MCP는 '강력한 감지를 통과할 수 있는' 종합 stealth를 제공하지 않음; 프로토콜 수준 솔루션(예: rebrowser-patches)은 별도 통합 필요, 내장되지 않음.

자세한 내용은 docs/guides/anti-detect.md 참조.

기능 개요

• Hook: create_hook / inject_hook (기본적으로 탐색 간 persist) / get_hook_data / remove_hook (페이지 store 정리 포함) / hook_function …

• 디버깅: 스크립트 소스, 중단점, XHR break, 스텝, callframe evaluate (hook_function 등은 CDP safeEvaluateIife 사용)

• 브라우저: 탐색, snapshot+uid 클릭/양식 작성, fill_form, 네트워크/콘솔, 세션 상태

• 역공학: 수집, 난독화 해제, 암호화 탐지, Wasm, 재구축, 증거 내보내기

• 관찰: performance_* (Insight 포함), take_heapsnapshot, 경량 page_vitals_audit — 주로 full; performance_start_trace의 reload 기본값 false

• 수집 세션 유지: 대상 URL에 이미 있을 때 collect_code / collect_wasm 기본적으로 goto 안 함; 명시적 forceNavigate=true로만 새로고침; MCP 선택 페이지에서 UA를 강제 변경 안 함

• DOM / session: query_dom, localStorage 접근 등은 CDP 우선, puppeteer sourceURL 누출 감소

안정성 참고 사항 (역공학 절차)

1. 먼저 list_pages + select_page: 페이지가 선택되지 않으면 collector가 직접 오류 반환, 은밀히 기본 9222에 다시 연결 안 함.

2. collect_code는 한 번만 수집: 이전 버전의 returnMode=full 중복 collect 문제 수정; 대형 사이트는 returnMode=summary 우선.

3. inject_hook 기본 persist: 탐색 후에도 hook 유지; JSON.stringify 등 전역을 hook하면 후속 페이지 내 JSON 직렬화에 간섭 가능 — 신중히 사용하거나 즉시 remove_hook / 새로고침.

4. restore_session_state 기본적으로 탐색 안 함: 이동이 필요하면 navigateToSavedUrl=true 전달.

5. attach_browser: 현재 LAUNCH 세션인 경우, shutdown 시 자체 실행 브라우저를 종료한 후 연결 변경 (응답에 previousLaunchClosed 포함).

6. --autoConnect는 9222–9225만 스캔: 다른 포트는 --remoteDebuggingPort 사용.

개발

npm install
npm run build
npm start -- --remoteDebuggingPort 9333 --toolProfile slim

부하 테스트:

# LAUNCH + ATTACH 主流程
node scripts/stress-reverse-flow.mjs

# 扫描修复项回归（profile / safeEval / getActivePage / hook persist）
node scripts/stress-fix-regression.mjs

요구사항: Node ^20.19 || ^22.12 || >=23

License

Apache-2.0. chrome-devtools-mcp 및 js-reverse-strong-mcp에서 발전, NOTICE 참조.