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
}

配置文件查找顺序：

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

环境变量覆盖

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

工具一览 (34 个)

session — 浏览器生命周期

典型流程：

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

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

nav — 页面导航

dom — 元素查找与读取

定位器格式：

act — 元素交互

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 — 页面状态

js — JavaScript 执行

net — 网络控制

请求拦截典型流程：

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_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 — 服务器信息

核心概念

会话管理

每个浏览器连接对应一个 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