Camoufox Versatile

中文 | English

基于反指纹浏览器（Camoufox）的 MCP Server，支持 通用 captcha 挑战自动通过 + JSVMP 签名还原管线。

Fork 自 camoufox-reverse-mcp，新增：

• 内置 captcha 通用检测 + 自动通过（基于 camoufox_captcha）
• 全新 JSVMP 离线复现管线：WASM 反汇编 / Worker 源码捕获 / WS 流量抓取 / 离线重放 + 自动 diff

---

快速开始

安装

方式一：AI 对话框直接安装（推荐）

在你常用的 AI 编码工具（Cursor / Claude Code / Windsurf / Coze 等）的对话框中输入：

帮我安装下这个 MCP 工具：camoufox-versatile-mcp
项目地址：https://github.com/usernamexiaozhang/camoufox-versatile-mcp

AI 会自动完成以下全部步骤：

1. git clone 或 pip install 克隆安装项目
2. 读取 pyproject.toml 确认依赖
3. 配置 Cursor 的 mcpServers（自动写入 settings.json）
4. 启动 MCP Server 并验证连接

为什么推荐这种方式？ AI 了解你的操作系统、Python 环境、Cursor 版本，它可以处理 Windows/macOS/Linux 的路径差异，自动选择合适的安装命令，并在安装完成后告诉你是否成功。

方式二：手动安装

git clone https://github.com/usernamexiaozhang/camoufox-versatile-mcp
cd camoufox-versatile-mcp
pip install -e .

客户端配置（Cursor）

{
  "mcpServers": {
    "camoufox-versatile": {
      "command": "python",
      "args": ["-m", "camoufox_versatile_mcp"]
    }
  }
}

启动参数

参数	说明
--headless	无头模式运行
--proxy	代理服务器，如 --proxy http://127.0.0.1:7890
--geoip	启用 GeoIP 推理（根据代理 IP 自动设置地理位置）
--humanize	启用拟人化鼠标移动
--os	OS 指纹：auto / windows / macos / linux
--locale	浏览器语言，如 zh-CN

---

工具一览（共 45 个）

浏览器控制（11 个）

工具	说明
launch_browser	启动 Camoufox 反指纹浏览器（含 i_know_what_im_doing + disable_coop + forceScopeAccess 默认三件套）
close_browser	关闭浏览器
navigate	导航到指定 URL（支持 auto_solve_challenge 参数）
reload	刷新页面
take_screenshot	截图
take_snapshot	获取页面无障碍树
click / type_text	点击元素 / 输入文本
wait_for	等待元素出现或 URL 匹配
get_page_info	获取当前页面信息
scroll	滚动页面
go_back / go_forward	前进 / 后退

通用 Captcha 挑战自动通过（2 个）⭐

工具	说明
detect_captcha	检测当前页面是否有 captcha 挑战（不点击）
auto_solve_captcha	自动检测 + 通过 captcha 挑战（captcha_type / challenge_type）

支持 cloudflare 的 Turnstile 和 Interstitial 两种模式，captcha_type 参数预留扩展位（hcaptcha、recaptcha 等）。

注意：非标准 Cloudflare 挑战（如自定义 WAF checkbox）需要额外定制化处理。

JS 执行与调试（1 个）

工具	说明
evaluate_js	在页面上下文执行任意 JS 表达式

脚本分析（2 个）

工具	说明
scripts(action)	脚本管理：list / get / save
search_code	搜索关键词

Hook 与追踪（4 个）

工具	说明
hook_function	Hook 或追踪函数
inject_hook_preset	注入预置 Hook（xhr / fetch / crypto / websocket / debugger_bypass / cookie / runtime_probe）
remove_hooks	移除所有 Hook
inject_hook	注入自定义 JS Hook

网络分析（5 个）

工具	说明
network_capture(action)	网络捕获控制
list_network_requests	列出已捕获的请求
get_network_request	获取请求完整详情
get_request_initiator	获取请求发起的 JS 调用栈
intercept_request	拦截请求

JSVMP 逆向分析（5 个）

工具	说明
hook_jsvmp_interpreter	JSVMP 运行时探针
instrumentation(action)	源码级插桩
compare_env	浏览器环境指纹收集
detect_vmp	检测页面使用了哪种 VMP 保护（obfuscated / string_eval / vm_dispatch / wasm）
trace_vmp_for_sign	签名安全 Tap：追踪 VMP 读取了哪些 fingerprint 属性

