Browserose MCP

Browserose MCP

MCP代理工具，用于控制谷歌Chrome浏览器。

Browserose MCP是一个MCP（模型上下文协议）服务器，允许AI代理和IDE进行控制 谷歌浏览器 通过剧作家，与完整 iframe支持：在iframe内进行快照和交互（例如ALM SCORM播放器、嵌入式应用程序）。

该工具集足以实现完全的端到端自动化。 您可以完成整个流程——登录、多步导航、嵌套iframe、测验和课程完成——而无需手动步骤或切换选项卡。根据需要使用导航、定位器、帧选择器、坐标回退和诊断。

需求

• Node.js 18+
• Chrome已安装（或已设置 PLAYWRIGHT_MCP_USE_CHROMIUM=1 使用铬）
• 剧作家浏览器： npx playwright install chromium （或 chrome 如果可用）

安装和构建

npm install
npx playwright install chromium
npm run build

光标/IDE配置

增添 ~/.cursor/mcp.json （或项目 .cursor/mcp.json):

{
  "mcpServers": {
    "playwright-chrome": {
      "command": "node",
      "args": ["/absolute/path/to/Browserose-MCP/build/index.js"]
    }
  }
}

编辑后重新启动游标 mcp.json.

环境变量

• PLAYWRIGHT_MCP_HEADLESS --设置为 1 或 true 无头运行浏览器（默认：headed以便看到窗口）。
• PLAYWRIGHT_MCP_USE_CHROMIUM --设置为 1 或 true 使用Playwright的Chromium而不是系统Chrome。
• PLAYWRIGHT_MCP_VIEWPORT_MAXIMIZED --窗口打开 默认最大化。设置为 0 或 false 使用固定尺寸（见下面的宽度/高度）。
• PLAYWRIGHT_MCP_VIEWPORT_WIDTH --视口宽度（像素）（默认值： 1280).仅在禁用最大化时使用。
• PLAYWRIGHT_MCP_VIEWPORT_HEIGHT --视口高度（像素）（默认值： 800).仅在禁用最大化时使用。

示例： 要使用固定大小而不是最大化，请设置 PLAYWRIGHT_MCP_VIEWPORT_MAXIMIZED=0 并且可选 PLAYWRIGHT_MCP_VIEWPORT_WIDTH=1920, PLAYWRIGHT_MCP_VIEWPORT_HEIGHT=1080.

弹出处理程序

当链接或按钮打开时 新标签页 （例如。 转到活动 在IBM SkillsBuild上，将在新窗口中打开SCORM播放器），MCP 自动附加到该新选项卡浏览器上下文监听 page 事件；当创建新页面时，内部 page 参考已更新，以便 所有后续工具调用（导航、单击、快照、frame_probe等）都在新选项卡中运行不是原来的那个。您不需要手动切换选项卡或使用单独的“切换到选项卡”工具：单击 转到活动，等待播放器加载，然后继续使用相同的工具——它们将已经指向播放器选项卡。实现：in src/browser.ts, context.on("page", (newPage) => { page = newPage; }) 在每个新页面上运行（弹出或目标=\_blank）。在拉取更改后重新启动MCP服务器（或Cursor），使处理程序处于活动状态。

工具（快速参考）

______________________________________________________________________

工具参考和用例

每个工具的详细说明以及何时使用。可选 frameSelector 用途 >> 对于嵌套的iframe（例如。 iframe#a >> iframe#b).

导航

基于快照和引用的交互

这些工具使用可访问性/DOM快照来获取 参考文献 （例如。 s1e2).然后，您可以将该引用传递给单击、键入、悬停或选择。当页面（或iframe）具有相同的来源并具有正常的DOM时，效果最佳。

基于定位器的交互（无快照）

这些工具使用Playwright定位器（角色+名称、文本或css）和 不需要快照。它们在跨源iframe中工作，当引用不可用或快照为空时，它们是主要的逃逸窗口。

按情况定制： 使用 nth 当多个元素匹配时（例如，名为“提交”的第四个按钮）。使用 enabledOnly 单击第一个 启用 当DOM有多个禁用副本时，进行匹配。使用 scopeCss 将搜索限制在容器内（例如。 .quiz-card, [role="dialog"])因此，您不会在侧边栏或其他面板中匹配相同的文本或角色。

基于坐标的交互（逃生口）

当快照和定位器都失败时（例如画布、自定义渲染UI或错误的帧深度），请使用相对于帧的坐标。

诊断（找到正确的帧/层）

当一个框架在快照中没有显示按钮或空文本时，真正的UI通常位于 子iframe, 画布，或 阴影DOM。这些工具可以帮助你找到它。

效用

______________________________________________________________________

实践中的用例

• 普通web自动化（主页）\

