Skip to main content
Glama

frx-director-mcp

两种模式驱动浏览器逆向 —— ① 强模型领航 · 低模型实操 ② 强模型带自建经验库 · 亲自直驱

MCP Node TypeScript tests firefox-reverse

EN — TL;DR: An MCP server bridging a high-capability model (Claude / GPT) to the firefox-reverse browser's built-in reverse-engineering engine. Two composable modes: (1) Delegate — the strong model directs while a cheap worker (DeepSeek / Qwen / GLM) executes all tooling (token cost-split); (2) Direct-drive — the strong model uses its own skill / experience library and calls the 71 browser tools itself via agent_call_tool. It can also manage isolated fingerprint environments and signed Firefox extensions. Never touches your API key (configured once in the browser).

frx-director-mcp 是一个 MCP 服务,把强模型(Claude / GPT)通过标准 MCP 协议接到 firefox-reverse 浏览器内置的逆向引擎上。两种可自由组合的模式:

  • 模式一 · 领航委派(高模型配置、低模型调用):强模型当 director 只下方向、审结论;便宜的 worker 模型(DeepSeek-flash / Qwen-turbo / GLM)在浏览器里执行全部工具(抓包、签名追踪、补环境、脚本验证…)。token 天然拆分——强模型的判断力用在最高杠杆点,重复执行交给低成本模型;worker 复用浏览器内置的逆向方法论。

  • 模式二 · 经验库直驱(高模型带自建经验库、亲自调用):强模型用自己的经验库 / 技能(skill)/ 方法论,通过 agent_call_tool 亲自直调浏览器的 71 个工具(signer_trace / jsvmp_trace / closure_read / page_eval / 环境管理 / 扩展管理 / Skills…),跳过 worker。更快更准、可注入你自己的逆向经验;代价是每个工具回合花强模型的 token。

两种模式共用同一套桥接与浏览器引擎,可按任务、按步自由切换。0.3.0 起还可通过 MCP 管理 Firefox-Reverse 指纹环境(列表、新建、打开、关闭、导入采集 JSON),用 FRX_ENV_ID 启动指定独立 profile。0.3.2 起为 CLI 主模型补齐 agent_poll / agent_read_brief,避免 agent_start 后主模型停住不读结果。0.3.3 起修正三端自启动的 Marionette 端口传递方式。服务本身零站点逻辑、不接触任何 API Key(Key 仅在浏览器侧配置)。


目录

两种模式 · 工作流程 · 系统架构 · 快速开始 · 一键使用 · 工具参考 · 安全与约束 · 开发

Related MCP server: RE-MCP Server

两种模式

模式一 · 领航委派

模式二 · 经验库直驱

谁执行工具

便宜的 worker 模型(浏览器内)

强模型自己(经 MCP 直调)

强模型角色

下方向 / 审阶段结论

亲自调用每个工具

经验 / 方法论来源

浏览器内置 skill(worker 用)

强模型自带的经验库 / skill

token 开销

低(每轮读结论 + 写一条方向)

高(每个工具回合都花强模型 token)

适合

长任务、省钱、worker 够用

强模型本身懂逆向、要更快更准、要带自己的经验库

关键工具

agent_start / agent_send / agent_read

agent_tools + agent_call_tool

模式一(默认,省钱主路) 是结构性的成本拆分:强模型只在最高杠杆点介入,assist(AI 辅助阶段门)强制 worker 每阶段产出可审阅结论,让强模型尽早拦截错误路线。

模式二(0.2.0 起,opt-in 增益) 把浏览器的 71 个工具直接暴露给强模型:先 agent_tools 看清能力与参数,再 agent_call_tool 亲自直调。强模型可带自己的逆向经验库 / skill(例如把一套方法论作为 system prompt),用引擎级工具(页面检测不到)一步步控制浏览器。

两者不是二选一:可以同一会话里简单步骤亲自 agent_call_tool 快跑、繁重重复步骤 agent_start 委派 worker。唯一约束:同一浏览器同一时刻只跑一种——agent_call_tool 在有 worker 会话运行时会被拒绝(与 agent 共享标签页 / hook / trace 状态,并发会串味),先 agent_stop / agent_wait_for_stop 再直调。

工作流程

模式一 · 领航委派(强模型下方向、worker 执行):

  强模型 director (Claude / GPT)                  firefox-reverse 浏览器
  ┌───────────────────────┐    MCP / stdio     ┌──────────────────────────────┐
  │ ① agent_start  下目标  │ ─────────────────▶ │ worker 模型(便宜)执行 71 工具 │
  │ ② agent_poll 短轮询    │                    │ 抵达阶段门 → 产出阶段结论       │
  │ ③ agent_read_brief/read│ ◀───────────────── │                              │
  │ ④ agent_send   纠方向  │ ─────────────────▶ │ 按新方向继续                  │
  └───────────────────────┘                    └──────────────────────────────┘
        └──────────── 循环 ②~④,直到产出可独立运行的结果 ────────────┘

强模型每轮只消耗少量 token(读结论 + 写一条方向);worker 承担全部工具执行。

模式二 · 经验库直驱(强模型带自己的经验库、亲自调每个工具):

  强模型 (Claude + 自建经验库/skill)              firefox-reverse 浏览器
  ┌───────────────────────┐    MCP / stdio     ┌──────────────────────────────┐
  │ ① agent_tools 看能力   │ ─────────────────▶ │ 返回 71 工具的名/参数/说明     │
  │ ② agent_call_tool 直调 │ ─────────────────▶ │ 引擎级 dispatch → 工具信封     │
  │   (signer_trace/       │ ◀───────────────── │ (与内置 Agent 同一套引擎)     │
  │    page_eval/…)        │                    │                              │
  └───────────────────────┘                    └──────────────────────────────┘
        └── 强模型用自己的判断+经验库,逐个工具推进,无需 worker ──┘

