ruyipage-mcp

Предоставляет возможности автоматизации Firefox BiDi из ruyiPage в виде набора инструментов, вызываемых ИИ, через MCP (Model Context Protocol).

Поддерживает любые MCP-клиенты, такие как Claude Code, Cursor и другие.

Характеристики

• 34 инструмента, охватывающих весь процесс автоматизации браузера: запуск/подключение к браузеру, навигация по страницам, поиск и взаимодействие с DOM, скриншоты/PDF, Cookie/Storage, выполнение JS, перехват/прослушивание сети/сбор данных, управление вкладками, эмуляция устройств, подписка на события BiDi.

• Приоритет нативных действий BiDi — такие операции, как клик, ввод текста, перетаскивание, сохраняют isTrusted=true, что лучше подходит для сценариев с высокой защитой от ботов.

• Поддержка подключения к браузерам с отпечатками (fingerprint browsers) — автоматическое обнаружение и подключение к Firefox-браузерам, таким как ADS / FlowerBrowser.

• Интеллектуальное управление элементами — реестр элементов LRU, автоматическая очистка + повторный поиск устаревших элементов.

• Автоматическое сжатие скриншотов — автоматическое масштабирование сверхшироких изображений, сжатие JPEG, сохранение больших файлов на диск.

• Передача через stdio — стандартный JSON-RPC 2.0, готов к использованию «из коробки».

Related MCP server: MCP Selenium Server

Установка

Предварительные требования

• Python >= 3.10

• ruyiPage >= 1.1.0

• Браузер Firefox (рекомендуется использовать Firefox, поставляемый с ruyiPage)

Установка из исходного кода

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

Вы также можете просто передать ссылку на GitHub ИИ, чтобы он помог вам с установкой

Конфигурация

Claude Code

Способ 1: .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

Сервер передает сообщения JSON-RPC через stdin/stdout, логи выводятся в 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 — Информация о сервере

Основные концепции

Управление сессиями

Каждое соединение с браузером соответствует сессии, идентифицируемой по host:port (например, 127.0.0.1:9222).

• Если активна только одна сессия, параметр session_id во всех инструментах можно опустить, он будет определен автоматически.

• Если сессий несколько, необходимо явно передавать session_id.

• session_launch создает owned-сессию, session_quit завершит процесс браузера.

• session_attach / session_auto_attach создают attached-сессию, session_quit только освобождает соединение.

Реестр элементов

Элементы, найденные через dom_find / dom_find_all, регистрируются в реестре элементов текущей сессии и возвращают короткий 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, если размер скриншота позволяет; если он превышает 800 КБ, он сохраняется на диск и возвращается путь к файлу.

Сопутствующие проекты

• ruyiPage — основная библиотека автоматизации Firefox BiDi

• ruyipage-skill — Skill для запуска анализа автоматизации ИИ

• Firefox Fingerprint Browser — сопутствующая среда 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 и предназначен исключительно для законных, соответствующих требованиям и некоммерческих целей личных исследований и технического обмена.

Лицензия

BSD-3-Clause