使用 browser_snapshot （或 browser_snapshot_frame 无嵌套/最小嵌套）以获取引用，然后 browser_click, browser_type, browser_hover, browser_select_option 与这些裁判。可选的 browser_screenshot 用于验证。

• 登录流程\

通常在主页上： browser_type_locator 和 browser_click_locator 随着 role/name 或 text （例如电子邮件→ 继续→ 密码→ 登录）。不需要快照。

• 单一iframe，同源\

browser_snapshot_frame 随着 frameSelector: "iframe#id" → 获取参考文献→ browser_click / browser_type 与相同 frameSelector.

• 跨源或“空”iframe\

快照可能为空或引用可能不起作用。请使用 定位器: browser_list_clickables 随着 frameSelector 那么，看看那里有什么 browser_click_locator 和 browser_type_locator 与相同 frameSelector 以及角色/文本/css。

• ALM/SCORM（嵌套iframe）\

可见的课程UI通常位于 三级 iframe。如果 browser_frame_probe 上 iframe#pplayer_iframe >> iframe#modulePlayerIframe 显示 clickables: 0，跑 browser_frame_inventory 在那条链子上；它将列出子iframe（例如。 iframe#content-frame).将链条延伸至 ... >> iframe#content-frame 和使用 browser_list_clickables 和 browser_click_locator （例如。 role: "button", name: "Next")在那里。一句话：当框架没有DOM内容时，使用 框架_库存 要找到真正的内容iframe，然后将其添加到链中。

• 画布或自定义渲染UI\

如果frame_inventory显示了一个大画布，但没有有用的iframe，或者定位器不匹配：使用 browser_click_at_rel_debug 看看（rx，ry）降落在哪里，然后 browser_click_at_rel 调整后的（rx，ry），或 browser_frame_bbox + browser_click_at 计算（x，y）。

• 测验/多个相同按钮\

当存在多个“提交”或“下一步”按钮，但只有一个被启用时，使用 browser_click_locator 随着 enabledOnly: true （同样 role/name)因此，第一个启用的匹配被点击。或使用 browser_list_clickables 随着 role: "button", name: "SUBMIT" （以及可选 enabledOnly: true)要查看索引，请单击 nth.使用 scopeCss （例如。 .quiz-card)仅限于当前问题卡，避免与侧边栏匹配。

• 调试“点击不起作用”\

检查：（1）框架是否正确？ → browser_frame_probe 和 browser_frame_inventory（2）正确的元素？ → browser_list_clickables 在该框架内； browser_hit_test_rel 看看下面是什么（rx，ry）。（3）正确的坐标？ → browser_click_at_rel_debug（4）多场比赛？ → use nth 或 enabledOnly.

______________________________________________________________________

端到端：IBM技能构建/ALM课程

您可以仅使用Browserose MCP工具运行整个课程流程：从IBM页面到登录、学习计划、启动活动以及完成课程和测验。

1.从IBM页面开始并登录

• 导航 转到课程或计划URL（例如。 https://skills.yourlearning.ibm.com/activity/PLAN-...).
• 如果重定向到登录： browser_click_locator 随着 text: "Log in with ibm" （或同等）。在IBM登录页面上：

- browser_type_locator 随着 role: "textbox", name: "IBMid"，以及电子邮件。 - browser_click_locator 随着 role: "button", name: "Continue". - browser_type_locator 随着 role: "textbox", name: "Password"，以及密码。 - browser_click_locator 随着 role: "button", name: "Log in".

• 使用 browser_wait 和 browser_screenshot 根据需要确认下一页。

2.打开学习计划和模块

• 从计划页面： browser_click_locator 随着 text: "Microcredential 1: Data Classification" （或右侧部分）。
• 然后 browser_click_locator 随着 text: "Classifying and Sourcing Data" （或目标模块）。
• 启动活动： browser_click_locator 随着 role: "button", name: "Go to activity".
• 等待玩家： 点击 转到活动 可以打开SCORM播放器 新标签页MCP会自动附加到新选项卡（弹出处理程序），因此下一个工具调用将在播放器选项卡中运行。使用 browser_wait （例如5-8秒），然后 browser_frame_probe 或 browser_frame_inventory 上 iframe#pplayer_iframe （然后 iframe#pplayer_iframe >> iframe#modulePlayerIframe 如果需要），直到内容帧出现。可见的课程UI位于 内容框架:\

iframe#pplayer_iframe >> iframe#modulePlayerIframe >> iframe#content-frame

3.内容框架：课程和“继续”

• 继续/下一步（内容）：\

browser_click_locator 随着 frameSelector: "iframe#pplayer_iframe >> iframe#modulePlayerIframe >> iframe#content-frame", css: "button.continue-btn".

• 使用 browser_list_clickables 说完这个 frameSelector 发现按钮（例如“下一步”、“继续”）。使用 browser_screenshot 说完这个 frameSelector 当你需要看到屏幕上的内容时。

