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 → 手动打开目标站 → 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：临时 profile，减少「browser already running / profile 占用」。

• 不要与已占用同一 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、rebuild、证据导出

• 观测：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 仍在；若 hook 了 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。