游戏MCP

Name: 游戏MCP
Author: jomon003

作者：jomon00310 星标更新：2025-07-22

安装使用来源：spider==github.com

项目介绍

PlayMCP 浏览器自动化服务器

一个全面的MCP（模型上下文协议）服务器，用于通过Playwright进行浏览器自动化。此服务器提供了38个强大的工具，用于网络抓取、测试和自动化。

功能

🚀 核心浏览器自动化 (21个工具)

导航: navigate, goForward, goBack (通过滚动)
交互: click, type, hover, dragAndDrop, selectOption
鼠标控制: moveMouse, mouseMove, mouseClick, mouseDrag
键盘: pressKey
等待: waitForText, waitForSelector
截图: screenshot, takeScreenshot (增强版)
页面信息: getPageSource, getPageText, getPageTitle, getPageUrl
元素分析: getElementContent, getElementHierarchy
脚本与样式: getScripts, getStylesheets, getMetaTags

🔍 高级数据提取 (7个工具)

链接与图片: getLinks, getImages
表单: getForms
控制台监控: getConsoleMessages
网络监控: getNetworkRequests
JavaScript执行: executeJavaScript, evaluateWithReturn

📁 文件操作 (2个工具)

文件上传: uploadFiles
对话处理: handleDialog

⚙️ 浏览器管理 (8个工具)

浏览器控制: openBrowser, closeBrowser
视口管理: resize
页面操作: scroll (增强反馈)
元素层次: 深度DOM分析，可配置深度
增强截图: 全页、特定元素、自定义路径
鼠标坐标: 像素级精确鼠标控制
等待条件: 智能等待元素和文本

快速开始

安装

# 克隆仓库
git clone https://github.com/jomon003/PlayMCP.git
cd PlayMCP

# 安装依赖
npm install

# 构建项目
npm run build

# 测试服务器
npm test

基本用法

// 启动服务器
node ./dist/server.js

// 通过JSON-RPC发送MCP命令
{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}

工具分类

🎯 导航与交互

navigate: 转到任意URL
goForward: 在浏览器历史中前进
click: 使用智能选择器解析点击元素
type: 使用真实的键盘模拟输入文本
hover: 鼠标悬停以显示提示和交互
dragAndDrop: 在位置之间拖动元素
selectOption: 从下拉菜单或多选框中选择选项
pressKey: 发送特定的键盘键（如Enter、Escape等）

⏱️ 智能等待

waitForText: 等待特定文本出现
waitForSelector: 等待元素加载
内置超时和错误处理

🖱️ 精确鼠标控制

mouseMove: 移动到确切坐标
mouseClick: 在特定像素处点击
mouseDrag: 在坐标点之间拖动
moveMouse: 增强的鼠标定位

📊 数据提取

getElementHierarchy: 深度DOM结构分析
getConsoleMessages: 监控浏览器控制台输出
getNetworkRequests: 追踪HTTP请求和响应
getLinks: 提取所有页面链接及其元数据
getImages: 获取所有图像及其属性
getForms: 分析表单结构和字段

🎬 视觉与媒体

screenshot: 基础截图捕捉
takeScreenshot: 高级截图（全页、元素、自定义路径）
resize: 控制视口尺寸

📁 文件与对话操作

uploadFiles: 处理文件输入上传
handleDialog: 管理警告、确认和提示

⚙️ JavaScript执行

executeJavaScript: 运行JavaScript代码
evaluateWithReturn: 执行带有返回值的JS

核心浏览器控制

openBrowser - 启动新的浏览器实例，可选无头模式
navigate - 导航到任意URL
click - 使用CSS选择器点击元素
type - 输入文本到输入字段
moveMouse - 将鼠标移动到特定坐标
scroll - 按指定数量滚动页面，支持增强反馈和平滑滚动
screenshot - 截取页面、视口或特定元素的截图
closeBrowser - 关闭浏览器实例

页面内容提取

getPageSource - 获取完整的HTML源代码
getPageText - 获取文本内容（剥离HTML）
getPageTitle - 获取页面标题
getPageUrl - 获取当前URL
getScripts - 提取页面中的所有JavaScript代码
getStylesheets - 提取所有CSS样式表
getMetaTags - 获取所有meta标签及其属性
getLinks - 获取所有链接及其href、文本和标题
getImages - 获取所有图像及其src、alt和尺寸
getForms - 获取所有表单及其字段和属性
getElementContent - 获取特定元素的HTML和文本内容
getElementHierarchy - 获取具有父子关系的层次DOM结构

高级功能

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, smooth?: boolean`
`screenshot`	拍摄截图	`path: string, type?: string, selector?: string`
`getPageSource`	获取HTML源代码	无
`getPageText`	获取文本内容	无
`getPageTitle`	获取页面标题	无
`getPageUrl`	获取当前URL	无
`getScripts`	获取JavaScript代码	无
`getStylesheets`	获取CSS样式表	无
`getMetaTags`	获取meta标签	无
`getLinks`	获取所有链接	无
`getImages`	获取所有图像	无
`getForms`	获取所有表单	无
`getElementContent`	获取元素内容	`selector: string`
`getElementHierarchy`	获取DOM层次结构	`selector?: string, maxDepth?: number, includeText?: boolean, includeAttributes?: boolean`
`executeJavaScript`	运行JavaScript	`script: string`
`closeBrowser`	关闭浏览器	无

安装

完整安装步骤

前提条件
- Node.js 16+ (从nodejs.org下载)
- Git (用于克隆仓库)

克隆和设置

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

安装Playwright浏览器
```
npx playwright install
```
这会下载必要的浏览器二进制文件（Chromium, Firefox, Safari）。
验证安装
```
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 Desktop (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, smooth: false })
// 返回：{ before: {x: 0, y: 0}, after: {x: 0, y: 500}, scrolled: {x: 0, y: 500} }

// 平滑滚动
await scroll({ x: 0, y: 300, smooth: true })

// 鼠标交互
await moveMouse({ x: 100, y: 200 })
await click({ selector: ".dropdown-menu" })

DOM结构分析：

// 获取页面层次结构（3层深）
await getElementHierarchy({ maxDepth: 3 })

// 获取详细的层次结构，包括文本和属性
await getElementHierarchy({ 
  selector: "#main-content", 
  maxDepth: -1, 
  includeText: true, 
  includeAttributes: true 
})

// 获取特定部分的基本结构
await getElementHierarchy({ selector: ".sidebar", maxDepth: 2 })

高级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" })

快速开始

安装和设置：

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(`找到 ${links.length} 个链接`)

// 分析页面结构
const hierarchy = await getElementHierarchy({ maxDepth: 2 })
console.log('页面结构：', hierarchy)

开发

src/server.ts - 主MCP服务器实现
src/controllers/playwright.ts - Playwright浏览器控制器
src/mcp/ - MCP协议实现
src/types/ - TypeScript类型定义

要求

系统要求

Node.js 16+ (推荐长期支持版本)
操作系统：Windows、macOS 或 Linux
内存：至少2GB RAM（推荐4GB+用于大量使用）
磁盘空间：约500MB用于浏览器二进制文件和依赖项

依赖项

Playwright：处理浏览器自动化（自动安装）
TypeScript：用于编译（开发依赖项）
浏览器二进制文件：通过npx playwright install下载

故障排除

常见问题

"浏览器未初始化"错误
- 确保在其他浏览器操作之前调用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许可证