4.练习题：两遍策略

最快的通过方式是：（1）第一次通过——任意回答，提交， 从反馈中读取正确答案，记住它；2. 再来一次（3）第二遍——用记住的正确选项作答并提交。

• 开始或重新开始测验：\

browser_click_locator 在内容框架中 text: "START QUIZ" 或 text: "TAKE AGAIN".

• 选择一个选项：\

如果定位器像 #qmc-X-label 被覆盖物覆盖，使用 browser_click_at_rel 在内容框架中，例如。 rx: 0.5，以及 ry 大致：第一个选项~0.48-0.52，第二个选项~0.56-0.6，第三个选项~0.64-0.68（如果布局不同，请调整）。或使用 browser_hit_test_rel / browser_click_at_rel_debug 以确认。

• 提交：\

browser_click_locator 在内容框架中 role: "button", name: "SUBMIT", enabledOnly: true （因此单击了活动的SUBMIT）。

• 阅读反馈：\

提交后，使用 browser_frame_probe 在内容框架上阅读 textSample （或使用 browser_screenshot)获取“正确答案：…”，并按问题索引（Q1、Q2、…）存储。

• 下一个问题：\

browser_click_at_rel 在内容框架中 rx: 0.65, ry: 0.85 （下一步按钮区域）。重复直到测验完成（不再提交或看到完成）。

• 第二遍：\

点击 再来一次，然后对于每个问题，单击与存储的正确答案匹配的选项（通过 ry 如果正确的选项文本是可点击的，则通过标签或定位器）， 提交，然后单击（0.65，0.85）进行下一步，直到测验完成。

5.完成测验并完成模块后

• 测验完成后，使用 browser_click_locator 在内容框架中 css: "button.continue-btn" （或等效）继续下一课或关闭模块。
• 在后续的课程和测验中重复相同的模式，直到模块/课程标记为完成。

摘要： 所有步骤——登录、计划导航、“进入活动”、等待玩家、继续上课、测验（两次通过，包括阅读反馈和重新开始）和完成——都可以用现有的工具（导航、点击指示器、键入指示器、列表可选项、frame_probe、frame_inventory、点击_at_rel、截图、等待）完成。无需手动切换标签或使用外部工具。

______________________________________________________________________

使用iframe（包括跨源/ALM SCORM）

1. 导航到包含iframe的页面（例如ALM课程页面）。
2. 呼叫 browser_snapshot 随着 includeFrames: true 获取主页和同源iframe，或调用 browser_snapshot_frame 随着 frameSelector: "iframe" （或 iframe#id)只得到那帧的树。
3. 使用返回的参考值 browser_click, browser_type，等等，并通过相同的 frameSelector。对于嵌套的iframe，使用链式选择器 >>例如。 iframe#pplayer_iframe >> iframe#modulePlayerIframe.

示例：在第一个iframe中单击“下一步”：

• browser_snapshot_frame 随着 frameSelector: "iframe" → 获取“下一步”按钮的参考（例如。 f1e2).
• browser_click 随着 ref: "f1e2", frameSelector: "iframe".

逃生舱（交叉起点/SCORM）： 对于快照失败的帧，直接使用Playwright定位器（无AX/DOMSnapshot）：

• browser_list_clickables 随着 frameSelector: "iframe#pplayer_iframe >> iframe#modulePlayerIframe" → 列出带有文本和启用/禁用的按钮/链接。
• ALM烧焦： 可见的课程UI（例如“下一步”、“学习目标”）位于 三级 iframe。使用 browser_frame_inventory 上 iframe#pplayer_iframe >> iframe#modulePlayerIframe 查看子iframe；然后链接到内容帧： iframe#pplayer_iframe >> iframe#modulePlayerIframe >> iframe#content-frame.使用该选择器 browser_list_clickables 和 browser_click_locator （例如。 role: "button", name: "Next").
• browser_click_locator 与相同 frameSelector 和 role: "button", name: "Next" （或 text: "Next") → 单击元素。之所以有效，是因为剧作家直接针对画面的背景。

交叉原点/SCORM（AX树为空）： 服务器还对帧使用3层快照：

1. A级 --CDP Accessibility.getFullAXTree （参考文献 backendDOMNodeId；通过框模型单击）。
2. B级 --如果AX为空，CDP DOMSnapshot.captureSnapshot （参考视口坐标；单击通过 Input.dispatchMouseEvent).
3. C级 --使用 browser_screenshot 随着 frameSelector那么 browser_click_at 与相同 frameSelector 和 (x, y) 按坐标单击（例如画布或AX和DOM快照都失败时）。

______________________________________________________________________

许可证和作者

• 许可证： 这个项目是 开源.自由使用和修改。
• 开发商： 埃塔利·奥马尔