MCP Rnw Browser

🚀 React Native Web用MCPブラウザサーバ

React Native Webアプリケーション用に特別に設計された、Model Context Protocol (MCP)ブラウザ自動化サーバです。複数タブのサポート、スクリーンショット機能、および永続的なブラウザセッションを備えています。

🚀 クイックスタート

このMCPサーバは、React Native Webアプリケーションでの自動化を可能にします。標準のブラウザ自動化ツールでは機能しないReact Native Webのジェスチャーレスポンダーシステムに対応しています。

✨ 主な機能

• 座標ベースのクリック - 合成クリックではなく、page.mouse.down() / page.mouse.up()を使用します。
• 複数の要素検索戦略 - CSSセレクター、テキストコンテンツ、testID、または正確な座標を使用して要素を見つけます。
• カスタムページスナップショット - アクセシビリティツリーに依存せず、位置情報を持つインタラクティブな要素を表示します。
• スクリーンショットサポート - AIエージェントが表示できるBase64エンコードされたPNG画像を返します。
• 複数タブ管理 - ブラウザタブの作成、切り替え、および閉じる操作をサポートします。
• 永続的なセッション - ツール呼び出し間でブラウザを開いたままにして、継続的なインタラクションを可能にします。
• 完全なブラウザ制御 - ナビゲート、入力、スクロール、キー押下、JavaScriptの評価などを行えます。

📦 インストール

npmからのインストール

npm install @nizarius/mcp-rnw-browser
npx playwright install chromium

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

git clone https://github.com/nizarius/mcp-rnw-browser.git
cd mcp-rnw-browser
npm install
npm run build
npx playwright install chromium

Cursorの設定

CursorのMCP設定（~/.cursor/mcp.jsonまたはCursor Settings > MCP）に追加します。

npmパッケージを使用する場合（推奨）

{
  "mcpServers": {
    "rnw-browser": {
      "command": "npx",
      "args": ["@nizarius/mcp-rnw-browser"]
    }
  }
}

ローカルインストールを使用する場合

{
  "mcpServers": {
    "rnw-browser": {
      "command": "node",
      "args": ["/path/to/mcp-rnw-browser/dist/index.js"]
    }
  }
}

💻 使用例

ナビゲーション

rnw_navigate

URLにナビゲートします。セッションが存在しない場合は、ブラウザセッションを作成します。

{ "url": "http://localhost:8081" }

戻り値: すべてのインタラクティブな要素を含むページのスナップショット。

スクリーンショットとスナップショット

rnw_snapshot

ページ上のインタラクティブな要素の位置情報を含むテキストスナップショットを取得します。要素のタグ、テキストコンテンツ、testID、ロール、位置、およびクリック用の中心座標を返します。

// パラメータ不要
{}

戻り値: すべてのインタラクティブな要素の位置情報を含むテキストリスト。

rnw_screenshot

スクリーンショットを撮り、Base64エンコードされたPNG画像として返します。

// ビューポートのスクリーンショット（デフォルト）
{}

// 全ページのスクリーンショット（スクロール可能な領域全体をキャプチャ）
{ "fullPage": true }

// 特定の要素のスクリーンショット（特定の要素をキャプチャ）
{ "selector": "#my-component" }

戻り値: AIエージェントが直接表示できるBase64エンコードされたPNG画像。

インタラクション

rnw_click

React Native Web互換のマウスイベント（mousedown/mouseup）を使用して要素をクリックします。

// CSSセレクターによる指定
{ "selector": "button.submit", "findBy": "css" }

// テキストコンテンツによる指定（部分一致）
{ "selector": "Sign In", "findBy": "text" }

// testIDによる指定（data-testid属性）
{ "selector": "login-button", "findBy": "testid" }

// 正確な座標による指定（要素検出が失敗した場合に便利）
{ "x": 500, "y": 300, "findBy": "coordinates" }

戻り値: クリック座標と更新されたページのスナップショット。

rnw_type

フォーカスされた要素にテキストを入力するか、最初に要素を見つけてから入力します。

