Playmcp

🚀 PlayMCP瀏覽器自動化服務器

PlayMCP是一個基於Playwright的綜合性MCP（模型上下文協議）服務器，用於瀏覽器自動化。該服務器為網頁抓取、測試和自動化提供了強大的工具。

🚀 快速開始

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(`Found ${links.length} links`)

✨ 主要特性

核心瀏覽器控制

• 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": "Browser automation server using 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": "Browser automation with 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()

高級用法

// 運行自定義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
    }))
  `
})

📚 詳細文檔

可用工具參考

🔧 技術細節

開發文件結構

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

系統要求

• Node.js 16+（推薦使用LTS版本）
• 操作系統：Windows、macOS或Linux
• 內存：至少2GB RAM（大量使用時推薦4GB以上）
• 磁盤空間：~500MB用於瀏覽器二進制文件和依賴項

依賴項

• Playwright：處理瀏覽器自動化（自動安裝）
• TypeScript：用於編譯（開發依賴）
• 瀏覽器二進制文件：通過 npx playwright install 下載

故障排除

常見問題

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許可證。