jjx-js-reverse-mcp

English README

Unified JavaScript Reverse MCP: Full Hook / Breakpoint / Script Debugging + Browser Operation Chain + CDP Anti-Detection.

One process connects to one browser, solving the issue of simultaneously running js-reverse-mcp and chrome-devtools-mcp causing two windows to open.

The mode is determined by startup parameters, not by conversation prompts.
Prompts cannot make the MCP "auto-recognize" ATTACH / LAUNCH; to switch modes, modify mcp.json and Reload, or register two MCP entries and select one.

Quick Selection Guide

Dual Mode Browser Lifecycle

• ATTACH and LAUNCH parameters are mutually exclusive (cannot write both --remoteDebuggingPort and --executablePath).

• If ATTACH fails, it will not secretly open a new browser (avoids the "thinks it took over, but actually started another one" issue).

• At runtime, you can call attach_browser for dynamic takeover; there is no symmetrical "dynamic launch" tool — to truly self-start, you must use LAUNCH startup parameters.

Tools: get_browser_mode / attach_browser / check_browser_health

ATTACH: CLI Example

# 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 Example

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

Cursor mcp.json: Copy by Scenario

The global configuration path is typically: %USERPROFILE%\.cursor\mcp.json
After modifying, be sure to: Settings → Tools & MCP → Reload the corresponding server.

Please modify the paths according to your local machine: your-jjx-js-reverse-mcp-path, your-chrome.exe-path.

Scenario 1 — ATTACH Daily Reversing (Recommended)

Suitable for: keeping login session, fewer new windows, coordinating with 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"
      ]
    }
  }
}

Process: Open the bat first → Manually open the target site → Reload MCP (if not loaded) → In conversation, request "Disable new_page / disable launch, first list_pages".

Scenario 2 — ATTACH Classic 9222

When the browser is started with --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"
      ]
    }
  }
}

Scenario 3 — LAUNCH Self-Start Cloak (Automation / Allows Re-login)

Suitable for: no existing login session needed; accepting the possible yellow bar "Chrome is being controlled by automated test software".

{
  "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: Temporary profile, reduces "browser already running / profile in use" issues.

• Do not compete for the same profile directory as a running bat instance; if there's a conflict, close the extra browser first, or switch back to ATTACH.

Scenario 4 — Two Sets Coexist (ATTACH + LAUNCH, Selectable During Conversation)

To avoid repeatedly modifying the configuration, register two servers and enable/select the corresponding one in 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"
      ]
    }
  }
}

Note: When both are enabled, the Agent might call the "wrong" one; specify jjx-attach or jjx-launch in the prompt, or only enable one of them.

Scenario 5 — Smaller Tool Set (observe / hook)

Only change --toolProfile, keep the mode parameters unchanged.

Reconnaissance (fewer tools, faster decision-making):

--toolProfile observe

Focus on Hooks / Breakpoints:

--toolProfile hook

Full (includes performance / heapsnapshot / heavy AI / deep Wasm):

--toolProfile full

Scenario 6 — Disable Stealth (Pure Debugging)

Append to the end of the args in ATTACH or LAUNCH:

"--no-stealth"

For high anti-bot sites, keep Stealth enabled by default (do not add this flag).

Scenario 7 — ATTACH Auto-Detect Port

Scans local ports 9222–9225; if none found, returns an error and does not launch:

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

If the desktop bat is fixed to 9333, which is outside the 9222–9225 range, use the explicit port from Scenario 1, and do not rely on --autoConnect.

Relationship Between Prompts and Configuration

Local reference prompt templates:

• your-ATTACH-mode-prompt-template-path

• your-LAUNCH-mode-prompt-template-path

More details: docs/guides/browser-modes.md, docs/guides/anti-detect.md

CDP Anti-Detection (Concise)

Basic CDP leak guard is enabled by default (can be disabled with --no-stealth):

1. CdpLeakGuard: Cleans up cdc_* / selenium globals, patches navigator.webdriver, minimizes chrome.*, sanitizes Error stacks; pre-injects into new documents + re-injects after navigation

2. evaluate_script / Injection Paths: Prioritizes CDP Runtime.evaluate, reduces __puppeteer_evaluation_script__ leaks

3. Removed: StealthScripts2025 (Chrome 131 UA / Canvas / WebGL / Audio fingerprint masking) — outdated and easily conflicts with real kernel

Tools: enable_cdp_guard / inject_stealth (equivalent to basic guard) / stealth_status
Manual UA: set_user_agent (does not modify Client Hints)

For strong anti-bot sites, use CloakBrowser native fingerprint + real login session ATTACH. This MCP does not provide an all-in-one stealth that can "pass strong detection"; protocol-level solutions (e.g., rebrowser-patches) need to be integrated separately and are not built-in.

See docs/guides/anti-detect.md.

Capabilities Overview

• Hooks: create_hook / inject_hook (persists across navigation by default) / get_hook_data / remove_hook (also clears page store) / hook_function …

• Debugging: Script sources, breakpoints, XHR breakpoints, stepping, callframe evaluation (hook_function etc. via CDP safeEvaluateIife)

• Browser: Navigation, snapshot+uid click/form filling, fill_form, network/console, session state

• Reversing: Collection, deobfuscation, encryption detection, Wasm, rebuild, evidence export

• Observation: performance_* (including Insight), take_heapsnapshot, lightweight page_vitals_audit — mostly in full; performance_start_trace has reload defaulting to false

• Collection preserving session: When already on the target URL, collect_code / collect_wasm will not goto by default; only refreshes with explicit forceNavigate=true; will not force UA change on the selected MCP page

• DOM / session: query_dom, accessing localStorage etc. prioritizes CDP, reducing puppeteer sourceURL leaks

Stability Notes (Reversing Flow)

1. First list_pages + select_page: If no page is selected, the collector will directly report an error and will not silently connect to the default 9222.

2. collect_code collects only once: Fixes the double collect issue of the old returnMode=full; for large sites, prefer returnMode=summary.

3. inject_hook persists by default: Hooks remain after navigation; if hooking globals like JSON.stringify, it may interfere with subsequent JSON serialization on the page — use cautiously or remove_hook / refresh in time.

4. restore_session_state does not navigate by default: Use navigateToSavedUrl=true if navigation is needed.

5. attach_browser: If currently in a LAUNCH session, shutdown will close the self-started browser before reconnecting (the response includes previousLaunchClosed).

6. --autoConnect only scans 9222–9225: For other ports, use --remoteDebuggingPort.

Development

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

Stress testing:

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

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

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

License

Apache-2.0. Derived from chrome-devtools-mcp and js-reverse-strong-mcp, see NOTICE.