强模型直接掌舵引擎工具:更快更准、可注入自己的逆向经验;代价是工具回合的 token 由强模型承担。

系统架构

director (Claude / GPT)
   │  stdio (MCP)
   ▼
frx-director-mcp ──── 21 tools ──── BrowserBridge(Marionette 默认 / File 备用)
   │  模式一: agent_start/send/read…      │  模式二: agent_tools + agent_call_tool
   │                                   │  TCP 127.0.0.1:2828 · chrome-context ExecuteScript
   │  每会话 convo / turnlog           ▼
   │                          ChromeUtils.importESModule(AgentSession.sys.mjs)
   ▼                                   │  run / getState / stop
 本地工作目录                agentSession 单例(firefox-reverse 父进程常驻)
                                       ▼
                       内置逆向 Agent(worker 模型)+ 工作目录 ledger.md / progress.md

桥接层(BrowserBridge)是抽象接口,默认实现走 Marionette;可切换至 FileBridge 作为备用通道,工具层无需改动。

快速开始

前置条件

  1. 安装 firefox-reverse 浏览器,并在其 Agent 设置中为一个便宜的 worker 模型配置 API Key(DeepSeek / 通义千问 / GLM 等;本服务不接触该 Key)。

    💡 worker 模型选型(重要):走 MCP 驱动这种长工具循环时,务必选标准 / 快速档,推荐 deepseek-v4-flash —— 实测零漂移、约 2–3 分钟/阶段、配合最顺。切勿用推理档(如 deepseek-v4-pro):推理档在长工具循环里易退化成「只吐纯文本计划、不再调用工具」而中断,是 worker 的首要失败模式。可在浏览器 Agent 设置里把默认 worker 设为该档,或在 agent_start({ model: "deepseek-v4-flash" }) 里临时指定(同一个 Key、无需改配置)。

  2. 以 Marionette + 系统权限启动浏览器(chrome 上下文执行特权 JS 所必需)。macOS 推荐走 .app 的 LaunchServices 启动链路:

    open -n -a "/Applications/Firefox Reverse.app" --args \
        -marionette -remote-allow-system-access -no-remote -new-instance \
        -profile "<你的 profile>"

    Windows / Linux 可直接用 Firefox Reverse 可执行文件带同样参数启动。默认 Marionette 端口是 2828;自定义端口请配置 FRX_MARIONETTE_PORT 并使用自动拉起,启动器会通过官方 pref/环境变量传入。也可以配置 FRX_AUTOLAUNCH=1 + FRX_FIREFOX_BIN + FRX_PROFILE,由本服务自动拉起;macOS 下 FRX_FIREFOX_BIN 可指向 /Applications/Firefox Reverse.app 或 .app/Contents/MacOS/firefox,MCP 会自动转换为 open -n -a ... --args。

  3. Node.js ≥ 18。

方式一:让 AI 自动安装(推荐)

在你的 AI 编码工具(Cursor / Claude Code / Codex 等)对话框中输入:

帮我安装并配置这个 MCP 工具:frx-director-mcp 项目地址:https://github.com/WhiteNightShadow/frx-director-mcp

AI 将自动完成 克隆 → 安装依赖 → 构建 → 写入客户端 MCP 配置 的全过程。

方式二:手动安装

git clone https://github.com/WhiteNightShadow/frx-director-mcp.git
cd frx-director-mcp
npm install && npm run build      # 产物:dist/index.js

将以下条目加入你客户端的 MCP 配置(<安装路径> 替换为实际路径):

{ "mcpServers": { "frx-director": {
  "command": "node",
  "args": ["<安装路径>/frx-director-mcp/dist/index.js"]
} } }
{ "mcpServers": { "frx-director": {
  "command": "node",
  "args": ["<安装路径>/frx-director-mcp/dist/index.js"]
} } }
claude mcp add frx-director -- node <安装路径>/frx-director-mcp/dist/index.js

可选环境变量(均有默认值;方式一会由 AI 自动填写,完整说明见 .env.example):

变量

说明

FRX_MARIONETTE_PORT

Marionette 端口,默认 2828

FRX_JSX_PROMPT_SRC

指向 firefox-reverse 的 AgentPanel.jsx,使 director 系统提示与浏览器 UI 同步

FRX_WORKSPACE_ROOT

会话工作目录根。默认放在 firefox-reverse 仓库旁 …/firefox-reverse-ws(从 FRX_JSX_PROMPT_SRC 推断仓库位置;推断不出则 ~/firefox-reverse-ws),每个会话一个子目录

FRX_DATA_DIR

MCP 自身状态(convo / turnlog,非逆向产物),默认 ~/.frx-director-mcp/data

FRX_AUTOLAUNCH + FRX_FIREFOX_BIN / FRX_PROFILE

由本服务自动拉起带 Marionette 的浏览器;macOS 自动使用 .app 启动,Windows/Linux 直接启动可执行文件

FRX_ENV_ID / FRX_ENVS_ROOT

绑定并启动指定 Firefox-Reverse 环境;默认环境根目录为 ~/.firefox-reverse/environments,未设置 FRX_ENV_ID 时沿用 FRX_PROFILE 兼容路径

📂 逆向产物在哪里? 工作目录归属 firefox-reverse 项目、而非 MCP 工具自身。默认每个会话的目录是 <firefox-reverse 仓库旁>/firefox-reverse-ws/<会话id>/(从 FRX_JSX_PROMPT_SRC 推断仓库位置;推断不出则 ~/firefox-reverse-ws/<会话id>/)—— 抓取的脚本、还原代码、ledger.md / progress.md 都落在这里,与你从哪个目录启动无关;agent_start / agent_read 的返回也会带上该会话的具体路径。要改位置,设 FRX_WORKSPACE_ROOT 即可。

