# jjx-js-reverse-mcp

[English README](README.en.md)

统一的 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 示例

```bash
# 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 示例

```bash
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`。

```json
{
  "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` 启动时：

```json
{
  "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 正受到自动测试软件的控制」黄条。

```json
{
  "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 里启用/选用对应那一个：

```json
{
  "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`，模式参数不变。

**侦察（更少工具、决策更快）：**

```text
--toolProfile observe
```

**Hook / 断点为主：**

```text
--toolProfile hook
```

**全量（含 performance / heapsnapshot / 重型 AI / 深层 Wasm）：**

```text
--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` 末尾追加：

```text
"--no-stealth"
```

强风控站点逆向一般保持默认 Stealth（勿加该项）。

### 场景 7 — ATTACH 自动探测端口

探测本机 `9222–9225`；找不到则**报错且不 launch**：

```json
{
  "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/browser-modes.md)、[docs/guides/anti-detect.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](./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`。

---

## 开发

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

压测：

```bash
# 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](https://github.com/ChromeDevTools/chrome-devtools-mcp) 与 [js-reverse-strong-mcp](https://github.com/lwjjike/JSReverser-Strong-MCP) 演进，见 [NOTICE](./NOTICE)。