Skip to main content
Glama
camoufox-jsreverser-mcp

camoufox-jsreverser-mcp

by wukaka

camoufox-jsreverser-mcp

面向 Firefox 的前端 JavaScript 逆向工程 MCP 服务器,底层走 WebDriver BiDi 与 Firefox Remote Debugging Protocol (RDP)。

对外暴露约 88 个 MCP 工具,覆盖:

  • 页面状态、Frame、导航、截图

  • 脚本:列出 / 取源码 / 跨脚本搜索 / 单脚本检索

  • 调试器:行/列断点与文本断点、暂停 / 恢复 / 步入步过步出、callframe 求值、对象 inspect

  • Hook:函数 hook、trace、采样通道、任意 preload 注入

  • 网络与 WebSocket:请求池、initiator 调用栈、帧捕获、XHR 断点

  • DOM:query / 结构 / 点击 / 输入 / 等待元素

  • Storage 以及会话级 save / load / dump / restore

  • Stealth:firefox-default preset、跨 realm 的 inject_stealth_hook、worker 推送

  • AST 与 LLM:反混淆、摘要、理解、加密规则识别

  • Rebuild + 证据链:bundle 构建、环境差异、证据写入、报告导出

  • Worker、per-context preference(set_javascript_enabled / set_csp_enabled)

为什么是 Camoufox(而不是原版 Firefox)

工具集中大约 80%(调试器 / 脚本 / DOM / 网络 / Hook / AST / LLM)与浏览器二进制无关——它走 WebDriver BiDi 和 Firefox RDP,这两个协议原版 Firefox 150 同样支持。那为什么仍要绑定 Camoufox?因为剩下的 20%——反检测面——需要C++ 层面的二进制补丁,任何 preload 脚本都无法等价实现。

差异分布如下:

能力

实现位置

原版 Firefox

Camoufox

调试器 / 脚本 / DOM / 网络 / Hook / AST / LLM 工具

BiDi + RDP 的 TypeScript

✅ 可用

✅ 可用

inject_stealth_hook 跨 realm 的 Function.prototype.toString 伪装

TypeScript preload

✅ 可用

✅ 可用

navigator.webdriver === false

C++ 二进制补丁

❌ 锁死为 true(getter 不可配置)

✅ 已 patch

navigator.plugins / mimeTypes 真实形状

C++ 注入

❌ 空或过短

✅ 真实

WebGL vendor / renderer 伪装

C++ 覆盖

❌ 泄露真实 GPU 或 "Mozilla"

✅ 伪装

Canvas 2D / AudioContext 像素与采样级噪声

C++ 注入

❌ 指纹稳定可识别

✅ 加噪

字体枚举伪装

C++ 字体表替换

❌ 真实安装字体

✅ 伪装

WebDriver 协议侧信道(RemoteAgent 类、Marionette 残留)

C++ 删除

❌ 可被探测

✅ 清理

Camoufox/<ver> UA 品牌泄漏

字符串问题

n/a

可用 set_user_agent 修改

结论:在原版 Firefox 上,仅 navigator.webdriver === true 这一条,就足以让 CreepJS / sannysoft / 商业反爬评分系统直接判定为机器人,根本走不到我们 preload 那一层。TypeScript 层的 Object.defineProperty(navigator, 'webdriver', ...) 只能影响主 realm,覆盖不到 worker、iframe、特权页;何况 Firefox 150 上 webdriver 属性描述符是锁死的,重定义会抛错。用 Proxy 包 navigator 也会被 navigator === window.navigator.constructor.prototype.constructor 这类比较探测到。

我们的 inject_stealth_hook 已经把 Hook 表面清理干净(Function.toString 伪装、跨 realm 探针、零全局变量——证据见 stealth-evidence/SUMMARY.md stage 6),但它有意止步于 Hook 边界。引擎级信号(navigator.webdriver、Canvas 噪声、GPU 字符串)按设计不在其能力范围内。

Related MCP server: camoufox-reverse-mcp

安装

需要 Node.js 20+。