// 現在フォーカスされている要素に入力
{ "text": "Hello World" }

// 最初に要素を見つけてから入力（クリックしてフォーカスを設定）
{ "text": "Hello World", "selector": "input", "findBy": "css" }

// 入力してEnterキーを押す（例: 検索/送信）
{ "text": "Hello World", "selector": "input", "findBy": "css", "pressEnter": true }

戻り値: 入力されたテキストの確認。

rnw_scroll

ページまたは特定のスクロール可能な要素をスクロールします。

// ページを下に300ピクセルスクロール
{ "direction": "down", "amount": 300 }

// ページを上にスクロール
{ "direction": "up", "amount": 500 }

// 特定のコンテナ内をスクロール
{ "direction": "down", "amount": 200, "selector": ".scroll-container" }

パラメータ: direction（up/down/left/right）、amount（ピクセル、デフォルト: 300）、selector（オプション）。

戻り値: 更新されたページのスナップショット。

rnw_wait

指定された時間または要素がページに表示されるまで待機します。

// 1秒（1000ms）待機
{ "time": 1000 }

// 要素が表示されるまで待機（5秒のタイムアウト）
{ "selector": "button.loaded", "findBy": "css" }

// テキストが表示されるまで待機
{ "selector": "Loading complete", "findBy": "text" }

戻り値: 待機が完了したことの確認、またはタイムアウトした場合はエラー。

rnw_press_key

キーボードのキーを押します。ナビゲーション、フォーム送信、またはショートカットのトリガーに役立ちます。

// Enterキーを押す
{ "key": "Enter" }

// Escapeキーを押す
{ "key": "Escape" }

// 矢印キーを押す
{ "key": "ArrowDown" }

// Tabキーを押してフォーカスを移動
{ "key": "Tab" }

一般的なキー: Enter、Escape、Tab、ArrowUp、ArrowDown、ArrowLeft、ArrowRight、Backspace、Delete、Space。

戻り値: 押されたキーの確認。

rnw_evaluate

ブラウザコンテキストでJavaScriptを実行します。デバッグ、状態の読み取り、またはカスタムインタラクションの実行に便利です。

// ページのタイトルを取得
{ "script": "document.title" }

// 現在のURLを取得
{ "script": "window.location.href" }

// localStorageの値を読み取る
{ "script": "localStorage.getItem('authToken')" }

// 要素の数を取得
{ "script": "document.querySelectorAll('button').length" }

// カスタムアクションをトリガー
{ "script": "window.scrollTo(0, document.body.scrollHeight)" }

戻り値: スクリプト実行の結果をJSON文字列化したもの。

タブ管理

rnw_tabs_list

すべての開いているブラウザタブのインデックス、タイトル、およびURLをリストします。

// パラメータ不要
{}

戻り値: すべてのタブのインデックス、アクティブ状態、タイトル、およびURLを示すリスト。

rnw_tabs_new

新しいブラウザタブを作成し、必要に応じてURLにナビゲートします。新しいタブがアクティブタブになります。

// 空の新しいタブを作成（about:blank）
{}

// 新しいタブを作成してURLにナビゲート
{ "url": "http://localhost:8081/settings" }

戻り値: 新しいタブのインデックスとページのスナップショット。

rnw_tabs_select

インデックス（0から始まる）で特定のタブに切り替えます。利用可能なタブを確認するには、rnw_tabs_listを使用します。

// 2番目のタブに切り替え
{ "index": 1 }

// 1番目のタブに切り替え
{ "index": 0 }

戻り値: 選択されたタブのページのスナップショット。

rnw_tabs_close

ブラウザタブを閉じます。閉じたタブがアクティブだった場合、最も近い残りのタブに切り替えます。

// 現在のアクティブなタブを閉じる
{}

// 特定のインデックスのタブを閉じる
{ "index": 2 }

戻り値: 確認と新しいアクティブなタブのスナップショット。

セッション管理

rnw_session_status

現在のブラウザセッションの状態を取得します。アクションを実行する前にセッションがアクティブかどうかを確認するのに便利です。