Cookie 与存储（4 个）

工具	说明
cookies(action)	Cookie 管理
get_storage	获取 localStorage / sessionStorage
export_state / import_state	导出 / 导入浏览器状态

验证（1 个）

工具	说明
verify_fingerprint	验证指纹是否满足目标网站要求

环境感知（1 个）

工具	说明
get_env_info	获取当前浏览器环境信息（OS、UA、屏幕、语言等）

JSVMP 离线重放管线（8 个）🆕

工具	说明
get_tap_log	读取 trace_vmp_for_sign 记录的 Tap 日志
disassemble_wasm	将 WASM 字节码反汇编为 WAT + 导入/导出函数列表 + 入口函数猜测
capture_worker_js	劫持 new Worker()，捕获 blob: URL 源码（JSVMP 字节码的直接来源）
capture_ws_payloads	劫持 new WebSocket()，记录所有 send/recv 流量
auto_suggest_missing_props	根据失败日志 + trace_log 推荐缺失的 fingerprint prop
replay_vmp_offline	在 Node 沙箱中离线重放 VMP 代码（增强版：支持 supplied_env / expected_sign / auto_diff）
trace_vmp_for_sign	签名安全 Tap：追踪 VMP 读取了哪些 fingerprint 属性

---

JS 引擎 Trace + HTTP 包 Trace（3 个）🆕

|| 工具 | 说明 | ||------|------| || js_engine_trace | JS 引擎 tracing（三层独立方案，零编译，零 patch） | || http_packet_trace | HTTP 包 trace（捕获完整请求/响应 + 发起者 JS 调用栈） | || trace_js_and_http | 组合模式：同时开启 JS trace + HTTP trace，持续 N 秒后自动停止 |

基于 RuyiTrace 的 HttpPacketTrace 思路，用 Playwright 路由拦截实现，无需 RuyiTrace 的 C++ 插桩。

Captcha 挑战自动通过使用示例

方式一：导航时自动过挑战（推荐）

navigate(
    url="https://target-site-with-captcha.com/",
    auto_solve_challenge=True,        # 开启自动过挑战
    challenge_type="auto",             # auto 检测 turnstile/interstitial
    challenge_ready_delay=5.0,         # 等待 iframe 加载
    expected_content_selector="#main"  # 成功后等待主内容出现
)

方式二：手动调用工具

# 1. 先检测
result = detect_captcha()
# 返回: {"url": "...", "detected": {"turnstile": True, "interstitial": False}, "challenge_present": True}

# 2. 再解决
result = auto_solve_captcha(
    captcha_type="cloudflare",   # 当前支持 cloudflare
    challenge_type="auto",       # auto / interstitial / turnstile
    ready_delay=5.0,
    solve_attempts=3,
    verify=True
)
# 返回: {"solved": True, "verified": True, "challenge_type_used": "turnstile", ...}

---

JSVMP 离线重放管线（典型流程）

┌─────────────────────────────────────────────────────────┐
│  ① 浏览器端：trace_vmp_for_sign()                       │
│     → 追踪 VMP 读取了哪些 fingerprint 属性               │
│     → 输出 prop → value 列表                            │
│                                                         │
│  ② WASM 反汇编：disassemble_wasm()                       │
│     → 传入 b64/hex/wasm-url                            │
│     → 输出 WAT + imports/exports + 入口函数猜测          │
│                                                         │
│  ③ Worker 源码捕获：capture_worker_js()                  │
│     → 劫持 new Worker(blob:...)                        │
│     → 获取 VMP 字节码源码                               │
│                                                         │
│  ④ WS 流量抓取：capture_ws_payloads()                   │
│     → 劫持 new WebSocket()                              │
│     → 记录 VMP 获取字节码的请求/响应                    │
│                                                         │
│  ⑤ 离线重放：replay_vmp_offline()                       │
│     → Node 沙箱执行 VMP 代码                             │
│     → supplied_env 注入缺失的 fingerprint                │
│     → auto_diff 对比签名是否匹配                         │
│                                                         │
│  ⑥ 缺失属性建议：auto_suggest_missing_props()           │
│     → 结合 trace_log + 失败日志推荐 props                │
│     → 输出可直接复制到 supplied_env                      │
└─────────────────────────────────────────────────────────┘

