ruyipage-mcp
ruyipage-mcp
ruyiPage の Firefox BiDi 自動化機能を、MCP (Model Context Protocol) を通じてAIが呼び出せるツールセットとして公開します。
Claude Code、Cursorなど、あらゆるMCPクライアントをサポートしています。
特徴
34種類のツール:ブラウザ自動化の全プロセスを網羅(ブラウザの起動/接続、ページナビゲーション、DOM検索と操作、スクリーンショット/PDF、Cookie/ストレージ、JS実行、ネットワークインターセプト/監視/データ収集、タブ管理、デバイスエミュレーション、BiDiイベント購読)
ネイティブBiDiアクション優先 — クリック、入力、ドラッグなどの操作で
isTrusted=trueを維持し、リスク管理が厳しい環境に適しています指紋ブラウザの接続をサポート — ADS / FlowerBrowser などのFirefoxベースの指紋ブラウザを自動検出し、接続可能
インテリジェントな要素管理 — LRU要素レジストリ、自動クリーンアップ + 期限切れ要素の自動再検索
スクリーンショットの自動圧縮 — 超広角画像の自動リサイズ、JPEG圧縮、大容量画像の自動保存
stdio転送 — 標準JSON-RPC 2.0、設定不要ですぐに使用可能
Related MCP server: MCP Selenium Server
インストール
前提条件
Python >= 3.10
ruyiPage >= 1.1.0
Firefoxブラウザ(ruyiPage付属のFirefoxカーネルを推奨)
ソースコードからのインストール
git clone https://github.com/LoseNine/ruyipage-mcp.git
cd ruyipage-mcp
pip install -e .GitHubのリンクをAIに渡してインストールを依頼することも可能です
設定
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サーバーはstdin/stdoutを通じてJSON-RPCメッセージを転送し、ログは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_CONFIG環境変数で指定されたパス現在の作業ディレクトリ内の
ruyipage_mcp.json設定ファイルが見つからない場合は、組み込みのデフォルト値を使用
設定項目 | 型 | デフォルト値 | 説明 |
| string |
| Firefox実行ファイルのパス |
| bool |
|
|
| bool |
|
|
| list |
| 許可するブラウザパスのリスト |
| int |
| セッションごとの要素レジストリLRU容量 |
| int |
| BiDiイベントバッファサイズ |
| int |
| すべての待機系ツールのタイムアウト上限(秒) |
環境変数による上書き
環境変数は設定ファイルよりも優先されるため、CIや一時的な上書きに適しています:
環境変数 | 対応する設定項目 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 設定ファイルのパスを指定 |
ツール一覧 (34種類)
session — ブラウザのライフサイクル
ツール | 説明 |
| 新しいFirefoxブラウザを起動。カスタムポート、ヘッドレスモード、プライベートモード、XPath Picker、ウィンドウサイズなどをサポート |
|
|
| プロセス特性に基づいてFirefox / ADS / FlowerBrowserを自動検出し接続 |
| ブラウザセッションを終了。 |
典型的なフロー:
session_launch(port=9222)
→ 操作页面...
→ session_quit()# 接管已打开的指纹浏览器
session_auto_attach(latest_tab=true)
→ 操作页面...
→ session_quit() # 仅释放连接,浏览器继续运行nav — ページナビゲーション
ツール | 説明 |
| URLを開く。 |
| 戻る |
| 進む |
| 更新 |
| 現在のページのURL、タイトル、ready stateを取得 |
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コードを実行。式として評価 ( |
| プリロードスクリプトの管理: |
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 — サーバー情報
ツール | 説明 |
| 現在のサーバー状態を返す:アクティブセッション、要素数、設定スイッチ、ツール名前空間リスト |
コアコンセプト
セッション管理
各ブラウザ接続は session に対応し、host:port(例:127.0.0.1:9222)を識別子とします。
アクティブなセッションが1つのみの場合、すべてのツールの
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パラメータを受け入れるすべてのツールは、dom_findを呼び出さずにロケータ文字列(例:css:button.submit)を直接渡すことも可能です
レスポンス形式
すべてのツール(state_screenshot を除く)は、統一されたJSONエンベロープを返します:
// 成功
{"ok": true, "data": ...}
// 失败
{"ok": false, "error": "error message"}state_screenshot は、スクリーンショットのサイズが許容範囲内であればMCP Image オブジェクトを直接返し、800KBを超える場合はファイルパスを返します。
関連プロジェクト
ruyiPage — コアとなるFirefox BiDi自動化ライブラリ
ruyipage-skill — AI自動化分析実行Skill
Firefox 指紋ブラウザ — 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