JinDaGe - playmcp MCP Details

article

README

🚀 PlayMCP浏览器自动化服务器

PlayMCP是一个全面的MCP（模型上下文协议）服务器，它利用Playwright实现浏览器自动化。该服务器为网页数据抓取、测试和自动化提供了强大的工具。

🚀 快速开始

安装并设置：

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

添加到MCP客户端配置
开始自动化操作：

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代码并返回结果

📚 详细文档

可用工具参考

| 工具 | 描述 | 必需参数 | |------|-------------|-------------------| | openBrowser | 启动浏览器实例 | headless?: boolean, debug?: boolean | | navigate | 导航到URL | url: string | | click | 点击元素 | selector: string | | type | 在元素中输入文本 | selector: string, text: string | | moveMouse | 将鼠标移动到坐标 | x: number, y: number | | scroll | 滚动页面 | x: number, y: number | | screenshot | 截图 | path: string, type?: string, selector?: string | | getPageSource | 获取HTML源代码 | 无 | | getPageText | 获取文本内容 | 无 | | getPageTitle | 获取页面标题 | 无 | | getPageUrl | 获取当前URL | 无 | | getScripts | 获取JavaScript代码 | 无 | | getStylesheets | 获取CSS样式表 | 无 | | getMetaTags | 获取元标签 | 无 | | getLinks | 获取所有链接 | 无 | | getImages | 获取所有图片 | 无 | | getForms | 获取所有表单 | 无 | | getElementContent | 获取元素内容 | selector: string | | executeJavaScript | 运行JavaScript | script: string | | closeBrowser | 关闭浏览器 | 无 |

使用方式

作为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执行
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" })

🔧 技术细节

开发文件结构

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下载

🛠️ 故障排除

常见问题

“Browser not initialized”错误
- 确保在进行其他浏览器操作之前调用openBrowser
- 检查Node.js版本是否为16或更高
Playwright安装失败

# 尝试手动安装浏览器
npx playwright install chromium
# 或安装所有浏览器
npx playwright install

Linux/macOS上的权限错误

# 确保脚本可执行
chmod +x dist/server.js

MCP配置中的路径问题
- 在配置中使用绝对路径
- 在Windows上使用双反斜杠：C:\\path\\to\\PlayMCP\\dist\\server.js
- 验证路径是否存在：node /path/to/PlayMCP/dist/server.js
浏览器崩溃或超时
- 尝试使用headless: false运行以进行调试
- 如果运行多个浏览器实例，增加系统内存
- 检查防病毒软件是否阻止了浏览器进程

测试安装

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

您应该会看到一个列出所有可用工具的JSON响应。

📄 许可证

本项目采用MIT许可证。

playmcp