支持的浏览器组合:Camoufox + geckodriver,且仅此一种。 原版 firefox --remote-debugging-port 暴露的是 CDP,不是 WebDriver BiDi,本项目不支持;并且 stealth 那半工具链也只对 Camoufox 生效(详见 为什么是 Camoufox)。

macOS

  1. Camoufox:从 https://github.com/daijro/camoufox/releases 下载最新 macOS .dmg,拖入 /Applications。首次运行右键 → 打开 绕过 Gatekeeper。

  2. geckodriver:brew install geckodriver。

    • Apple Silicon 装到 /opt/homebrew/bin/geckodriver。

    • Intel 装到 /usr/local/bin/geckodriver(与代码默认值一致)。

  3. 项目本体:

    npm install
    npm run build

集成 / e2e 套件需要 Camoufox 与 geckodriver 实际可用——握手失败会直接抛错,不会自动 skip。单元测试(npm test)不依赖任何浏览器二进制。

Linux / Windows

未做常规验证。从 Camoufox releases 与 geckodriver releases 自行安装,再通过 CAMOUFOX_PATH / GECKODRIVER_PATH(或 --camoufox-path / --geckodriver-path)指向二进制路径即可。

--stealth 到底控制什么

--stealth=auto(默认)会在会话初始化时把 src/stealth-scripts/ 下的 firefox-default preload 注入进去。--stealth=off 仅跳过这一层 preload —— Camoufox 的 C++ stealth 始终生效,与这个开关无关。

在 MCP 客户端中注册

本服务的预期使用方式是被 AI agent 驱动(Claude Code、Claude Desktop、Cursor 等)。从 shell 单独跑它不是真实的逆向工作流,唯一合理的场景是验证安装是否成功(见下方 冒烟测试)。

Claude Code (CLI)

# 在仓库目录下执行,确保 build 路径解析正确
claude mcp add camoufox-jsreverser \
  --env LLM_PROVIDER=openai \
  --env LLM_API_KEY=sk-... \
  --env GECKODRIVER_PATH=/opt/homebrew/bin/geckodriver \
  -- node "$(pwd)/build/src/index.js" --stealth=auto

或者直接编辑 ~/.claude.json:

{
  "mcpServers": {
    "camoufox-jsreverser": {
      "command": "node",
      "args": [
        "/绝对路径/camoufox-jsreverser-mcp/build/src/index.js",
        "--stealth=auto"
      ],
      "env": {
        "LLM_PROVIDER": "openai",
        "LLM_API_KEY": "sk-...",
        "GECKODRIVER_PATH": "/opt/homebrew/bin/geckodriver"
      }
    }
  }
}

env 块就是 agent 需要的全部配置。可用变量:

变量

用途

LLM_PROVIDER

openai / anthropic / openai-compatible。留空则 LLM 工具优雅禁用。

LLM_API_KEY

所选 provider 的 Bearer key。

LLM_BASE_URL

openai-compatible 必填;其他 provider 可选覆盖。

LLM_DEFAULT_MODEL

可选的默认 model id。

CAMOUFOX_PATH

Camoufox 二进制路径。macOS 默认:/Applications/Camoufox.app/Contents/MacOS/camoufox。

GECKODRIVER_PATH

geckodriver 二进制路径。默认 /usr/local/bin/geckodriver。Apple Silicon brew 装在 /opt/homebrew/bin/geckodriver,请在此覆盖。

understand_code、summarize_code、deobfuscate_code 这三个 LLM 后处理工具在未配置 provider 时会干净地返回 LlmNotConfigured——绝不会抛——所以即便没配 LLM key,其余工具面依然完全可用。

CLI flag

这些 flag 由 MCP 客户端通过 args 透传。常用的有:

Flag

含义

--stealth <auto|off>

初始化时是否注入 firefox-default preload(默认 auto)。不影响始终开启的 Camoufox C++ stealth。

--user-agent <ua>

覆盖会被识别的 Camoufox/<ver> UA 品牌字符串。

--camoufox-path <path>

覆盖 Camoufox 二进制(优先级高于 CAMOUFOX_PATH 与默认路径)。

