Playwright MCP Framework

剧作家MCP框架

一个混合测试和浏览器自动化框架，为人类和人工智能代理服务。

对于人类： 使用TypeScript的传统剧作家测试\ 对于代理商（MCP）： 通过模型上下文协议（JSON-RPC）进行浏览器控制

受启发于 Vibium，由剧作家提供动力。

______________________________________________________________________

🚀 快速开始

安装

npm install
npx playwright install

______________________________________________________________________

👨 人类：剧作家测试

使用Playwright强大的API编写并运行浏览器测试。

运行测试

无头模式（CI/自动）：

npm test

头部模式（请参阅浏览器）：

npm run test:headed

UI模式（交互式调试）：

npm run test:ui

写作测试

在中创建测试 tests/ 目录：

// tests/login.spec.ts
import { test, expect } from '@playwright/test';

test('user can login', async ({ page }) => {
  await page.goto('https://app.example.com');
  await page.getByLabel('Email').fill('user@example.com');
  await page.getByLabel('Password').fill('password');
  await page.getByRole('button', { name: 'Login' }).click();
  
  await expect(page).toHaveURL(/dashboard/);
});

了解更多：

• 剧作家文档
• 剧作家测试API

演示脚本

使用演示脚本探索BrowserManager功能：

# Basic demo: launch, navigate, screenshot, click
npm run demo

# Error demo: automatic error screenshots
npm run demo:error

# Type error demo: error context preservation
npm run demo:type-error

# Cleanup demo: screenshot management
npm run demo:clean

______________________________________________________________________

🤖 代理：MCP协议

状态： ✅ 已实施-7个可用工具

什么是MCP？

这 模型上下文协议（MCP） 是一种基于JSON-RPC的协议，允许AI代理（如Claude）与外部工具和服务进行交互。该框架实现了一个MCP服务器，该服务器通过stdio传输公开浏览器自动化功能。

它是如何工作的：

• 代理通过stdin发送JSON-RPC请求（每行一个JSON）
• 服务器使用Playwright执行浏览器操作
• 服务器通过stdout以JSON-RPC响应进行响应
• 所有日志都会进入stderr（永远不会污染stdout）

可用工具

已实施的7个工具：

1. browser_launch -启动新的浏览器会话（chromium）。选项：无头模式，用于调试的slowMo。
2. browser_navigate -导航到任何URL。返回前等待页面加载。
3. browser_find -通过CSS选择器搜索元素。返回标记名称、文本内容和边界框坐标。
4. browser_click -使用CSS选择器单击元素。包括自动可操作性检查。
5. browser_type -在输入框中键入文本。支持清除现有内容和自定义超时。
6. browser_screenshot -捕获屏幕截图以归档或以base64格式返回。支持全页面捕获。
7. browser_quit -关闭浏览器会话并清理资源。

运行MCP服务器

在stdio上启动JSON-RPC服务器：

npm run mcp

重要提示： 服务器使用stdio传输：

• 标准输入：接收JSON-RPC请求（每行一个）
• 标准输出：发送JSON-RPC响应（仅JSON，每行一个）
• 标准错误：日志和调试信息

手动测试

您可以通过将JSON请求管道传输到stdin来手动测试服务器。以下是一些可以复制/粘贴的示例：

1.初始化服务器：

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}

2.列出可用工具：

{"jsonrpc":"2.0","id":2,"method":"tools/list"}

3.启动浏览器（无头）：

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"browser_launch","arguments":{"headless":true}}}

4.导航到URL：

{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"browser_navigate","arguments":{"url":"https://example.com"}}}

5.找到一个元素：

{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"browser_find","arguments":{"selector":"h1","timeoutMs":5000}}}

6.单击元素：

{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"browser_click","arguments":{"selector":"a"}}}

7.在输入中键入：

{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"browser_type","arguments":{"selector":"input[type='text']","text":"Hello World"}}}

8.截图：

{"jsonrpc":"2.0","id":8,"method":"tools/call","params":{"name":"browser_screenshot","arguments":{"filename":"test.png","fullPage":true}}}

9.退出浏览器：

{"jsonrpc":"2.0","id":9,"method":"tools/call","params":{"name":"browser_quit","arguments":{}}}

自动化测试

运行烟雾测试套件以验证所有工具是否正常工作：

npm run test:mcp

这将执行一个端到端测试，该测试：

1. 将MCP服务器作为子进程启动
2. 初始化并列出工具
3. 执行完整的浏览器工作流（启动→ 导航→ find → 截图→ quit)
4. 验证所有响应

实施状态：

• 第一阶段：核心组件（浏览器管理器、记录器、配置）-✅ 完成
• 第二阶段：MCP服务器+7个工具✅ 完成
• 第3阶段：克劳德桌面集成-🚧 计划的

______________________________________________________________________

📚 文档

详细文档可在 /docs:

• 建筑 -框架设计、组件、路线图
• 可操作性规则 -定位器最佳实践，不睡觉政策
• 流程清理 -停机处理、信号管理
• 屏幕截图管理 -管理测试截图、清理策略
• MCP协议 -JSON-RPC规范，传输层
• MCP工具 -工具定义、模式、示例

______________________________________________________________________

🏗️ 项目结构

playwright-mcp-framework/
├── tests/                    # Playwright tests (for humans)
├── src/
│   ├── core/                 # Browser management
│   ├── mcp/                  # MCP server (for agents)
│   │   └── tools/            # MCP tool implementations
│   └── utils/                # Shared utilities
├── docs/                     # Documentation
├── scripts/                  # Utility scripts
└── playwright.config.ts      # Playwright configuration

______________________________________________________________________

🔧 配置

环境变量

使用环境变量配置框架行为：

日志级别：

• debug -详细日志记录（所有操作）
• info -正常日志记录（默认）
• warn -仅警告
• error -仅错误

使用示例：

# Run tests in headless mode with debug logging
HEADLESS=true LOG_LEVEL=debug npm test

# Slow down browser for debugging
SLOWMO_MS=1000 npm run demo

# Custom screenshot directory
SCREENSHOT_DIR=./test-output npm test

# Increase timeout for slow networks
DEFAULT_TIMEOUT_MS=60000 npm run demo

Windows（PowerShell）：

$env:HEADLESS="true"
$env:LOG_LEVEL="debug"
npm test

Windows（CMD）：

set HEADLESS=true
set LOG_LEVEL=debug
npm test

剧作家配置

看 剧作家配置ts 用于测试配置。

当前配置的浏览器：

• ✅ 铬（铬/边缘）
• ⚪ Firefox（已评论）
• ⚪ WebKit（Safari浏览器，已被评论）

______________________________________________________________________

🤝 贡献

这是一个与Playwright一起探索混合人类代理工作流程的实验项目。

关键原则：

• 仅定位器方法（无手动等待）
• TypeScript严格模式
• 所有流程都能顺利关闭
• 人类和特工使用相同的引擎

______________________________________________________________________

📖 参考文献

• Vibium框架 （灵感）
• 剧作家
• 模型上下文协议
• JSON-RPC 2.0