ruyipage-mcp

Expone las capacidades de automatización BiDi de Firefox de ruyiPage a través del MCP (Model Context Protocol) como un conjunto de herramientas invocables por IA.

Compatible con cualquier cliente MCP como Claude Code, Cursor, etc.

Características

• 34 herramientas que cubren todo el flujo de automatización del navegador: inicio/toma de control del navegador, navegación de páginas, búsqueda e interacción con el DOM, capturas de pantalla/PDF, Cookies/Almacenamiento, ejecución de JS, interceptación/escucha de red/recopilación de datos, gestión de pestañas, emulación de dispositivos, suscripción a eventos BiDi

• Prioridad a acciones BiDi nativas — Las operaciones como clics, entradas de texto, arrastrar y soltar mantienen isTrusted=true, siendo más adecuadas para escenarios de alto control de riesgos

• Soporte para tomar control de navegadores con huella digital — Puede detectar y tomar control automáticamente de navegadores con núcleo Firefox como ADS / FlowerBrowser

• Gestión inteligente de elementos — Registro de elementos LRU, reciclaje automático + re-búsqueda automática de elementos caducados

• Compresión automática de capturas de pantalla — Escalado automático de imágenes ultra anchas, compresión JPEG, guardado automático en disco para imágenes grandes

• Transporte stdio — JSON-RPC 2.0 estándar, listo para usar

Related MCP server: MCP Selenium Server

Instalación

Requisitos previos

• Python >= 3.10

• ruyiPage >= 1.1.0

• Navegador Firefox (se recomienda usar el núcleo de Firefox que acompaña a ruyiPage)

Instalación desde el código fuente

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

También puedes pasarle directamente el enlace de GitHub a la IA para que te ayude con la instalación

Configuración

Claude Code

Opción 1: .mcp.json a nivel de proyecto (recomendado)

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

Cursor / Otros clientes MCP

Añade lo siguiente en el archivo de configuración MCP correspondiente:

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

Ejecución independiente

python -m ruyipage_mcp

El servidor transmite mensajes JSON-RPC a través de stdin/stdout y los registros se envían a stderr.

Configuración

Archivo de configuración

Copia ruyipage_mcp.example.json como ruyipage_mcp.json y modifícalo según sea necesario:

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
}

Orden de búsqueda del archivo de configuración:

1. Ruta especificada por la variable de entorno RUYIPAGE_MCP_CONFIG

2. ruyipage_mcp.json en el directorio de trabajo actual

3. Si no se encuentra el archivo de configuración, se utilizan los valores predeterminados integrados

Sobrescritura mediante variables de entorno

Las variables de entorno tienen mayor prioridad que el archivo de configuración, ideales para CI o escenarios de sobrescritura temporal:

Resumen de herramientas (34)

session — Ciclo de vida del navegador

Flujo típico:

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

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

nav — Navegación de página

dom — Búsqueda y lectura de elementos

Formato de localizadores:

act — Interacción con elementos

Acciones soportadas por 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 — Estado de la página

js — Ejecución de JavaScript

net — Control de red

Flujo típico de interceptación de solicitudes:

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

Flujo típico de escucha de red:

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

ctx — Gestión de contexto

Ejemplo de operación de emulación:

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 — Información del servidor

Conceptos clave

Gestión de sesiones

Cada conexión al navegador corresponde a una sesión, identificada por host:port (ej. 127.0.0.1:9222).

• Cuando solo hay una sesión activa, el parámetro session_id de todas las herramientas puede omitirse, se resuelve automáticamente

• Cuando hay múltiples sesiones, es necesario pasar explícitamente el session_id

• session_launch crea una sesión owned, session_quit terminará el proceso del navegador

• session_attach / session_auto_attach crean una sesión attached, session_quit solo libera la conexión

Registro de elementos

Los elementos encontrados mediante dom_find / dom_find_all se registran en el registro de elementos de la sesión actual, devolviendo un ID corto (ej. el_a3f2b1).

• Reciclaje LRU — Cuando se alcanza el límite de capacidad (predeterminado 512), el elemento menos utilizado recientemente se recicla automáticamente

• Recuperación automática de caducidad — Al acceder a un elemento caducado, se intenta automáticamente volver a buscarlo usando el localizador original

• El ID del elemento se puede pasar a todas las herramientas que requieran una referencia de elemento, como act_click, act_input, dom_read, act_chain, etc.

• Todas las herramientas que aceptan el parámetro target también pueden recibir directamente una cadena de localizador (ej. css:button.submit), sin necesidad de llamar primero a dom_find

Formato de respuesta

Todas las herramientas (excepto state_screenshot) devuelven un sobre JSON unificado:

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

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

state_screenshot devuelve directamente un objeto Image de MCP cuando el tamaño de la captura lo permite; cuando supera los 800KB, se guarda en disco y devuelve la ruta del archivo.

Proyectos relacionados

• ruyiPage — Biblioteca central de automatización BiDi de Firefox

• ruyipage-skill — Skill de ejecución de análisis de automatización por IA

• Navegador con huella digital de Firefox — Entorno de huella digital de Firefox complementario

Arquitectura

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 es una biblioteca síncrona, MCP FastMCP es asyncio. Todas las llamadas a ruyiPage se conectan a través de asyncio.to_thread() para garantizar que el bucle de eventos de MCP no se bloquee.

Declaración de uso

Este proyecto sigue la declaración de uso de ruyiPage y está limitado únicamente a fines de investigación personal, intercambio técnico legal, conforme y sin fines de lucro.

Licencia

BSD-3-Clause