MCP Rnw Browser

🚀 React Native Web的MCP瀏覽器服務器

這是一個專門為 React Native Web 應用程序設計的模型上下文協議（MCP）瀏覽器自動化服務器。它支持多標籤頁、具備截圖功能，並且能保持持久的瀏覽器會話。

🚀 快速開始

React Native Web 使用手勢響應系統，監聽 mousedown/mouseup 事件，而非標準的 click 事件，這導致像 Playwright 的 locator.click() 這類標準瀏覽器自動化工具無法正常工作。而本 MCP 服務器使用 Playwright 的底層 page.mouse API 進行 基於座標的點擊，能夠正確觸發 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 設置 > 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（上/下/左/右），amount（像素，默認值：300），selector（可選）。

返回值：更新後的頁面快照。

rnw_wait

等待指定時間或直到元素出現在頁面上。

// 等待 1 秒（1000 毫秒）
{ "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 查看可用標籤頁。

// 切換到第二個標籤頁
{ "index": 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"
    文本："Sign In"
    中心座標：(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] 主頁 - http://localhost:8081/
[1]（活動）設置 - 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 許可證。