// パラメータ不要
{}

戻り値:

• isRunning: ブラウザがアクティブかどうか
• tabCount: 開いているタブの数
• currentTabIndex: アクティブなタブのインデックス
• currentUrl: アクティブなタブのURL
• viewport: ブラウザウィンドウの寸法（幅 x 高さ）

rnw_close

ブラウザを閉じ、セッションを終了します。すべてのタブが閉じられ、リソースが解放されます。

// パラメータ不要
{}

戻り値: ブラウザセッションが終了したことの確認。

📚 詳細ドキュメント

標準のPlaywrightクリック（RNWでは機能しない）

// これは合成の'click'イベントをディスパッチし、RNWは無視します
await element.click();

このMCPサーバのクリック（RNWで機能する）

// これはRNWが反応する実際のmousedown/mouseupイベントをトリガーします
await page.mouse.move(x, y);
await page.mouse.down();
await page.mouse.up();

AIエージェントを使用した例

エージェント: React Native Webアプリにナビゲートし、スクリーンショットを撮り、ログインボタンをクリックします。

> rnw_navigate { "url": "http://localhost:8081" }

ページが読み込まれました。次のインタラクティブな要素が見えます:
[0] button testid="login-button"
    text: "Sign In"
    center: (640, 400)

> rnw_screenshot {}

[ページのPNG画像が返されます]

> rnw_click { "selector": "login-button", "findBy": "testid" }

(640, 400)でクリックしました。ログインフォームが表示されました。

> rnw_tabs_new { "url": "http://localhost:8081/settings" }

新しいタブ[1]を作成し、設定ページにナビゲートしました。

> rnw_tabs_list {}

開いているタブ (2):
[0] Home - http://localhost:8081/
[1] (active) Settings - http://localhost:8081/settings

継続的なセッションワークフロー

ブラウザセッションはツール呼び出し間で保持され、以下のことが可能です:

1. 多段階のインタラクション - ナビゲート、スクリーンショット、インタラクション、再度スクリーンショット
2. 視覚的な検証 - アクション後のUI状態を検証するためにスクリーンショットを撮る
3. 多ページのワークフロー - 複雑なテストシナリオのために複数のタブを開く
4. デバッグ - rnw_evaluateを使用してページの状態を検査する

エージェント: 多段階のフォーム送信をテストします。

> rnw_navigate { "url": "http://localhost:8081/form" }
> rnw_screenshot {}  // 初期状態を検証
> rnw_type { "text": "John Doe", "selector": "[data-testid='name-input']", "findBy": "css" }
> rnw_screenshot {}  // 入力されたテキストを検証
> rnw_click { "selector": "Submit", "findBy": "text" }
> rnw_screenshot {}  // 送信結果を検証
> rnw_close {}       // 完了したらセッションを終了

トラブルシューティング

要素が見つからない場合

• React Native WebコンポーネントにtestIDプロパティが設定されていることを確認してください。
• rnw_snapshotを使用して利用可能な要素を確認してください。
• findBy: "text"を使用してテキストコンテンツで要素を検索してみてください。

クリックが登録されない場合

• 要素が表示され、他の要素に覆われていないことを確認してください。
• クリックする前にrnw_waitで遅延を増やしてみてください。
• 要素検出が失敗した場合は、直接座標を使用してみてください。

スクリーンショットが機能しない場合

• ブラウザセッションがアクティブであることを確認してください（rnw_session_status）。
• 要素のスクリーンショットの場合は、セレクターが表示されている要素と一致することを確認してください。

バージョン履歴

v2.0.0

• Base64画像を返すスクリーンショットサポートを追加
• 複数タブ管理（リスト、新規作成、選択、閉じる）を追加
• セッション状態ツールを追加
• ツールの応答形式を改善
• 永続的なブラウザセッション

v1.0.0

• RNW互換のクリック機能を持つ初期リリース
• 基本的なナビゲート、スナップショット、およびインタラクションツール

📄 ライセンス

MIT