工具接入自检

  • 外部 AI/CLI 成功加载本 MCP 后,默认 all 模式应出现 frx_status、agent_tools、agent_call_tool 和 frx_env_list;显式 direct/delegate 分组的入口不同,见下表。

  • notes_add、net_get、page_click、run_node、fs_* 属于 Firefox Reverse 浏览器内核工具:先调用 agent_tools 查看目录,再通过 agent_call_tool({ name, args }) 直调;它们不会全部展开成顶层 MCP 函数。

  • Firefox Reverse v0.26.0 的完整 agent_tools({}) 应返回 count:71、missingDeclared:[];v0.24/v0.25 为 68。数量由浏览器动态提供,不要求旧浏览器升级才能使用本 MCP。扩展、环境、页面等工具都通过实际目录查询。

启动工具分组(v0.4.0)

在 MCP 环境配置中设置 FRX_TOOL_PROFILE。默认 all 保持原来的 23 个顶层入口;修改后重启 MCP,并让客户端重新加载工具目录。

值

顶层入口数

范围

all

23

原有全部入口,默认兼容模式

direct

13

状态、目录、9 个环境管理入口、自动化扫描、agent_call_tool;不提供 worker 委派入口

delegate

12

状态、目录、10 个 Agent 委派/等待/读取/控制入口;不提供直驱和环境管理入口

所有分组保留 frx_status 和 agent_tools。direct 只需浏览器桥接就绪,不需要内置 worker 的模型 Key;all 的历史 ready 语义不变,同时提供 directReady/delegateReady。分组是客户端工具暴露策略,不是权限隔离/安全沙箱,不改变浏览器工具确认、活跃 worker 冲突保护或工具执行语义。direct 模式遇到正在运行的 worker,需在浏览器 UI 停止或使用 all 模式管理,不会自动终止它。

目录可以按需取:agent_tools({prefix:"page_",compact:true,limit:20}) 返回名称、参数和确认信息;需要说明时省略 compact,再用 query 按名称/描述过滤。无参调用保留完整目录;过滤结果提供 totalAvailable/totalMatches/truncated,不能把被筛掉的工具当作未实现。不承诺固定 Token 节省比例。

  • 如果本轮函数列表里只有 open_url,说明看到的是外部宿主自己的工具,本 MCP 尚未完成初始化;open_url 不属于 Firefox Reverse 或 frx-director-mcp。先查看 MCP stderr / 客户端日志,并确认 Node、MCP 命令和环境变量配置。

  • v0.3.6 起,MCP 会先完成 stdio 握手和工具注册,再解析 FRX_ENV_ID、分配端口、等待 Windows 冷启动与 Marionette;即使环境配置或浏览器启动失败,frx_status 仍会保留并返回具体诊断。

一键使用(两种模式)

挑一种模式,将对应整段原样复制作为首条消息发给你的强模型;它会自动完成环境自检、引导你补齐配置、向你询问目标,并按该模式驱动逆向。

模式一 · 领航委派(省 token,worker 干活)

你现在通过一个叫 frx-director 的 MCP,指挥 firefox-reverse 浏览器里的内置逆向 Agent。
你是专业的 Web 端爬虫 / 签名逆向工程师,只负责【方向决策】,不亲自调用浏览器工具——所有工具执行由浏览器里那个便宜的 worker 模型完成,你只读它的阶段结论、给方向。成本拆分:你(强模型)每轮只花少量 token 审阅结论 + 写一条方向;便宜的 worker 承担全部工具执行。

【第 0 步 · 环境自检】先调用 frx_status。
- ready=true → 进入下面流程。
- bridgeConnected=false 或 hasKey=false → 把返回的 note 用一句话告诉用户、引导其补齐(用 -marionette 启动浏览器,或在浏览器 Agent 设置里为一个便宜 worker 模型如 qwen-turbo / deepseek-v4-flash 配置 Key);待其完成后再次 frx_status 确认,再继续。

【第 1 步 · 明确目标】若用户尚未提供目标,向其索取以下 4 项:
  ① 站点 URL(能观察到目标请求的页面) ② 接口 URL(要复现的请求) ③ 目标参数(要还原的签名 / 加密参数名) ④ 输出目标(通常为:Node.js 黑盒复刻、脱离浏览器独立请求成功)。

【第 2 步 · 启动】agent_start({task:"将上述 4 项整合为清晰任务", targetUrl:"站点 URL"});返回 tid,后续均使用它。
  在 task 中给出你的判型与方法建议:简单站点优先 hook 比对标准算法、不必硬扣混淆;JSVMP 不逆字节码、走黑盒补环境;不臆测函数名,先 signer_trace 抓取真实入参。

【第 3 步 · 等待与审阅】
  CLI/命令行客户端优先循环调用 agent_poll({tid, timeoutSec:60, intervalSec:5})。
  - phase:"running" → worker 仍在执行,不是失败;继续 agent_poll,或改用 agent_wait_for_stop 长等待。
  - phase:"settled" → 先使用返回里的 brief;若需要完整产物再 agent_read({tid, includeProgressFile:true})。
  - phase:"error" 或 no-state → agent_read_brief({tid}) + agent_runlog({tail:30}) 做诊断。
  支持长等待的客户端也可直接 agent_wait_for_stop({tid});settled 后用 agent_read_brief 或 agent_read 读取结论。
  ★采信结论前务必查看 driftHint:勿将「模型漂移为纯文本 / idle 超时」误判为「路线确属不通」(worker 的首要失败模式)。

