jjx-js-reverse-mcp

README en inglés

Entorno unificado de reverse engineering JavaScript para MCP: Hooks completos / puntos de interrupción / depuración de scripts + cadena de operaciones del navegador + anti-detección CDP.

Un proceso se conecta solo a un navegador, resolviendo el problema de tener que abrir dos ventanas al ejecutar simultáneamente js-reverse-mcp y chrome-devtools-mcp.

El modo se determina por los parámetros de inicio, no por el prompt de la conversación.
El prompt no puede hacer que MCP «reconozca automáticamente» ATTACH / LAUNCH; para cambiar de modo, modifica mcp.json y recarga, o registra dos entradas MCP y elige una.

Selección rápida

Ciclo de vida del navegador en modo dual

• Los parámetros de ATTACH y LAUNCH son excluyentes (no se puede escribir --remoteDebuggingPort y --executablePath al mismo tiempo).

• Si ATTACH falla, no se abrirá un nuevo navegador a escondidas (evitando el «creo que tomé el control, pero en realidad inicié otro»).

• En tiempo de ejecución se puede usar attach_browser para tomar el control dinámicamente; no existe una herramienta simétrica de «launch dinámico» — para auto-iniciar realmente debes usar el parámetro de inicio LAUNCH.

Herramientas: get_browser_mode / attach_browser / check_browser_health

ATTACH: Ejemplo de 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: Ejemplo de CLI

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

mcp.json de Cursor: copia según el escenario

La ruta de configuración global suele ser: %USERPROFILE%\.cursor\mcp.json
Después de modificarlo, asegúrate de: Settings → Tools & MCP → Reload del servidor correspondiente.

Ajusta las rutas según tu máquina: tu-ruta-jjx-js-reverse-mcp, tu-ruta-chrome.exe.

Escenario 1 — ATTACH para reverse engineering diario (recomendado)

Adecuado para: mantener sesión iniciada, abrir pocas ventanas nuevas, combinado con 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"
      ]
    }
  }
}

Flujo: primero abre el bat → abre manualmente el sitio objetivo → Recarga MCP (si no está cargado) → en la conversación pide «prohibir new_page / prohibir launch, primero list_pages».

Escenario 2 — ATTACH clásico 9222

Cuando el navegador se inicia con --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"
      ]
    }
  }
}

Escenario 3 — LAUNCH auto-inicio de Cloak (automatización / reinicio de sesión)

Adecuado para: no necesitas sesión ya iniciada; aceptas la posible barra amarilla «Chrome está siendo controlado por software de pruebas automatizadas».

{
  "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: perfil temporal, reduce «browser already running / perfil ocupado».

• No compitas por el mismo directorio con una instancia bat que ya esté usando el mismo perfil; si hay conflicto, cierra los navegadores sobrantes o vuelve a ATTACH.

Escenario 4 — Dos conjuntos coexistiendo (ATTACH + LAUNCH, elegir durante la conversación)

Para no tener que modificar la configuración repetidamente, registra dos servidores y habilita/selecciona el correspondiente en 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"
      ]
    }
  }
}

Nota: si ambos están habilitados, el agente puede llamar al «incorrecto»; especifica en el prompt jjx-attach o jjx-launch, o habilita solo uno.

Escenario 5 — Conjunto de herramientas más pequeño (observe / hook)

Solo cambia --toolProfile, los parámetros de modo permanecen igual.

Reconocimiento (menos herramientas, decisiones más rápidas):

--toolProfile observe

Principalmente hooks / puntos de interrupción:

--toolProfile hook

Completo (incluye rendimiento / heapsnapshot / AI pesada / Wasm profundo):

--toolProfile full

Escenario 6 — Desactivar Stealth (depuración pura)

Añade al final de args en ATTACH o LAUNCH:

"--no-stealth"

Para sitios con fuerte control de riesgos, generalmente se mantiene el Stealth por defecto (no añadas esta opción).

Escenario 7 — ATTACH detección automática de puertos

Escanea los puertos 9222–9225 del equipo; si no encuentra, da error y no lanza:

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