--geckodriver-path <path>

覆盖 geckodriver 二进制(优先级同上)。

--attach, --bidi-url <ws>, --rdp-port <port>

不启动新进程,而是连接已运行的 geckodriver 会话。仅开发/调试用。

冒烟测试安装

要确认服务能起、MCP 客户端能与之握手,本地手动跑一次:

node build/src/index.js --stealth=auto

它会通过 stdio 讲 MCP 协议。成功启动没有任何 banner——静默就是对的。按 Ctrl-C 退出。这种 shell 直跑模式下的本地 env 覆盖,可以放在仓库根目录的 .env 文件里(cp .env.example .env);优先级为:MCP 客户端 env > .env > 系统环境。日常配置请始终放在客户端那边。

Stealth 工具

工具

用途

inject_stealth

通过 BiDi preload 应用 stealth preset(默认 firefox-default)。仅主 realm。

inject_stealth_to_workers

把 preset 推送到 dedicated / shared worker realm(worker 序章已运行后再注入)。watch:true 会持续监听后续新建 worker,到会话结束为止。

inject_stealth_hook

用 Function.toString 伪装 + 通道采样的 Proxy 包装某个全局点路径(如 window.fetch)。可选 neutraliseTiming 让 performance.now / Date.now 单调推进以掩盖断点停顿。

inject_preload_script

直接注入任意 preload JS——上面三个都套不上时的逃生口。

list_stealth_presets / list_stealth_features

反查 capability 已知的所有 preset / feature。

set_user_agent

通过 BiDi emulation 覆盖 Camoufox/<ver> UA 品牌字符串。

测试分层

npm run lint               # eslint
npm run typecheck          # tsc --noEmit
npm test                   # vitest test/unit(快,不需要浏览器)
npm run test:integration   # 真 BiDi/RDP,经 geckodriver
npm run test:e2e           # 完整 MCP-over-stdio 工作流(W1–W7)

集成 / e2e 在缺少 Firefox 或 geckodriver 时会干净 skip,因此开发者机器上没装浏览器也不会污染单元测试结果。

CI 在 Firefox latest + latest-esr 两条线上各跑一遍三层(见 .github/workflows/ci.yml)。

License

ISC。

Available Tools

84 tools
analyze_targetC

Summarize cached scripts: crypto signature hits + sensitive API usage. Filter by URL substring.

Inputs: urlSubstring, maxScripts.

analyze_websocket_messagesC

Cluster frames by byte-signature heuristic. v1 local-only; no LLM.

Inputs: wsid (required).

break_on_xhrB

Install a hook that issues debugger; when XHR/fetch URL matches the pattern. v1 fires only if DevTools is open; M3 RDP wires the actual debugger pause.

Inputs: urlPattern (required).

check_browser_healthA

Verify Firefox is connected and BiDi reports ready.

Inputs: no named parameters.

click_elementC

Click a DOM element identified by its sharedId.

Inputs: sharedId (required), contextId.

collect_codeC

Fetch and cache the source of every script URL on the active page. If urls/urlSubstring given, only those are collected.

Inputs: urls, urlSubstring, maxScripts.

collection_diffB

Diff two keyed collections (scripts / requests / hooks). Items with the same key but different hash become "changed". Used by evidence comparisons.

Inputs: left (required), right (required).

create_hookB

Create a hook definition. Use inject_hook to attach it to the page or workers.

Inputs: name (required), targetExpr (required), capture (required).

delete_session_stateB

Delete a named session snapshot from memory.

Inputs: name (required).

deobfuscate_codeB

Apply local AST transforms (constant fold / string array decrypt / dead-code / control-flow hint) to deobfuscate a JS snippet.

Inputs: source (required), transforms.

detect_cryptoB

Run static crypto-algorithm signature rules (AES/RC4/MD5/SHA*/Base64/HMAC/RSA/SM*) against inline source or a cached script.

Inputs: source, scriptUrl.

diff_env_requirementsA

