ruyipage-mcp

MCP Server for ruyiPage Firefox Automation

将 ruyiPage 的 Firefox BiDi 自动化能力，通过 MCP (Model Context Protocol) 暴露为 AI 可调用的工具集。

支持 Claude Code、Cursor 等任意 MCP 客户端。

特性

34 个工具，覆盖浏览器自动化全流程：启动/接管浏览器、页面导航、DOM 查找与交互、截图/PDF、Cookie/Storage、JS 执行、网络拦截/监听/数据采集、标签页管理、设备模拟、BiDi 事件订阅
原生 BiDi 动作优先 — 点击、输入、拖拽等操作保持 isTrusted=true，更适合高风控场景
支持接管指纹浏览器 — 可自动探测并接管 ADS / FlowerBrowser 等 Firefox 内核指纹浏览器
智能元素管理 — LRU 元素注册表，自动回收 + 过期元素自动重查
截图自动压缩 — 超宽图片自动缩放，JPEG 压缩，大图自动落盘
stdio 传输 — 标准 JSON-RPC 2.0，开箱即用

安装

前置要求

Python >= 3.10
ruyiPage >= 1.1.0
Firefox 浏览器（推荐使用 ruyiPage 配套的 Firefox 内核）

从源码安装

git clone https://github.com/LoseNine/ruyipage-mcp.git
cd ruyipage-mcp
pip install -e .

也可以直接把github连接给ai，让ai帮你装

配置

Claude Code

方式一： 项目级 .mcp.json（推荐）

{
  "mcpServers": {
    "ruyipage": {
      "command": "python",
      "args": ["-m", "ruyipage_mcp"]
    }
  }
}

Cursor / 其他 MCP 客户端

在对应 MCP 配置文件中添加：

{
  "mcpServers": {
    "ruyipage": {
      "command": "python",
      "args": ["-m", "ruyipage_mcp"]
    }
  }
}

独立运行

python -m ruyipage_mcp

服务器通过 stdin/stdout 传输 JSON-RPC 消息，日志输出到 stderr。

配置

配置文件

将 ruyipage_mcp.example.json 复制为 ruyipage_mcp.json，按需修改：

cp ruyipage_mcp.example.json ruyipage_mcp.json

{
  "browser_path": "E:\\ruyi_firefox\\firefox.exe",
  "disable_run_js": false,
  "disable_extensions": false,
  "browser_path_whitelist": [],
  "max_elements": 512,
  "event_buffer_size": 500,
  "wait_timeout_ceiling": 60
}

配置文件查找顺序：

RUYIPAGE_MCP_CONFIG 环境变量指定的路径
当前工作目录下的 ruyipage_mcp.json
若未找到配置文件，使用内置默认值

| 配置项 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | browser_path | string | E:\ruyi_firefox\firefox.exe | Firefox 可执行文件路径 | | disable_run_js | bool | false | 设为 true 禁用 js_run 工具 | | disable_extensions | bool | false | 设为 true 禁用扩展相关能力 | | browser_path_whitelist | list | [] (允许任意路径) | 允许的浏览器路径列表 | | max_elements | int | 512 | 每个会话的元素注册表 LRU 容量 | | event_buffer_size | int | 500 | BiDi 事件缓冲区大小 | | wait_timeout_ceiling | int | 60 | 所有等待类工具的超时上限（秒） |

环境变量覆盖

环境变量优先级高于配置文件，适合 CI 或临时覆盖场景：

| 环境变量 | 对应配置项 | |----------|------------| | RUYIPAGE_MCP_BROWSER_PATH | browser_path | | RUYIPAGE_MCP_DISABLE_RUN_JS | disable_run_js (1 = true) | | RUYIPAGE_MCP_DISABLE_EXTENSIONS | disable_extensions (1 = true) | | RUYIPAGE_MCP_BROWSER_PATH_WHITELIST | browser_path_whitelist (逗号分隔) | | RUYIPAGE_MCP_MAX_ELEMENTS | max_elements | | RUYIPAGE_MCP_EVENT_BUFFER_SIZE | event_buffer_size | | RUYIPAGE_MCP_WAIT_TIMEOUT_CEILING | wait_timeout_ceiling | | RUYIPAGE_MCP_CONFIG | 指定配置文件路径 |

工具一览 (34 个)

session — 浏览器生命周期

