MCP Rnw Browser

React Native Web的MCP浏览器服务器

](https://www.npmjs.com/package/@nizarius/mcp-rnw-browser) 

模型上下文协议（MCP）浏览器自动化服务器，专门设计用于 React原生Web 应用。具有多标签支持、屏幕截图功能和持久浏览器会话。

问题

React Native Web使用手势响应系统来监听 mousedown/mouseup 事件而非标准 click 事件。这打破了Playwright等标准浏览器自动化工具 locator.click() 方法。

解决方案

此MCP服务器使用 基于坐标的点击 剧作家的低级水平 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

光标配置

添加到光标MCP设置(~/.cursor/mcp.json 或光标设置>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

获取页面上交互元素的文本快照及其位置。返回元素标签、文本内容、测试ID、角色、位置和单击的中心坐标。

// No parameters required
{}

退货： 所有交互元素及其位置的文本列表。

rnw_screenshot

截取屏幕截图并以base64编码的PNG图像返回。

// Viewport screenshot (default)
{}

// Full page screenshot (captures entire scrollable area)
{ "fullPage": true }

// Element screenshot (captures specific element)
{ "selector": "#my-component" }

退货： Base64编码的PNG图像，AI代理可以直接查看。

交互

rnw_click

使用React Native Web兼容的鼠标事件（mousedown/moseup）单击元素。

// By CSS selector
{ "selector": "button.submit", "findBy": "css" }

// By text content (partial match)
{ "selector": "Sign In", "findBy": "text" }

// By testID (data-testid attribute)
{ "selector": "login-button", "findBy": "testid" }

// By exact coordinates (useful when element detection fails)
{ "x": 500, "y": 300, "findBy": "coordinates" }

退货： 单击坐标和更新的页面快照。

rnw_type

在焦点元素中键入文本，或先找到一个元素并键入。

// Type into currently focused element
{ "text": "Hello World" }

// Find element first, then type (clicks to focus)
{ "text": "Hello World", "selector": "input", "findBy": "css" }

// Type and press Enter (e.g., for search/submit)
{ "text": "Hello World", "selector": "input", "findBy": "css", "pressEnter": true }

退货： 确认键入的文本。

rnw_scroll

滚动页面或特定的可滚动元素。

// Scroll page down by 300 pixels
{ "direction": "down", "amount": 300 }

// Scroll page up
{ "direction": "up", "amount": 500 }

// Scroll within a specific container
{ "direction": "down", "amount": 200, "selector": ".scroll-container" }

参数： direction （上/下/左/右）， amount （像素，默认值：300）， selector （可选）。

退货： 已更新页面快照。

rnw_wait

等待指定的时间或直到页面上出现元素。

// Wait for 1 second (1000ms)
{ "time": 1000 }

// Wait for element to appear (with 5s timeout)
{ "selector": "button.loaded", "findBy": "css" }

// Wait for text to appear
{ "selector": "Loading complete", "findBy": "text" }

退货： 等待完成时确认，超时时出错。

rnw_press_key

按键盘键。可用于导航、表单提交或触发快捷方式。

// Press Enter
{ "key": "Enter" }

// Press Escape
{ "key": "Escape" }

// Press arrow keys
{ "key": "ArrowDown" }

// Press Tab to move focus
{ "key": "Tab" }

常用密钥： 输入、转义、制表符、向上箭头、向下箭头、向左箭头、向右箭头、Backspace、删除、空格。

退货： 确认按键已按下。

rnw_evaluate

在浏览器上下文中执行JavaScript。可用于调试、读取状态或执行自定义交互。

// Get page title
{ "script": "document.title" }

// Get current URL
{ "script": "window.location.href" }

// Read localStorage value
{ "script": "localStorage.getItem('authToken')" }

// Get element count
{ "script": "document.querySelectorAll('button').length" }

// Trigger custom action
{ "script": "window.scrollTo(0, document.body.scrollHeight)" }

退货： 脚本执行的JSON字符串化结果。

选项卡管理

rnw_tabs_list

列出所有打开的浏览器选项卡及其索引、标题和URL。

// No parameters required
{}

退货： 显示索引、活动状态、标题和URL的所有选项卡的列表。

rnw_tabs_new

创建一个新的浏览器选项卡，并可选择导航到URL。新选项卡将成为活动选项卡。

// Create empty new tab (about:blank)
{}

// Create new tab and navigate to URL
{ "url": "http://localhost:8081/settings" }

退货： 新建选项卡索引和页面快照。

rnw_tabs_select

按索引切换到特定选项卡（从0开始）。使用 rnw_tabs_list 查看可用选项卡。

// Switch to second tab
{ "index": 1 }

// Switch to first tab
{ "index": 0 }

退货： 所选选项卡页面的快照。

rnw_tabs_close

关闭浏览器选项卡。如果关闭的选项卡处于活动状态，则切换到最近的剩余选项卡。

// Close current active tab
{}

// Close specific tab by index
{ "index": 2 }

退货： 新活动选项卡的确认和快照。

会话管理

rnw_session_status

获取当前浏览器会话状态。可用于在执行操作之前检查会话是否处于活动状态。

// No parameters required
{}

退货：

• isRunning：浏览器是否处于活动状态
• tabCount：打开的选项卡数量
• currentTabIndex：活动选项卡索引
• currentUrl：活动选项卡的URL
• viewport：浏览器窗口尺寸（宽x高）

rnw_close

关闭浏览器并结束会话。所有选项卡均已关闭，资源已释放。

// No parameters required
{}

退货： 确认浏览器会话已结束。

运作原理

标准剧作家点击（不适用于RNW）

// This dispatches a synthetic 'click' event that RNW ignores
await element.click();

此MCP服务器的点击（与RNW配合使用）

// This triggers real mousedown/mouseup events that RNW responds to
await page.mouse.move(x, y);
await page.mouse.down();
await page.mouse.up();

AI Agent使用示例

Agent: Let me navigate to your React Native Web app, take a screenshot, and click the login button.

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

Page loaded. I can see the following interactive elements:
[0] button testid="login-button"
    text: "Sign In"
    center: (640, 400)

> rnw_screenshot {}

[Returns PNG image of the page]

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

Clicked at (640, 400). The login form is now visible.

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

Created new tab [1] and navigated to settings page.

> rnw_tabs_list {}

Open Tabs (2):
[0] Home - http://localhost:8081/
[1] (active) Settings - http://localhost:8081/settings

连续会话工作流

浏览器会话在工具调用期间持续存在，从而启用：

1. 多步交互 -导航、截图、交互、再次截图
2. 视觉验证 -截图以验证操作后的UI状态
3. 多页工作流 -为复杂的测试场景打开多个选项卡
4. 调试 -使用 rnw_evaluate 检查页面状态

Agent: I'll test the multi-step form submission.

> rnw_navigate { "url": "http://localhost:8081/form" }
> rnw_screenshot {}  // Verify initial state
> rnw_type { "text": "John Doe", "selector": "[data-testid='name-input']", "findBy": "css" }
> rnw_screenshot {}  // Verify text entered
> rnw_click { "selector": "Submit", "findBy": "text" }
> rnw_screenshot {}  // Verify submission result
> rnw_close {}       // End session when done

故障排除

未找到元素

• 确保你的React Native Web组件具有 testID 道具组
• 使用 rnw_snapshot 查看可用元素
• 尝试使用文本内容 findBy: "text"

点击次数未注册

• 确保该元素可见，且未被其他元素覆盖
• 尝试通过以下方式增加延迟 rnw_wait 单击之前
• 如果元素查找失败，则直接使用坐标

截图不起作用

• 确保浏览器会话处于活动状态(rnw_session_status)
• 对于元素截图，请验证选择器是否与可见元素匹配

版本历史

v2.0.0版本

• 添加了base64图像返回的屏幕截图支持
• 添加了多标签管理（列表、新建、选择、关闭）
• 添加会话状态工具
• 改进了工具响应格式
• 持续浏览器会话

v1.0.0

• 与RNW兼容的初始版本点击
• 基本导航、快照和交互工具

许可证

麻省理工学院