Custom Playwright MCP

剧作家MCP服务器

提供Playwright浏览器自动化功能的模型上下文协议（MCP）服务器。该服务器使GitHub Copilot等AI助手能够执行网络抓取、测试和浏览器自动化任务。

特性

此MCP服务器公开 25个全面的剧作家工具 按类别组织：

🆕 自动录制功能

所有操作都会自动记录！ 您可以使用单个命令从任何工作流生成完整的Playwright测试文件：

"Generate a Playwright test from my workflow"

这将在中自动创建测试文件 generated-tests/ 你所有的行动。无需手动录制！

导航和页面控制（6个工具）

• 剧作家_航空：导航到具有自定义等待条件的URL
• 剧作家：在浏览器历史记录中导航回来
• 剧作家_前进：在浏览器历史记录中向前导航
• 剧作家重播：重新加载当前页面
• 剧作家_set_viewport：设置自定义视口尺寸
• 剧作家_get_page_info：获取当前页面URL和标题

元素交互（8个工具）

• 剧作家：点击元素（支持多个按钮和点击次数）
• 剧作家菲尔：快速填写输入字段
• 剧作家类型：使用键盘模拟和延迟键入文本
• 剧作家：将鼠标悬停在元素上
• 剧作家精选：选择下拉选项
• 剧作家复选框：选中或取消选中复选框
• 剧作家_戏剧与戏剧：拖放元素
• 剧作家_press_key：按键盘键（Enter、Escape等）

数据提取（3个工具）

• 剧作家_摘录_正文：从单个或多个元素中提取文本
• 剧作家_属性：从元素中获取属性值
• 剧作家_评价：执行自定义JavaScript并获取结果

等待与同步（1个工具）

• 剧作家等待选择：等待具有自定义超时和状态的元素

捕捉（1个工具）

• 剧作家_编剧：捕获完整或部分页面截图

测试记录和生成（4个工具）

• 剧作家_记录_开始：开始记录用户操作以生成测试
• 剧作家_记录_停止：停止录制操作
• 剧作家生成测试：生成测试脚本（Types/JavaScript/Python中的剧作家/Pupeter/Selenium）
• 剧作家_生成_工作流_测试: 🆕 从当前工作流操作自动生成Playwright测试

浏览器管理（2个工具）

• 剧作家卢斯：关闭浏览器并清理
• 所有工具都支持有状态的浏览器会话（Cookie、身份验证、历史记录保留）

📋 先决条件

在开始之前，请确保您已经：

• Node.js 18或更高版本 - 点击此处下载
• npm （附带Node.js）
• VS Code （用于GitHub Copilot集成）- 点击此处下载
• GitHub Copilot订阅 （适用于AI驱动的使用）

🔧 安装和设置

步骤1：克隆存储库

git clone 
cd playwright-mcp-server

步骤2：安装依赖项

npm install

这将安装：

• @modelcontextprotocol/sdk -MCP协议实现
• playwright -浏览器自动化库
• zod -架构验证
• TypeScript及其相关依赖

步骤3：安装Playwright浏览器

npx playwright install chromium

这将下载Chromium浏览器二进制文件（~170MB）。您还可以安装其他浏览器：

# Optional: Install all browsers
npx playwright install

步骤4：构建服务器

npm run build

这将TypeScript编译为JavaScript build/ 目录。

步骤5：配置VS代码（GitHub Copilot集成）

创建或更新 .vscode/mcp.json 在 您的工作空间 （不在本项目中）：

{
  "mcpServers": {
    "playwright": {
      "command": "node",
      "args": ["/absolute/path/to/playwright-mcp-server/build/index.js"]
    }
  }
}

⚠️ 重要提示： 替换 /absolute/path/to/playwright-mcp-server/ 使用您克隆此仓库的实际路径。

示例：

• 窗户： "C:\\Users\\YourName\\Projects\\playwright-mcp-server\\build\\index.js"
• Mac/Linux： "/home/username/projects/playwright-mcp-server/build/index.js"

步骤6：重新加载VS代码

1. 按 Ctrl+Shift+P （Windows/Linux）或 Cmd+Shift+P （Mac）
2. 键入“重新加载窗口”，然后按Enter键
3. 或者简单地重新启动VS Code

步骤7：验证安装

在VS Code中打开GitHub Copilot Chat并尝试：

Navigate to https://example.com and take a screenshot

如果它有效，你就准备好了！ 🎉

💡 用法示例

基本浏览器自动化

在GitHub Copilot聊天中使用自然语言：

