ruyipage-mcp

Stellt die Firefox BiDi-Automatisierungsfunktionen von ruyiPage über das MCP (Model Context Protocol) als eine für KI aufrufbare Tool-Sammlung bereit.

Unterstützt beliebige MCP-Clients wie Claude Code, Cursor usw.

Funktionen

• 34 Tools, die den gesamten Prozess der Browser-Automatisierung abdecken: Starten/Übernehmen von Browsern, Seitennavigation, DOM-Suche und -Interaktion, Screenshots/PDF, Cookies/Storage, JS-Ausführung, Netzwerk-Interception/Monitoring/Datenerfassung, Tab-Management, Geräteemulation, BiDi-Event-Abonnement

• Native BiDi-Aktionen bevorzugt — Aktionen wie Klicken, Eingeben, Ziehen usw. behalten isTrusted=true bei, was besser für Szenarien mit hohem Risikoschutz geeignet ist

• Unterstützung für die Übernahme von Fingerprint-Browsern — Kann automatisch ADS / FlowerBrowser und andere Firefox-basierte Fingerprint-Browser erkennen und übernehmen

• Intelligentes Element-Management — LRU-Element-Registry, automatische Bereinigung + automatische erneute Suche nach abgelaufenen Elementen

• Automatische Screenshot-Komprimierung — Automatische Skalierung von überbreiten Bildern, JPEG-Komprimierung, automatische Speicherung großer Bilder auf der Festplatte

• stdio-Übertragung — Standard JSON-RPC 2.0, sofort einsatzbereit

Related MCP server: MCP Selenium Server

Installation

Voraussetzungen

• Python >= 3.10

• ruyiPage >= 1.1.0

• Firefox-Browser (empfohlen wird der mit ruyiPage mitgelieferte Firefox-Kernel)

Installation aus dem Quellcode

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

Sie können auch einfach den GitHub-Link an die KI geben, damit diese die Installation für Sie übernimmt

Konfiguration

Claude Code

Methode 1: Projektbezogene .mcp.json (empfohlen)

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

Cursor / Andere MCP-Clients

Fügen Sie Folgendes zur entsprechenden MCP-Konfigurationsdatei hinzu:

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

Unabhängiger Betrieb

python -m ruyipage_mcp

Der Server überträgt JSON-RPC-Nachrichten über stdin/stdout, Protokolle werden nach stderr ausgegeben.

Konfiguration

Konfigurationsdatei

Kopieren Sie ruyipage_mcp.example.json nach ruyipage_mcp.json und passen Sie sie nach Bedarf an:

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
}

Suchreihenfolge für die Konfigurationsdatei:

1. Pfad, der durch die Umgebungsvariable RUYIPAGE_MCP_CONFIG angegeben ist

2. ruyipage_mcp.json im aktuellen Arbeitsverzeichnis

3. Falls keine Konfigurationsdatei gefunden wird, werden die eingebauten Standardwerte verwendet

Überschreiben durch Umgebungsvariablen

Umgebungsvariablen haben eine höhere Priorität als die Konfigurationsdatei, was für CI oder temporäre Überschreibungen geeignet ist:

Tool-Übersicht (34)

session — Browser-Lebenszyklus

Typischer Ablauf:

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

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

nav — Seitennavigation

dom — Element-Suche und -Lesen

Locator-Formate:

act — Element-Interaktion

Von act_chain unterstützte Aktionen:

[
  {"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 — Seitenstatus

js — JavaScript-Ausführung

net — Netzwerkkontrolle

Typischer Ablauf für Request-Interception:

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

Typischer Ablauf für Netzwerk-Monitoring:

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

ctx — Kontext-Management

Beispiel für Emulations-Aktionen:

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 — Server-Informationen

Kernkonzepte

Sitzungsmanagement

Jede Browser-Verbindung entspricht einer Sitzung, identifiziert durch host:port (z. B. 127.0.0.1:9222).

• Wenn nur eine aktive Sitzung vorhanden ist, kann der session_id-Parameter bei allen Tools weggelassen werden; er wird automatisch aufgelöst

• Bei mehreren Sitzungen muss die session_id explizit übergeben werden

• session_launch erstellt eine owned-Sitzung, session_quit beendet den Browser-Prozess

• session_attach / session_auto_attach erstellen eine attached-Sitzung, session_quit gibt nur die Verbindung frei

Element-Registry

Elemente, die über dom_find / dom_find_all gefunden wurden, werden in der Element-Registry der aktuellen Sitzung registriert und geben eine kurze ID zurück (z. B. el_a3f2b1).

• LRU-Bereinigung — Wenn die Kapazitätsgrenze (Standard 512) erreicht ist, wird das am längsten nicht verwendete Element automatisch entfernt

• Automatische Wiederherstellung bei Ablauf — Beim Zugriff auf ein abgelaufenes Element wird automatisch versucht, es mit dem ursprünglichen Locator erneut zu finden

• Die Element-ID kann an alle Tools übergeben werden, die eine Element-Referenz benötigen, wie act_click, act_input, dom_read, act_chain usw.

• Alle Tools, die einen target-Parameter akzeptieren, können auch direkt einen Locator-String (z. B. css:button.submit) entgegennehmen, ohne dass dom_find vorher aufgerufen werden muss

Antwortformat

Alle Tools (außer state_screenshot) geben einen einheitlichen JSON-Umschlag zurück:

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

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

state_screenshot gibt bei zulässiger Screenshot-Größe direkt ein MCP-Image-Objekt zurück; bei Überschreitung von 800 KB wird das Bild auf der Festplatte gespeichert und der Dateipfad zurückgegeben.

Zugehörige Projekte

• ruyiPage — Die Kern-Firefox-BiDi-Automatisierungsbibliothek

• ruyipage-skill — KI-Automatisierungsanalyse-Skill

• Firefox Fingerprint-Browser — Zugehörige Firefox-Fingerprint-Umgebung

Architektur

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 ist eine synchrone Bibliothek, MCP FastMCP basiert auf asyncio. Alle ruyiPage-Aufrufe werden über asyncio.to_thread() gebrückt, um sicherzustellen, dass die MCP-Ereignisschleife nicht blockiert wird.

Nutzungserklärung

Dieses Projekt folgt der Nutzungserklärung von ruyiPage und ist ausschließlich für legale, regelkonforme und nicht-kommerzielle Zwecke der persönlichen Forschung und des technischen Austauschs bestimmt.

Lizenz

BSD-3-Clause