Diff two pip-style requirement files. Returns added / removed / changed / unchanged buckets plus counts.

Inputs: left (required), right (required).

dump_session_stateB

Export a named snapshot as a JSON string (for writing to disk).

Inputs: name (required).

evaluate_on_callframeA

Evaluate a JavaScript expression in the context of the current paused callframe. Throws if not paused.

Inputs: expression (required).

evaluate_scriptC

Evaluate a JS expression in a window realm of the active (or specified) context.

Inputs: expression (required), awaitPromise, contextId, realmId.

export_rebuild_bundleC

Bundle cached scripts + hook samples + network samples + env probes into artifacts/tasks//.

Inputs: taskId (required), envProbes, includeNetwork, includeHooks.

export_session_reportA

Render a Markdown summary of the current session (scripts / requests / hooks / evidence) into artifacts/tasks//report.md.

Inputs: taskId (required), title.

find_clickable_elementsB

Find all clickable elements (links, buttons, role=button, onclick, submit inputs) on the active page.

Inputs: contextId.

find_in_scriptA

Find string or regex pattern in a single cached script. Use get_script_source first to populate the cache.

Inputs: url (required), pattern (required), regex.

get_console_messageA

Get a single console entry by index.

Inputs: index (required).

get_dom_structureA

Get a flattened summary of the DOM tree (up to depth 4, 20 children per node).

Inputs: no named parameters.

get_hook_dataB

Read collected samples for a hook. Optionally limit count and filter by timestamp.

Inputs: hookId (required), limit, since.

get_network_requestA

Get full details of a single network request by ID. Optionally fetch its body via networkObserver.getData.

Inputs: requestId (required), fetchBody, dataType.

get_paused_infoA

Get information about the current paused state (callframe, location, why). Fails if not paused.

Inputs: no named parameters.

get_performance_metricsA

Get W3C performance metrics from the active page (navigation timing + paint). M3 adds engine-level metrics behind the same tool.

Inputs: no named parameters.

get_request_initiatorB

Get the initiator info for a request. Returns BiDi initiator + (when M3 initiatorTracer is wired) normalized {type, stack[{scriptUrl,line,column,functionName?}]}.

Inputs: requestId (required).

get_script_sourceA

Get the source of a script by URL. Fetches via the page (BiDi limitation; CORS may block cross-origin). Cached.

Inputs: url (required).

get_storageA

Read cookies, localStorage, sessionStorage, and IndexedDB names for the active page.

Inputs: no named parameters.

get_websocket_messageC

Get a single frame by wsid + frameIndex.

Inputs: wsid (required), frameIndex (required).

get_websocket_messagesC

Get multiple frames for a wsid with optional filters.

Inputs: wsid (required), limit, since, dir.

hook_functionB

Create and inject a hook in one call. Convenience wrapper around create_hook + inject_hook.

Inputs: name (required), targetExpr (required), capture (required), target.

inject_hookC

Inject a created hook into the page or worker(s). target: "page" | "worker:" | "all-workers" (default "page").

Inputs: hookId (required), target.

inject_preload_scriptB

Inject arbitrary preload JavaScript via BiDi script.addPreloadScript. Source runs before page scripts.

Inputs: source (required).

inject_stealthC

Apply a stealth preset via BiDi preload. Default: firefox-default.

Inputs: preset.

inject_stealth_hookA

Render a stealth-hardened wrap (Function.toString masking + channel-emitting Proxy) over one or more dotted global paths, optionally with performance.now/Date.now timing neutralisation, then install via BiDi preload. Main world only — use inject_stealth_to_workers for worker realms.

Inputs: wraps, neutraliseTiming, timingMaxGapMs.

inject_stealth_to_workersA

Push a stealth preset (default firefox-default) into every dedicated/shared worker realm via post-start eval. With watch:true (default) subscribes to new-worker events for the rest of the session.

Inputs: preset, watch.

inspect_objectC

Inspect an RDP object grip: preview + prototype + own properties (+ optional internal slots).

Inputs: grip, actor, withInternalSlots.

list_breakpointsA

List all currently registered breakpoints.