Navigate to https://news.ycombinator.com and get the page title

Go to https://example.com, click the link with text "More information", and take a screenshot

Navigate to https://github.com, fill the search box with "playwright", and press Enter

高级交互

Go to https://amazon.com, hover over the menu, wait for the dropdown, and extract all category names

Navigate to a form page, check the terms checkbox, select "United States" from the country dropdown, and click submit

Open the developer console and execute: document.querySelectorAll('a').length

测试记录和生成

Start recording a test named "login_flow"
Navigate to https://example.com/login
Fill the username field with "testuser"
Fill the password field with "password123"
Click the login button
Wait for the dashboard to load
Stop recording
Generate a Playwright test in TypeScript, save as "login.spec.ts"

这将在中创建一个完整的测试文件 generated-tests/login.spec.ts!

多步骤工作流

1. Navigate to https://opensource-demo.orangehrmlive.com/web/index.php/auth/login
2. Extract the demo credentials from the page
3. Login with those credentials
4. Verify the dashboard title
5. Take a screenshot

数据提取

Go to https://news.ycombinator.com and extract all article titles

Navigate to a product page and get the price attribute from the element with class "product-price"

🎬 测试生成功能

自动生成测试（新增！）

只需执行您的工作流程并生成测试：

Navigate to https://example.com
Click login button
Fill username with "test"
Fill password with "pass"
Click submit

Generate a Playwright test from my workflow

结果：完成测试文件 generated-tests/workflow_TIMESTAMP.spec.ts

手动记录（原始方法）

记录→ 生成→ Run

第一步：开始录制

Start recording "checkout_flow"

第二步：执行操作 （全部自动记录）

Navigate to https://demo-store.com
Click .add-to-cart
Fill #email with "test@example.com"
Click .checkout-button

步骤3：停止录制

Stop recording

步骤4：生成测试

Generate a Playwright test in TypeScript, save as "checkout.spec.ts"

或者为不同的框架生成：

Generate a Puppeteer test in JavaScript, save as "checkout.test.js"
Generate a Selenium test in Python, save as "test_checkout.py"

生成的测试文件 保存在 generated-tests/ 目录，并准备运行！

📚 工具参考

导航和页面控制

元素交互

数据提取

等待与捕捉

测试生成

浏览器管理

🏗️ 建筑

此MCP服务器遵循 100%本地架构:

┌─────────────────────────────────────────────────────────┐
│                    YOUR LOCAL MACHINE                    │
│                                                          │
│  ┌──────────────┐                                       │
│  │   VS Code    │                                       │
│  │ + Copilot    │                                       │
│  └──────┬───────┘                                       │
│         │ stdio (no network)                            │
│         ▼                                                │
│  ┌──────────────────────────────────┐                  │
│  │  Playwright MCP Server            │                  │
│  │  (build/index.js)                │                  │
│  └──────────────┬───────────────────┘                  │
│                 │                                        │
│                 ▼                                        │
│  ┌──────────────────────────────────┐                  │
│  │  Chromium Browser (Local)         │                  │
│  └───────────────────────────────────┘                  │
│                                                          │
└─────────────────────────────────────────────────────────┘

要点：

• ✅ 无外部MCP服务 -一切都在本地运行
• ✅ stdio通信 -没有HTTP或WebSocket连接
• ✅ 不需要API密钥 -无需身份验证
• ✅ 隐私第一 -您的自动化脚本永远不会离开您的机器
• ✅ 离线功能 -在没有互联网的情况下工作（访问网站除外）

🛠️ 发展

构建命令

# Build once
npm run build

# Watch mode (auto-rebuild on changes)
npm run watch

# Clean build
rm -rf build && npm run build

项目结构

playwright-mcp-server/
├── .github/
│   └── copilot-instructions.md   # GitHub Copilot context
├── .vscode/
│   └── mcp.json                  # MCP server configuration
├── src/
│   └── index.ts                  # Main server implementation
├── build/
│   └── index.js                  # Compiled output (generated)
├── generated-tests/              # Generated test files (created at runtime)
├── package.json                  # Dependencies
├── tsconfig.json                 # TypeScript configuration
└── README.md                     # This file

扩展服务器

要添加新工具，请执行以下操作：

1. 定义架构 在 src/index.ts:

const MyToolSchema = z.object({
  param1: z.string().describe("Description"),
  param2: z.number().optional(),
});

1. 添加工具定义:

{
  name: "playwright_my_tool",
  description: "What this tool does",
  inputSchema: { /* JSON schema */ }
}

