Playwright Spa MCP

🎭 Playwright SPA MCP服务器

为现代web应用程序构建的Playwright MCP服务器。 持久会话、React/Vue/Angular支持、143多个设备和智能DOM等待。

🇫🇷 *Playwright MCP服务器针对现代单页应用程序进行了优化。*

______________________________________________________________________

✨ 为什么选择此服务器？

______________________________________________________________________

🚀 快速开始

安装

# One command - no clone needed!
claude mcp add playwright-spa -- npx -y github:manganate006/playwright-spa-mcp

# Install Playwright browser
npx playwright install chromium

克劳德桌面版 (claude_desktop_config.json):

{
  "mcpServers": {
    "playwright-spa": {
      "command": "npx",
      "args": ["-y", "github:manganate006/playwright-spa-mcp"]
    }
  }
}

📦 Alternative: Clone & install locally

git clone https://github.com/manganate006/playwright-spa-mcp.git
cd playwright-spa-mcp
npm install
npx playwright install chromium

# Add to Claude
claude mcp add playwright-spa -- node $(pwd)/src/index.js

______________________________________________________________________

🛠️ 可用工具（22）

📸 屏幕截图和导航

📝 表单交互

⛓️ 行为链

🔐 会话

🌐 高级

______________________________________________________________________

💡 使用示例

🔐 登录React应用程序

// Start a persistent session
spa_session_start({ session: "myapp" })

// Login with realistic typing (triggers React onChange properly)
spa_chain({
  session: "myapp",
  url: "https://app.example.com/login",
  spaMode: "react",
  chain: [
    { action: "type-realistic", selector: "#email", value: "user@example.com" },
    { action: "type-realistic", selector: "#password", value: "secret123" },
    { action: "click", selector: "button[type=submit]" },
    { action: "wait-for-idle" },
    { action: "screenshot" }
  ]
})

// Continue with the same session - React state is preserved! 🎉
spa_click({ session: "myapp", selector: ".dashboard-item" })

📱 移动设备测试

spa_screenshot({
  url: "https://example.com",
  device: "iPhone 15 Pro",  // or use shortcut: "iphone-pro"
  fullPage: true
})

🍪 API请求浏览器验证

// After logging in, make API calls with session cookies
spa_http_request({
  session: "myapp",
  url: "https://api.example.com/user/profile",
  method: "GET"
})
// Cookies are automatically included!

______________________________________________________________________

📱 设备快捷方式

💡 使用 spa_list_devices 查看所有143+设备！

______________________________________________________________________

⛓️ 链动作参考

浏览器

screenshot · click · double-click · right-click · fill · type · type-realistic · hover · scroll

导航

go-back · go-forward · reload

等待

wait · wait-for · wait-for-idle · wait-for-spa

表格

clear · check · uncheck · upload · focus · blur

键盘

press （Enter、Tab、Escape等）

高级

drag · evaluate · iframe-click · iframe-fill

______________________________________________________________________

⚛️ SPA框架支持

反应

• ✅ 等待React完成渲染
• ✅ 适当的 onChange 受控输入事件
• ✅ type-realistic 对于复杂的形式

Vue

• ✅ 检测Vue实例
• ✅ 正确触发v-model绑定

Angular

• ✅ 等待Zone.js稳定
• ✅ 处理异步操作

💡 使用 spaMode: "auto" 用于自动检测！

______________________________________________________________________

🖥️ CLI使用情况

# Simple screenshot
node browser.js --url "https://example.com" --action screenshot

# With device emulation
node browser.js --url "https://example.com" --device "iPhone 15" --action screenshot

# Action chain
node browser.js --url "https://site.com" --chain '[
  {"action": "fill", "selector": "#email", "value": "test@test.com"},
  {"action": "click", "selector": "button"},
  {"action": "screenshot"}
]'

# List all devices
node browser.js --list-devices

# List all actions
node browser.js --list-actions

______________________________________________________________________

📂 项目结构

playwright-spa-mcp/
├── src/
│   ├── index.js          # MCP server entry point
│   └── server.js         # MCP server implementation (22 tools)
├── lib/
│   ├── actions.js        # Browser actions
│   ├── chain-executor.js # Chain execution engine
│   ├── devices.js        # 143+ device presets
│   ├── http-actions.js   # HTTP request actions
│   ├── session-manager.js
│   └── spa-utils.js      # SPA detection & waiting
├── browser.js            # CLI interface
├── browser-daemon.js     # Daemon mode
└── package.json

______________________________________________________________________

🌐 使用此MCP构建的项目

______________________________________________________________________

🤝 贡献

欢迎投稿！请随时打开问题或提交PR。

______________________________________________________________________

📄 许可证

麻省理工学院©2024

______________________________________________________________________

Built with ❤️ for Claude Code and Claude Desktop

Making browser automation actually work with modern SPAs