de en es ja ko ru zh

ruyipage-mcp

Name: ruyipage-mcp
Author: neverl805

by neverl805

Overview Schema Source Related Servers Discussions Admin

Python

Local

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
設定ファイルが見つからない場合は、組み込みのデフォルト値を使用

設定項目	型	デフォルト値	説明
`browser_path`	string	`E:\ruyi_firefox\firefox.exe`	Firefox実行ファイルのパス
`disable_run_js`	bool	`false`	`true` に設定すると `js_run` ツールを無効化
`disable_extensions`	bool	`false`	`true` に設定すると拡張機能関連の機能を無効化
`browser_path_whitelist`	list	`[]` (任意のパスを許可)	許可するブラウザパスのリスト
`max_elements`	int	`512`	セッションごとの要素レジストリLRU容量
`event_buffer_size`	int	`500`	BiDiイベントバッファサイズ
`wait_timeout_ceiling`	int	`60`	すべての待機系ツールのタイムアウト上限（秒）

環境変数による上書き

環境変数は設定ファイルよりも優先されるため、CIや一時的な上書きに適しています：

環境変数	対応する設定項目
`RUYIPAGE_MCP_BROWSER_PATH`	`browser_path`
`RUYIPAGE_MCP_DISABLE_RUN_JS`	`disable_run_js` (`1` = true)
`RUYIPAGE_MCP_DISABLE_EXTENSIONS`	`disable_extensions` (`1` = true)
`RUYIPAGE_MCP_BROWSER_PATH_WHITELIST`	`browser_path_whitelist` (カンマ区切り)
`RUYIPAGE_MCP_MAX_ELEMENTS`	`max_elements`
`RUYIPAGE_MCP_EVENT_BUFFER_SIZE`	`event_buffer_size`
`RUYIPAGE_MCP_WAIT_TIMEOUT_CEILING`	`wait_timeout_ceiling`
`RUYIPAGE_MCP_CONFIG`	設定ファイルのパスを指定

ツール一覧 (34種類)

session — ブラウザのライフサイクル

ツール	説明
`session_launch`	新しいFirefoxブラウザを起動。カスタムポート、ヘッドレスモード、プライベートモード、XPath Picker、ウィンドウサイズなどをサポート
`session_attach`	`host:port` を介して実行中のFirefoxに接続
`session_auto_attach`	プロセス特性に基づいてFirefox / ADS / FlowerBrowserを自動検出し接続
`session_quit`	ブラウザセッションを終了。`owned` セッションはプロセスを直接終了し、`attached` セッションは接続のみを解放

典型的なフロー：

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

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

nav — ページナビゲーション

ツール	説明
`nav_get`	URLを開く。`complete` / `interactive` / `none` の待機戦略をサポート
`nav_back`	戻る
`nav_forward`	進む
`nav_refresh`	更新
`nav_info`	現在のページのURL、タイトル、ready stateを取得

dom — 要素の検索と読み取り

ツール	説明
`dom_find`	単一の要素を検索し、`element_id` を返す。`#id`、`css:`、`xpath:`、`text:`、`tag:` による特定をサポート
`dom_find_all`	一致するすべての要素を検索し、リストを返す（デフォルト上限20、最大100）
`dom_read`	要素属性の読み取り：`text` / `html` / `inner_html` / `outer_html` / `value` / `attrs` / `rect` / `all`
`dom_query_in`	既存の要素内で子要素を検索
`dom_wait_for`	要素の出現を待機（タイムアウト付き）
`dom_release`	要素ハンドルを解放し、レジストリ領域を回収

ロケーター形式：

形式	例	説明
`#id`	`#search-box`	IDセレクター
`css:`	`css:div.card > a`	CSSセレクター
`xpath:`	`xpath://button[text()='Login']`	XPath
`text:`	`text:ログイン`	テキスト一致
`tag:`	`tag:input`	タグ名

act — 要素のインタラクション

ツール	説明
`act_click`	要素をクリック。左クリック / 右クリック / ダブルクリックをサポート。JSクリックも選択可能。デフォルトでネイティブBiDiアクション (`isTrusted=true`) を使用
`act_input`	テキストを入力。ネイティブBiDiキーボード入力。既存内容のクリアを選択可能。JSフォールバックをサポート
`act_simple`	単純操作：`hover` / `clear` / `focus` / `scroll_into_view`
`act_chain`	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 — ページ状態

ツール	説明
`state_screenshot`	スクリーンショット。全ページ、要素単位のスクリーンショット、ファイル保存をサポート。自動圧縮、大容量画像の自動保存
`state_save_pdf`	現在のページをPDFとして保存
`state_cookies`	Cookie管理：`get` / `set` / `delete`。名前/ドメインによるフィルタリングをサポート
`state_storage`	localStorage / sessionStorage管理：`items` / `get` / `set` / `delete` / `clear`

