Browser Ops MCP

浏览器操作系统mcp

browser-ops-mcp 是一个由Playwright驱动的CLI和MCP服务器，用于稳定的浏览器自动化。它使本地守护进程保持活动状态，以便代理可以打开页面、拍摄结构化快照、通过以下方式进行交互 snapshotId + ref，提取内容，并继续执行，而无需在每个命令上重建状态。

browser-ops architecture

为什么是现在

• 人工智能代理现在在浏览器中花费了大量时间，但大多数浏览器自动化仍然会因选择器漂移和状态丢失而崩溃。
• MCP生态系统使得在不重复逻辑的情况下向人类和代理暴露相同的能力变得切实可行。
• 这个回购倾向于2026年仍然痛苦的部分：一个稳定的快照合约，在页面突变后保持交互的确定性。

现场实例

存储库包括演示夹具的可复制示例输出：

• examples/demo-snapshot.json
• examples/demo-extract-text.json

设计选择

• snapshotId + ref 是主要的交互模型，而不是自由形式的CSS选择器。
• CLI和MCP共享相同的守护进程和操作层，因此它们不能分开。
• 快照输出首先是可访问性，并且有意地小到足以在终端中检查。
• 修改操作会立即使之前的快照无效，这会使过时的引用快速失败，而不是默默地对错误的元素进行操作。
• extract 故意狭窄。它回来了 text, markdown, links，或 forms 而不是试图成为一个通用的抓取引擎。

比较

安装

npm install
npm run build
npx playwright install chromium

或者在发布后全局安装：

npm install -g @aeewws/browser-ops-mcp
browser-ops --help

快速入门

browser-ops-mcp 针对代理循环进行了优化，其中每个浏览器操作都是 基于一个新的、可检查的快照：

1. 打开目标页面；
2. 请求可访问性优先快照；
3. 通过行动 snapshotId + ref;
4. 每次突变后再拍一张快照；
5. 提取最小的有用结果。

打开页面：

browser-ops open https://example.com

快照当前交互元素：

browser-ops snapshot

与新的参考文献互动：

browser-ops fill r1 "Ada Lovelace" --snapshot snap_123
browser-ops snapshot
browser-ops click r4 --snapshot snap_456
browser-ops wait --text "Submitted"
browser-ops extract --mode text
browser-ops screenshot --path ./browser-ops.png
browser-ops close

运行MCP服务器：

browser-ops serve-mcp

MCP客户端配置

对于接受JSON样式服务器定义的本地MCP客户端，请连接 构建包后，将服务器作为stdio命令：

{
  "mcpServers": {
    "browser-ops": {
      "command": "node",
      "args": ["./dist/cli/index.js", "serve-mcp"],
      "cwd": "/absolute/path/to/browser-ops-mcp"
    }
  }
}

如果软件包是全局安装的，则命令可以更短：

{
  "mcpServers": {
    "browser-ops": {
      "command": "browser-ops",
      "args": ["serve-mcp"]
    }
  }
}

代理任务模式

• Web应用程序质量保证： 打开本地预览、快照控件、提交表单、等待

对于成功标记，然后提取文本作为证据。

• 文件检查： 访问生成的文档，提取链接，并失败

缺少所需页面或锚点时的工作流。

• 传统管理流程： 在多个操作中保持会话活动，而无需

强制代理在每个命令后重建浏览器状态。

• 人类可读的切换： 保存屏幕截图和最新快照JSON，以便

审阅者可以看到代理实际执行的操作。

命令

• open ：在默认会话中打开URL
• snapshot：使用以下命令生成结构化页面快照 sessionId, snapshotId, url, title，以及 elements[]
• click --snapshot ：单击最新快照中的元素
• fill --snapshot ：填写输入或文本区域
• select --snapshot ：在中选择一个选项 ``
• wait：等待文本、URL片段或持续时间
• extract：提取物 text, markdown, links，或 forms
• screenshot：保存PNG屏幕截图
• close：关闭活动浏览器会话
• serve-mcp：通过stdio运行MCP服务器

MCP工具

• open_page
• snapshot_page
• click_element
• fill_element
• select_option
• wait_for
• extract_content
• take_screenshot
• close_session

MCP工具有意镜像CLI操作层。这使得守护进程得以保留， 快照无效规则、提取模式和截图行为相同 无论是人工通过终端进行调试，还是代理调用工具。

快照合同

每一次互动都与一个特定的 snapshotId。一旦页面发生突变 click, fill，或 select，旧快照将过时，下一个命令必须使用新快照。

每个快照元素包括：

{
  "ref": "r1",
  "role": "button",
  "name": "Submit",
  "text": "Submit",
  "value": "",
  "disabled": false
}

它不是什么

• 它不是一个云浏览器农场。
• 它不是验证码求解器。
• 它不是一个通用的scraper或完整的浏览器测试平台。
• 它并没有试图取代剧作家本身。

发展

npm install
npm run build
npm run typecheck
npm test

烟雾测试打开 tests/fixtures/demo.html 使用Playwright，填写表单，提交表单，并验证提取的文本。

如果Playwright已更新，但本地浏览器缓存缺失，则完整 测试套件要求下载Chromium。在小型系统驱动器上，运行 npm run typecheck 首先，仅在需要时安装浏览器缓存 端到端浏览器测试。

发布说明

v0.1.0

• 围绕同一Playwright支持的操作添加第一个CLI和MCP服务器

层。

• 定义 snapshotId + ref 确定性代理的交互契约

浏览器操作。

• 包括可重复的演示输出、烟雾测试、包装检查和CI。

局限性

• v1是单用户，仅限本地
• 它不承诺CAPTCHA解决方案
• 支持带头会话，但守护进程仍然一次假定一个活动会话ID
• 目前的快照模型是故意保守的；复杂的页面可能需要更有针对性的选择器或后续快照。