Inputs: no named parameters.

list_console_messagesC

Return console log entries from the active session. Optionally limit and filter by level.

Inputs: limit, level.

list_framesA

List frames (top + iframes) under the active page as a flat array.

Inputs: no named parameters.

list_hooksA

List all registered hooks with their injection status and sample count.

Inputs: no named parameters.

list_network_requestsA

List network requests collected since session start. Filter by URL substring, method, or response presence.

Inputs: urlSubstring, method, hasResponse, limit.

list_pagesB

List browsing contexts (tabs and iframes) currently open in Firefox.

Inputs: no named parameters.

list_scriptsA

List script resources loaded on the active page (URL + size). Does not include inline blocks; M3 RDP version will.

Inputs: no named parameters.

list_session_statesA

List all named session snapshots in memory.

Inputs: no named parameters.

list_stealth_featuresB

List the stealth features the capability knows about.

Inputs: no named parameters.

list_stealth_presetsB

List the stealth presets the capability knows about.

Inputs: no named parameters.

list_websocket_connectionsC

List active WebSocket connections detected on the page.

Inputs: urlSubstring, targetId.

list_workersA

List workers (dedicated, shared, service) visible on the active page. M3 RDP version adds offline worker detection.

Inputs: no named parameters.

load_session_stateC

Load a snapshot from a JSON string (previously produced by dump_session_state).

Inputs: name (required), json (required).

monitor_eventsC

Start a monitor for RDP resource types (console-message, error-message, network-event, source, document-event, etc.).

Inputs: resourceTypes, events.

new_pageC

Open a new browsing context (tab).

Inputs: url, background.

pauseA

Pause script execution in the debugger thread.

Inputs: no named parameters.

query_domC

CSS selector query against the active page. Returns shared node references.

Inputs: selector (required), contextId.

record_reverse_evidenceC

Append a reverse-engineering evidence record to artifacts/tasks//runtime-evidence.jsonl.

Inputs: taskId (required), category (required), signal (required), detail, +2 more.

remove_breakpointB

Remove an existing breakpoint by its bpId.

Inputs: bpId (required).

remove_hookC

Remove a hook and its preload script registration.

Inputs: hookId (required).

remove_xhr_breakpointA

Remove an XHR/fetch breakpoint registered by break_on_xhr.

Inputs: id (required).

restore_session_stateC

Restore a previously saved snapshot back into the browser (cookies + localStorage + sessionStorage).

Inputs: name (required).

resumeA

Resume script execution after a pause.

Inputs: no named parameters.

risk_panelB

Aggregate risk signals across cached scripts: crypto, exfil, fingerprint, storage writes, dynamic eval. Returns weighted score.

Inputs: urlSubstring.

save_session_stateB

Snapshot cookies + localStorage + sessionStorage of all known window realms into an in-memory snapshot.

Inputs: name (required).

search_in_scriptsA

Search a string or regex across ALL cached scripts. Populate the cache with get_script_source first.

Inputs: pattern (required), regex, urlSubstring, maxHits.

search_in_sourcesA

Alias of search_in_scripts. M3 RDP version differentiates by including dynamically-evaluated sources too.

Inputs: pattern (required), regex, urlSubstring, maxHits.

select_frameB

Set the active frame (iframe) context for subsequent tool calls. Pass empty string to clear.

Inputs: frameContextId (required).

select_pageB

Set the active browsing context for subsequent tool calls.

Inputs: contextId (required).

select_workerA

Set the active worker realm. Pass empty string to clear. Used as default target by hook tools.

Inputs: workerRealmId (required).

set_breakpointA

Set a breakpoint by source URL + line (+ optional column). columnTolerance > 0 enables multi-hit auto-resume until the paused column falls within ± tolerance of the requested column.

Inputs: sourceUrl (required), line (required), column, columnTolerance.

set_breakpoint_on_textA

Set a breakpoint by searching for a text string in cached sources (+ optional sourceUrl filter). columnTolerance > 0 enables multi-hit auto-resume.

Inputs: text (required), sourceUrl, columnTolerance.