【第 4 步 · 方向修正】agent_send({tid, guidance:"..."}) 写一条具体、有序、可防止走弯路的指令,例如:
  「仅执行第 1+2+3 步」「每步先验证再进入下一步」「先完成两个简单目标、勿过早深入最难的 JSVMP」「输出不匹配通常是输入未喂对,勿转向字节级逆向」「仅回报这 3 项」。
  同时识别其自相矛盾(日志显示成功却写为失败)、拦截其臆断(如「换一个 bundle 就要换密钥」)。

【第 5 步 · 循环】重复第 3–4 步,直至产出可用结果(Node 独立请求目标接口、返回有效业务数据)。
  当路线已锁定、仅剩机械收尾时,可 agent_set_mode({tid, mode:"auto"}) 让 worker 无人值守完成;若卡住再切回 assist。
  若发现其正驶向错误路线,agent_stop({tid}) 中止后再以 agent_send 修正(进展已持久化,中止不丢失)。

现在开始:先调用 frx_status。

模式二 · 经验库直驱(强模型亲自调工具,可带你自己的逆向经验库)

适合用懂逆向的强模型(如 Claude)+ 你自己的方法论 / skill。把你的经验库(一套逆向方法论、站点经验、判型规则…)放在这段之前或作为 system prompt 一并给模型;它将用 agent_call_tool 亲自驱动浏览器。

你现在通过一个叫 frx-director 的 MCP,亲自直驱 firefox-reverse 浏览器的逆向引擎工具(直驱模式,不经 worker)。
你是资深 Web 逆向工程师,按【你自己的经验库 / 方法论】判型与决策,并亲手调用浏览器引擎工具完成逆向。

【第 0 步 · 环境自检】先调用 frx_status。bridgeConnected=false → 引导用户用 -marionette 启动浏览器后重试。
  注意:直驱模式只用浏览器引擎工具、不需要 worker 模型的 Key(hasKey=false 也能直驱)。

【第 1 步 · 看清能力】按任务用 agent_tools 的 prefix/query 查询相关 name 与参数;需要全部能力时无参读取,不必每轮重复整表
  (signer_trace / jsvmp_trace / closure_read / webapi_trace / whitebox_diff / wasm_probe / crypto_scan 等,页面检测不到)。

【第 2 步 · 明确目标】若用户未给,索取:① 站点 URL ② 接口 URL ③ 目标参数(签名/加密参数名)④ 输出目标(通常 Node 黑盒复刻、脱离浏览器请求成功)。

【第 3 步 · 亲自直驱】用 agent_call_tool({name, args}) 按你的方法论逐步推进,例如:
  - page_navigate 到站点 → net_capture 抓目标请求 → 看签名参数长相判型;
  - 标准算法优先 hook 比对(signer_trace / page_eval 装 hook 记入参出参 → 本地标准库比对),不硬扣混淆;
  - JSVMP 不逆字节码、走黑盒补环境;闭包真值用 closure_read;WASM 用 wasm_probe;
  - 扩展先用 addons_query 搜索/查看状态,再用 addons_manage 管理生命周期或打开配置页;
  - run_node 在工作目录里跑复刻、字节级比对自证;fs_write 落产物。
  每次直调读返回信封(ok/data/error),据此决定下一步——这就是你的工具循环。

【约束】① 同一时刻只跑直驱:别再 agent_start 起 worker(会与直调抢同一标签页被拒)。
  ② 最终产物要能脱离浏览器独立运行(Node 补环境/纯算);浏览器只作分析与验证。

现在开始:先调用 frx_status,再 agent_tools。

工具参考

通用

工具

说明

frx_status

首先调用 —— 自检:Marionette 是否连通、当前 worker provider / model、Key 是否已配置;未就绪时返回引导说明

agent_tools

动态列出当前浏览器实际注册的 71 个工具(名称 / 说明 / 是否需确认 / 参数名),包含引擎级逆向工具(signer_trace / jsvmp_trace / closure_read / webapi_trace / whitebox_diff / wasm_probe…,页面检测不到),以及页面、文件、Skills、记忆、指纹环境和扩展管理能力。两种模式都用:委派时照它写 guidance,直驱时照它填 agent_call_tool 的参数

指纹环境管理

工具

说明

frx_env_current / frx_env_list

查看当前连接环境与本机环境列表

frx_env_create / frx_env_rename

新建与内核一致的 Firefox 环境(默认中国大陆简体中文),或重命名已有环境

frx_env_open / frx_env_close / frx_env_delete

打开、关闭、删除独立 profile + 独立进程环境

frx_env_import_json / frx_env_import_capture

导入完整环境 JSON 或外部浏览器采集到的 fingerprint JSON

frx_page_automation_scan

扫描当前页常见自动化暴露点,辅助比较手动启动与 MCP 启动差异

模式一 · 领航委派(强模型下方向,worker 执行)

工具

说明

agent_start

创建会话:绑定工作目录、选择 AI 辅助模式、导航至目标、下达首轮任务(仅校验 hasKey,不接触 Key)。推荐返回后继续 agent_poll / agent_wait_for_stop,settled 后读取结果

agent_poll

CLI 友好的短轮询:默认最多等 60 秒,仍在跑返回 phase:"running" 和下一步提示;settled 时默认附带 agent_read_brief 结果,避免主模型启动后停住

agent_wait_for_stop

阻塞至 worker 抵达阶段门(settled);超时仍运行则返回 phase:"running"(继续等待,非失败)

agent_read_brief

简短读取阶段结论,默认不带 progress.md / ledger.md,只取最近 5 步和 2000 字,适合 CLI 主模型快速续上

agent_read

读取阶段结论 + progress.md / ledger.md + driftHint / runlogTail

agent_state

轻量存活 / 进度快照

agent_send

委派模式核心动作 —— 携带上轮结论、追加方向指令、发起下一轮

agent_set_mode