完整示例

# Step 1: 在浏览器中追踪 VMP 读取的属性
props = trace_vmp_for_sign(
    trigger_js="sign({order_id: 12345})",
    wait_ms=500,
)

# Step 2: 反汇编 WASM（如果 VMP 使用了 WebAssembly）
wasm_info = disassemble_wasm(wasm_b64, source_kind="base64", generate_wat=True)
print(wasm_info["exports"])   # e.g. ["enc", "dec"]
print(wasm_info["entry_candidates"])

# Step 3: 离线重放（第一次可能 diff 不匹配）
result = replay_vmp_offline(
    vmp_code=vmp_code,
    entry="sign",
    input={"order_id": 12345},
    expected_sign="target_sign_value",
    auto_diff=True,
)
if not result["diff"]["match"]:
    # Step 4: 获取建议的缺失 prop
    suggestions = auto_suggest_missing_props(
        failed_replay_error=result["diff"]["replayed_preview"],
        supplied_env={},
    )
    print(suggestions["suggestions"])

    # Step 5: 重新重放（带上建议的 env）
    result = replay_vmp_offline(
        vmp_code=vmp_code,
        entry="sign",
        input={"order_id": 12345},
        expected_sign="target_sign_value",
        auto_diff=True,
        supplied_env={"navigator": {"userAgent": "..."}},
    )
    assert result["diff"]["match"]

---

JS 引擎 Trace + HTTP 包 Trace 使用示例

方式一：组合模式（最简单）

# 同时开启 JS trace + HTTP trace，持续 5 秒后自动停止
result = trace_js_and_http(
    duration=5,
    trace_js=True,
    trace_http=True,
    trace_values=True,           # 捕获函数参数值
    trace_dom_events=True,       # 捕获 DOM 事件
    capture_http_body=False,    # 不捕获响应体（省空间）
)
# result["js_trace_summary"]   → JS 函数调用热图
# result["http_trace"]         → HTTP 请求摘要

方式二：分步控制

# Layer 1: 安装 JS 源码级 tracer（无需特殊浏览器）
js_engine_trace(action="install_js", max_depth=20, trace_values=True)

# 导航到目标页面，触发 JS
navigate("https://target-site.com/api/sign")

# 读取 trace 结果
result = js_engine_trace(action="read", session_id="abc12345")
# → hot_functions, depth_histogram, sample_events

# Layer 2: HTTP 包 trace
http_packet_trace(action="start", capture_body=True)

# 触发目标请求
await page.evaluate("fetch('/api/sign', {method:'POST', body: JSON.stringify({a:1})})")

# 读取 HTTP trace
http_result = http_packet_trace(action="read")
# → api_requests, javascript_requests, slow_requests

方式三：CDP DevTools 原生 tracer（需要 remote_debugging_port）

# 启动带 remote debugging 的浏览器
launch_browser(remote_debugging_port=9222)

# 启动 CDP 原生 tracer（Firefox 内置的 JS ExecutionTracer）
js_engine_trace(
    action="start_cdp",
    trace_values=True,
    trace_dom_events=True,
    trace_dom_mutations=False,
    max_records=50000,
    cdp_port=9222,
)

---

技术架构

┌─────────────────────────────────────────────────┐
│           AI 编码助手 (Cursor / Claude)          │
│                    ↕ MCP (stdio)                  │
├─────────────────────────────────────────────────┤
│           camoufox-versatile-mcp                 │
│  ┌──────────┬──────────┬──────────┬──────────┐  │
│  │Navigation│ Script   │Debugging │ Hooking  │  │
│  ├──────────┼──────────┼──────────┼──────────┤  │
│  │ Network  │ JSVMP    │  Cookie  │  Verify  │  │
│  ├──────────┼──────────┼──────────┼──────────┤  │
│  │ ★ Captcha Auto-Solve (cloudflare)           │  │
│  │ ★ JSVMP Pipeline (WASM/Worker/WS/Replay)    │  │
│  └──────────┴──────────┴──────────┴──────────┘  │
│                    ↕ Playwright API              │
├─────────────────────────────────────────────────┤
│      Camoufox (反指纹 Firefox, Juggler 协议)     │
└─────────────────────────────────────────────────┘

---

许可证

MIT