set_csp_enabledA

Enable or disable CSP enforcement for a browsing context. Per-context scope via BiDi browsingContext.setBypassCSP — when enabled=false, bypass is set so inline injections succeed.

Inputs: enabled (required), contextId.

set_javascript_enabledA

Enable or disable JavaScript execution for a browsing context. Per-context scope via BiDi emulation.setScriptingEnabled — does not affect other tabs.

Inputs: enabled (required), contextId.

set_user_agentC

Override the User-Agent string for a browsing context via BiDi emulation.setUserAgentOverride.

Inputs: userAgent (required), contextId.

step_intoC

Step into the current function call.

Inputs: no named parameters.

step_outA

Step out of the current function, resuming until the caller.

Inputs: no named parameters.

step_overC

Step over the current statement (skips into function calls).

Inputs: no named parameters.

stop_monitorA

Stop a monitor previously started by monitor_events.

Inputs: monitorId (required).

summarize_codeC

Use an LLM to produce a bullet-list summary of a JS snippet. Returns LlmNotConfigured when no provider is set.

Inputs: source (required), maxBullets, model.

take_screenshotC

Take a screenshot of the active page as base64 PNG.

Inputs: contextId.

trace_functionA

Trace a function: hook with capture preset [args, return, stack]. Convenience wrapper for call-chain debugging.

Inputs: name (required), targetExpr (required), target.

type_textC

Type text into a DOM element identified by its sharedId.

Inputs: sharedId (required), text (required), clearFirst, contextId.

understand_codeB

Use an LLM to explain what a JS snippet does. Returns LlmNotConfigured cleanly when no provider is set.

Inputs: source (required), question, model, maxTokens.

unhook_functionC

Alias for remove_hook (kept for compatibility with the original CDP project naming).

Inputs: hookId (required).

wait_for_elementC

Wait for a CSS selector to match an element on the active page.

Inputs: selector (required), timeoutMs, state, contextId.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.6/5.0

    Scored across 84 tools

    Disambiguation2/5

    Many tools overlap in purpose, such as multiple injectors (inject_hook, inject_preload_script, inject_stealth, inject_stealth_hook), breakpoint setters (set_breakpoint, set_breakpoint_on_text), and search tools (search_in_scripts, search_in_sources, find_in_script). Convenience wrappers like hook_function, trace_function, and unhook_function add ambiguity. An agent would struggle to select the correct tool.

    Naming Consistency3/5

    Tool names mostly follow verb_noun in snake_case (e.g., analyze_target, list_scripts), but inconsistencies exist: mix of 'get_' vs 'list_' for retrieval, 'find_' vs 'search_' for searches, and some compound names (break_on_xhr, type_text) break the pattern. Overall moderately consistent but deviations are notable.

    Tool Count1/5

    84 tools is far beyond typical MCP server scope (3-15 tools). This extreme count suggests scope creep, many niche utilities, and overlapping functionality. The number makes the server unwieldy and poorly scoped for its stated purpose.

    Completeness3/5

    The tool set covers a broad range of reverse engineering tasks (debugging, script analysis, deobfuscation, stealth, networking, sessions). However, gaps exist: limited DOM manipulation (only click, type_text), no storage value access, and many tools marked as v1 or M3, indicating incomplete implementation. Comprehensive but not fully polished.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      An MCP server for JavaScript reverse engineering that enables AI to perform browser debugging, script analysis, and automated hook injection. It streamlines complex workflows like deobfuscation, network tracing, and risk assessment through direct browser integration.
      35
      20 npm
      1,049
      Apache 2.0
    • A
      license
      B
      quality
      A
      maintenance
      An anti-detection browser MCP server designed for JavaScript reverse engineering through the Camoufox engine. It enables AI assistants to perform dynamic debugging, function hooking, and network interception while bypassing sophisticated bot detection mechanisms.
      42
      571
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A JavaScript reverse engineering MCP server that enables AI coding assistants to debug and analyze JavaScript code in web pages.
      1,064 npm
      17
      Apache 2.0