1. 实现处理程序:

case "playwright_my_tool": {
  const { param1, param2 } = MyToolSchema.parse(args);
  const page = await browserManager.ensurePage();
  // Your implementation
  return { content: [{ type: "text", text: "Result" }] };
}

1. 重建: npm run build

🔒 安全与隐私

• 仅限本地操作 -没有数据发送到外部服务器
• 无头模式 -浏览器在没有可见窗口的情况下运行（可配置）
• 输入验证 -所有参数均已Zod模式验证
• 沙盒浏览器 -Chromium运行时带有安全标志
• 无遥测 -无使用情况跟踪或分析

最佳实践：

• 导航到不受信任的URL时要小心
• 在传递给之前验证用户输入 playwright_evaluate
• 运行前检查生成的测试脚本
• 仅在受信任的环境中使用

🐛 故障排除

问题：MCP服务器未连接

解决方案：

# 1. Verify build exists
ls build/index.js

# 2. Test server manually
node build/index.js

# 3. Check VS Code MCP configuration
cat .vscode/mcp.json

# 4. Reload VS Code
# Ctrl+Shift+P → "Reload Window"

问题：浏览器启动失败

解决方案：

# Install/reinstall browsers
npx playwright install chromium

# Check system dependencies (Linux)
npx playwright install-deps chromium

# Test browser manually
npx playwright open https://example.com

问题：找不到工具

原因： MCP服务器缓存或版本过时

解决方案：

# Rebuild
npm run build

# Clear VS Code cache and reload
# Ctrl+Shift+P → "Developer: Reload Window"

问题：截图未保存

原因： 权限问题或路径无效

解决方案：

# Create screenshots directory
mkdir -p screenshots

# Check write permissions
ls -la

问题：生成的测试未显示

原因： 未创建目录

解决方案： 测试会自动保存到 generated-tests/ 目录。如果缺失：

mkdir generated-tests

调试模式

通过修改启用详细日志记录 src/index.ts:

console.error("DEBUG:", JSON.stringify(request, null, 2));

然后重建并检查终端输出。

🎯 用例

1. Web剪贴

Navigate to a news site and extract all article titles and links

2. 自动化测试

Record my login flow, then generate a test suite

3. 表单自动化

Fill out and submit contact forms with test data

4. 视觉回归测试

Take screenshots of my app in different viewport sizes

5. 数据收集

Navigate through paginated results and collect all product information

6. 基于浏览器的脚本

Execute custom JavaScript to analyze page performance

📝 配置选项

更改浏览器类型

编辑 src/index.ts:

// Use Firefox instead of Chromium
import { firefox } from "playwright";
this.browser = await firefox.launch({ ... });

头部模式（可见浏览器）

编辑 src/index.ts:

this.browser = await chromium.launch({
  headless: false, // Show browser window
  args: ["--no-sandbox", "--disable-setuid-sandbox"],
});

自定义视口

默认值为1280x720。变化 src/index.ts:

this.context = await browser.newContext({
  viewport: { width: 1920, height: 1080 },
  userAgent: "...",
});

屏幕截图目录

生成的测试保存到 generated-tests/.修改 src/index.ts:

const testsDir = path.join(process.cwd(), "my-custom-tests");

🤝 贡献

欢迎投稿！方法如下：

1. 分叉存储库
2. 创建要素分支: git checkout -b feature/amazing-feature
3. 进行更改
4. 构建和测试: npm run build
5. 提交: git commit -m 'Add amazing feature'
6. 推: git push origin feature/amazing-feature
7. 打开拉取请求

开发设置

git clone 
cd playwright-mcp-server
npm install
npm run build
# Make changes in src/
npm run watch  # Auto-rebuild on changes

📄 许可证

麻省理工学院

🔗 相关资源

• 模型上下文协议 -MCP官方文件
• 剧作家 -浏览器自动化框架
• MCP TypeScript SDK -官方SDK
• **** -AI配对程序员
• VS Code -推荐编辑

⭐ 支持与社区

如果你觉得这个项目有用：

• ⭐ 标记此存储库
• 🐛 在GitHub上报告问题
• 💡 建议新功能
• 🤝 促进改进

📮 支持

• 问题：GitHub问题
• 讨论：GitHub讨论
• 文档：此README和内联代码注释

🎉 致谢

• 与 模型上下文协议
• 由...驱动 剧作家
• 受到MCP社区的启发

______________________________________________________________________

由以下材料制成❤️ 用于浏览器自动化