Better Playwright MCP

🚀 better-playwright-mcp

better-playwright-mcp 是一个更出色的 Playwright MCP（模型上下文协议）服务器，采用客户端 - 服务器架构实现浏览器自动化。它通过创新的语义快照算法，能将页面内容减少多达 90%，同时保留所有有意义的元素，有效解决了传统浏览器自动化工具常面临的令牌限制问题。

🚀 快速开始

安装

npm install -g better-playwright-mcp

运行

默认模式（MCP）

MCP 服务器需要 HTTP 服务器运行。你需要启动这两个服务器： 步骤 1：启动 HTTP 服务器

npx better-playwright-mcp server

步骤 2：在另一个终端中，启动 MCP 服务器

npx better-playwright-mcp

MCP 服务器将：

1. 开始在标准输入输出上监听 MCP 协议消息。
2. 连接到端口 3102 上的 HTTP 服务器。
3. 通过 HTTP 服务器路由浏览器自动化命令。

独立 HTTP 服务器模式

你也可以独立运行 HTTP 服务器（这对于调试或自定义集成很有用）：

npx better-playwright-mcp server

选项：

• -p, --port <number> - 服务器端口（默认：3102）
• --host <string> - 服务器主机（默认：localhost）
• --headless - 以无头模式运行浏览器
• --chromium - 使用 Chromium 而不是 Chrome
• --no-user-profile - 不使用持久用户配置文件
• --user-data-dir <path> - 用户数据目录
• --snapshot-dir <path> - 保存快照的目录

✨ 主要特性

• 🎯 通过语义 HTML 快照减少 90% 的令牌使用。
• 🎭 通过 MCP 实现完整的 Playwright 浏览器自动化。
• 🏗️ 客户端 - 服务器架构，更好地分离关注点。
• 🛡️ 隐身模式，避免被检测。
• 📍 基于哈希的元素标识符，实现精确目标定位。
• 💾 持久的浏览器配置文件。
• 🚀 针对长时间运行的自动化任务进行优化。
• 📊 支持令牌感知输出，并自动截断。

📦 安装指南

npm install -g better-playwright-mcp

💻 使用示例

基础用法

创建和导航页面

// MCP 工具使用
{
  "tool": "createPage",
  "arguments": {
    "name": "shopping",
    "description": "Amazon shopping page",
    "url": "https://amazon.com"
  }
}

// 返回: { pageId: "uuid", snapshot: "..." }

与元素交互

// 使用 xp 标识符点击元素
{
  "tool": "browserClick",
  "arguments": {
    "pageId": "uuid",
    "ref": "3fa2b8c1"  // 快照中的 xp 属性值
  }
}

// 在输入字段中输入文本
{
  "tool": "browserType",
  "arguments": {
    "pageId": "uuid",
    "ref": "xp456",
    "text": "search query",
    "submit": true  // 输入后按 Enter 键
  }
}

捕获页面状态

// 获取语义快照
{
  "tool": "getPageSnapshot",
  "arguments": {
    "pageId": "uuid"
  }
}

// 截图
{
  "tool": "getScreenshot",
  "arguments": {
    "pageId": "uuid",
    "fullPage": true,
    "type": "png"
  }
}

📚 详细文档

MCP 工具

当与 AI 助手一起使用时，可使用以下工具：

页面管理

• createPage - 创建一个带有名称和描述的新浏览器页面。
• activatePage - 通过 ID 激活特定页面。
• closePage - 关闭特定页面。
• listPages - 列出所有管理的页面及其标题和 URL。
• closeAllPages - 关闭所有管理的页面。
• listPagesWithoutId - 列出未管理的浏览器页面。
• closePagesWithoutId - 关闭所有未管理的页面。
• closePageByIndex - 按索引关闭页面。

浏览器操作

• browserClick - 使用元素的 xp 标识符点击元素。
• browserType - 在元素中输入文本。
• browserHover - 悬停在元素上。
• browserSelectOption - 在下拉菜单中选择选项。
• browserPressKey - 按下键盘键。
• browserFileUpload - 上传文件到文件输入框。
• browserHandleDialog - 处理浏览器对话框（警告、确认、提示）。
• browserNavigate - 导航到 URL。
• browserNavigateBack - 返回上一页。
• browserNavigateForward - 前进到下一页。
• scrollToBottom - 滚动到页面/元素底部。
• scrollToTop - 滚动到页面/元素顶部。
• waitForTimeout - 等待指定的毫秒数。
• waitForSelector - 等待元素出现。

快照和实用工具

• getPageSnapshot - 获取带有 xp 标识符的语义 HTML 快照。
• getScreenshot - 截图（PNG/JPEG）。
• getPDFSnapshot - 生成页面的 PDF。
• getElementHTML - 获取特定元素的 HTML。
• downloadImage - 从 URL 下载图像。
• captureSnapshot - 通过自动滚动捕获全页。

