Playmcp

🚀 PlayMCP瀏覽器自動化服務器

PlayMCP是一個全面的MCP（模型上下文協議）服務器，它藉助Playwright實現瀏覽器自動化。該服務器為網頁數據抓取、測試和自動化操作提供了強大的工具。

✨ 主要特性

核心瀏覽器控制

• openBrowser - 啟動一個新的瀏覽器實例，支持可選的無頭模式
• navigate - 導航到任意URL
• click - 使用CSS選擇器點擊元素
• type - 在輸入字段中輸入文本
• moveMouse - 將鼠標移動到指定座標
• scroll - 按指定量滾動頁面
• screenshot - 對頁面、視口或特定元素進行截圖
• closeBrowser - 關閉瀏覽器實例

頁面內容提取

• getPageSource - 獲取完整的HTML源代碼
• getPageText - 獲取文本內容（去除HTML標籤）
• getPageTitle - 獲取頁面標題
• getPageUrl - 獲取當前URL
• getScripts - 從頁面提取所有JavaScript代碼
• getStylesheets - 提取所有CSS樣式表
• getMetaTags - 獲取所有帶有屬性的元標籤
• getLinks - 獲取所有帶有href、文本和標題的鏈接
• getImages - 獲取所有帶有src、alt和尺寸的圖像
• getForms - 獲取所有帶有字段和屬性的表單
• getElementContent - 獲取特定元素的HTML和文本內容

高級功能

• executeJavaScript - 在頁面上執行任意JavaScript代碼並返回結果

📋 可用工具參考

📦 安裝指南

完整安裝步驟

1. 前提條件

   • Node.js 16+（從 nodejs.org 下載）
   • Git（用於克隆倉庫）

2. 克隆並設置

   git clone <repository-url>
   cd PlayMCP
   npm install
   npm run build
   

3. 安裝Playwright瀏覽器

   npx playwright install
   

   這將下載必要的瀏覽器二進制文件（Chromium、Firefox、Safari）。

4. 驗證安裝

   npm run start
   

   如果一切正常，你應該會看到 "Browser Automation MCP Server starting..."。

快速安裝

git clone <repository-url>
cd PlayMCP
npm install && npm run build && npx playwright install

💻 使用示例

作為MCP服務器

添加到你的MCP配置文件中：

標準MCP配置：

{
  "servers": {
    "playmcp-browser": {
      "type": "stdio",
      "command": "node",
      "args": ["./dist/server.js"],
      "cwd": "/path/to/PlayMCP",
      "description": "使用Playwright的瀏覽器自動化服務器"
    }
  }
}

替代配置（適用於VS Code GitHub Copilot）：

{
  "servers": {
    "playmcp-browser": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/PlayMCP/dist/server.js"]
    }
  }
}

Windows用戶：

{
  "servers": {
    "playmcp-browser": {
      "type": "stdio",
      "command": "node",
      "args": ["C:\\path\\to\\PlayMCP\\dist\\server.js"]
    }
  }
}

VS Code GitHub Copilot集成

此MCP服務器與VS Code GitHub Copilot完全兼容。將上述配置添加到你的MCP設置後，你可以直接在VS Code中使用所有瀏覽器自動化工具。

配置示例

Claude桌面版（config.json位置）：

• Windows: %APPDATA%\Claude\config.json
• macOS: ~/Library/Application Support/Claude/config.json
• Linux: ~/.config/Claude/config.json

VS Code MCP擴展： 添加到你的VS Code settings.json或MCP配置文件中。

完整配置示例：

{
  "mcpServers": {
    "playmcp-browser": {
      "type": "stdio",
      "command": "node",
      "args": ["/Users/username/PlayMCP/dist/server.js"],
      "description": "使用Playwright進行瀏覽器自動化"
    }
  }
}

工具使用示例

基礎用法

// 打開瀏覽器並導航
await openBrowser({ headless: false, debug: true })
await navigate({ url: "https://example.com" })

// 提取內容
const title = await getPageTitle()
const links = await getLinks()
const forms = await getForms()

高級用法

// 表單自動化
// 填寫表單
await click({ selector: "#login-button" })
await type({ selector: "#username", text: "user@example.com" })
await type({ selector: "#password", text: "password123" })
await click({ selector: "#submit" })

// 頁面交互
// 滾動和交互
await scroll({ x: 0, y: 500 })
await moveMouse({ x: 100, y: 200 })
await click({ selector: ".dropdown-menu" })

// 高級JavaScript執行
// 運行自定義JavaScript
await executeJavaScript({ 
  script: "document.querySelectorAll('h1').length" 
})

// 修改頁面內容
await executeJavaScript({ 
  script: "document.body.style.backgroundColor = 'lightblue'" 
})

// 提取複雜數據
await executeJavaScript({ 
  script: `
    Array.from(document.querySelectorAll('article')).map(article => ({
      title: article.querySelector('h2')?.textContent,
      summary: article.querySelector('p')?.textContent
    }))
  `
})

// 截圖和文檔記錄
// 進行截圖
await screenshot({ path: "./full-page.png", type: "page" })
await screenshot({ path: "./element.png", type: "element", selector: "#main-content" })

🚀 快速開始

1. 安裝並設置：

   git clone <repo-url> && cd PlayMCP
   npm install && npm run build && npx playwright install
   

2. 添加到你的MCP客戶端配置

3. 開始自動化操作：

   await openBrowser({ debug: true })
   await navigate({ url: "https://news.ycombinator.com" })
   const links = await getLinks()
   console.log(`找到 ${links.length} 個鏈接`)
   

📚 詳細文檔

開發相關

• src/server.ts - 主要的MCP服務器實現
• src/controllers/playwright.ts - Playwright瀏覽器控制器
• src/mcp/ - MCP協議實現
• src/types/ - TypeScript類型定義

系統要求

依賴項

故障排除

常見問題

1. “Browser not initialized” 錯誤

   • 確保在其他瀏覽器操作之前調用 openBrowser
   • 檢查Node.js版本是否為16或更高

2. Playwright安裝失敗

   # 嘗試手動安裝瀏覽器
   npx playwright install chromium
   # 或安裝所有瀏覽器
   npx playwright install
   

3. Linux/macOS上的權限錯誤

   # 確保腳本可執行
   chmod +x dist/server.js
   

4. MCP配置中的路徑問題

   • 在配置中使用絕對路徑
   • 在Windows上，使用雙反斜槓：C:\\path\\to\\PlayMCP\\dist\\server.js
   • 驗證路徑是否存在：node /path/to/PlayMCP/dist/server.js

5. 瀏覽器崩潰或超時

   • 嘗試以 headless: false 模式運行進行調試
   • 如果運行多個瀏覽器實例，增加系統內存
   • 檢查防病毒軟件是否阻止了瀏覽器進程

測試安裝

# 直接測試服務器
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node ./dist/server.js

你應該會看到一個列出所有可用工具的JSON響應。

📄 許可證

本項目採用MIT許可證。