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