ruyipage-mcp
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
}Порядок поиска файла конфигурации:
Путь, указанный в переменной окружения
RUYIPAGE_MCP_CONFIGruyipage_mcp.jsonв текущей рабочей директорииЕсли файл не найден, используются встроенные значения по умолчанию
Параметр | Тип | По умолчанию | Описание |
| string |
| Путь к исполняемому файлу Firefox |
| bool |
| Установите |
| bool |
| Установите |
| list |
| Список разрешенных путей к браузерам |
| int |
| Емкость LRU реестра элементов для каждой сессии |
| int |
| Размер буфера событий BiDi |
| int |
| Максимальный лимит ожидания для всех инструментов ожидания (в секундах) |
Переопределение через переменные окружения
Переменные окружения имеют приоритет над файлом конфигурации, что удобно для CI или временных изменений:
Переменная окружения | Соответствующий параметр |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Указание пути к файлу конфигурации |
Обзор инструментов (34)
session — Жизненный цикл браузера
Инструмент | Описание |
| Запуск нового браузера Firefox. Поддерживает пользовательский порт, headless-режим, приватный режим, XPath Picker, размер окна и т.д. |
| Подключение к уже запущенному Firefox через |
| Автоматическое обнаружение и подключение к Firefox / ADS / FlowerBrowser по характеристикам процесса |
| Закрытие сессии браузера. Сессии |
Типичный процесс:
session_launch(port=9222)
→ 操作页面...
→ session_quit()# 接管已打开的指纹浏览器
session_auto_attach(latest_tab=true)
→ 操作页面...
→ session_quit() # 仅释放连接,浏览器继续运行nav — Навигация по странице
Инструмент | Описание |
| Открытие URL, поддерживает стратегии ожидания |
| Назад |
| Вперед |
| Обновить |
| Получение URL, заголовка и состояния готовности текущей страницы |
dom — Поиск и чтение элементов
Инструмент | Описание |
| Поиск одного элемента, возвращает |
| Поиск всех соответствующих элементов, возвращает список (лимит по умолчанию 20, максимум 100) |
| Чтение атрибутов элемента: |
| Поиск дочерних элементов внутри уже найденного элемента |
| Ожидание появления элемента (с таймаутом) |
| Освобождение дескриптора элемента, очистка места в реестре |
Форматы локаторов:
Формат | Пример | Описание |
|
| ID селектор |
|
| CSS селектор |
|
| XPath |
|
| Сопоставление текста |
|
| Имя тега |
act — Взаимодействие с элементами
Инструмент | Описание |
| Клик по элементу. Поддерживает левую/правую кнопку, двойной клик, опциональный JS-клик. По умолчанию использует нативные действия BiDi ( |
| Ввод текста. Нативный ввод с клавиатуры BiDi, опциональная очистка содержимого. Поддерживает откат к JS |
| Простые операции: |
| Выполнение цепочки действий 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 — Состояние страницы
Инструмент | Описание |
| Скриншот. Поддерживает скриншот всей страницы, элемента, сохранение в файл. Автоматическое сжатие, большие изображения сохраняются на диск |
| Сохранение текущей страницы в PDF |
| Управление Cookie: |
| Управление localStorage / sessionStorage: |
js — Выполнение JavaScript
Инструмент | Описание |
| Выполнение JS-кода на странице. Может быть вычислено как выражение ( |
| Управление preload-скриптами: |
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 — Управление контекстом
Инструмент | Описание |
| Управление вкладками: |
| Эмуляция устройств: геолокация, часовой пояс, язык, пресеты мобильных устройств, автономный режим, переключатели JS |
| Подписка на события BiDi: единая точка входа для управления |
Пример операции эмуляции:
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
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Official Browserless MCP server: browser automation, scraping, screenshots and PDFs for AI agents.
Web scraping, browser automation, screenshots and AI data extraction for AI agents via MCP.
Live browser debugging for AI assistants — DOM, console, network via MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server paired with a Firefox extension that enables LLM clients to control the user's browser, supporting tab management, history search, and content reading.353MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server implementation that enables browser automation through standardized MCP clients, supporting features like navigation, element interaction, and screenshots across Chrome, Firefox, and Edge browsers.MIT
- AlicenseNot gradedqualityBmaintenanceAn MCP Server that enables AI assistants to interact with your local browsers.55MIT
- AlicenseCqualityCmaintenanceEnables AI assistants to read and drive a real, logged-in Firefox browser, including tabs, cookies, history, and site interactions, all through the Model Context Protocol.5216 npmMIT