js — JavaScript実行

ツール	説明
`js_run`	ページ内でJSコードを実行。式として評価 (`as_expr=true`) または関数本体として実行可能。環境変数で無効化可能
`js_preload`	プリロードスクリプトの管理：`add`（ページ読み込み前に毎回注入）/ `remove`

net — ネットワーク制御

ツール	説明
`net_intercept`	リクエストインターセプト：`start` → `wait_and_resolve`（continue/mock/fail）→ `stop`
`net_listen`	ネットワーク監視：`start` → `wait`（URL/methodでフィルタリング）→ `stop`
`net_collector`	データコレクター：`add` → `get`（request_idでリクエスト/レスポンスボディを取得）→ `remove`
`net_headers`	追加のリクエストヘッダーを設定/クリア
`net_cache`	キャッシュ動作の設定：`default`（通常キャッシュ）/ `bypass`（強制再リクエスト）

リクエストインターセプトの典型的なフロー：

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 — コンテキスト管理

ツール	説明
`ctx_tabs`	タブ管理：`list` / `create` / `close` / `activate` / `reload`
`ctx_emulation`	デバイスエミュレーション：位置情報、タイムゾーン、言語、モバイルデバイスプリセット、オフラインモード、JSスイッチ
`ctx_events`	BiDiイベント購読：`page.events` / `page.navigation` / `page.downloads` を一元管理

エミュレーション操作の例：

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 — サーバー情報

ツール	説明
`ruyipage_describe_capabilities`	現在のサーバー状態を返す：アクティブセッション、要素数、設定スイッチ、ツール名前空間リスト

コアコンセプト

セッション管理

各ブラウザ接続は 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を超える場合はファイルパスを返します。

アーキテクチャ

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

This server cannot be deployed

Let your AI agent see the webWeb-to-screenshot MCP for Claude, Cursor and Codex. No cookie banners. Free to start.snap-render.comAd

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

hithereiamaliff-mcp-nextcloudOAuth
ai.smithery
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Cloud Storage File Systems Workplace & Productivity
238
Firecrawl MCP Server A
io.github.firecrawl
MCP server for Firecrawl — web search, scraping, and biomedical/arXiv paper search.
Browser Automation Web Scraping Search
317,570
sncro A
io.github.scottconfusedgorilla
Live browser debugging for AI assistants — DOM, console, network via MCP.
Browser Automation Developer Tools Monitoring
2
Mercado PagoOAuth
com.mercadopago.mcp
The Mercado Pago MCP Server implements the Model Context Protocol to provide AI agents and LLMs with access to Mercado Pago's APIs and tools within compatible development environments. It acts as an intermediary that translates Mercado Pago resources into executable functions (tools) that AI applications can invoke to perform actions and automate flows. The server simplifies integration, enables using documentation to implement or improve code, and optimizes operations through natural language interactions without manual implementations.
Finance E-commerce & Retail App Automation
2

Related MCP Servers

Browser Control MCP
Browser Automation Agent Orchestration
eyalzh
A
license
Not graded
quality
C
maintenance
An 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.
Updated a month ago (2026-08-23 18:44 UTC)
13 npm
327
MIT
MCP Selenium Server
sapangupta63
A
license
Not graded
quality
D
maintenance
A 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.
Updated a year ago (2025-07-28 10:36 UTC)
1,195 npm
MIT
mcp-browser-kit
Browser Automation Web Scraping App Automation
ndthanhdev
A
license
Not graded
quality
A
maintenance
An MCP Server that enables AI assistants to interact with your local browsers.
Updated 3 days ago (2026-10-05 13:52 UTC)
3,059 npm
55
MIT
FoxBridge MCP
Browser Automation Web Scraping
sinamohsenifar
A
license
C
quality
C
maintenance
Enables 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.
Updated 3 months ago (2026-07-06 17:16 UTC)
52
15 npm
MIT

ruyipage-mcp

特徴

インストール

前提条件

ソースコードからのインストール

GitHubのリンクをAIに渡してインストールを依頼することも可能です

設定

Claude Code

Cursor / その他のMCPクライアント

スタンドアロン実行

設定

設定ファイル

環境変数による上書き

ツール一覧 (34種類)

session — ブラウザのライフサイクル

nav — ページナビゲーション

dom — 要素の検索と読み取り

act — 要素のインタラクション

state — ページ状態

js — JavaScript実行

net — ネットワーク制御

ctx — コンテキスト管理

meta — サーバー情報

コアコンセプト

セッション管理

要素レジストリ

レスポンス形式

関連プロジェクト

アーキテクチャ

利用規約

ライセンス

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Browser Control MCP

MCP Selenium Server

mcp-browser-kit

FoxBridge MCP