zhizhuodemao/js-reverse-mcp

무엇인가요

js‑reverse‑mcp 는 Node.js 기반의 MCP (Model‑Controlled‑Program) 서버로, 대규모 언어 모델 에이전트(Claude Code, Cursor, GitHub Copilot 등)가 실제 Chrome 브라우저를 디버깅 보조 도구로 사용할 수 있게 해줍니다. DevTools 데이터(스크립트, 브레이크포인트, 네트워크 트래픽, WebSocket 메시지, 브라우저 스토리지, 로컬 파일)를 AI 친화적인 간결한 원시 데이터로 재구성하여, 에이전트가 페이지에서 JavaScript의 동작을 단계적으로 추론할 수 있도록 합니다.

핵심 아이디어

완전한 Chrome DevTools UI를 모델에 노출하는 것이 목적이 아닙니다. 대신 서버는 list_scripts, set_breakpoint_on_text, evaluate_script, list_network_requests와 같은 명확하게 정의된 도구를 제공하며, 짧은 구조화된 출력을 반환하거나 대용량 블롭을 파일에 씁니다. LLM은 다음 작업을 결정하고, 내보낸 파일을 읽은 후, 원시 소스나 바이너리 데이터로 인해 과부하되지 않고 분석을 계속할 수 있습니다.

주요 기능

카테고리	도구(예시)	기능
페이지 및 탐색	new_page, navigate_page, select_page, click_element, take_screenshot	페이지 열기, 이동, 요소 상호작용, 스크린샷 캡처
스크립트 분석	list_scripts, get_script_source, save_script_source, search_in_sources	로드된 모든 JS 열거, 소스 가져오기(최소화된/WASM 포함), 텍스트 검색, 디스크에 내보내기
브레이크포인트 및 실행	set_breakpoint_on_text, break_on_xhr, list_breakpoints, get_paused_info, step, evaluate_script	텍스트 또는 URL 패턴으로 브레이크포인트 설정, 실행 일시정지, 콜프레임 확인, 단계 실행, 페이지 또는 일시정지된 프레임에서 임의의 JS 실행
네트워크 및 WebSocket	list_network_requests, clear_network_requests, get_request_initiator, get_websocket_messages	HTTP/XHR/fetch 요청 캡처, 헤더/본문 내보내기, 요청을 유도한 JS 콜스택 추적, WS 트래픽 검사
브라우저 상태	clear_site_data	현재 사이트의 쿠키, 스토리지, 캐시 초기화(안티봇 흐름 재실행에 유용)
유틸리티	list_console_messages	추가적인 컨텍스트를 제공하기 위해 콘솔 메시지 가져오기

탐지 회피 / 스텔스 기능

• 프로토콜 수준 스텔스 – Patchright의 커스텀 포크가 자동화를 드러내는 일반적인 CDP 플래그를 비활성화하고, evaluate 호출을 격리된 월드에서 실행합니다.
• 옵션 바이너리 레이어 – --cloak 옵션을 사용하면 Chrome이 CloakBrowser로 교체되며, navigator.webdriver, canvas, WebGL, 오디오, GPU, 폰트, 화면 크기, WebRTC, TLS 세부 정보 등의 지문을 가리킵니다.
• 프로필 관리 – 지속적 프로필은 로그인 상태를 유지; --isolated는 각 세션마다 새 임시 프로필을 시작; --cloak는 별도의 프로필 디렉터리를 사용.
• 사운드 없는 탐색 – CDP 네트워크/디버거 도메인은 도구가 명시적으로 필요할 때까지 비활성화되어 조기 탐지를 줄입니다.

실행 방법

• 제로 설치 – AI 어시스턴트의 MCP 설정에 서버를 추가:

{ "mcpServers": { "js-reverse": { "command": "npx", "args": ["js-reverse-mcp"] } } }

• 로컬 설치 – git clone … && npm install && npm run build 후 빌드된 index.js를 MCP에 지정.
• 옵션 플래그 –
  • --cloak – CloakBrowser 활성화 (처음 실행 시 약 200 MiB 바이너리 다운로드).
  • --isolated – 각 세션마다 새 user-data-dir로 시작.
  • --browserUrl <CDP‑endpoint> – 이미 실행 중인 Chrome(또는 AdsPower 같은 지문 브라우저)에 연결.
  • --allowedRoots <path> – 에이전트가 읽기/쓰기 가능한 호스트 디렉터리 제한.

AI 에이전트의 일반적인 워크플로우

1. new_page → 타겟 URL 열기.
2. list_scripts → 관심 있는 함수 찾기 (예: encrypt 검색).
3. set_breakpoint_on_text → 함수 시작 지점에 브레이크포인트 설정.
4. 페이지 액션 트리거; 일시정지되면 get_paused_info와 evaluate_script로 인수 확인.
5. list_network_requests … outputFile=…로 관련 네트워크 요청 내보내기.
6. 필요 시 clear_site_data 실행 후 안티봇 흐름 재실행.

안전성 주의사항

• --allowedRoots가 설정되지 않은 경우 서버는 호스트의 모든 파일을 읽고 쓸 수 있으므로, 제어된 환경에서 실행해야 합니다.
• 연결된 AI 모델에 전체 브라우저 상태(쿠키, localStorage, 콘솔 출력)가 노출되므로, 민감한 데이터를 포함하는 페이지에서는 사용하지 마세요.

라이선스

Apache‑2.0

---

요약하면: js‑reverse‑mcp 는 Chrome DevTools 데이터를 LLM 에이전트를 위한 간결한 도구 상자로 변환하는 "AI 우선" 디버깅 브리지이며, 스크래핑 방지 사이트를 탐색하기 위한 내장 스텔스 기능을 갖추고 있습니다. AI 지원 JavaScript 리버스 엔지니어링과 자동 웹 분석을 목적으로 하는 진정한 소프트웨어 프로젝트입니다.