工作原理

语义快照的实际应用

原始 HTML

<div class="wrapper" style="padding: 20px; margin: 10px;">
  <div class="container">
    <div class="inner">
      <button class="btn btn-primary" onclick="handleClick()" 
              style="background: blue; color: white;">
        Click me
      </button>
    </div>
  </div>
</div>

语义快照

button xp=3fa2b8c1 Click me

该算法：

• 移除不必要的包装 div。
• 去除内联样式和事件处理程序。
• 添加唯一标识符（xp 属性） - 元素 XPath 的哈希值。
• 仅保留有意义的内容。

基于差异的优化

为了减少数据传输和令牌使用：

• 第一个快照始终是完整的。
• 后续快照仅包含更改（差异）。
• 自动缓存以提高性能。

隐身功能

浏览器实例配置了：

• 自定义用户代理字符串。
• 禁用自动化指示符。
• WebGL 供应商欺骗。
• Canvas 指纹保护。

🔧 技术细节

问题所在

• 全页 HTML 通常超过 100K+ 令牌。
• 大多数 HTML 是噪声：内联样式、跟踪脚本、不可见元素。
• AI 助手的上下文窗口有限（即使有 200K 限制）。
• 仅加载几页后，复杂的网页自动化就变得不可能。

解决方案：语义快照

我们的核心创新是一种多阶段修剪算法，它：

1. 识别有意义的元素 - 交互式元素（按钮、输入框）、语义 HTML5 标签和包含文本的元素。
2. 生成唯一标识符 - 每个元素都有一个基于哈希的 xp 属性，该属性源自其 XPath，用于精确目标定位。
3. 移除不可见内容 - 标记并移除具有 display:none、零尺寸或隐藏父元素的元素。
4. 解开无用的包装器 - 消除仅包装其他元素的 div 和 span。
5. 去除不必要的属性 - 仅保留必要的属性，如 href、value、placeholder。

结果：一个简洁、语义化的表示，通常只使用原始令牌的 10%，同时保持完整功能。

架构

本项目实现了独特的两层架构：

1. MCP 服务器 - 通过模型上下文协议与 AI 助手通信。
2. HTTP 服务器 - 在后台运行以控制实际的浏览器实例。

AI 助手 <--[MCP 协议]--> MCP 服务器 <--[HTTP]--> HTTP 服务器 <---> 浏览器

这种设计允许 MCP 服务器保持轻量级，同时将浏览器控制委托给专用的 HTTP 服务。

开发

先决条件

• Node.js >= 18.0.0
• TypeScript
• Chrome 或 Chromium 浏览器

从源代码构建

# 克隆仓库
git clone https://github.com/yourusername/better-playwright-mcp.git
cd better-playwright-mcp

# 安装依赖
npm install

# 构建项目
npm run build

# 在开发模式下运行
npm run dev

项目结构

better-playwright-mcp/
├── src/
│   ├── index.ts                 # MCP 模式入口点
│   ├── server.ts                # HTTP 服务器模式入口点
│   ├── playwright-mcp.ts        # MCP 服务器实现
│   ├── client/
│   │   └── playwright-client.ts # MCP→HTTP 通信的 HTTP 客户端
│   ├── server/
│   │   └── playwright-server.ts # 控制浏览器的 HTTP 服务器
│   ├── extractor/
│   │   ├── parse2.ts           # 生成 xp 标识符的 HTML 解析
│   │   ├── simplify-html.ts    # HTML 简化
│   │   └── utils.ts            # 提取实用工具
│   └── utils/
│       └── token-limiter.ts    # 令牌计数和限制
├── bin/
│   └── cli.js                  # CLI 入口点
├── package.json
├── tsconfig.json
├── CLAUDE.md                   # AI 助手说明
└── README.md

故障排除

常见问题

1. MCP 服务器无法连接

   • 确保 HTTP 服务器在端口 3102 上可访问。
   • 检查防火墙设置。
   • 尝试使用 DEBUG=* npx better-playwright-mcp 运行。

2. 浏览器无法启动

   • 确保安装了 Chrome 或 Chromium。
   • 尝试使用 --chromium 标志。
   • 检查系统资源。

3. 令牌限制超出

   • 快照会自动截断为 20,000 令牌。
   • 使用目标选择器减少快照大小。
   • 考虑使用截图而不是快照进行视觉检查。

调试模式

启用详细日志记录：

DEBUG=* npx better-playwright-mcp

日志和记录

操作记录保存到：

• macOS/Linux: /tmp/playwright-records/
• Windows: %TEMP%\playwright-records\

每个页面都有自己的目录，其中包含带时间戳的操作日志。

贡献

欢迎贡献！请随时提交拉取请求。

📄 许可证

MIT