jjx-js-reverse-mcp

English README

統一的なJavaScriptリバースMCP：フック / ブレークポイント / スクリプトデバッグ + ブラウザ操作チェーン + CDP検出回避。

1プロセスで1つのブラウザにのみ接続し、js-reverse-mcpとchrome-devtools-mcpを同時に接続して2つのウィンドウが開く問題を解決します。

モードは起動パラメータで決定され、会話のプロンプトでは決定されません。
プロンプトでMCPにATTACH / LAUNCHを「自動認識」させることはできません。モードを変更するにはmcp.jsonを編集してReloadするか、2セットの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を先に開く → 手動で対象サイトを開く → MCPをReload（未ロードの場合）→ 会話で「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 / profile 使用中」を軽減。

• 同じプロファイルを占有しているbatインスタンスとディレクトリを奪い合わない；競合したら余分なブラウザを閉じるか、ATTACHに戻す。

シナリオ4 — 2セット併用（ATTACH + LAUNCH、会話時に選択）

設定を何度も変更したくない場合、2つのサーバーを登録し、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

フック / ブレークポイント主体：

--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リークガードが有効（--no-stealthで無効化可能）：

1. CdpLeakGuard：cdc_* / seleniumグローバルをクリア、navigator.webdriverを修正、chrome.*を最小化、Errorスタックをサニタイズ；新しいドキュメントに事前注入 + ナビゲーション後に再注入

2. evaluate_script / 注入パス：CDP Runtime.evaluateを優先、__puppeteer_evaluation_script__の漏洩を低減

3. 削除済み：StealthScripts2025（Chrome 131 UA / Canvas / WebGL / Audioなどのフィンガープリント偽装）——時代遅れで実際のカーネルと競合しやすい

ツール：enable_cdp_guard / inject_stealth（基本ガードと同等）/ stealth_status
手動UA：set_user_agent（Client Hintsは変更しない）

強力なリスク管理にはCloakBrowserネイティブフィンガープリント + 実際のログイン状態ATTACHを使用してください。本MCPは「強力な検出を通過できる」オールインワンステルスを提供しません；プロトコルレベルのソリューション（rebrowser-patchesなど）は個別に統合する必要があり、組み込まれていません。

詳細はdocs/guides/anti-detect.mdを参照。

機能概要

• フック：create_hook / inject_hook（デフォルトでpersist、ナビゲーション間で保持）/ get_hook_data / remove_hook（ついでにページストアをクリア）/ hook_function …

• デバッグ：スクリプトソース、ブレークポイント、XHRブレーク、ステップ実行、コールフレーム評価（hook_functionなどはCDP safeEvaluateIife経由）

• ブラウザ：ナビゲーション、スナップショット+uidクリック/フォーム入力、fill_form、ネットワーク/コンソール、セッション状態

• リバース：収集、難読化解除、暗号化検出、Wasm、リビルド、証拠エクスポート

• 観測：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は1回だけ収集：旧バージョンのreturnMode=fullでの二重collectを修正；大規模サイトでは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を参照。