jjx-js-reverse-mcp

English README

Единый MCP для обратного инжиниринга JavaScript: полное Hook / точки останова / отладка скриптов + цепочка операций с браузером + CDP антидетекция.

Один процесс подключается только к одному браузеру, решая проблему одновременного использования js-reverse-mcp и chrome-devtools-mcp, приводящего к открытию двух окон.

Режим определяется параметрами запуска, а не подсказками в диалоге.
Подсказки не могут заставить MCP «автоматически распознать» ATTACH / LAUNCH; для смены режима измените mcp.json и перезагрузите, или зарегистрируйте две записи 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 соответствующего сервера.

Пути изменяйте под свою систему: путь_к_вашему_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 → вручную открыть целевой сайт → Reload MCP (если не загрузился) → в диалоге потребовать «запретить 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 / профиль занят».

• Не конфликтуйте с экземпляром bat, использующим тот же профиль; при конфликте закройте лишние браузеры или вернитесь к ATTACH.

Сценарий 4 — Два набора (ATTACH + LAUNCH, выбор в диалоге)

Чтобы не менять конфигурацию каждый раз, зарегистрируйте два сервера и в 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 (чистая отладка)

Добавьте в конец args для ATTACH или LAUNCH:

"--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 (маскировка User-Agent Chrome 131 / Canvas / WebGL / Audio и т.д.) — устарело и может конфликтовать с реальным ядром

Инструменты: enable_cdp_guard / inject_stealth (аналог базового guard) / stealth_status
Ручной User-Agent: 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, пошаговое выполнение, evaluate в callframe (hook_function и др. через CDP safeEvaluateIife)

• Браузер: навигация, снимок+uid клик/заполнение форм, fill_form, сеть/консоль, состояние сессии

• Реверс: сбор, деобфускация, обнаружение шифрования, Wasm, восстановление, экспорт доказательств

• Наблюдение: performance_* (включая Insight), take_heapsnapshot, легкий page_vitals_audit — в основном в full; reload для performance_start_trace по умолчанию false

• Сбор с сохранением сессии: при нахождении на целевом URL collect_code / collect_wasm по умолчанию не делают goto; обновление только при явном forceNavigate=true; на выбранной странице MCP не будет принудительно менять User-Agent

• DOM / сессия: query_dom, чтение/запись localStorage и т.д. приоритетно через CDP, уменьшая утечку sourceURL от Puppeteer

Важные замечания по стабильности (процесс реверса)

1. Сначала list_pages + select_page: если страница не выбрана, коллектор сразу выдаст ошибку, не будет скрытно подключаться к 9222 по умолчанию.

2. collect_code собирает только один раз: исправлена ошибка двойного collect в старой версии с returnMode=full; для больших сайтов предпочтительнее returnMode=summary.

3. inject_hook persist по умолчанию: хук остается после навигации; если вы заフックнули JSON.stringify и другие глобальные функции, это может помешать сериализации 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.