ruyipage-mcp
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=truebei, was besser für Szenarien mit hohem Risikoschutz geeignet istUnterstü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_mcpDer 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:
Pfad, der durch die Umgebungsvariable
RUYIPAGE_MCP_CONFIGangegeben istruyipage_mcp.jsonim aktuellen ArbeitsverzeichnisFalls keine Konfigurationsdatei gefunden wird, werden die eingebauten Standardwerte verwendet
Konfigurationsoption | Typ | Standardwert | Beschreibung |
| string |
| Pfad zur Firefox-Programmdatei |
| bool |
| Auf |
| bool |
| Auf |
| list |
| Liste der erlaubten Browser-Pfade |
| int |
| LRU-Kapazität der Element-Registry pro Sitzung |
| int |
| Größe des BiDi-Event-Puffers |
| int |
| Timeout-Obergrenze für alle Warte-Tools (in Sekunden) |
Überschreiben durch Umgebungsvariablen
Umgebungsvariablen haben eine höhere Priorität als die Konfigurationsdatei, was für CI oder temporäre Überschreibungen geeignet ist:
Umgebungsvariable | Entsprechende Konfigurationsoption |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Pfad zur Konfigurationsdatei angeben |
Tool-Übersicht (34)
session — Browser-Lebenszyklus
Tool | Beschreibung |
| Startet einen neuen Firefox-Browser. Unterstützt benutzerdefinierte Ports, Headless-Modus, Privatsphäre-Modus, XPath Picker, Fenstergröße usw. |
| Übernimmt einen bereits laufenden Firefox über |
| Erkennt und übernimmt Firefox / ADS / FlowerBrowser automatisch anhand von Prozessmerkmalen |
| Schließt die Browsersitzung. |
Typischer Ablauf:
session_launch(port=9222)
→ 操作页面...
→ session_quit()# 接管已打开的指纹浏览器
session_auto_attach(latest_tab=true)
→ 操作页面...
→ session_quit() # 仅释放连接,浏览器继续运行nav — Seitennavigation
Tool | Beschreibung |
| Öffnet eine URL, unterstützt Warte-Strategien wie |
| Zurück |
| Vorwärts |
| Aktualisieren |
| Ruft URL, Titel und Ready-State der aktuellen Seite ab |
dom — Element-Suche und -Lesen
Tool | Beschreibung |
| Sucht ein einzelnes Element und gibt |
| Sucht alle passenden Elemente und gibt eine Liste zurück (Standard-Limit 20, Maximum 100) |
| Liest Element-Attribute: |
| Sucht innerhalb eines bereits gefundenen Elements nach Unterelementen |
| Wartet auf das Erscheinen eines Elements (mit Timeout) |
| Gibt das Element-Handle frei und gibt Speicher in der Registry frei |
Locator-Formate:
Format | Beispiel | Beschreibung |
|
| ID-Selektor |
|
| CSS-Selektor |
|
| XPath |
|
| Text-Übereinstimmung |
|
| Tag-Name |
act — Element-Interaktion
Tool | Beschreibung |
| Klickt auf ein Element. Unterstützt Links-/Rechtsklick / Doppelklick, optional JS-Klick. Verwendet standardmäßig native BiDi-Aktionen ( |
| Gibt Text ein. Native BiDi-Tastatureingabe, optionales Leeren vorhandener Inhalte. Unterstützt JS-Fallback |
| Einfache Aktionen: |
| Führt eine BiDi-Aktionskette (JSON-Array) aus, unterstützt Tastendruck, Klicken, Bewegen, Ziehen, Scrollen, Pausieren usw. |
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
Tool | Beschreibung |
| Screenshot. Unterstützt Vollseiten-Screenshot, Element-Screenshot, Speichern in Datei. Automatische Komprimierung, automatische Speicherung großer Bilder auf der Festplatte |
| Speichert die aktuelle Seite als PDF |
| Cookie-Management: |
| localStorage / sessionStorage-Management: |
js — JavaScript-Ausführung
Tool | Beschreibung |
| Führt JS-Code auf der Seite aus. Kann als Ausdruck ( |
| Verwaltet Preload-Skripte: |
net — Netzwerkkontrolle
Tool | Beschreibung |
| Request-Interception: |
| Netzwerk-Monitoring: |
| Datensammler: |
| Setzt/Löscht zusätzliche Request-Header |
| Setzt Cache-Verhalten: |
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
Tool | Beschreibung |
| Tab-Management: |
| Geräteemulation: Geolocation, Zeitzone, Sprache, Mobilgeräte-Presets, Offline-Modus, JS-Schalter |
| BiDi-Event-Abonnement: Einheitlicher Einstiegspunkt für |
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
Tool | Beschreibung |
| Gibt den aktuellen Serverstatus zurück: aktive Sitzungen, Elementanzahl, Konfigurationsschalter, Liste der Tool-Namespaces |
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östBei mehreren Sitzungen muss die
session_idexplizit übergeben werdensession_launcherstellt eine owned-Sitzung,session_quitbeendet den Browser-Prozesssession_attach/session_auto_attacherstellen eine attached-Sitzung,session_quitgibt 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_chainusw.Alle Tools, die einen
target-Parameter akzeptieren, können auch direkt einen Locator-String (z. B.css:button.submit) entgegennehmen, ohne dassdom_findvorher 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
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