| 工具 | 说明 | |------|------| | session_launch | 启动新 Firefox 浏览器。支持自定义端口、无头模式、隐私模式、XPath Picker、窗口大小等 | | session_attach | 通过 host:port 接管已运行的 Firefox | | session_auto_attach | 按进程特征自动探测并接管 Firefox / ADS / FlowerBrowser | | session_quit | 关闭浏览器会话。owned 会话直接关闭进程，attached 会话仅释放连接 |

典型流程：

session_launch(port=9222)
  → 操作页面...
  → session_quit()

# 接管已打开的指纹浏览器
session_auto_attach(latest_tab=true)
  → 操作页面...
  → session_quit()  # 仅释放连接，浏览器继续运行

nav — 页面导航

| 工具 | 说明 | |------|------| | nav_get | 打开 URL，支持 complete / interactive / none 等待策略 | | nav_back | 后退 | | nav_forward | 前进 | | nav_refresh | 刷新 | | nav_info | 获取当前页面的 URL、标题、ready state |

dom — 元素查找与读取

| 工具 | 说明 | |------|------| | dom_find | 查找单个元素，返回 element_id。支持 #id、css:、xpath:、text:、tag: 定位 | | dom_find_all | 查找所有匹配元素，返回列表（默认上限 20，最大 100） | | dom_read | 读取元素属性：text / html / inner_html / outer_html / value / attrs / rect / all | | dom_query_in | 在已有元素内部继续查找子元素 | | dom_wait_for | 等待元素出现（带超时） | | dom_release | 释放元素句柄，回收注册表空间 |

定位器格式：

| 格式 | 示例 | 说明 | |------|------|------| | #id | #search-box | ID 选择器 | | css: | css:div.card > a | CSS 选择器 | | xpath: | xpath://button[text()='Login'] | XPath | | text: | text:登录 | 文本匹配 | | tag: | tag:input | 标签名 |

act — 元素交互

| 工具 | 说明 | |------|------| | act_click | 点击元素。支持左键 / 右键 / 双击，可选 JS 点击。默认使用原生 BiDi 动作 (isTrusted=true) | | act_input | 输入文本。原生 BiDi 键盘输入，可选清空已有内容。支持 JS 回退 | | act_simple | 简单操作：hover / clear / focus / scroll_into_view | | act_chain | 执行 BiDi 动作链（JSON 数组），支持按键、点击、移动、拖拽、滚轮、暂停等 |

act_chain 支持的动作：

[
  {"action": "press", "key": "Enter"},
  {"action": "click"},
  {"action": "click", "element_id": "el_abc123"},
  {"action": "move_to", "element_id": "el_abc123"},
  {"action": "move_to", "x": 100, "y": 200},
  {"action": "double_click"},
  {"action": "right_click"},
  {"action": "key_down", "key": "Shift"},
  {"action": "key_up", "key": "Shift"},
  {"action": "type", "text": "hello"},
  {"action": "scroll", "x": 0, "y": -300},
  {"action": "pause", "duration": 500}
]

state — 页面状态

| 工具 | 说明 | |------|------| | state_screenshot | 截图。支持全页面截图、元素截图、保存到文件。自动压缩，超大图自动落盘 | | state_save_pdf | 将当前页面保存为 PDF | | state_cookies | Cookie 管理：get / set / delete。支持按 name/domain 过滤 | | state_storage | localStorage / sessionStorage 管理：items / get / set / delete / clear |

js — JavaScript 执行

| 工具 | 说明 | |------|------| | js_run | 在页面中执行 JS 代码。可作为表达式求值 (as_expr=true) 或函数体执行。可通过环境变量禁用 | | js_preload | 管理 preload script：add（每次页面加载前注入）/ remove |

net — 网络控制

| 工具 | 说明 | |------|------| | net_intercept | 请求拦截：start → wait_and_resolve（continue/mock/fail）→ stop | | net_listen | 网络监听：start → wait（按 URL/method 过滤）→ stop | | net_collector | 数据采集器：add → get（按 request_id 获取请求/响应体）→ remove | | net_headers | 设置/清除额外请求头 | | net_cache | 设置缓存行为：default（正常缓存）/ bypass（强制重新请求） |

请求拦截典型流程：