在 assist(逐阶段)与 auto(无人值守)之间切换

agent_stop

中止当前轮(进展已持久化至工作目录,不丢失)

agent_runlog

引擎级运行日志,用于区分「确属路线不通」与「模型漂移 / idle 超时」

模式二 · 经验库直驱(强模型带自建经验库,亲自调用)

工具

说明

agent_call_tool

直驱核心动作 —— 强模型亲自直调一个浏览器引擎工具(跳过 worker)。先 agent_tools 查 name/参数,再 agent_call_tool({name, args})。返回工具信封(ok/data/error,永不抛、已校验未知工具与缺参)。⚠ 有 worker 会话运行时被拒绝(共享页面 / hook 状态);需 firefox-reverse v0.20.0+

Firefox 扩展直驱(Firefox Reverse v0.24.0+)

agent_call_tool({name:"addons_query", args:{action:"search", query:"Violentmonkey", limit:5}})
agent_call_tool({name:"addons_query", args:{action:"list"}})
agent_call_tool({name:"addons_manage", args:{action:"install", ref:"violentmonkey", confirm:true}})
agent_call_tool({name:"addons_manage", args:{action:"open_options", id:"扩展 GUID"}})

安装来源仅接受 AMO 标识,Firefox 会校验哈希、兼容性、阻止列表和签名状态;安装与卸载必须显式传 confirm:true。系统/内置扩展不可修改,扩展配置页打开后继续使用 page_info / page_elements / page_click / page_type 操作。

📝 版本更新记录

