Playwright Web Browser

🚀 Playwright MCP 服務器

該項目是一個使用 Model Context Protocol (MCP) 提供 Playwright 網頁內容檢索功能的服務器，能實現頁面導航、內容檢索、交互元素檢測等多種功能，為網頁操作和測試提供便利。

🚀 快速開始

該項目是一個使用 Model Context Protocol (MCP) 提供 Playwright 網頁內容檢索功能的服務器。你可以按照以下步驟啟動並使用該服務器。

✨ 主要特性

• 頁面導航
• 全頁內容檢索
• 可見內容檢索
• 交互元素檢測
• 鼠標操作模擬
• 測試用例迴響功能

📦 安裝指南

使用 Smithery 安裝

通過 Smithery 自動安裝 Playwright MCP Server for Claude Desktop：

npx -y @smithery/cli install @showfive/playwright-mcp-server --client claude

手動安裝

npm install

💻 使用示例

啟動服務器

npm run build
npm start

MCP 工具

以下工具可供使用：

1. navigate

   • 導航至指定 URL
   • 參數：{ url: string }
   • 返回值：導航結果

2. get_all_content

   • 檢索整個頁面的內容
   • 參數：無
   • 返回值：頁面中的所有文本內容

3. get_visible_content

   • 檢索當前可見的內容
   • 參數：{ minVisiblePercentage?: number }
   • 返回值：當前可見的文本內容

4. get_interactive_elements

   • 獲取交互元素的位置信息（按鈕、鏈接等）
   • 參數：無
   • 返回值：頁面上交互元素的座標和邊界信息

5. move_mouse

   • 將鼠標指針移動到指定座標
   • 參數：{ x: number, y: number }
   • 返回值：操作結果

6. mouse_click

   • 在指定座標執行鼠標點擊
   • 參數：{ x: number, y: number, button?: "left" | "right" | "middle", clickCount?: number }
   • 返回值：點擊操作的結果

7. mouse_wheel

   • 執行鼠標滾輪滾動
   • 參數：{ deltaY: number, deltaX?: number }
   • 返回值：滾動操作的結果

8. drag_and_drop

   • 執行拖放操作
   • 參數：{ sourceX: number, sourceY: number, targetX: number, targetY: number }
   • 返回值：拖放操作的結果

9. echo

   • 測試用例迴響工具
   • 參數：{ message: string }
   • 返回值：發送的消息

🔧 技術細節

運行測試

# 執行所有測試
npm test

# 以監控模式運行測試
npm run test:watch

# 生成覆蓋率報告
npm run test:coverage

測試結構

• tools/*.test.ts：每個工具的功能測試
• mcp-server.test.ts：MCP 服務器功能測試

實現特點

1. 內容檢索

   • 全頁內容檢索
   • 可見內容-only 檢索
   • 正確的 HTML 解析

2. 交互操作

   • 交互元素檢測和位置信息獲取
   • 鼠標操作模擬（移動、點擊、滾動）
   • 拖放支持

3. 錯誤處理

   • 正確的導航錯誤處理
   • 超時處理
   • 無效 URL 檢測

4. 靈活性配置

   • 無頭模式與有頭模式選擇
   • 自定義用戶代理
   • 視口大小設置

📄 許可證

ISC

⚠️ 重要提示

• 使用 MCP 服務器前請確保環境變量已正確設置。
• 使用目標網站的服務條款進行內容檢索時，請遵守相關規定。
• 發送多個請求時保持適當的間隔。
• 執行鼠標操作時，保持適當的時間間隔以模擬實際用戶交互。