net_intercept(op="start", url_patterns="api/login")
  → 触发页面操作
  → net_intercept(op="wait_and_resolve", action='{"mode":"mock","status":200,"body":"{}"}')
  → net_intercept(op="stop")

网络监听典型流程：

net_listen(op="start", targets="api/data", method="POST")
  → 触发页面操作
  → net_listen(op="wait", timeout=10)
  → net_listen(op="stop")

ctx — 上下文管理

| 工具 | 说明 | |------|------| | ctx_tabs | 标签页管理：list / create / close / activate / reload | | ctx_emulation | 设备模拟：地理位置、时区、语言、移动设备预设、离线模式、JS 开关 | | ctx_events | BiDi 事件订阅：统一入口管理 page.events / page.navigation / page.downloads |

模拟操作示例：

ctx_emulation(op="set_geolocation", latitude=39.9, longitude=116.4)
ctx_emulation(op="set_timezone", timezone_id="Asia/Tokyo")
ctx_emulation(op="set_locale", locales="ja-JP,ja")
ctx_emulation(op="apply_mobile_preset", width=390, height=844, device_pixel_ratio=3)
ctx_emulation(op="set_offline", enabled=true)
ctx_emulation(op="set_offline", enabled=false)

meta — 服务器信息

| 工具 | 说明 | |------|------| | ruyipage_describe_capabilities | 返回当前服务器状态：活跃会话、元素数量、配置开关、工具命名空间列表 |

核心概念

会话管理

每个浏览器连接对应一个 session，以 host:port（如 127.0.0.1:9222）作为标识。

当只有一个活跃 session 时，所有工具的 session_id 参数可省略，自动解析
有多个 session 时，需要显式传入 session_id
session_launch 创建的是 owned 会话，session_quit 会终止浏览器进程
session_attach / session_auto_attach 创建的是 attached 会话，session_quit 仅释放连接

元素注册表

通过 dom_find / dom_find_all 查到的元素会被注册到当前 session 的元素注册表中，返回一个短 ID（如 el_a3f2b1）。

LRU 回收 — 达到容量上限（默认 512）时，最久未使用的元素自动回收
过期自动恢复 — 访问过期元素时，自动尝试用原始定位器重新查找
元素 ID 可传给 act_click、act_input、dom_read、act_chain 等所有需要元素引用的工具
所有接受 target 参数的工具也可直接传入定位器字符串（如 css:button.submit），无需先调用 dom_find

响应格式

所有工具（state_screenshot 除外）返回统一 JSON 信封：

// 成功
{"ok": true, "data": ...}

// 失败
{"ok": false, "error": "error message"}

state_screenshot 在截图体积允许时直接返回 MCP Image 对象；超过 800KB 时落盘返回文件路径。

配套项目

ruyiPage — 核心 Firefox BiDi 自动化库
ruyipage-skill — AI 自动化分析运行 Skill
Firefox 指纹浏览器 — 配套 Firefox 指纹环境

架构

python -m ruyipage_mcp
  → __main__.py → server.run()
    → 导入 tools/*.py（触发 @mcp.tool() 注册 34 个工具）
    → 注册 atexit 清理（退出时关闭 owned 浏览器）
    → mcp.run(transport="stdio")

ruyipage_mcp/
├── app.py          # FastMCP("ruyipage-mcp") 单例
├── config.py       # 环境变量配置
├── registries.py   # SessionRegistry + ElementRegistry (LRU)
├── runtime.py      # async/sync 桥接 + 响应封装 + 元素解析
├── server.py       # 入口 + atexit 清理
└── tools/
    ├── session.py  # 浏览器启动/接管/关闭
    ├── nav.py      # 页面导航
    ├── dom.py      # 元素查找/读取
    ├── act.py      # 元素交互/动作链
    ├── state.py    # 截图/PDF/Cookie/Storage
    ├── js.py       # JS 执行/预加载脚本
    ├── net.py      # 网络拦截/监听/采集
    ├── ctx.py      # 标签页/模拟/事件
    └── meta.py     # 服务器状态

ruyiPage 是同步库，MCP FastMCP 是 asyncio。所有 ruyiPage 调用通过 asyncio.to_thread() 桥接，确保 MCP 事件循环不被阻塞。

使用声明

本项目遵循 ruyiPage 的使用声明，仅限合法、合规、非盈利的个人研究与技术交流用途。

License

BSD-3-Clause

MCP Servers