jjx-js-reverse-mcp

English README

统一的 JavaScript 逆向 MCP：全量 Hook / 断点 / 脚本调试 + 浏览器操作链路 + CDP 反检测。

一个进程只连接一个浏览器，解决同时挂 js-reverse-mcp 与 chrome-devtools-mcp 导致开两个窗口的问题。

模式由启动参数决定，不是由对话提示词决定。
提示词无法让 MCP「自动识别」ATTACH / LAUNCH；要换模式请改 mcp.json 后 Reload，或注册两套 MCP 条目后选用。

快速选型

你的场景	推荐模式	关键参数
已用 bat / 手动开浏览器并登录，要保登录态	ATTACH	--remoteDebuggingPort 9333（或你的端口）
从零自动化、可重登、不在乎黄条	LAUNCH	--executablePath + 建议 --isolated
日常逆向、减少 Agent 工具噪声	任意模式 +	--toolProfile slim（含 AI 反混淆/理解，不含 heap/trace）
只做侦察（读脚本/网络，禁导航关页）	任意模式 +	--toolProfile observe
专注 Hook / 断点	任意模式 +	--toolProfile hook
需要性能 trace / 堆快照 / 深层 Wasm decompile	任意模式 +	--toolProfile full（默认）
纯调试、关闭 CDP leak guard	任意模式 +	--no-stealth

---

双模式浏览器生命周期

模式	何时使用	CLI（互斥）	退出时
ATTACH	浏览器已带 --remote-debugging-port 打开，并已访问目标站	--browserUrl / --remoteDebuggingPort / --wsEndpoint / --autoConnect	只 disconnect，不杀用户浏览器
LAUNCH	需要 MCP 自己启动 Chrome/CloakBrowser	--executablePath / --channel	关闭 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

Profile	大约用途	说明
full	全能力	默认；含 close_page、performance trace、heapsnapshot、深层 Wasm
slim	日常逆向	推荐；含 deobfuscate_code / understand_code / analyze_wasm_module；不含 close_page（防误关登录页）、不含 heap/trace
observe	只读侦察	不含 navigate_page / new_page / close_page / 点击填表
hook	Hook + 调试	聚焦注入与断点

场景 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。

---

提示词与配置的关系

你想做的事	正确做法
接管 bat 已开浏览器	mcp.json 用 ATTACH + 端口一致；提示词写「禁止 launch / new_page」
MCP 自己开浏览器	mcp.json 改成 LAUNCH 并 Reload（或用 jjx-launch 条目）
只改提示词切换模式	无效——服务端不读聊天内容

本地可参考话术模版：

• 你的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。