v0.4.0(2026-10-11)

  • 工具分组(Issue #3):FRX_TOOL_PROFILE=all/direct/delegate,默认 23 个入口不变,直驱 13、委派 12;只在启动时选择,避免运行时工具列表与客户端缓存不一致。

  • 按需目录:agent_tools 支持 prefix/query/compact/limit,完整查询兼容旧行为;实际浏览器工具数动态读取,Firefox Reverse v0.26.0 增至 71。

  • 独立实例启动:补充当前 Firefox 基线有效的 -new-instance,保留旧参数兼容,不绕过 profile 锁、不全量终止浏览器进程。

  • 验证:33 项本地测试通过,含真实 MCP SDK 注册/调用、stdio 冷启动失败时三种目录仍可用,以及已有委派循环与启动路径回归;不强制底层执行 start/wait/read 流程。

  • 依赖维护:锁定依赖更新到兼容的 SDK 1.32.1,约束 Hono Node adapter 保留 1.x 的 Node 18 兼容;Node 18.20.8/24 均通过 33 项测试,发布时 npm audit --omit=dev 为 0。开发测试依赖仍有 9 项既有告警,本轮未强制升级开发工具大版本;预构建发行包只需 npm ci --omit=dev。当前服务是 stdio,不启用 SDK HTTP/OAuth 路径,SDK 公告说明该 OAuth 问题不影响 stdio 服务端。

v0.3.8(2026-09-17)

  • frx_env_create 增加可选 consistencyMode,转交支持原生一致策略的新版 Firefox Reverse;不传时仍使用浏览器自身默认值,不强制迁移历史环境。

  • 工具说明明确:原生一致策略不随机 Screen/DPR/GPU;工具数和 Agent 委派流程不变。

  • 原生一致环境以文件传配置,清除继承的旧 inline 指纹与父 token,避免 Windows 环境块容量限制;历史配置保留 inline 路径,显式传入的 inline(包括空字符串)不被悄悄替换。

  • 修复 macOS LaunchServices 启动时继承环境变量造成的中文路径乱码:路径/标签通过 open --env 传递,JSON 使用等价 ASCII 转义且不进入进程参数。已在本机验证中文配置路径可读。

  • MCP initialize 握手从 package.json 读取实际版本,避免客户端看到旧版本号;7 个测试文件、25 项测试通过,实际 stdio 验证 23 个入口工具、68 个浏览器工具及环境列表。

  • 配合 Firefox-Reverse v0.25.0 使用;更新后重启 MCP 客户端连接。发布包不包含个人 .env 或浏览器 profile。

v0.3.7(2026-09-03)

  • 68 个浏览器工具说明同步:README 与 agent_tools 描述同步 Firefox Reverse v0.24.0,明确 23 个顶层 MCP 编排工具和 68 个浏览器工具的边界。

  • 扩展管理直驱说明:补充 addons_query / addons_manage 的搜索、列表、签名安装和配置页示例,以及确认与系统扩展保护边界。

  • 协议保持兼容:仍由 agent_tools 动态读取浏览器真实注册表,旧浏览器返回其自身工具数量;本版不改变启动、会话、环境或 Marionette 协议。

v0.3.6(2026-08-20)

  • 环境解析也不再阻塞注册:新增延迟浏览器桥,FRX_ENV_ID 读取、环境端口分配和真实 Bridge 创建全部移到 MCP initialize/tools/list 之后;彻底消除环境目录或端口探测拖慢外部宿主握手的剩余竞态。

  • 未就绪调用快速失败:浏览器桥尚在解析时,工具调用立即返回 startup.phase=resolving/starting,不会把单次 MCP 请求挂在几十秒冷启动后面。

  • 历史结论:启动握手阻塞从 MCP 初版就存在,旧静态 agent_tools 在首次引入时也只返回 36/44 个有说明工具;v0.23 的独立 profile 冷启动与 66 工具扩容只是让旧问题更容易显现,并非 Firefox v0.23 新删了工具。

  • 回归扩展:新增延迟桥单测及 FRX_ENV_ID 解析失败进程级测试,并继续要求 Windows / Ubuntu 双平台 CI。

v0.3.5(2026-08-20)

  • Windows 冷启动工具注册修复:MCP stdio 握手和固定工具注册提前到 Firefox 自动拉起 / Marionette 端口等待之前,避免浏览器启动几十秒时被外部 CLI 判定 MCP 启动超时、最终只剩宿主自带的 open_url。

  • 浏览器工具目录补全:agent_tools 改为读取浏览器实际 backend 注册表,修复旧静态 stub 只返回 38/66 个工具的问题;新增 missingDeclared 一致性诊断。

  • 失败保持可诊断:FRX_FIREFOX_BIN、FRX_ENV_ID 或浏览器启动配置错误不再直接退出 MCP;frx_status 返回 mcpToolsRegistered 与 startup.phase/error,用户修正浏览器配置后可明确复查。

  • 进程级回归测试:真实启动 MCP stdio 子进程,在故意破坏 Firefox autolaunch 的情况下验证 initialize / tools/list 仍成功,且包含 frx_status、agent_tools、agent_call_tool、不包含外部宿主的 open_url。

v0.3.4(2026-07-29)

  • Firefox-only 环境创建:frx_env_create 不再接受浏览器内核类型,新环境始终使用与 Firefox Reverse 内核一致的 Firefox 指纹。

  • 中文地区参数:新建环境默认中国大陆简体中文,并支持传入 language、languages、locale 和 timezone 自定义地区组合。

  • 兼容历史环境:已有环境的指纹文件和 profile 不会因 MCP 升级而自动修改;新增测试覆盖默认值、自定义值和旧环境兼容路径。

v0.3.3(2026-07-13,main 补丁)

  • Marionette 端口修复:移除 Firefox 153 不识别的 --marionette-port 启动参数,改用 MOZ_MARIONETTE_PREF_STATE_ACROSS_RESTARTS 注入 marionette.port,保证 Windows、macOS、Linux 以及多指纹环境使用各自端口。

  • 启动文档纠正:手动启动示例不再展示无效参数;自定义端口统一通过 FRX_MARIONETTE_PORT + FRX_AUTOLAUNCH=1 配置。

v0.3.2(2026-07-07,main 补丁)

  • CLI 委派闭环增强:新增 agent_poll,把「短等待状态」和「settled 后简短读取」合成一个动作,降低 GPT/CLI 在 agent_start 后停住不读结果的概率。

  • 简短结果读取:新增 agent_read_brief,默认只读最近 5 步与 2000 字阶段结论,不加载 progress.md / ledger.md,避免大输出让命令行主模型卡住或跳步。

  • 流程提示增强:agent_start、工具描述和一键提示词补充 agent_start → agent_poll/agent_wait_for_stop → agent_read_brief/agent_read 的推荐闭环,不做底层硬拦截,保留外部编排、人工检查和长等待客户端的自由度。

v0.3.1(2026-07-07,main 补丁)

  • 三端 autolaunch 加固:FRX_AUTOLAUNCH=1 启动时先检查 Marionette 端口,启动后等待端口 ready,不再把 spawn 成功误判为浏览器可用。

  • macOS 启动修复:当 FRX_FIREFOX_BIN 指向 /Applications/Firefox Reverse.app 或 .app/Contents/MacOS/firefox 时,自动转换为 open -n -a "...app" --args ...,避免直接拉二进制导致 Firefox Reverse 短暂启动后退出。

  • profile 锁处理:启动前检测 .parentlock / parent.lock / lock;确认没有真实进程占用时才清理 stale lock,避免误删正在使用的 profile 锁。

  • 失败诊断增强:记录启动方式、启动命令、早退 exitCode/signal/stderr、锁文件清理情况;frx_status 与 MCP stderr 提示改为明确指出 profile 占用、端口不可达或浏览器早退。

  • 本地验证:新增 launcher 单测覆盖 macOS LaunchServices 与 Windows/Linux 直接可执行路径,并用临时 profile 实测 macOS autolaunch 可正常拉起 Marionette。

v0.3.0(2026-07-07)

  • Firefox-Reverse 环境管理:新增 frx_env_current/list/create/rename/open/close/delete/import_json/import_capture,可通过 MCP 管理指纹环境。

  • 指定环境启动:支持 FRX_ENV_ID / FRX_ENVS_ROOT,读取环境 env.json 后使用独立 profile、指纹配置、代理配置、trace 目录与 Marionette 端口启动。

  • 自动化暴露扫描:新增 frx_page_automation_scan,用于比较 MCP 启动与手动启动时的 WebDriver、UA-CH、plugins、permissions、WebGL/canvas/audio/WebRTC/storage 等暴露点。

  • 兼容旧模式:未设置 FRX_ENV_ID 时继续沿用 FRX_PROFILE,保留原有委派模式与直驱模式。

v0.2.x

  • 直驱模式:新增 agent_tools / agent_call_tool,强模型可以跳过 worker,亲自调用浏览器内置逆向工具。

  • 长任务稳定性:强化阶段等待、运行日志、漂移提示和会话读取能力,降低长工具循环中断概率。

安全与约束

  • 不接触 API Key —— Key 仅在浏览器侧配置;agent_start 仅校验 hasKey 布尔值;运行日志归档对疑似 Key 做脱敏处理。

  • 本地回环 —— Marionette 端口(2828)仅绑定 127.0.0.1,请勿对外暴露:能连接该端口者即拥有 agentSession 的全部能力(含 page_eval / 文件写入 / run_node)。

  • 站点无关 —— 本服务仅负责「驱动 + 读取状态」,不含任何站点逻辑或算法。

  • 桥接机制 —— 经 Marionette 在 chrome 上下文中 importESModule 命中父进程单例(newSandbox:false)。若未来 Firefox 构建破坏此路径,可切换 FRX_BRIDGE=file 使用 FileBridge 备用通道。

开发

npm run dev        # tsx 直接运行 src/index.ts
npm run typecheck  # tsc --noEmit
npm test           # vitest(mock 桥接 + mock Marionette 服务,无需真实浏览器)

技术栈:TypeScript(strict、NodeNext)+ 官方 @modelcontextprotocol/sdk,stdio 传输。源起于实战工具 frx_drive.py(经 Marionette 编程驱动 firefox-reverse 内置 Agent),将其子命令封装为标准 MCP 工具,并修复了 4 处经实测验证的缺陷:等待超时上调至 5400s 且「超时 ≠ 失败」、仅以 settled 判定阶段结束、agent_read 折入 drift / runlog 信号、fire‑and‑forget 后重新轮询确认启动。

License

本项目以 Apache License 2.0 发布。Copyright © 2026 WhiteNightShadow。

本项目是 firefox-reverse 的配套工具,仅供安全研究、接口对接与授权测试,请在合法授权范围内使用。

Available Tools

23 tools
agent_call_toolDirectly run ONE browser tool (bypass the worker)A

★你(director)亲自跑一个浏览器引擎工具,跳过 DeepSeek worker —— 强模型直驱引擎级工具,比委派 worker 磨更快更准。代价:每个工具回合都花 director 的 token(打破默认成本拆分;按需用、不用就仍走 agent_start/agent_send 省钱流)。先 agent_tools 查 name 和参数。返回工具信封(ok/data/error);浏览器侧 dispatch 永不抛、已校验未知工具与缺参。⚠ 任一 worker 会话正在跑时会被拒绝;先在浏览器侧栏停止/等待,或在 all 工具分组下调用 agent_stop/agent_wait_for_stop,再直调。需浏览器 v0.20.0+。

Inputs: name (required), args, workspaceRoot.

agent_pollShort-poll a worker turn for CLI clientsA

CLI 友好的短轮询:最多等 30-120 秒查看 worker 是否 settled,避免一次 agent_wait_for_stop 长等 5400s 导致命令行无进度。默认 timeoutSec=60、intervalSec=5; 若 settled 且 readOnSettled 未设 false,会自动附带 brief 结论。agent_start 后推荐优先循环调用它。

Inputs: tid (required), stepTail, timeoutSec, intervalSec, +2 more.

agent_readRead the worker's stage conclusionA

读 worker 的阶段结论(①发现 ②2-3 方向 ③推荐)给 director 评判:含完整 content 尾、步骤尾、工作目录 progress.md/ledger.md(worker 真正依赖的持久知识),以及 ★driftHint + runlogTail——assist 模式下任何'纯文字无工具'都被强制成 final,真结论和模型漂移经 getState 分不开,所以读结论时必须看 driftHint/runlog 的 finishReason,别把 drift/idle-timeout 当成真的'路线走不通'(这是 worker 头号失败模式)。只读、可反复调。

Inputs: tid (required), stepTail, contentChars, includeProgressFile.

agent_read_briefRead a compact worker conclusionA

CLI 友好的简短读取:等价于 agent_read({includeProgressFile:false, stepTail:5, contentChars:2000})。用于 settled 后快速把 worker 结论交给主模型,避免 progress.md/ledger.md 或大 steps 输出让某些 CLI 卡住。

Inputs: tid (required), stepTail, contentChars.

agent_runlogEngine run log (diagnostic)A

引擎级 run 日志(getRunLog):请求/响应时序、重试、idle 看门狗超时、finishReason、drift 检测。诊断用——让 director 区分'worker 真的判定路线走不通' vs '模型侧 drift / idle 超时 / 推理档模型(如 deepseek-v4-pro)吐了纯文字计划没调工具',下结论前先核它。

Inputs: tid.

agent_sendSend a direction correction (the director's core move)A

★director 的核心动作:把方向纠正作为下一条 user 消息发出去并起下一轮(=harness 的 advance)。服务端会:把 worker 上一轮的【完整】最终结论作为 assistant 轮接上(上一轮空/被停则合成占位,保证 user/assistant 交替合法)→ 追加你的 guidance 作为新 user 轮 → 持久化 → 以当前模式重跑。若还有一轮在跑会拒绝(先 wait 或 stop)。guidance 写得像真人纠正:具体、有序、'只做第 1+2+3 步'、'每步先验证再下一步'、'只回报这 3 件事'、防兔子洞。

Inputs: tid (required), guidance (required), assist, maxRounds.

agent_set_modeSwitch assist/autoA

切会话模式:'assist'=每轮阶段门停给 director review(成本拆分默认);'auto'=worker 跑到完成不停。路线锁定后可切 'auto' 让 worker 无人值守收尾,卡住再切回 'assist'。

Inputs: tid (required), mode (required).

agent_startStart a worker sessionA

开一个新的逆向会话:配置 worker 模型(默认沿用浏览器里已配的)+关掉工具确认门、(可选)导航到目标 URL、建工作目录、用便宜的 worker 模型以【AI 辅助模式】发出第一轮(task 作为第 0 条 user)。返回 tid,后续都用它。推荐流程:GPT/CLI 委派模式下,agent_start 返回后继续 agent_poll/agent_wait_for_stop 观察阶段状态,settled 后用 agent_read_brief/agent_read 读取结论。绝不读/写 worker 的 key——key 由用户预先在浏览器里配好;这里只校验 hasKey=true。worker 选标准/快档别选推理档(推理档在长工具循环里易漂移成纯文字),如 deepseek-v4-flash / qwen-turbo / glm。

Inputs: task (required), model, assist, provider, +4 more.

agent_stateCheap liveness snapshotA

廉价的存活/进度快照(比 agent_read 轻):running/settled/nSteps/checkpointSeq/错误/contentTail 短尾/driftHint。用在等待循环里,或发 guidance 前确认上一轮真的停了。注意:健康的 turn 也会几十秒 nSteps 不动(一个长工具/LLM 回合),别据此判'卡死'——唯一可靠的'活着'信号是有没有 settled。

Inputs: tid (required).

agent_stopAbort the current grindA

砍掉 worker 当前这一轮(agentSession.stop)。用在:读到快照发现 worker 正冲向错误路线,想立刻截停并 agent_send 纠正、不想干等它 settle。进展已落盘(ledger/progress.md),停掉不丢持久状态。

Inputs: tid (required).

agent_toolsList the browser-side toolsA

列出浏览器侧实际可用的工具清单(名称/说明/是否需确认/参数名)。支持 prefix/query 筛选和 compact 精简返回,工具数量以当前浏览器为准。包含引擎级逆向工具(signer_trace/jsvmp_trace/closure_read/webapi_trace/whitebox_diff/wasm_probe 等)、环境管理以及 Firefox 扩展查询/管理(addons_query/addons_manage)。all 分组可委派 worker 或用 agent_call_tool 直调。只读、无副作用。

Inputs: limit, query, prefix, compact.

agent_wait_for_stopWait for the worker's stage gateA

阻塞轮询直到 worker 这一轮 settled(阶段门到了)。这是'便宜模型磨完了、该读了'的信号。★真实 turn 常 20-30 分钟,默认超时 5400s;★超时但还 running 时返回 phase:'running'(=还在磨、去 agent_read 看看再决定继续等还是 stop+纠正),绝不是'失败'。settled 才是唯一的'阶段结束'信号(不靠 nSteps 之类)。

Inputs: tid (required), timeoutSec, intervalSec.

frx_env_closeClose a Firefox Reverse environmentC

关闭指定环境进程。

Inputs: id (required).

frx_env_createCreate a Firefox Reverse environmentA

一键新建 Firefox 环境;新版内核默认原生一致策略,保持真实 Screen/DPR/GPU,默认中国大陆简体中文。旧版浏览器仍按自身默认策略执行。

Inputs: name, locale, language, timezone, +3 more.

frx_env_currentGet current Firefox Reverse environmentA

返回当前连接的 Firefox Reverse 进程所属环境;不是环境进程时 environment=null。

Inputs: refresh.

frx_env_deleteDelete a Firefox Reverse environmentA

删除已关闭环境。必须显式传 confirm:true。

Inputs: id (required), confirm (required).

frx_env_import_captureImport pasted fingerprint capture JSONC

把外部浏览器控制台采集到的 JSON 文本导入指定环境。

Inputs: id (required), text (required).

frx_env_import_jsonImport a full Firefox Reverse environment JSONA

导入完整环境 JSON。新环境只接受 Firefox 指纹;支持 {name,id,fingerprint,proxy,generateOptions} 或 {env,fingerprint,proxy},id 已存在时需 overwrite:true。

Inputs: id, name, text, config, +1 more.

frx_env_listList Firefox Reverse environmentsC

列出 firefox-reverse 环境,供 MCP 侧环境管理按钮使用。

Inputs: refresh.

frx_env_openOpen a Firefox Reverse environmentC

打开指定环境:独立 profile + 独立 Firefox 进程。

Inputs: id (required).

frx_env_renameRename a Firefox Reverse environmentC

重命名已有环境。

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

frx_page_automation_scanScan browser automation exposure in the current pageA

在当前网页内容上下文扫描常见自动化/底层环境暴露点:navigator.webdriver、UA-CH、plugins、permissions、WebGL/canvas/audio/WebRTC/storage 等。用于比较手动打开与 MCP 打开的全局差异,不做单站点加密分析。

Inputs: saveTo.

frx_statusPreflight: check setup before startingA

★开跑前先调这个自检:MCP 工具是否已注册、浏览器启动阶段、marionette 连没连、当前 worker provider/model、worker key 配没配。没就绪就照返回的 note 一句话引导用户(启动浏览器加 marionette / 在浏览器设置里配便宜 worker 模型的 Key),就绪了再 agent_start。只读、无副作用。

Inputs: no named parameters.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 23 tools

    Disambiguation4/5

    The agent_* family has mild overlap: agent_read, agent_read_brief, and agent_state all read worker state, and agent_wait_for_stop vs agent_poll both wait for settle. However, descriptions clearly differentiate them (full vs brief vs cheap snapshot; long blocking vs short CLI polling), so misselection risk is low. Env tools (create/open/close/rename/delete/list/current/import_json/import_capture) each target a distinct action.

    Naming Consistency4/5

    All names use snake_case with clear verb_noun patterns. There are three prefix families (frx_env_*, frx_*, agent_*) reflecting different subsystems, with frx_status and frx_page_automation_scan being minor deviations from frx_env_*. Within each group the convention is consistent and readable.

    Tool Count4/5

    23 tools is on the heavy side (the 16-25 band), but the server genuinely spans two subsystems: browser environment lifecycle management and director/worker agent orchestration. Each area justifies roughly ten tools, so the count is defensible rather than padded.

    Completeness4/5

    Env lifecycle is well covered (create/open/close/rename/delete/list/current plus two import paths), and the worker orchestration surface (start/send/stop/poll/wait/read/state/runlog/set_mode/tools/call_tool) supports the full director loop. Minor gaps: no env settings update beyond rename/import, and no browser launch control (deliberately external).

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A local, privacy-first MCP server that orchestrates Ghidra, Binary Ninja, x64dbg, and system tools to provide AI assistants with powerful binary analysis capabilities.
      -
    • A
      license
      B
      quality
      C
      maintenance
      MCP server for offensive-security tooling, enabling AI agents to run reconnaissance, CVE intelligence, JavaScript analysis, HTTP probing, and port scanning against authorized targets.
      10
      MIT