Si el bat de escritorio usa fijo 9333, que no está en el rango 9222–9225, usa el puerto explícito del escenario 1, no confíes en --autoConnect.

Relación entre prompts y configuración

Plantillas de frases de referencia locales:

• tu-ruta-plantilla-prompt-modo-attach

• tu-ruta-plantilla-prompt-modo-launch

Más información: docs/guides/browser-modes.md, docs/guides/anti-detect.md

Anti-detección CDP (resumido)

Por defecto está habilitada la protección básica contra fugas CDP (se puede desactivar con --no-stealth):

1. CdpLeakGuard: limpia los globales cdc_* / selenium, repara navigator.webdriver, minimiza chrome.*, desinfecta stack de errores; preinyección en nuevos documentos + reinyección después de la navegación

2. evaluate_script / ruta de inyección: prioriza CDP Runtime.evaluate, reduce la fuga de __puppeteer_evaluation_script__

3. Eliminado: StealthScripts2025 (suplantación de huellas dactilares como Chrome 131 UA / Canvas / WebGL / Audio) — obsoleto y propenso a conflictos con el kernel real

Herramientas: enable_cdp_guard / inject_stealth (equivalente al guard básico) / stealth_status
UA manual: set_user_agent (no modifica Client Hints)

Para sitios con fuerte control de riesgos, usa huellas dactilares nativas de CloakBrowser + inicio de sesión real con ATTACH. Este MCP no ofrece un paquete stealth completo para «pasar controles fuertes»; las soluciones a nivel de protocolo (como rebrowser-patches) requieren integración separada, no incluidas.

Ver docs/guides/anti-detect.md.

Resumen de capacidades

• Hooks: create_hook / inject_hook (por defecto persistente entre navegaciones) / get_hook_data / remove_hook (también limpia el store de la página) / hook_function …

• Depuración: código fuente de scripts, puntos de interrupción, XHR break, paso a paso, evaluación en callframe (hook_function etc. usa CDP safeEvaluateIife)

• Navegador: navegación, snapshot+uid clic/relleno, fill_form, red/consola, estado de sesión

• Reverse engineering: recolección, desofuscación, detección de encriptación, Wasm, reconstrucción, exportación de evidencia

• Observación: performance_* (incluye Insight), take_heapsnapshot, page_vitals_audit ligero — la mayoría en full; reload de performance_start_trace por defecto false

• Recolección y preservación de sesión: cuando ya se está en la URL objetivo, collect_code / collect_wasm por defecto no hacen goto; solo actualiza si forceNavigate=true explícito; en la página seleccionada por MCP no se fuerza el UA

• DOM / session: query_dom, acceso a localStorage etc. prioriza CDP, reduciendo fugas de sourceURL de puppeteer

Notas de estabilidad (flujo de reverse engineering)

1. Primero list_pages + select_page: si no hay página seleccionada, el collector dará error directamente, no se conectará sigilosamente al 9222 por defecto.

2. collect_code solo recolecta una vez: solucionado el problema de doble collect con returnMode=full en versiones anteriores; para sitios grandes, prioriza returnMode=summary.

3. inject_hook por defecto persistente: el hook sigue después de la navegación; si se hookean globales como JSON.stringify, puede interferir con la serialización JSON en páginas posteriores — úsalo con cuidado o elimina el hook / actualiza a tiempo.

4. restore_session_state por defecto no navega: si necesitas redirigir, pasa navigateToSavedUrl=true.

5. attach_browser: si la sesión actual es LAUNCH, al cerrar se cerrará el navegador auto-iniciado y luego se cambiará la conexión (en la respuesta aparece previousLaunchClosed).

6. --autoConnect solo escanea 9222–9225: para otros puertos, usa --remoteDebuggingPort.

Desarrollo

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

Pruebas de estrés:

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

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

Requisitos: Node ^20.19 || ^22.12 || >=23

Licencia

Apache-2.0. Basado en chrome-devtools-mcp y js-reverse-strong-mcp, ver NOTICE.