# https://github.com/executeautomation/mcp-playwright 项目说明书
生成时间：2026-05-13 07:26:04 UTC
## 目录
- [快速入门指南](#getting-started)
- [系统架构](#architecture)
- [工具参考手册](#tool-reference)
- [设备模拟功能](#device-emulation)
- [测试代码生成](#code-generation)
- [HTTP/SSE 传输模式](#http-transport)
- [Docker 容器化部署](#docker-deployment)
- [客户端配置指南](#client-configuration)
- [日志与监控](#logging-monitoring)
- [故障排除指南](#troubleshooting)
## 快速入门指南
### 相关页面
相关主题：[系统架构](#architecture), [工具参考手册](#tool-reference), [客户端配置指南](#client-configuration)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/executeautomation/mcp-playwright/blob/main/README.md)
- [package.json](https://github.com/executeautomation/mcp-playwright/blob/main/package.json)
- [DOCKER.md](https://github.com/executeautomation/mcp-playwright/blob/main/DOCKER.md)
- [examples/http-mode-example.md](https://github.com/executeautomation/mcp-playwright/blob/main/examples/http-mode-example.md)
- [CLAUDE_DESKTOP_CONFIG.md](https://github.com/executeautomation/mcp-playwright/blob/main/CLAUDE_DESKTOP_CONFIG.md)
# 快速入门指南
本指南将帮助您快速上手 **mcp-playwright** 项目，这是一个基于 Model Context Protocol (MCP) 的 Playwright 自动化服务器。通过本指南，您将了解如何安装、配置并开始使用该服务器进行浏览器自动化操作。
## 项目概述
mcp-playwright 是一个开源的 MCP 服务器实现，它将 Playwright 浏览器自动化能力通过 MCP 协议暴露给 AI 助手和开发工具。该项目由 ExecuteAutomation 维护，支持多浏览器引擎（Chromium、Firefox、WebKit），并提供 stdio 和 HTTP 两种通信模式。
**核心特性：**
| 特性 | 说明 |
|------|------|
| 协议支持 | Model Context Protocol (MCP) |
| 浏览器支持 | Chromium、Firefox、WebKit |
| 通信模式 | stdio（标准输入输出）、HTTP Server |
| 安装方式 | npm、mcp-get、Smithery、Docker |
| 日志管理 | 自动写入文件（stdio 模式） |
## 环境要求
在开始之前，请确保您的系统满足以下要求：
- **Node.js**: 20.x 或更高版本
- **操作系统**: Windows、macOS、Linux
- **网络**: 能够访问 npm registry 下载依赖包
您可以通过以下命令检查 Node.js 版本：
```bash
node --version
```
## 安装方式
mcp-playwright 提供多种安装方式，您可以根据使用场景选择最合适的一种。
### 方式一：使用 npm 全局安装
这是最直接的安装方式：
```bash
npm install -g @executeautomation/playwright-mcp-server
```
安装完成后，可执行文件 `playwright-mcp-server` 将全局可用。资料来源：[README.md:54]()
### 方式二：使用 npx 免安装运行
如果您不想全局安装，可以使用 npx 直接运行：
```bash
npx -y @executeautomation/playwright-mcp-server
```
这种方式每次都会下载最新版本，适合临时使用或测试场景。资料来源：[README.md:42]()
### 方式三：使用 mcp-get 安装
mcp-get 是专门为 MCP 服务器设计的包管理工具：
```bash
npx @michaellatman/mcp-get@latest install @executeautomation/playwright-mcp-server
```
### 方式四：使用 Smithery 自动安装
Smithery 提供了针对 Claude Desktop 的自动化安装：
```bash
npx @smithery/cli install @executeautomation/playwright-mcp-server --client claude
```
### 方式五：Docker 部署
对于容器化环境，可以使用 Docker 运行：
```bash
docker run -i --rm mcp-playwright:latest
```
Docker 部署的详细配置请参考 [DOCKER.md](DOCKER.md)。资料来源：[DOCKER.md:1]()
## 配置 AI 客户端
安装完成后，您需要在 AI 客户端中配置 MCP 服务器连接。以下是常见客户端的配置方法。
### Claude Desktop 配置
**配置文件位置：**
| 操作系统 | 配置文件路径 |
|----------|--------------|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |
**stdio 模式配置（推荐）：**
```json
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["-y", "@executeautomation/playwright-mcp-server"]
}
}
}
```
**HTTP 模式配置：**
如果您使用 HTTP 模式运行服务器，可以配置如下：
```json
{
"mcpServers": {
"playwright": {
"url": "http://localhost:8931/mcp"
}
}
}
```
> **注意**：Claude Desktop 目前需要 stdio 模式。如果您需要 HTTP 模式，建议使用 VS Code 或其他自定义客户端。资料来源：[README.md:25-35]()
### Claude Code 配置
使用 Claude Code 时，可以通过命令行添加 MCP 服务器：
```bash
claude mcp add --transport stdio playwright npx @executeautomation/playwright-mcp-server
```
### VS Code MCP 扩展配置
对于 VS Code 用户，可以使用以下配置：
```json
{
"name": "playwright",
"command": "npx",
"args": ["-y", "@executeautomation/playwright-mcp-server"]
}
```
## 运行模式
mcp-playwright 支持两种运行模式，您可以根据需求选择。
### stdio 模式（标准输入输出）
stdio 模式是 Claude Desktop 的推荐模式。在此模式下，MCP 服务器通过标准输入和标准输出与客户端通信。
**启动方式：**
```bash
npx -y @executeautomation/playwright-mcp-server
```
**配置说明：**
| 参数 | 说明 |
|------|------|
| `-i` | 保持 STDIN 打开以接收输入 |
| `--rm` | 容器退出时自动删除 |
在 stdio 模式下，日志会自动写入文件而非控制台，以确保 JSON-RPC 通信的清洁性。日志文件位置为 `~/playwright-mcp-server.log`。资料来源：[README.md:30]()
### HTTP 模式（独立服务器）
HTTP 模式适合以下场景：
- 在无显示环境的系统中运行有头浏览器
- 从 IDE 工作进程调用
- 需要远程部署
- VS Code 用户
**启动 HTTP 服务器：**
```bash
# 使用 npx
npx @executeautomation/playwright-mcp-server --port 8931
# 或使用全局安装后
playwright-mcp-server --port 8931
```
服务器启动后将显示可用端点：
```
==============================================
Playwright MCP Server (HTTP Mode)
==============================================
Port: 8931
ENDPOINTS:
- SSE Stream: GET http://localhost:8931/sse
- Messages: POST http://localhost:8931/messages?sessionId=
- MCP (unified): GET http://localhost:8931/mcp
- MCP (unified): POST http://localhost:8931/mcp?sessionId=
- Health Check: GET http://localhost:8931/health
```
资料来源：[README.md:38-52]()
**健康检查：**
```bash
curl http://localhost:8931/health
```
## 浏览器安装
### 自动安装（推荐）
mcp-playwright **会在首次使用时自动安装浏览器**。当服务器检测到缺少浏览器时，会自动：
1. 下载并安装所需浏览器（Chromium、Firefox 或 WebKit）
2. 在控制台显示安装进度
3. 安装完成后自动重试您的请求
无需手动操作！
### 手动安装
如果您偏好手动安装或遇到自动安装问题：
```bash
# 安装所有浏览器
npx playwright install
# 或安装特定浏览器
npx playwright install chromium
npx playwright install firefox
npx playwright install webkit
```
**浏览器存储位置：**
| 操作系统 | 路径 |
|----------|------|
| Windows | `%USERPROFILE%\AppData\Local\ms-playwright` |
| macOS | `~/Library/Caches/ms-playwright` |
| Linux | `~/.cache/ms-playwright` |
资料来源：[README.md:57-72]()
## 项目架构
下面通过 Mermaid 图展示 mcp-playwright 的整体架构：
```mermaid
graph TD
A[AI 客户端
Claude Desktop/VS Code] -->|stdio 或 HTTP| B[MCP 协议层]
B --> C[Playwright MCP Server]
C --> D[Playwright 核心]
D --> E[Chromium]
D --> F[Firefox]
D --> G[WebKit]
H[日志系统] --> C
style A fill:#e1f5fe
style C fill:#fff3e0
style D fill:#e8f5e9
```
### 组件说明
| 组件 | 说明 | 源码位置 |
|------|------|----------|
| MCP 协议层 | 处理 JSON-RPC 通信协议 | `@modelcontextprotocol/sdk` |
| 工具处理器 | 执行浏览器自动化操作 | `src/tools/` |
| 日志中间件 | 请求日志和错误追踪 | `src/logging/middleware.ts` |
| Playwright 核心 | 跨浏览器自动化引擎 | `playwright@1.57.0` |
## 常用工作流程
### 基本导航流程
```mermaid
graph LR
A[启动服务器] --> B[配置客户端]
B --> C[打开浏览器]
C --> D[导航到 URL]
D --> E[执行交互]
E --> F[获取结果]
```
### Docker 部署流程
如果您选择 Docker 部署，典型的工作流程如下：
```mermaid
graph TD
A[编写 docker-compose.yml] --> B[配置环境变量]
B --> C[配置卷挂载]
C --> D[启动容器]
D --> E[配置 AI 客户端连接]
E --> F[开始使用]
```
**示例 docker-compose.yml：**
```yaml
services:
playwright-mcp:
image: mcp-playwright:latest
environment:
- PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
- NODE_ENV=production
volumes:
- ./data:/app/data
- ./screenshots:/app/screenshots
```
资料来源：[DOCKER.md:38-48]()
## 环境变量
您可以通过环境变量配置服务器行为：
| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD` | 跳过浏览器自动下载 | `1`（Docker 中默认） |
| `NODE_ENV` | 运行环境 | `production` |
**Docker 中设置环境变量：**
```bash
docker run -i --rm \
-e PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 \
mcp-playwright:latest
```
资料来源：[DOCKER.md:26-31]()
## 故障排除
### 容器立即退出
MCP 服务器需要通过 stdin 接收输入，确保使用 `-i` 标志：
```bash
docker run -i --rm mcp-playwright:latest
```
### 浏览器未找到
Docker 镜像默认跳过浏览器下载以减小体积。如需预安装浏览器，创建自定义 Dockerfile：
```dockerfile
FROM mcp-playwright:latest
RUN npx playwright install chromium --with-deps
```
### 权限问题
如果遇到挂载卷权限问题：
```bash
docker run -i --rm \
-v $(pwd)/data:/app/data \
--user $(id -u):$(id -g) \
mcp-playwright:latest
```
### 日志位置
stdio 模式下，日志文件位置为：`~/playwright-mcp-server.log`
## 下一步
完成快速入门后，您可以：
- 阅读完整的 [API 文档](https://executeautomation.github.io/mcp-playwright/docs/playwright-web/Supported-Tools)
- 了解支持的 [设备配置](https://executeautomation.github.io/mcp-playwright/docs/playwright-web/Device-Quick-Reference)
- 参考 [调整提示指南](https://executeautomation.github.io/mcp-playwright/docs/playwright-web/Resize-Prompts-Guide)
- 查看 [GitHub Issues](https://github.com/executeautomation/mcp-playwright/issues) 获取帮助
## 资源链接
| 资源 | 链接 |
|------|------|
| 官方文档 | https://executeautomation.github.io/mcp-playwright/ |
| API 参考 | https://executeautomation.github.io/mcp-playwright/docs/playwright-web/Supported-Tools |
| GitHub 仓库 | https://github.com/executeautomation/mcp-playwright |
| 问题反馈 | https://github.com/executeautomation/mcp-playwright/issues |
---
## 系统架构
### 相关页面
相关主题：[快速入门指南](#getting-started), [HTTP/SSE 传输模式](#http-transport), [日志与监控](#logging-monitoring)
相关源码文件
以下源码文件用于生成本页说明：
- [src/index.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/index.ts)
- [src/http-server.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/http-server.ts)
- [src/requestHandler.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/requestHandler.ts)
- [src/toolHandler.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/toolHandler.ts)
- [src/sse/server.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/sse/server.ts)
- [src/logging/middleware.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/middleware.ts)
- [src/logging/logger.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/logger.ts)
- [src/tools.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools.ts)
# 系统架构
## 概述
mcp-playwright 是一个基于 Model Context Protocol (MCP) 的 Playwright 自动化服务器，为 AI 助手提供浏览器自动化能力。该项目采用模块化架构设计，支持两种运行模式：stdio（标准输入输出）和 HTTP 模式。 资料来源：[package.json](https://github.com/executeautomation/mcp-playwright/blob/main/package.json)
## 核心架构组件
### 组件架构图
```mermaid
graph TB
subgraph "传输层"
STDIO[STDIO 传输]
HTTP[HTTP 服务器]
SSE[SSE 流]
end
subgraph "核心层"
MCP_SDK[MCP SDK
1.24.3]
RequestHandler[请求处理器]
ToolHandler[工具处理器]
end
subgraph "工具层"
BrowserTools[浏览器工具]
InteractionTools[交互工具]
OutputTools[输出工具]
ContentTools[内容提取工具]
end
subgraph "浏览器层"
Chromium[@playwright/browser-chromium]
Firefox[@playwright/browser-firefox]
WebKit[@playwright/browser-webkit]
end
subgraph "日志层"
Logger[日志记录器]
Middleware[日志中间件]
end
STDIO --> MCP_SDK
HTTP --> SSE
HTTP --> RequestHandler
MCP_SDK --> RequestHandler
RequestHandler --> ToolHandler
ToolHandler --> BrowserTools
ToolHandler --> InteractionTools
ToolHandler --> OutputTools
ToolHandler --> ContentTools
BrowserTools --> Chromium
BrowserTools --> Firefox
BrowserTools --> WebKit
RequestHandler --> Middleware
Middleware --> Logger
```
## 传输层架构
### STDIO 模式
STDIO 模式是 MCP 协议的默认传输方式，适用于 Claude Desktop 等本地客户端。服务器通过标准输入输出进行 JSON-RPC 通信，日志自动写入 `~/playwright-mcp-server.log` 文件。 资料来源：[README.md](https://github.com/executeautomation/mcp-playwright/blob/main/README.md)
```mermaid
graph LR
Client[Claude Desktop
或其他 MCP 客户端] <--> STDIO
STDIO --> Server[主服务器进程]
Server --> Logger[文件日志
playwright-mcp-server.log]
```
### HTTP 模式
HTTP 模式提供独立的 HTTP 服务器，支持远程访问和 VS Code 等 IDE 集成。服务器绑定到 `127.0.0.1`（仅本地），提供 SSE 流式传输和消息接口。 资料来源：[src/http-server.ts:1-50](https://github.com/executeautomation/mcp-playwright/blob/main/src/http-server.ts)
```mermaid
graph LR
subgraph "HTTP 端点"
SSE[SSE Stream
GET /sse]
Messages[Messages
POST /messages]
MCP[MCP 统一接口
GET/POST /mcp]
Health[Health Check
GET /health]
end
Client[外部客户端] --> HTTP_Server[HTTP 服务器
127.0.0.1:8931]
HTTP_Server --> SSE
HTTP_Server --> Messages
HTTP_Server --> MCP
HTTP_Server --> Health
```
### HTTP 端点配置
| 端点 | 方法 | 路径 | 说明 |
|------|------|------|------|
| SSE Stream | GET | `/sse` | 服务器发送事件流 |
| Messages | POST | `/messages?sessionId=` | 发送消息接口 |
| MCP 统一 | GET/POST | `/mcp` | MCP 协议统一接口 |
| Health Check | GET | `/health` | 健康检查端点 |
## 请求处理流程
### 请求生命周期
```mermaid
sequenceDiagram
participant Client as MCP 客户端
participant Middleware as 日志中间件
participant RequestHandler as 请求处理器
participant ToolHandler as 工具处理器
participant Tools as 工具实现
participant Logger as 日志记录器
Client->>Middleware: JSON-RPC 请求
Middleware->>Logger: 记录请求开始
Middleware->>RequestHandler: 转发请求
RequestHandler->>ToolHandler: 分发工具调用
ToolHandler->>Tools: 执行具体工具
Tools-->>ToolHandler: 返回结果
ToolHandler-->>RequestHandler: 返回响应
RequestHandler-->>Middleware: 返回结果
Middleware->>Logger: 记录请求完成
Middleware-->>Client: JSON-RPC 响应
```
### 请求处理器
请求处理器（RequestHandler）负责接收 MCP 协议的 JSON-RPC 请求，进行参数验证和错误处理，然后分发到相应的工具处理器。 资料来源：[src/requestHandler.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/requestHandler.ts)
核心职责包括：
- 解析 MCP 协议消息格式
- 验证请求参数
- 路由工具调用到对应的处理器
- 处理错误和异常情况
## 工具系统架构
### 工具分类
所有工具定义统一在 `src/tools.ts` 中声明，分为以下几类： 资料来源：[src/tools.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools.ts)
| 类别 | 工具名称 | 说明 |
|------|----------|------|
| **浏览器操作** | `playwright_navigate` | 页面导航 |
| | `playwright_screenshot` | 页面截图 |
| | `playwright_close` | 关闭浏览器 |
| **元素交互** | `playwright_click` | 点击元素 |
| | `playwright_fill` | 填写表单 |
| | `playwright_select` | 选择下拉选项 |
| | `playwright_hover` | 悬停元素 |
| | `playwright_press_key` | 按键操作 |
| | `playwright_drag` | 拖拽操作 |
| **内容提取** | `playwright_get_visible_text` | 获取可见文本 |
| | `playwright_get_visible_html` | 获取 HTML 内容 |
| **输出工具** | `playwright_save_as_pdf` | 保存为 PDF |
| **API 测试** | `playwright_expect_response` | 期望响应验证 |
| | `playwright_assert_response` | 断言响应 |
| **IFrame** | `playwright_iframe_click` | IFrame 点击 |
| | `playwright_iframe_fill` | IFrame 填写 |
### 浏览器启动条件
工具系统使用条件启动机制，仅在需要时启动浏览器： 资料来源：[src/tools.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools.ts)
```typescript
export const BROWSER_TOOLS = [
"playwright_navigate",
"playwright_screenshot",
"playwright_click",
"playwright_iframe_click",
"playwright_iframe_fill",
"playwright_fill",
"playwright_select",
"playwright_hover",
"playwright_upload_file",
"playwright_evaluate",
"playwright_resize",
"playwright_close",
"playwright_expect_response",
"playwright_assert_response",
"playwright_custom_user_agent",
"playwright_get_visible_text",
...
];
```
### 工具处理器
工具处理器（ToolHandler）负责管理浏览器实例的生命周期和执行具体工具调用。 资料来源：[src/toolHandler.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/toolHandler.ts)
```mermaid
graph TB
subgraph "ToolHandler"
BrowserManager[浏览器管理器]
ToolRegistry[工具注册表]
SessionManager[会话管理器]
end
ToolRegistry -->|执行| BrowserManager
SessionManager -->|状态| BrowserManager
```
## 日志系统架构
### 日志中间件
日志中间件（LoggingMiddleware）拦截所有工具调用请求，记录详细的执行上下文和错误信息。 资料来源：[src/logging/middleware.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/middleware.ts)
```mermaid
graph LR
Request[请求] --> Middleware[日志中间件]
Middleware --> Sanitize[参数脱敏]
Middleware --> LogStart[记录开始]
Request -->|执行| Handler[工具处理器]
Handler -->|结果| Middleware
Middleware --> LogComplete[记录完成]
Middleware --> LogError[记录错误]
Middleware --> Response[响应]
```
### 日志级别和上下文
| 方法 | 用途 |
|------|------|
| `info()` | 一般信息日志 |
| `warn()` | 警告信息日志 |
| `error()` | 错误信息日志 |
| `logRequest()` | 请求详情日志 |
| `logError()` | 错误详情日志 |
日志上下文包含丰富的系统信息： 资料来源：[src/logging/logger.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/logger.ts)
- 错误名称和消息
- 堆栈跟踪
- 时间戳
- Node.js 版本
- 平台和架构信息
- 内存使用情况
- 运行时间
### 错误分类
日志中间件实现了智能错误分类功能： 资料来源：[src/logging/middleware.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/middleware.ts)
| 错误类型 | 触发条件 |
|----------|----------|
| `validation` | 参数验证失败、缺少必填字段 |
| `resource` | 浏览器/页面连接断开、协议错误 |
| `authentication` | 未授权访问、权限不足 |
| `rate_limit` | 请求频率限制 |
| `system` | 超时、元素未找到、导航失败 |
## 多浏览器支持
### 浏览器类型
项目支持三种浏览器引擎，通过 `browserType` 参数指定： 资料来源：[CHANGELOG.md](https://github.com/executeautomation/mcp-playwright/blob/main/CHANGELOG.md)
| 浏览器 | 参数值 | 包依赖 |
|--------|--------|--------|
| Chromium | `chromium` | `@playwright/browser-chromium` |
| Firefox | `firefox` | `@playwright/browser-firefox` |
| WebKit | `webkit` | `@playwright/browser-webkit` |
### 浏览器依赖版本
所有浏览器包版本统一为 `1.57.0`，核心 Playwright 版本也保持一致。 资料来源：[package.json](https://github.com/executeautomation/mcp-playwright/blob/main/package.json)
```json
{
"@playwright/browser-chromium": "1.57.0",
"@playwright/browser-firefox": "1.57.0",
"@playwright/browser-webkit": "1.57.0",
"playwright": "1.57.0"
}
```
## 服务器启动流程
```mermaid
graph TB
Start[启动] --> Args[解析命令行参数]
Args --> Mode{运行模式}
Mode -->|stdio| STDIO_Init[STDIO 模式初始化]
Mode -->|http| HTTP_Init[HTTP 模式初始化]
STDIO_Init --> SDK_Init[MCP SDK 初始化]
HTTP_Init --> Express[Express 服务器]
Express --> Routes[注册路由]
Routes --> SSE_Init[SSE 服务初始化]
SSE_Init --> SSE_Ready[SSE 就绪]
SDK_Init --> RegisterTools[注册工具]
RegisterTools --> Loop[事件循环]
Loop -->|请求| Handle[处理请求]
Handle -->|调用| Execute[执行工具]
Execute --> Response[返回结果]
Response --> Loop
```
## 入口点架构
### src/index.ts 主入口
主入口文件负责根据命令行参数选择运行模式： 资料来源：[src/index.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/index.ts)
```mermaid
graph LR
Node[Node.js] --> Index[index.ts]
Index --> ParseArgs[解析 --port 参数]
ParseArgs -->|有端口参数| HTTP[HTTP 模式]
ParseArgs -->|无端口参数| STDIO[STDIO 模式]
```
### HTTP 服务器初始化
HTTP 服务器使用 Express 框架，绑定到本地主机（安全考虑）： 资料来源：[src/http-server.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/http-server.ts)
```typescript
// 安全配置：仅绑定本地主机
const host = '127.0.0.1';
const httpServer = app.listen(port, host, () => {
logger.info(`Playwright MCP HTTP server listening on ${host}:${port}`);
});
```
## SSE 服务器架构
### SSE 服务端点
SSE（Server-Sent Events）服务器负责将服务器端事件推送到客户端。 资料来源：[src/sse/server.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/sse/server.ts)
```mermaid
graph LR
Client[客户端] -->|建立连接| SSE[SSE 服务器]
SSE -->|事件流| Client
HTTP_Server[HTTP 服务器] -->|管理| SSE
```
### 会话管理
SSE 服务器支持多会话管理，每个会话通过 `sessionId` 标识：
- `/sse` - 建立 SSE 连接
- `/messages?sessionId=` - 发送消息到指定会话
- `/mcp` - MCP 统一接口（支持 sessionId 参数）
## 安全特性
### 安全设计原则
| 特性 | 说明 |
|------|------|
| 本地绑定 | HTTP 服务器仅绑定 `127.0.0.1`，防止外部访问 |
| 日志脱敏 | 工具参数自动脱敏，移除敏感字段 |
| STDIO 隔离 | stdio 模式下日志仅写入文件 |
### 参数脱敏规则
日志中间件自动识别并脱敏以下敏感字段： 资料来源：[src/logging/middleware.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/middleware.ts)
```typescript
const sensitiveFields = ['password', 'token', 'secret', 'key', 'auth'];
```
## 依赖关系图
### 核心依赖
| 包名 | 版本 | 用途 |
|------|------|------|
| `@modelcontextprotocol/sdk` | 1.24.3 | MCP 协议实现 |
| `express` | ^4.21.1 | HTTP 服务器框架 |
| `cors` | ^2.8.5 | 跨域资源共享 |
| `playwright` | 1.57.0 | 浏览器自动化核心 |
| `uuid` | 11.1.0 | 会话 ID 生成 |
## 测试架构
### 测试框架
项目使用 Jest 作为测试框架，测试文件位于 `src/__tests__` 目录： 资料来源：[README.md](https://github.com/executeautomation/mcp-playwright/blob/main/README.md)
```bash
# 运行测试
npm test
# 带覆盖率
npm run test:coverage
# 自定义测试脚本
node run-tests.cjs
```
### 评估测试
使用 `mcp-eval` 包进行 AI 能力评估：
```bash
OPENAI_API_KEY=your-key npx mcp-eval src/evals/evals.ts src/tools/codegen/index.ts
```
## 总结
mcp-playwright 采用清晰的层次化架构设计：
1. **传输层**：支持 STDIO 和 HTTP 两种模式，适配不同客户端需求
2. **协议层**：基于 MCP SDK 实现标准化的工具调用协议
3. **处理层**：请求处理器和工具处理器分离，职责明确
4. **工具层**：模块化的浏览器自动化工具集，支持多浏览器
5. **日志层**：完善的日志记录和错误追踪机制
该架构确保了系统的可扩展性、可维护性和安全性，同时提供了灵活的部署选项。
---
## 工具参考手册
### 相关页面
相关主题：[快速入门指南](#getting-started), [设备模拟功能](#device-emulation), [测试代码生成](#code-generation)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tools.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools.ts)
- [src/tools/index.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/index.ts)
- [src/tools/browser/index.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/index.ts)
- [src/tools/browser/screenshot.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/screenshot.ts)
- [src/tools/browser/visiblePage.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/visiblePage.ts)
- [src/logging/middleware.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/middleware.ts)
- [package.json](https://github.com/executeautomation/mcp-playwright/blob/main/package.json)
# 工具参考手册
Playwright MCP Server 提供了一套完整的浏览器自动化工具集，通过 MCP（Model Context Protocol）协议暴露给 AI 助手使用。本工具手册详细介绍了所有可用工具的功能、参数配置及使用方法。
## 1. 工具系统概述
### 1.1 架构设计
MCP Playwright 的工具系统采用模块化分层架构，将不同类型的工具按功能域划分为独立的模块。
```mermaid
graph TD
A[MCP Client
Claude/Copilot] --> B[Tool Handler
handleToolCall]
B --> C[Browser Tools
浏览器操作]
B --> D[API Tools
API 测试]
B --> E[Codegen Tools
代码生成]
C --> C1[navigate/click/fill]
C --> C2[screenshot/evaluate]
C --> C3[resize/hover]
C --> C4[drag/press_key]
D --> D1[api_request]
D --> D2[expect_response]
D --> D3[assert_response]
E --> E1[代码生成工具]
```
资料来源：[src/tools.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools.ts)
### 1.2 工具分类
| 工具类别 | 前缀命名 | 功能说明 |
|---------|---------|---------|
| 浏览器工具 | `playwright_*` | 网页导航、元素交互、内容提取 |
| API 工具 | `api_*` | HTTP 请求测试、响应验证 |
| 代码生成工具 | `codegen_*` | 测试代码自动生成 |
### 1.3 工具依赖关系
浏览器操作类工具需要启动浏览器实例，系统通过 `BROWSER_TOOLS` 数组标识这些工具：
```typescript
export const BROWSER_TOOLS = [
"playwright_navigate",
"playwright_screenshot",
"playwright_click",
"playwright_iframe_click",
"playwright_iframe_fill",
"playwright_fill",
"playwright_select",
"playwright_hover",
"playwright_upload_file",
"playwright_evaluate",
"playwright_resize",
"playwright_close",
"playwright_expect_response",
"playwright_assert_response",
"playwright_custom_user_agent",
"playwright_get_visible_text",
];
```
资料来源：[src/tools.ts:1-16](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools.ts)
---
## 2. 浏览器工具详解
### 2.1 导航与浏览器控制
#### playwright_navigate
打开指定 URL 并启动浏览器会话。
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| url | string | 是 | 目标网页 URL |
| browserType | string | 否 | 浏览器类型：chromium/firefox/webkit，默认 chromium |
```javascript
// 示例：使用 Firefox 打开网页
await playwright_navigate({
url: "https://example.com",
browserType: "firefox"
});
```
#### playwright_close
关闭当前浏览器实例并清理资源。
```javascript
await playwright_close();
```
资料来源：[src/tools/browser/index.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/index.ts)
### 2.2 元素交互工具
#### playwright_click
点击页面上的指定元素。
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| selector | string | 是 | CSS 选择器 |
| button | string | 否 | 鼠标按钮：left/right/middle，默认 left |
| clickCount | number | 否 | 点击次数：1/2/3 |
| modifiers | string | 否 | 按住的修饰键：Alt/Control/Meta/Shift |
#### playwright_fill
向输入框填充文本内容。
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| selector | string | 是 | CSS 选择器 |
| value | string | 是 | 要填充的文本值 |
#### playwright_select
从下拉菜单中选择选项。
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| selector | string | 是 | select 元素选择器 |
| value | string | 是 | 选项值或标签 |
| selectType | string | 否 | 选择类型：value/label/index |
#### playwright_hover
鼠标悬停在指定元素上。
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| selector | string | 是 | CSS 选择器 |
#### playwright_drag
将元素从一位置拖拽到另一位置。
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| sourceSelector | string | 是 | 源元素选择器 |
| targetSelector | string | 是 | 目标元素选择器 |
#### playwright_press_key
模拟键盘按键操作。
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| key | string | 是 | 按键名称 |
| selector | string | 否 | 聚焦元素选择器 |
| modifiers | string | 否 | 组合修饰键 |
#### playwright_click_and_switch_tab
点击链接并切换到新打开的标签页。
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| selector | string | 是 | 链接选择器 |
资料来源：[src/tools.ts:20-80](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools.ts)
### 2.3 截图与内容提取
#### playwright_screenshot
对当前页面或指定元素进行截图。
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| name | string | 否 | 截图名称标识（默认 screenshot） |
| selector | string | 否 | 元素选择器，指定则截取元素而非全页 |
| fullPage | boolean | 否 | 是否截取整个可滚动页面 |
| storeBase64 | boolean | 否 | 是否存储 base64 副本到内存 |
| downloadsDir | string | 否 | 保存目录路径 |
```javascript
// 全页面截图
await playwright_screenshot({
name: "homepage",
fullPage: true
});
// 元素截图
await playwright_screenshot({
selector: "#banner",
name: "banner-element"
});
```
截图后，系统自动将 base64 数据存储到内存中供后续访问：
```typescript
if (args.storeBase64 !== false) {
this.screenshots.set(args.name || 'screenshot', base64Screenshot);
this.server.notification({
method: "notifications/resources/list_changed",
});
}
```
资料来源：[src/tools/browser/screenshot.ts:40-50](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/screenshot.ts)
#### playwright_get_visible_text
提取页面或元素的可见文本内容。
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| selector | string | 否 | 元素选择器，不指定则获取整个页面 |
#### playwright_get_visible_html
获取页面或元素的完整 HTML 内容。
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| selector | string | 否 | 元素选择器 |
| removeScripts | boolean | 否 | 移除 script 标签 |
| removeComments | boolean | 否 | 移除 HTML 注释 |
| removeStyles | boolean | 否 | 移除 style 标签 |
| removeMeta | boolean | 否 | 移除 meta 标签 |
| cleanHtml | boolean | 否 | 应用所有清理选项 |
| minify | boolean | 否 | 压缩 HTML |
```javascript
// 获取清理后的 HTML
await playwright_get_visible_html({
selector: "#content",
cleanHtml: true,
minify: true
});
```
资料来源：[src/tools/browser/visiblePage.ts:1-50](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/visiblePage.ts)
### 2.4 设备模拟与视口控制
#### playwright_resize
调整浏览器视口大小或模拟设备。
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| width | number | 否 | 视口宽度（像素） |
| height | number | 否 | 视口高度（像素） |
| device | string | 否 | 预设设备名称（自动设置 viewport、userAgent） |
| orientation | string | 否 | 设备方向：portrait/landscape |
支持 143 种预设设备，包括：
- iPhone 系列（iPhone 13, iPhone 15 Pro Max 等）
- iPad 系列（iPad Pro 11, iPad Mini 等）
- Pixel 系列（Pixel 7, Pixel 8 等）
- Samsung Galaxy 系列
- 桌面浏览器（Desktop Chrome, Firefox, Safari）
```javascript
// 模拟 iPhone 13
await playwright_resize({ device: "iPhone 13" });
// 模拟 iPad 横屏
await playwright_resize({
device: "iPad Pro 11",
orientation: "landscape"
});
// 自定义视口
await playwright_resize({
width: 1920,
height: 1080
});
```
资料来源：[README.md:1-30](https://github.com/executeautomation/mcp-playwright/blob/main/README.md)
### 2.5 JavaScript 执行
#### playwright_evaluate
在浏览器上下文中执行任意 JavaScript 代码。
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| script | string | 是 | 要执行的 JavaScript 代码 |
| params | object | 否 | 传递给脚本的参数 |
```javascript
// 获取页面标题
const title = await playwright_evaluate({
script: "() => document.title"
});
// 带参数执行
const links = await playwright_evaluate({
script: "(count) => Array.from(document.links).slice(0, count)",
params: { count: 10 }
});
```
### 2.6 文件操作
#### playwright_upload_file
上传文件到页面中的文件上传控件。
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| selector | string | 是 | 文件输入框选择器 |
| filePaths | string[] | 是 | 文件路径数组 |
```javascript
await playwright_upload_file({
selector: "input[type='file']",
filePaths: ["/path/to/file.pdf", "/path/to/image.png"]
});
```
#### playwright_save_as_pdf
将当前页面保存为 PDF 文件。
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| outputPath | string | 是 | 输出文件路径 |
| format | string | 否 | 页面格式：A4/Letter |
| printBackground | boolean | 否 | 是否打印背景图形 |
| margin | object | 否 | 页边距配置 |
```javascript
await playwright_save_as_pdf({
outputPath: "/tmp/report.pdf",
format: "A4",
printBackground: true,
margin: {
top: "1cm",
right: "1cm",
bottom: "1cm",
left: "1cm"
}
});
```
---
## 3. API 测试工具
### 3.1 API 请求工具
#### api_request
发送 HTTP 请求并进行测试验证。
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| url | string | 是 | 请求 URL |
| method | string | 否 | HTTP 方法：GET/POST/PUT/DELETE/PATCH |
| headers | object | 否 | 请求头 |
| body | object | 否 | 请求体 |
| timeout | number | 否 | 超时时间（毫秒） |
| authorization | string | 否 | Bearer 认证令牌 |
```javascript
// 发送 POST 请求
const response = await api_request({
url: "https://api.example.com/users",
method: "POST",
headers: {
"Content-Type": "application/json"
},
body: {
name: "张三",
email: "zhangsan@example.com"
},
authorization: "Bearer your-token-here"
});
```
### 3.2 响应验证工具
#### playwright_expect_response
设置预期响应模式，验证后续请求的响应。
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| urlPattern | string | 是 | URL 匹配模式（正则表达式） |
| statusCode | number | 否 | 预期状态码 |
| headers | object | 否 | 预期响应头 |
| bodyPattern | string | 否 | 预期响应体模式 |
#### playwright_assert_response
对已发生的响应进行断言验证。
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| urlPattern | string | 是 | URL 匹配模式 |
| assertType | string | 是 | 断言类型：status/header/body |
| expectedValue | any | 是 | 预期值 |
---
## 4. 工具执行流程
### 4.1 请求处理流程
```mermaid
sequenceDiagram
participant Client as MCP 客户端
participant Handler as Tool Handler
participant Logger as 日志中间件
participant Browser as Playwright 浏览器
participant Tools as 工具实现
Client->>Handler: 工具调用请求
Handler->>Logger: 记录请求开始
Logger->>Browser: 检查/启动浏览器
Browser->>Tools: 传递参数
Tools->>Browser: 执行浏览器操作
Browser-->>Tools: 返回结果
Tools-->>Logger: 返回响应
Logger-->>Client: 返回结果+日志
```
资料来源：[src/logging/middleware.ts:1-30](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/middleware.ts)
### 4.2 日志记录机制
工具执行中间件提供完整的请求追踪功能：
| 日志阶段 | 记录内容 |
|---------|---------|
| 请求开始 | 工具名称、参数、请求 ID |
| 执行中 | 操作类型、浏览器状态 |
| 完成 | 状态码、耗时、响应内容 |
| 错误 | 错误分类、堆栈跟踪、系统上下文 |
错误分类系统：
```typescript
private categorizeToolError(toolName: string, error: Error): ErrorCategory {
const message = error.message.toLowerCase();
// 资源错误
if (message.includes('browser') || message.includes('page') ||
message.includes('closed') || message.includes('disconnected')) {
return 'resource';
}
// 验证错误
if (message.includes('invalid') || message.includes('validation')) {
return 'validation';
}
// 认证错误
if (message.includes('unauthorized') || message.includes('forbidden')) {
return 'authentication';
}
// 超时错误
if (message.includes('timeout')) {
return 'system';
}
}
```
资料来源：[src/logging/middleware.ts:50-100](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/middleware.ts)
---
## 5. 工具命名规范
### 5.1 命名限制
工具名称必须遵循以下约束：
| 限制项 | 最大值 | 原因 |
|-------|-------|------|
| 工具名称长度 | 60 字符 | Cursor 等客户端限制 |
| 服务器前缀 | playwright_ | 区分不同 MCP 服务器 |
完整工具标识符格式：`playwright-mcp:playwright_xxx`
### 5.2 推荐的短命名
| 完整名称 | 用途场景 |
|---------|---------|
| playwright_navigate | 导航 |
| playwright_click | 点击 |
| playwright_fill | 填充表单 |
| playwright_screenshot | 截图 |
| playwright_close | 关闭 |
---
## 6. 错误处理
### 6.1 错误分类
| 错误类型 | 触发条件 | 示例消息 |
|---------|---------|---------|
| validation | 参数验证失败 | "invalid selector"、"required parameter missing" |
| resource | 浏览器资源问题 | "browser closed"、"target page closed" |
| authentication | 认证授权失败 | "unauthorized"、"access denied" |
| rate_limit | 请求频率限制 | "rate limit exceeded" |
| system | 超时/系统错误 | "timeout waiting for element" |
### 6.2 错误上下文捕获
系统自动捕获并记录以下错误上下文信息：
```typescript
{
errorName: string, // 错误类型名称
errorMessage: string, // 错误消息
stack: string, // 堆栈跟踪
timestamp: string, // ISO 时间戳
nodeVersion: string, // Node.js 版本
platform: string, // 操作系统平台
memoryUsage: object, // 内存使用情况
uptime: number, // 进程运行时间
toolName: string, // 工具名称
toolCategory: string, // 工具类别
browserContext: object // 浏览器上下文
}
```
---
## 7. 配置与运行模式
### 7.1 标准模式（stdio）
适合 Claude Desktop 等标准 MCP 客户端：
```json
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["-y", "@executeautomation/playwright-mcp-server"]
}
}
}
```
### 7.2 HTTP 模式
适合 VS Code、自定义客户端和远程部署：
```bash
npx @executeautomation/playwright-mcp-server --port 8931
```
可用端点：
| 端点 | 方法 | 用途 |
|-----|------|------|
| /sse | GET | SSE 流推送 |
| /messages | POST | 消息接收 |
| /mcp | GET/POST | MCP 统一接口 |
| /health | GET | 健康检查 |
### 7.3 Docker 部署
```bash
docker run -i --rm mcp-playwright:latest
```
环境变量配置：
| 变量名 | 说明 | 默认值 |
|-------|------|-------|
| PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD | 跳过浏览器自动安装 | false |
| NODE_ENV | 运行环境 | development |
---
## 8. 快速参考表
### 8.1 常用工具速查
| 功能需求 | 推荐工具 | 必需参数 |
|---------|---------|---------|
| 打开网页 | playwright_navigate | url |
| 点击元素 | playwright_click | selector |
| 填写表单 | playwright_fill | selector, value |
| 页面截图 | playwright_screenshot | - |
| 获取文本 | playwright_get_visible_text | selector |
| 调整窗口 | playwright_resize | width, height |
| 模拟设备 | playwright_resize | device |
| 发送请求 | api_request | url |
### 8.2 参数类型速查
| 类型标识 | 说明 | 示例 |
|---------|------|------|
| string | 字符串 | "hello" |
| number | 数字 | 123 |
| boolean | 布尔值 | true/false |
| object | 对象 | {key: "value"} |
| string[] | 字符串数组 | ["a", "b", "c"] |
---
## 9. 依赖版本
| 依赖包 | 版本 | 用途 |
|-------|------|------|
| playwright | 1.57.0 | 浏览器自动化核心 |
| @modelcontextprotocol/sdk | 1.24.3 | MCP 协议实现 |
| @playwright/test | ^1.57.0 | 测试框架 |
| express | ^4.21.1 | HTTP 服务器（HTTP 模式） |
资料来源：[package.json:1-30](https://github.com/executeautomation/mcp-playwright/blob/main/package.json)
---
## 设备模拟功能
### 相关页面
相关主题：[工具参考手册](#tool-reference), [快速入门指南](#getting-started)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tools/browser/resize.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/resize.ts)
- [src/tools/browser/useragent.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/useragent.ts)
- [scripts/list-devices.cjs](https://github.com/executeautomation/mcp-playwright/blob/main/scripts/list-devices.cjs)
- [docs/docs/playwright-web/Device-Quick-Reference.md](https://github.com/executeautomation/mcp-playwright/blob/main/docs/docs/playwright-web/Device-Quick-Reference.md)
# 设备模拟功能
## 概述
设备模拟功能是 MCP Playwright 服务器的核心特性之一，允许 AI 助手和自动化测试工具在真实的设备配置下测试 Web 应用程序。该功能通过 `playwright_resize` 工具实现，支持 **143 种真实设备预设**，涵盖 iPhone、iPad、Pixel、Galaxy 以及主流桌面浏览器。
设备模拟功能的核心价值在于：
- 无需物理设备即可在真实设备配置下进行测试
- 自动模拟设备的视口尺寸、用户代理字符串、触摸事件和设备像素比
- 支持横竖屏切换
- 与 AI 助手自然语言交互
资料来源：[README.md](https://github.com/executeautomation/mcp-playwright/blob/main/README.md)
## 架构设计
### 组件关系
```mermaid
graph TD
A[playwright_resize 工具] --> B[ResizeTool 类]
B --> C[BrowserToolBase 基类]
B --> D[Playwright devices 模块]
C --> E[BrowserContext]
D --> F[设备配置数据]
F --> F1[viewport 视口尺寸]
F --> F2[userAgent 用户代理]
F --> F3[deviceScaleFactor 像素比]
F --> F4[isMobile 移动标识]
F --> F5[hasTouch 触摸支持]
```
### 执行流程
```mermaid
sequenceDiagram
participant AI as AI 助手
participant MCP as MCP 服务器
participant PT as Playwright ResizeTool
participant PW as Playwright Core
AI->>MCP: playwright_resize({ device: "iPhone 13" })
MCP->>PT: execute(args, context)
alt 使用设备预设
PT->>PT: 查询 devices['iPhone 13']
PT->>PT: 提取设备属性
PT->>PT: 验证设备存在性
PT->>PW: page.setViewportSize({width, height})
PT->>PW: page.setExtraHTTPHeaders({User-Agent})
else 自定义尺寸
PT->>PT: 验证 width, height 参数
PT->>PT: 检查分辨率限制 (≤7680x4320)
PT->>PW: page.setViewportSize({width, height})
end
alt 设备预设 + 横竖屏
PT->>PT: 根据 orientation 交换宽高
end
PT-->>MCP: ToolResponse
MCP-->>AI: 成功响应
```
## 核心实现
### ResizeTool 类
`ResizeTool` 继承自 `BrowserToolBase`，负责处理设备模拟的核心逻辑。
资料来源：[src/tools/browser/resize.ts:6-12](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/resize.ts)
```typescript
export class ResizeTool extends BrowserToolBase {
async execute(args: any, context: ToolContext): Promise {
return this.safeExecute(context, async (page) => {
let width: number;
let height: number;
let deviceName: string | undefined;
let shouldSetUserAgent = false;
let userAgent: string | undefined;
let isMobile = false;
let hasTouch = false;
let deviceScaleFactor = 1;
// 设备预设解析逻辑
// ...
});
}
}
```
### 设备预设处理逻辑
```mermaid
graph TD
S[开始] --> A{args.device 存在?}
A -->|是| B[查找设备预设]
A -->|否| C[使用 width/height 参数]
B --> D{设备存在?}
D -->|否| E[返回错误 + 热门设备列表]
D -->|是| F[提取设备属性]
F --> F1[提取 viewport 尺寸]
F --> F2[提取 userAgent]
F --> F3[提取 isMobile]
F --> F4[提取 hasTouch]
F --> F5[提取 deviceScaleFactor]
F1 --> G{orientation 参数?}
C --> G
E --> END[返回]
G -->|landscape| H[交换宽高]
G -->|portrait| I[保持原尺寸]
H --> J[应用视口配置]
I --> J
J --> K[返回成功响应]
K --> END
```
资料来源：[src/tools/browser/resize.ts:21-85](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/resize.ts)
## API 参考
### 工具名称
`playwright_resize`
### 输入参数
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `device` | `string` | 否 | 设备预设名称，如 "iPhone 13"、"Desktop Chrome" |
| `width` | `number` | 否 | 视口宽度（像素），与 device 二选一 |
| `height` | `number` | 否 | 视口高度（像素），与 device 二选一 |
| `orientation` | `string` | 否 | 设备方向：`portrait`（竖屏）或 `landscape`（横屏） |
### 参数优先级
1. 若指定 `device`，优先使用设备预设配置
2. 若未指定 `device`，使用自定义 `width` 和 `height`
3. `orientation` 参数仅在 `device` 模式下生效，用于切换横竖屏
### 设备预设 vs 自定义尺寸
| 特性 | 设备预设模式 | 自定义尺寸模式 |
|------|-------------|---------------|
| 视口尺寸 | 自动从预设提取 | 手动指定 |
| 用户代理 | 自动设置为设备 UA | 不修改 |
| 触摸支持 | 自动启用 | 不启用 |
| 设备像素比 | 自动设置 | 默认为 1 |
| 移动端模拟 | 自动标识 | 不标识 |
| 横竖屏切换 | 支持 | 不支持 |
## 使用示例
### 基础设备模拟
```javascript
// 测试 iPhone 13
await playwright_resize({ device: "iPhone 13" });
```
### 横竖屏切换
```javascript
// iPad Pro 横屏模式
await playwright_resize({ device: "iPad Pro 11", orientation: "landscape" });
// iPhone 14 竖屏模式（默认）
await playwright_resize({ device: "iPhone 14", orientation: "portrait" });
```
### 桌面浏览器
```javascript
// Chrome 桌面视图
await playwright_resize({ device: "Desktop Chrome" });
// Firefox 桌面视图
await playwright_resize({ device: "Desktop Firefox" });
```
### 自定义视口尺寸
```javascript
// 自定义 1920x1080 分辨率
await playwright_resize({ width: 1920, height: 1080 });
```
## 支持的设备列表
设备模拟功能支持 Playwright 内置的完整设备库，包含 **143 种设备预设**。
### 设备分类
| 类别 | 示例设备 | 数量 |
|------|----------|------|
| iPhone 系列 | iPhone 13, iPhone 13 Pro, iPhone 14, iPhone 15 | ~15+ |
| iPad 系列 | iPad Pro 11, iPad Pro 12.9, iPad Mini | ~10+ |
| Pixel 系列 | Pixel 5, Pixel 7, Pixel 8 | ~10+ |
| Galaxy 系列 | Galaxy S9+, Galaxy S21, Galaxy S24 | ~15+ |
| Kindle 系列 | Kindle Paperwhite, Kindle Fire | ~5+ |
| 桌面浏览器 | Desktop Chrome, Desktop Firefox, Desktop Safari | 3 |
### 热门设备建议
当用户输入不存在的设备名时，系统会返回热门设备建议列表：
```
Device "xxx" not found. Popular devices: iPhone 13, iPhone 13 Pro, iPhone 14,
iPhone 15, iPad Pro 11, iPad Pro 12.9, Pixel 5, Pixel 7, Galaxy S9+, Galaxy S24,
Desktop Chrome, Desktop Firefox, Desktop Safari.
Use playwright.devices to see all 143 available devices.
```
资料来源：[src/tools/browser/resize.ts:43-53](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/resize.ts)
## 设备配置属性
每个设备预设包含以下属性：
| 属性 | 类型 | 描述 |
|------|------|------|
| `viewport.width` | `number` | 视口宽度（像素） |
| `viewport.height` | `number` | 视口高度（像素） |
| `viewport.deviceScaleFactor` | `number` | 设备像素比（通常为 1-3） |
| `viewport.isMobile` | `boolean` | 是否为移动设备 |
| `viewport.hasTouch` | `boolean` | 是否支持触摸 |
| `userAgent` | `string` | HTTP User-Agent 字符串 |
### 示例：iPhone 13 配置
```javascript
{
viewport: {
width: 390,
height: 844,
deviceScaleFactor: 3,
isMobile: true,
hasTouch: true,
isLandscape: false
},
userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 15_0 like Mac OS X) AppleWebKit/605.1.15'
}
```
## 参数验证规则
### 设备预设模式
- 设备名称必须在 Playwright devices 库中存在
- `orientation` 必须是 `portrait` 或 `landscape`
### 自定义尺寸模式
| 验证项 | 规则 | 错误消息 |
|--------|------|----------|
| 参数必填 | `width` 和 `height` 至少提供一个 | "Width or height parameter is required" |
| 正整数验证 | 值必须大于 0 | "Width and height must be positive integers" |
| 分辨率上限 | 不超过 7680x4320 (8K) | "Width and height must not exceed 7680x4320 (8K resolution)" |
资料来源：[src/tools/browser/resize.ts:103-112](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/resize.ts)
## AI 助手自然语言集成
设备模拟功能设计为与 AI 助手无缝集成，支持自然语言命令：
### 支持的命令模式
| 自然语言 | 转换为工具调用 |
|----------|---------------|
| "Test on iPhone 13" | `playwright_resize({ device: "iPhone 13" })` |
| "Switch to iPad view" | `playwright_resize({ device: "iPad Pro 11" })` |
| "Rotate to landscape" | `playwright_resize({ device: "iPhone 14", orientation: "landscape" })` |
| "Show desktop view" | `playwright_resize({ device: "Desktop Chrome" })` |
资料来源：[README.md](https://github.com/executeautomation/mcp-playwright/blob/main/README.md)
## 错误处理
### 常见错误及解决方案
| 错误类型 | 错误消息 | 解决方案 |
|----------|----------|----------|
| 设备不存在 | `Device "xxx" not found` | 使用热门设备列表中的设备名 |
| 尺寸无效 | `Width and height must be positive integers` | 提供正整数值 |
| 分辨率超限 | `Width and height must not exceed 7680x4320` | 使用合理的分辨率 |
| 浏览器未启动 | `Browser not launched` | 先调用 `playwright_navigate` 启动浏览器 |
### 错误响应格式
```json
{
"isError": true,
"content": [
{
"type": "text",
"text": "Device \"iPhone 99\" not found. Popular devices: iPhone 13, iPhone 13 Pro..."
}
]
}
```
## 与其他工具的配合
### 推荐的工具调用顺序
```mermaid
graph LR
A[playwright_navigate] --> B[playwright_resize]
B --> C[playwright_screenshot]
C --> D[playwright_click]
D --> E[playwright_fill]
```
1. **启动浏览器**：`playwright_navigate` - 初始化浏览器上下文
2. **设置设备**：`playwright_resize` - 应用设备模拟配置
3. **截图验证**：`playwright_screenshot` - 验证设备视图
4. **交互操作**：`playwright_click` / `playwright_fill` - 执行测试操作
## 性能注意事项
| 项目 | 建议 |
|------|------|
| 设备切换频率 | 避免频繁切换设备，每次切换都有性能开销 |
| 高分辨率设备 | 8K 以上分辨率可能导致内存问题 |
| 触摸事件 | `hasTouch: true` 会影响事件分发逻辑 |
| 设备像素比 | 高像素比（如 3x）会增加截图和渲染开销 |
## 相关工具
| 工具名称 | 功能描述 | 关系 |
|----------|----------|------|
| `playwright_navigate` | 启动浏览器并导航到 URL | 前置依赖 |
| `playwright_screenshot` | 截取页面截图 | 配合使用 |
| `playwright_custom_user_agent` | 自定义用户代理字符串 | 独立功能 |
| `playwright_get_visible_text` | 获取页面可见文本 | 配合使用 |
资料来源：[src/tools.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools.ts)
---
## 测试代码生成
### 相关页面
相关主题：[工具参考手册](#tool-reference)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tools/codegen/recorder.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/codegen/recorder.ts)
- [src/tools/codegen/generator.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/codegen/generator.ts)
- [src/tools/codegen/types.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/codegen/types.ts)
- [src/tools/codegen/index.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/codegen/index.ts)
# 测试代码生成
## 概述
测试代码生成（Code Generation）是 MCP Playwright 提供的一项高级功能，允许开发者通过 MCP 工具执行自动化操作，并自动记录这些操作，最终生成可重用的 Playwright 测试脚本。
该功能的核心价值在于：
- 将手动录制的用户操作自动转化为可执行的测试代码
- 支持从记录的会话中生成结构化的 Playwright 测试用例
- 提供灵活的配置选项以满足不同项目的测试需求
资料来源：[src/tools/codegen/index.ts:1-20]()
## 架构设计
### 核心组件
测试代码生成模块由三个主要组件构成：
| 组件 | 文件路径 | 职责 |
|------|----------|------|
| ActionRecorder | `recorder.ts` | 记录 MCP 工具调用操作 |
| PlaywrightGenerator | `generator.ts` | 根据记录的操作生成测试代码 |
| 工具接口 | `index.ts` | 提供对外的 MCP 工具入口 |
```mermaid
graph TD
A[MCP 客户端] --> B[start_codegen_session]
B --> C[ActionRecorder]
C --> D[CodegenSession]
D --> E[PlaywrightGenerator]
E --> F[PlaywrightTestCase]
F --> G[测试代码文件]
H[record_action] --> C
C --> I[get_session]
```
资料来源：[src/tools/codegen/generator.ts:1-10]()
### 类型定义
types.ts 文件定义了核心数据结构：
| 类型 | 用途 |
|------|------|
| `CodegenAction` | 单个工具调用操作的表示 |
| `CodegenSession` | 包含多个操作的会话容器 |
| `CodegenOptions` | 代码生成的配置选项 |
| `CodegenResult` | 生成的测试代码结果 |
| `PlaywrightTestCase` | 生成的测试用例结构 |
资料来源：[src/tools/codegen/types.ts]()
## 工作流程
### 整体流程
```mermaid
graph LR
A[开始会话] --> B[执行 MCP 工具]
B --> C[record_action]
C --> D{是否结束会话?}
D -->|否| B
D -->|是| E[generate_test]
E --> F[输出测试代码]
F --> G[保存到文件]
```
### 会话管理
1. **启动会话**：调用 `start_codegen_session` 初始化新的代码生成会话
2. **记录操作**：每个 MCP 工具调用通过 `record_action` 自动记录
3. **生成代码**：调用 `generate_playwright_test` 将会话转化为测试代码
4. **保存结果**：生成的代码保存到指定的输出目录
资料来源：[src/tools/codegen/index.ts:35-80]()
## 配置选项
`CodegenOptions` 接口提供以下可配置项：
| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `outputPath` | `string` | `'tests'` | 测试文件输出目录 |
| `testNamePrefix` | `string` | `'MCP'` | 测试名称前缀 |
| `includeComments` | `boolean` | `true` | 是否在生成的代码中包含注释 |
```typescript
const DEFAULT_OPTIONS: Required = {
outputPath: 'tests',
testNamePrefix: 'MCP',
includeComments: true,
};
```
资料来源：[src/tools/codegen/generator.ts:10-15]()
### 自定义配置示例
```json
{
"options": {
"outputPath": "/path/to/e2e",
"testNamePrefix": "E2E",
"includeComments": true
}
}
```
## MCP 工具接口
### start_codegen_session
启动一个新的代码生成会话。
**参数**：
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `options` | `CodegenOptions` | 否 | 代码生成配置选项 |
**返回值**：包含会话 ID 和状态的对象
资料来源：[src/tools/codegen/index.ts:35-50]()
### record_action
记录单个工具调用操作到当前会话。
**参数**：
| 参数名 | 类型 | 说明 |
|--------|------|------|
| `toolName` | `string` | 工具名称 |
| `args` | `object` | 工具参数 |
| `result` | `object` | 工具执行结果 |
### generate_playwright_test
根据记录的会话生成 Playwright 测试代码。
**参数**：
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `sessionId` | `string` | 是 | 会话 ID |
**返回值**：`CodegenResult`，包含生成的代码和文件路径
资料来源：[src/tools/codegen/generator.ts:30-45]()
### get_codegen_session
获取指定会话的信息和已记录的操作。
**参数**：
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `sessionId` | `string` | 是 | 会话 ID |
### cleanup_codegen_session
清理指定会话，释放相关资源。
**参数**：
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `sessionId` | `string` | 是 | 会话 ID |
## PlaywrightGenerator 类
`PlaywrightGenerator` 是核心的测试代码生成器类，负责将操作记录转化为 Playwright 测试代码。
```typescript
export class PlaywrightGenerator {
private static readonly DEFAULT_OPTIONS: Required = {
outputPath: 'tests',
testNamePrefix: 'MCP',
includeComments: true,
};
private options: Required;
}
```
### 公共方法
| 方法 | 返回类型 | 说明 |
|------|----------|------|
| `generateTest(session)` | `Promise` | 生成测试代码 |
| `createTestCase(session)` | `PlaywrightTestCase` | 创建测试用例对象 |
| `generateTestCode(testCase)` | `string` | 生成测试代码字符串 |
| `getOutputFilePath(session)` | `string` | 获取输出文件路径 |
### 生成流程
```mermaid
graph TD
A[generateTest] --> B[验证 session 数据]
B --> C[createTestCase]
C --> D[生成测试用例对象]
D --> E[generateTestCode]
E --> F[获取输出文件路径]
F --> G[返回 CodegenResult]
```
资料来源：[src/tools/codegen/generator.ts:35-55]()
### 选项验证
`validateOptions` 方法确保配置选项的类型正确：
| 验证规则 | 选项 | 类型要求 |
|----------|------|----------|
| 1 | `outputPath` | 必须为字符串 |
| 2 | `testNamePrefix` | 必须为字符串 |
| 3 | `includeComments` | 必须为布尔值 |
如果选项类型不匹配，将抛出相应的验证错误。
资料来源：[src/tools/codegen/generator.ts:20-30]()
## 错误处理
### 会话验证
- 无效的会话数据将抛出 `Invalid session data` 错误
- 会话必须包含有效的 `actions` 数组
### 选项验证
- `outputPath` 类型错误抛出 `outputPath must be a string`
- `testNamePrefix` 类型错误抛出 `testNamePrefix must be a string`
- `includeComments` 类型错误抛出 `includeComments must be a boolean`
### 常见错误场景
| 错误场景 | 错误信息 |
|----------|----------|
| 空 session | `Invalid session data` |
| actions 非数组 | `Invalid session data` |
| 选项类型错误 | `{optionName} must be a {type}` |
资料来源：[src/tools/codegen/generator.ts:25-40]()
## 使用示例
### 基本使用流程
```mermaid
sequenceDiagram
participant User
participant MCP as MCP Server
participant Recorder as ActionRecorder
participant Generator as PlaywrightGenerator
User->>MCP: start_codegen_session()
MCP->>Recorder: 创建新会话
User->>MCP: 导航到页面
User->>MCP: record_action("navigate", args)
MCP->>Recorder: 记录操作
User->>MCP: 执行其他操作
User->>MCP: generate_playwright_test(sessionId)
MCP->>Generator: 生成测试代码
Generator-->>User: 返回测试代码
```
### 完整配置示例
```json
{
"name": "start_codegen_session",
"description": "Start a new code generation session to record MCP tool actions",
"parameters": {
"type": "object",
"properties": {
"options": {
"type": "object",
"description": "Code generation options",
"properties": {
"outputPath": { "type": "string" },
"testNamePrefix": { "type": "string" },
"includeComments": { "type": "boolean" }
}
}
}
}
}
```
资料来源：[src/tools/codegen/index.ts:35-60]()
## 全局状态管理
代码生成模块使用全局变量存储浏览器和页面实例：
```typescript
declare global {
var browser: Browser | undefined;
var page: Page | undefined;
}
```
这允许在工具调用之间共享 Playwright 浏览器和页面上下文。
资料来源：[src/tools/codegen/index.ts:14-20]()
## 与其他模块的关系
```mermaid
graph TD
A[codegen 模块] --> B[logging 模块]
A --> C[browser 工具]
A --> D[MCP SDK]
B --> B1[middleware.ts]
B --> B2[logger.ts]
C --> C1[navigate.ts]
C --> C2[screenshot.ts]
C --> C3[click.ts]
```
codegen 模块依赖于 logging 模块进行操作记录，并使用 browser 工具执行实际的浏览器操作。
## 最佳实践
1. **会话管理**：在完成操作录制后及时清理会话，避免内存泄漏
2. **路径配置**：使用绝对路径或确保相对路径相对于工作区根目录
3. **命名规范**：使用有意义的 `testNamePrefix` 以便识别生成的测试
4. **注释保留**：在开发阶段保持 `includeComments: true` 以便理解生成的代码
5. **工具命名**：注意 Cursor 等客户端对工具名称有 60 字符限制
资料来源：[README.md:1-10]()
## 相关文档
- [HTTP 模式示例](../examples/http-mode-example.md)
- [Docker 部署指南](./DOCKER.md)
- [主要工具文档](./tools/README.md)
---
## HTTP/SSE 传输模式
### 相关页面
相关主题：[系统架构](#architecture), [客户端配置指南](#client-configuration), [Docker 容器化部署](#docker-deployment)
相关源码文件
以下源码文件用于生成本页说明：
- [src/http-server.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/http-server.ts)
- [src/sse/server.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/sse/server.ts)
- [src/sse/types.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/sse/types.ts)
- [src/sse/index.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/sse/index.ts)
- [examples/http-mode-example.md](https://github.com/executeautomation/mcp-playwright/blob/main/examples/http-mode-example.md)
# HTTP/SSE 传输模式
## 概述
HTTP/SSE 传输模式是 Playwright MCP Server 在 1.0.7 版本中引入的一种独立 HTTP 服务器部署方式。该模式允许将传统的 stdio 通信方式替换为基于 HTTP 和 Server-Sent Events (SSE) 的网络传输架构，适用于在无显示环境的系统中运行有头浏览器、从 IDE 工作进程发起连接，或需要支持多个并发客户端的场景。
此传输模式的核心价值在于将 MCP 协议适配到标准的 HTTP 协议栈上，使得客户端可以通过 RESTful API 与 MCP 服务器进行交互，同时利用 SSE 机制实现服务端向客户端的实时事件推送。
## 系统架构
### 整体架构图
```mermaid
graph TB
subgraph "MCP 客户端"
A[Claude Desktop / VS Code]
B[自定义 HTTP 客户端]
C[curl / Postman]
end
subgraph "HTTP/SSE 服务器"
D[Express Server
端口: 8931]
E[SSE 连接管理器]
F[Session 管理器]
G[请求日志中间件]
end
subgraph "MCP Server Core"
H[工具处理器]
I[浏览器工具集]
J[Playwright 引擎]
end
A -->|"HTTP POST /mcp"| D
B -->|"HTTP POST /mcp"| D
C -->|"HTTP GET /health"| D
D --> G
G --> F
F --> E
E -.->|"SSE Stream"| A
D --> H
H --> I
I --> J
style D fill:#e1f5fe
style E fill:#fff3e0
style F fill:#e8f5e9
```
### 核心组件
| 组件 | 文件位置 | 职责 |
|------|----------|------|
| HTTP Server | `src/http-server.ts` | 启动 Express 服务器，路由配置，端点暴露 |
| SSE Server | `src/sse/server.ts` | 管理 SSE 连接，处理事件流推送 |
| SSE Types | `src/sse/types.ts` | 定义 SSE 相关的数据类型和接口 |
| Session Manager | 内置于 `http-server.ts` | 管理多会话生命周期，跟踪连接状态 |
| 日志中间件 | `src/logging/middleware.ts` | 请求日志记录，错误分类，性能监控 |
## 启动服务器
### 基本启动命令
```bash
# 使用 npx 启动
npx @executeautomation/playwright-mcp-server --port 8931
# 全局安装后启动
npm install -g @executeautomation/playwright-mcp-server
playwright-mcp-server --port 8931
```
服务器启动后会显示以下端点信息：
```
==============================================
Playwright MCP Server (HTTP Mode)
==============================================
Port: 8931
ENDPOINTS:
- SSE Stream: GET http://localhost:8931/sse
- Messages: POST http://localhost:8931/messages?sessionId=
- MCP (unified): GET http://localhost:8931/mcp
- MCP (unified): POST http://localhost:8931/mcp?sessionId=
- Health Check: GET http://localhost:8931/health
```
资料来源：[examples/http-mode-example.md:1-20]()
### 环境变量配置
| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD` | 跳过浏览器下载 | `1` |
| `OPENAI_API_KEY` | API 密钥（用于评估） | - |
## API 端点详解
### 健康检查端点
```
GET http://localhost:8931/health
```
用于验证服务器运行状态，返回服务器健康状态信息。
```bash
curl http://localhost:8931/health
```
资料来源：[examples/http-mode-example.md:30]()
### SSE 流端点
```
GET http://localhost:8931/sse
```
建立与服务端的 SSE 连接，接收服务端推送的事件流。适用于需要实时接收 MCP 工具执行结果或通知的场景。
### 消息发送端点
```
POST http://localhost:8931/messages?sessionId=
Content-Type: application/json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "playwright_navigate",
"arguments": { "url": "https://example.com" }
}
}
```
### 统一 MCP 端点
```
GET http://localhost:8931/mcp # 获取 MCP 连接配置
POST http://localhost:8931/mcp # 发送 MCP 请求
POST http://localhost:8931/mcp?sessionId= # 指定会话的 MCP 请求
```
统一端点将 SSE 流和消息发送合并为一个简洁的接口，是推荐使用的端点。
## 客户端配置
### Claude Desktop 配置
Claude Desktop 目前需要使用 stdio 模式，不支持 HTTP 模式。如需远程访问，推荐通过 SSH 隧道方式连接。
### 自定义客户端配置
```json
{
"mcpServers": {
"playwright": {
"url": "http://localhost:8931/mcp"
}
}
}
```
资料来源：[examples/http-mode-example.md:18-24]()
## 会话管理
### 会话生命周期
```mermaid
stateDiagram-v2
[*] --> 创建会话: 首次连接
创建会话 --> 活跃: 开始通信
活跃 --> 活跃: 发送请求
活跃 --> 心跳: 空闲超时
心跳 --> 活跃: 收到消息
心跳 --> 关闭: 超时
活跃 --> 关闭: 客户端断开
关闭 --> [*]: 清理资源
```
### 会话标识
每个客户端连接通过 `sessionId` 参数进行标识，支持多个客户端并发连接。服务器自动管理会话的创建、维护和销毁。
## 安全特性
### 本地绑定
服务器默认绑定到 `127.0.0.1`（localhost），防止外部网络访问：
> **安全说明**：服务器默认仅监听本地回环地址，这可以防止意外的网络暴露和未授权访问。
资料来源：[README.md:40-45]()
### SSH 隧道远程访问
如需从远程机器访问，建议使用 SSH 隧道：
```bash
ssh -L 8931:localhost:8931 user@server-host
```
这种方式可以在保持服务器本地绑定的同时，实现安全的远程访问。
## 日志与监控
### 请求日志中间件
`src/logging/middleware.ts` 实现了完整的请求日志系统：
| 功能 | 说明 |
|------|------|
| 请求 ID 生成 | 为每个请求分配唯一标识符 |
| 执行时间记录 | 记录工具执行的开始和结束时间 |
| 参数脱敏 | 自动移除敏感字段（password、token、secret、key、auth） |
| 错误分类 | 将错误分为 validation、system、resource 等类别 |
### 日志级别
系统支持以下日志级别，按优先级从低到高：
1. `debug` - 调试信息
2. `info` - 一般信息
3. `warn` - 警告信息
4. `error` - 错误信息
### 文件日志
日志默认写入文件而非控制台，以保证 stdio 模式下的 JSON-RPC 通信不被干扰。日志文件位置：`~/playwright-mcp-server.log`
## 错误处理
### 错误分类系统
| 类别 | 触发条件 | 示例消息 |
|------|----------|----------|
| `validation` | 参数验证失败 | invalid、validation、required |
| `resource` | 资源不可用 | browser、page、connection、closed |
| `authentication` | 认证授权问题 | unauthorized、forbidden、permission |
| `rate_limit` | 速率限制 | rate limit、too many requests |
| `system` | 系统级错误 | timeout、element、navigation |
### 错误上下文捕获
错误对象包含丰富的上下文信息：
```typescript
{
errorName: string,
errorMessage: string,
stack: string,
timestamp: ISO8601,
nodeVersion: string,
platform: string,
arch: string,
memoryUsage: object,
uptime: number,
toolName?: string,
toolCategory?: string
}
```
资料来源：[src/logging/middleware.ts:100-115]()
## 部署场景
### Docker 部署
在 Docker 容器中运行时，HTTP 模式特别有用：
```bash
docker run -i --rm \
-p 8931:8931 \
mcp-playwright:latest
```
容器内运行需要使用 `-i` 标志保持 STDIN 开放，以便 MCP 服务器正常工作。
### Docker Compose 配置
```yaml
services:
playwright-mcp:
image: mcp-playwright:latest
ports:
- "8931:8931"
environment:
- NODE_ENV=production
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8931/health"]
interval: 30s
timeout: 10s
retries: 3
```
### 资源限制
```bash
docker run -i --rm \
--cpus="2.0" \
--memory="2g" \
-p 8931:8931 \
mcp-playwright:latest
```
## 与 Stdio 模式对比
| 特性 | Stdio 模式 | HTTP/SSE 模式 |
|------|------------|----------------|
| 通信方式 | 标准输入/输出 | HTTP + SSE |
| 多客户端 | 不支持 | 支持 |
| 远程访问 | 不直接支持 | 支持（需 SSH 隧道） |
| 健康检查 | 无 | 有（`/health`） |
| Claude Desktop | 支持 | 不支持 |
| VS Code | 支持 | 支持 |
| 日志输出 | 文件 | 文件 + 可配置 |
## 故障排除
### 容器立即退出
MCP 服务器需要通过 STDIN 接收输入。确保使用 `-i` 标志：
```bash
docker run -i --rm mcp-playwright:latest
```
### 浏览器未找到
Docker 镜像默认跳过浏览器下载以减小体积。如需预装浏览器，创建自定义 Dockerfile：
```dockerfile
FROM mcp-playwright:latest
RUN npx playwright install chromium --with-deps
```
### 端口占用
如果 8931 端口被占用，使用其他端口：
```bash
npx @executeautomation/playwright-mcp-server --port 8932
```
## 版本历史
| 版本 | 发布日期 | 主要变更 |
|------|----------|----------|
| 1.0.9 | 2025-12-09 | 修复 console 输出缓冲问题，使用 `process.stdout.write()` |
| 1.0.8 | 2025-12-08 | 改善 HTTP 模式下控制台输出可见性 |
| 1.0.7 | 2025-12-07 | 初始引入 HTTP/SSE 传输模式，多会话支持，健康检查 |
资料来源：[CHANGELOG.md:1-25]()
---
## Docker 容器化部署
### 相关页面
相关主题：[HTTP/SSE 传输模式](#http-transport), [客户端配置指南](#client-configuration)
相关源码文件
以下源码文件用于生成本页说明：
- [Dockerfile](https://github.com/executeautomation/mcp-playwright/blob/main/Dockerfile)
- [docker-compose.yml](https://github.com/executeautomation/mcp-playwright/blob/main/docker-compose.yml)
- [docker-build.sh](https://github.com/executeautomation/mcp-playwright/blob/main/docker-build.sh)
- [DOCKER.md](https://github.com/executeautomation/mcp-playwright/blob/main/DOCKER.md)
# Docker 容器化部署
## 概述
MCP Playwright 项目提供了完整的 Docker 容器化解决方案，使 Playwright MCP 服务器能够在隔离的容器环境中运行。该部署方案具有以下核心特性：
- **隔离执行环境**：通过 Docker 容器提供一致的运行时环境
- **简化依赖管理**：所有依赖在镜像构建时预装
- **易于部署分发**：支持 Docker Compose 一键启动
- **MCP 协议支持**：通过 stdio 或 HTTP 模式与 MCP 客户端通信
资料来源：[DOCKER.md]()
## 架构概览
```mermaid
graph TD
subgraph "宿主机 (Host)"
A[MCP 客户端
Claude Desktop / VS Code]
B[Docker 守护进程]
end
subgraph "Docker 容器"
C[Node.js 运行环境]
D[Playwright MCP Server
dist/index.js]
E[Playwright 浏览器
Chromium/Firefox/WebKit]
end
A -->|JSON-RPC / HTTP| B
B -->|docker run -i| C
C --> D
D -->|自动化控制| E
F[本地文件系统] -.->|volume mount| C
G[screenshots] -.->|volume mount| C
```
## 镜像构建
### 前置条件
在构建 Docker 镜像前，需要确保：
1. 本地已安装 Docker ([Install Docker](https://docs.docker.com/get-docker/))
2. 项目已通过 TypeScript 编译
3. 已安装生产环境依赖
### 构建流程
```mermaid
graph LR
A[npm install --omit=dev] --> B[npm run build]
B --> C[生成 dist/ 和 node_modules/]
C --> D[docker build -t mcp-playwright:latest .]
D --> E[Docker 镜像创建完成]
```
### 使用构建脚本
项目提供了便捷的构建脚本 `docker-build.sh`：
```bash
chmod +x docker-build.sh
./docker-build.sh
```
该脚本会自动执行以下操作：
1. 安装生产依赖 (`npm install --omit=dev`)
2. 编译 TypeScript 代码 (`npm run build`)
3. 构建 Docker 镜像
### 手动构建
手动构建需要分步执行：
```bash
# 1. 安装生产依赖并构建
npm install --omit=dev
npm run build
# 2. 构建 Docker 镜像
docker build -t mcp-playwright:latest .
# 3. 或指定版本标签
docker build -t mcp-playwright:1.0.6 .
```
**重要提示**：Dockerfile 会从本地构建目录复制 `node_modules` 和 `dist`，因此必须先安装 `--omit=dev` 标志的生产依赖，以保持镜像体积最小化。
资料来源：[DOCKER.md:1-50]()
## 容器运行模式
### 标准模式 (stdio)
stdio 模式是 **Claude Desktop 推荐的运行方式**。MCP 服务器通过标准输入输出与客户端通信：
```bash
docker run -i --rm mcp-playwright:latest
```
| 参数 | 说明 |
|------|------|
| `-i` | 保持 STDIN 打开，支持交互式通信 |
| `--rm` | 容器退出时自动删除 |
| `mcp-playwright:latest` | 镜像名称和标签 |
### Docker Compose 模式
项目提供了 `docker-compose.yml` 配置文件：
```bash
# 启动服务
docker compose run --rm playwright-mcp
# 或先构建后运行
docker compose build
docker compose run --rm playwright-mcp
```
`docker-compose.yml` 核心配置：
| 配置项 | 值 | 说明 |
|--------|-----|------|
| `stdin_open` | true | 打开标准输入 |
| `tty` | true | 分配伪终端 |
| `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD` | 1 | 跳过浏览器下载 |
资料来源：[docker-compose.yml]()
## MCP 客户端集成
### Claude Desktop 配置
对于 Claude Desktop 用户，需要修改配置文件：
**配置文件位置**：
| 操作系统 | 路径 |
|----------|------|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |
**配置示例**：
```json
{
"mcpServers": {
"playwright-docker": {
"command": "docker",
"args": ["run", "-i", "--rm", "mcp-playwright:latest"]
}
}
}
```
### VS Code MCP 扩展配置
对于 VS Code MCP 扩展：
```json
{
"name": "playwright-docker",
"command": "docker",
"args": ["run", "-i", "--rm", "mcp-playwright:latest"]
}
```
## 环境变量配置
| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD` | 跳过浏览器下载 | 未设置 |
| `NODE_ENV` | Node.js 运行环境 | `production` |
### 命令行设置环境变量
```bash
docker run -i --rm \
-e PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 \
-e NODE_ENV=production \
mcp-playwright:latest
```
### docker-compose.yml 设置环境变量
```yaml
services:
playwright-mcp:
environment:
- PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
- NODE_ENV=production
```
资料来源：[DOCKER.md:50-80]()
## 数据持久化
### 卷挂载配置
如需与容器共享文件或持久化数据，可使用 volume 挂载：
```bash
docker run -i --rm \
-v $(pwd)/data:/app/data \
-v $(pwd)/screenshots:/app/screenshots \
mcp-playwright:latest
```
### docker-compose.yml 卷配置
```yaml
services:
playwright-mcp:
volumes:
- ./data:/app/data
- ./screenshots:/app/screenshots
```
**注意**：挂载的目录路径必须是绝对路径或使用 `$(pwd)` 获取当前目录。
## 故障排除
### 容器立即退出
**问题**：容器启动后立即退出
**原因**：MCP 服务器需要通过 stdin 接收输入，未使用 `-i` 标志
**解决方案**：
```bash
# 错误
docker run --rm mcp-playwright:latest
# 正确
docker run -i --rm mcp-playwright:latest
```
### 浏览器未找到
**问题**：运行时报错找不到浏览器
**原因**：Docker 镜像默认跳过浏览器下载以减小体积
**解决方案**：创建自定义 Dockerfile 预装浏览器
```dockerfile
FROM mcp-playwright:latest
# 安装 Playwright 浏览器
RUN npx playwright install chromium --with-deps
```
### 权限问题
**问题**：挂载卷出现权限拒绝
**解决方案**：以指定用户身份运行
```bash
docker run -i --rm \
-v $(pwd)/data:/app/data \
--user $(id -u):$(id -g) \
mcp-playwright:latest
```
资料来源：[DOCKER.md:100-130]()
## 高级配置
### 资源限制
```bash
docker run -i --rm \
--cpus="2.0" \
--memory="2g" \
mcp-playwright:latest
```
### docker-compose.yml 资源限制配置
```yaml
services:
playwright-mcp:
deploy:
resources:
limits:
cpus: '2.0'
memory: 2G
```
### 健康检查配置
```yaml
services:
playwright-mcp:
healthcheck:
test: ["CMD", "node", "-e", "process.exit(0)"]
interval: 30s
timeout: 10s
retries: 3
```
### 自定义网络配置
```bash
# 创建网络
docker network create mcp-network
# 在指定网络中运行
docker run -i --rm --network mcp-network mcp-playwright:latest
```
## 从源码构建 Docker 镜像
如果希望完全在 Docker 内构建（不使用本地预编译的 dist）：
```dockerfile
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
ENV PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
RUN npm ci
COPY src ./src
COPY tsconfig.json ./
RUN npm run build
FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/package*.json ./
RUN npm ci --only=production
CMD ["node", "dist/index.js"]
```
此多阶段构建方式：
1. **Builder 阶段**：安装依赖并编译 TypeScript
2. **Runtime 阶段**：仅复制生产文件，减小镜像体积
## 安全最佳实践
### 以非 root 用户运行
```dockerfile
FROM mcp-playwright:latest
USER node
```
### 只读根文件系统
```bash
docker run -i --rm --read-only mcp-playwright:latest
```
### 安全扫描
```bash
docker scan mcp-playwright:latest
```
## 镜像优化
当前 Dockerfile 优化策略：
| 优化项 | 说明 |
|--------|------|
| 基础镜像 | Debian-based slim Node.js (~200MB) |
| 复制策略 | 复制预编译的 dist 目录 |
| 依赖策略 | 仅安装生产依赖 |
| 浏览器 | 默认跳过下载 |
**当前镜像大小**：约 200MB（不含浏览器）
资料来源：[DOCKER.md:180-200]()
## 快速入门命令汇总
```bash
# 1. 克隆项目
git clone https://github.com/executeautomation/mcp-playwright.git
cd mcp-playwright
# 2. 构建镜像
./docker-build.sh
# 3. 测试运行
docker run -i --rm mcp-playwright:latest
# 4. 配置 Claude Desktop
# 编辑 ~/.config/Claude/claude_desktop_config.json
# 5. 重启客户端服务
# 重启 Claude Desktop 使配置生效
```
## 相关信息
- **项目地址**：[executeautomation/mcp-playwright](https://github.com/executeautomation/mcp-playwright)
- **问题反馈**：[GitHub Issues](https://github.com/executeautomation/mcp-playwright/issues)（请添加 `docker` 标签）
- **标准模式部署**：请参阅 [README.md](./README.md) 了解 stdio 模式配置
- **HTTP 模式部署**：请参阅 [examples/http-mode-example.md](./examples/http-mode-example.md) 了解独立服务器部署
---
## 客户端配置指南
### 相关页面
相关主题：[快速入门指南](#getting-started), [HTTP/SSE 传输模式](#http-transport), [Docker 容器化部署](#docker-deployment)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/executeautomation/mcp-playwright/blob/main/README.md)
- [DOCKER.md](https://github.com/executeautomation/mcp-playwright/blob/main/DOCKER.md)
- [examples/http-mode-example.md](https://github.com/executeautomation/mcp-playwright/blob/main/examples/http-mode-example.md)
- [src/http-server.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/http-server.ts)
- [package.json](https://github.com/executeautomation/mcp-playwright/blob/main/package.json)
# 客户端配置指南
## 概述
Playwright MCP Server 支持多种客户端配置方式，以满足不同开发环境和部署场景的需求。本指南涵盖 **stdio 模式**（Claude Desktop 等）、**HTTP 模式**（VS Code、自定义客户端等）以及 **Docker 部署**的完整配置说明。
## 架构概览
```mermaid
graph TD
A[MCP 客户端] --> B{通信模式}
B -->|stdio| C[标准输入输出]
B -->|HTTP| D[SSE/Messages 端点]
C --> E[playwright-mcp-server]
D --> E
E --> F[Playwright 浏览器]
F --> G[自动化操作]
H[日志文件] -.->|~/playwright-mcp-server.log| E
```
## Stdio 模式配置
Stdio 模式是 MCP 协议的默认通信方式，适用于 Claude Desktop 等支持标准输入输出的客户端。
### Claude Desktop 配置
**配置文件位置：**
| 操作系统 | 配置文件路径 |
|---------|------------|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |
**配置示例：**
```json
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["-y", "@executeautomation/playwright-mcp-server"]
}
}
}
```
资料来源：[README.md:1-15]()
**注意事项：**
- stdio 模式下，日志自动重定向到文件而非控制台，以保持 JSON-RPC 通信的纯净性
- 日志文件位置：`~/playwright-mcp-server.log` 资料来源：[README.md:18]()
### Cline 与 Cursor 配置
对于 Cline 和 Cursor 等编辑器插件，工具名称长度限制为 60 字符（`server_name:tool_name`）。由于服务器名称为 `playwright-mcp`，请确保自定义工具名称不超过 40 字符。 资料来源：[README.md:5-10]()
## HTTP 模式配置
HTTP 模式适用于无显示环境（如 headless 系统）或 IDE 工作进程中的有头浏览器运行场景。
### 服务器启动
```bash
# 使用 npx 启动
npx @executeautomation/playwright-mcp-server --port 8931
# 全局安装后启动
npm install -g @executeautomation/playwright-mcp-server
playwright-mcp-server --port 8931
```
资料来源：[README.md:22-27]()
### 端点说明
| 端点类型 | 方法 | URL 格式 | 用途 |
|---------|------|---------|------|
| SSE 流 | GET | `http://localhost:8931/sse` | 服务器发送事件流 |
| 消息 | POST | `http://localhost:8931/messages?sessionId=` | 发送消息 |
| MCP 统一 | GET/POST | `http://localhost:8931/mcp` | 统一 MCP 接口 |
| 健康检查 | GET | `http://localhost:8931/health` | 服务状态检查 |
资料来源：[src/http-server.ts:1-50]()
### HTTP 服务器安全配置
服务器默认绑定到 `127.0.0.1`（localhost），防止外部网络访问：
```mermaid
graph LR
A[客户端] -->|localhost| B[127.0.0.1:8931]
C[外部请求] -.->|✗ 已阻止| B
```
资料来源：[src/http-server.ts:35-36]()
### Claude Desktop HTTP 配置
```json
{
"mcpServers": {
"playwright": {
"url": "http://localhost:8931/mcp"
}
}
}
```
资料来源：[examples/http-mode-example.md:1-15]()
### 健康检查
```bash
curl http://localhost:8931/health
```
响应示例：
```json
{
"status": "ok",
"version": "1.x.x",
"activeSessions": 0
}
```
## Docker 部署配置
### Docker 运行
**基本命令：**
```bash
docker run -i --rm mcp-playwright:latest
```
参数说明：
| 参数 | 作用 |
|-----|------|
| `-i` | 保持 STDIN 打开，支持交互式通信 |
| `--rm` | 容器退出时自动删除 |
| `mcp-playwright:latest` | 镜像名称和标签 |
资料来源：[DOCKER.md:40-50]()
**Docker Compose 配置：**
```yaml
services:
playwright-mcp:
image: mcp-playwright:latest
```
启动命令：
```bash
# 启动服务
docker compose run --rm playwright-mcp
# 构建并运行
docker compose build
docker compose run --rm playwright-mcp
```
### Docker 客户端配置
**Claude Desktop Docker 配置：**
```json
{
"mcpServers": {
"playwright-docker": {
"command": "docker",
"args": ["run", "-i", "--rm", "mcp-playwright:latest"]
}
}
}
```
资料来源：[DOCKER.md:10-20]()
**VS Code MCP Extension 配置：**
```json
{
"name": "playwright-docker",
"command": "docker",
"args": ["run", "-i", "--rm", "mcp-playwright:latest"]
}
```
资料来源：[DOCKER.md:22-28]()
## 环境变量配置
### Docker 环境变量
通过 `-e` 参数传递环境变量：
```bash
docker run -i --rm \
-e PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 \
-e NODE_ENV=production \
mcp-playwright:latest
```
**常用环境变量：**
| 变量名 | 默认值 | 说明 |
|-------|-------|------|
| `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD` | 未设置 | 设为 `1` 跳过浏览器下载 |
| `NODE_ENV` | `production` | Node.js 运行环境 |
资料来源：[DOCKER.md:30-45]()
### Docker Compose 环境变量
```yaml
services:
playwright-mcp:
environment:
- PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
- NODE_ENV=production
```
## 存储卷挂载
### 数据持久化
```bash
docker run -i --rm \
-v $(pwd)/data:/app/data \
-v $(pwd)/screenshots:/app/screenshots \
mcp-playwright:latest
```
### Docker Compose 卷配置
```yaml
services:
playwright-mcp:
volumes:
- ./data:/app/data
- ./screenshots:/app/screenshots
```
资料来源：[DOCKER.md:48-55]()
## 高级配置
### 资源限制
```bash
docker run -i --rm \
--cpus="2.0" \
--memory="2g" \
mcp-playwright:latest
```
Docker Compose 配置：
```yaml
services:
playwright-mcp:
deploy:
resources:
limits:
cpus: '2.0'
memory: 2G
```
资料来源：[DOCKER.md:130-140]()
### 自定义网络
```bash
docker network create mcp-network
docker run -i --rm --network mcp-network mcp-playwright:latest
```
### 用户权限配置
解决挂载卷权限问题：
```bash
docker run -i --rm \
-v $(pwd)/data:/app/data \
--user $(id -u):$(id -g) \
mcp-playwright:latest
```
### 健康检查配置
```yaml
services:
playwright-mcp:
healthcheck:
test: ["CMD", "node", "-e", "process.exit(0)"]
interval: 30s
timeout: 10s
retries: 3
```
## 故障排查
### 容器立即退出
**问题原因：** MCP 服务器需要通过 stdin 接收输入。
**解决方案：** 确保使用 `-i` 参数：
```bash
docker run -i --rm mcp-playwright:latest
```
资料来源：[DOCKER.md:60-65]()
### 浏览器未找到
Docker 镜像默认跳过浏览器下载以减小体积。首次使用时 Playwright 会自动下载浏览器。
**预安装浏览器（自定义 Dockerfile）：**
```dockerfile
FROM mcp-playwright:latest
# 安装 Playwright 浏览器
RUN npx playwright install chromium --with-deps
```
资料来源：[DOCKER.md:70-75]()
## 完整配置示例
### 最小化配置（Stdio 模式）
```json
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["-y", "@executeautomation/playwright-mcp-server"]
}
}
}
```
### 生产环境配置（HTTP 模式）
```json
{
"mcpServers": {
"playwright": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--cpus=2.0",
"--memory=2g",
"-e", "NODE_ENV=production",
"mcp-playwright:latest"
]
}
}
}
```
### Docker Compose 完整配置
```yaml
services:
playwright-mcp:
image: mcp-playwright:latest
environment:
- PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
- NODE_ENV=production
volumes:
- ./data:/app/data
- ./screenshots:/app/screenshots
deploy:
resources:
limits:
cpus: '2.0'
memory: 2G
healthcheck:
test: ["CMD", "node", "-e", "process.exit(0)"]
interval: 30s
timeout: 10s
retries: 3
```
## 版本信息
当前稳定版本参考 [CHANGELOG.md](https://github.com/executeautomation/mcp-playwright/blob/main/CHANGELOG.md)：
| 版本 | 发布日期 | 主要特性 |
|-----|---------|---------|
| 1.0.2 | 2024-11-10 | 多浏览器支持（Chromium、Firefox、WebKit） |
| 1.0.0 | 2024-11-01 | 首个主要版本，重构工具结构 |
**依赖版本：**
| 包名 | 版本 |
|-----|------|
| `@modelcontextprotocol/sdk` | 1.24.3 |
| `playwright` | 1.57.0 |
| `@playwright/browser-chromium` | 1.57.0 |
资料来源：[package.json:1-30]()
---
## 日志与监控
### 相关页面
相关主题：[系统架构](#architecture), [故障排除指南](#troubleshooting)
相关源码文件
以下源码文件用于生成本页说明：
- [src/logging/index.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/index.ts)
- [src/logging/logger.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/logger.ts)
- [src/logging/middleware.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/middleware.ts)
- [src/logging/types.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/types.ts)
- [src/monitoring/index.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/monitoring/index.ts)
- [src/monitoring/system.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/monitoring/system.ts)
- [src/rate-limiting/index.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/rate-limiting/index.ts)
- [src/rate-limiting/limiter.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/rate-limiting/limiter.ts)
# 日志与监控
## 概述
mcp-playwright 的日志与监控系统为 MCP 服务器提供了一套完整的请求追踪、错误分类和系统健康监测能力。该系统通过统一的日志记录层捕获所有工具调用请求、响应状态和错误信息，同时结合健康检查机制确保服务稳定运行。
核心功能包括：
- **请求日志记录**：追踪所有工具调用的生命周期
- **错误分类与增强上下文**：自动识别错误类型并收集诊断信息
- **敏感数据脱敏**：防止日志中泄露密码、Token 等敏感信息
- **系统健康监控**：实时监测 CPU、内存、错误率等关键指标
- **日志轮转**：自动管理日志文件大小和数量
## 架构设计
### 系统组件关系
```mermaid
graph TD
A[MCP 客户端请求] --> B[LoggingMiddleware]
B --> C[Logger]
B --> D[MonitoringSystem]
B --> E[工具处理器]
C --> F[文件日志]
D --> G[健康检查端点]
E --> H[Response]
B --> I[错误处理]
I --> C
D --> J[Rate Limiter]
```
### 日志层级
| 级别 | 用途 | 日志方法 |
|------|------|----------|
| debug | 调试信息，仅开发环境使用 | `logger.debug()` |
| info | 常规操作记录 | `logger.info()` |
| warn | 警告信息，需要关注但非致命 | `logger.warn()` |
| error | 错误信息，记录异常和堆栈 | `logger.error()` |
日志级别通过配置控制，低于配置级别的日志不会输出。 资料来源：[src/logging/logger.ts:156-162]()
## 日志系统
### Logger 核心功能
Logger 是日志系统的核心组件，支持以下功能：
| 功能 | 描述 | 配置项 |
|------|------|--------|
| 文件输出 | 写入本地日志文件 | `filePath`, `maxFileSize` |
| 日志轮转 | 自动管理日志文件数量 | `maxFiles` |
| 级别控制 | 按级别过滤日志 | `level` |
| 请求上下文 | 记录请求相关详细信息 | `RequestLogContext` |
| 错误增强 | 附带错误对象信息 | `ErrorLogContext` |
资料来源：[src/logging/logger.ts:1-60]()
### 日志格式化
每条日志条目包含以下结构化数据：
```typescript
interface LogEntry {
timestamp: string; // ISO 8601 格式时间戳
level: 'debug' | 'info' | 'warn' | 'error';
message: string; // 日志消息
requestId?: string; // 请求唯一标识
context?: Record; // 附加上下文
}
```
### 请求日志上下文
```typescript
interface RequestLogContext {
method: string; // HTTP 方法或工具调用类型
url?: string; // 请求路径或工具名称
body?: any; // 请求体（已脱敏）
statusCode?: number; // 响应状态码
duration?: number; // 处理时长（毫秒）
userAgent?: string; // 客户端标识
clientIp?: string; // 客户端 IP
}
```
资料来源：[src/logging/middleware.ts:1-40]()
## 中间件层
### LoggingMiddleware 工作流程
LoggingMiddleware 拦截所有 MCP 请求，提供统一的日志记录和错误处理能力：
```mermaid
sequenceDiagram
participant Client as MCP 客户端
participant Middleware as LoggingMiddleware
participant Logger as Logger
participant Handler as 工具处理器
participant Monitoring as MonitoringSystem
Client->>Middleware: 工具调用请求
Middleware->>Logger: logRequest() - 请求开始
Middleware->>Handler: 执行工具处理
Handler-->>Middleware: 处理结果
alt 成功响应
Middleware->>Logger: logRequest() - 请求成功
else 错误响应
Middleware->>Middleware: captureErrorContext()
Middleware->>Logger: warn() - 请求错误
end
Middleware->>Monitoring: recordRequest()
Middleware-->>Client: 返回响应
```
### 错误分类
中间件能够自动识别并分类错误类型：
| 错误类别 | 触发条件 | 示例 |
|----------|----------|------|
| validation | 包含 invalid、validation、required 等关键词 | 参数校验失败 |
| resource | 浏览器断开、页面关闭、协议错误 | 浏览器未启动 |
| authentication | 未授权、禁止访问、权限问题 | Token 无效 |
| rate_limit | 速率限制、请求过多 | 请求频率超限 |
| system | 超时、元素未找到、导航失败 | 元素等待超时 |
| unknown | 无法归类的其他错误 | 未知异常 |
资料来源：[src/logging/middleware.ts:80-110]()
### 错误上下文捕获
```typescript
interface ErrorContext {
errorName: string; // 错误类型名称
errorMessage: string; // 错误消息
stack?: string; // 堆栈跟踪
timestamp: string; // 错误发生时间
nodeVersion: string; // Node.js 版本
platform: string; // 操作系统平台
arch: string; // CPU 架构
memoryUsage: object; // 内存使用情况
uptime: number; // 进程运行时间
toolName?: string; // 调用的工具名称
toolCategory?: string; // 工具分类
}
```
资料来源：[src/logging/middleware.ts:120-145]()
## 敏感数据保护
### 脱敏策略
日志中间件包含智能数据脱敏功能，防止敏感信息泄露：
| 数据类型 | 脱敏规则 | 示例 |
|----------|----------|------|
| 密码字段 | 替换为 `[REDACTED]` | `password: "***"` |
| Token 字段 | 替换为 `[REDACTED]` | `token: "***"` |
| Secret 字段 | 替换为 `[REDACTED]` | `secret: "***"` |
| Key 字段 | 替换为 `[REDACTED]` | `apiKey: "***"` |
| Auth 字段 | 替换为 `[REDACTED]` | `auth: "***"` |
| 长请求体 | 截断并标注长度 | `[TRUNCATED:5000chars]` |
资料来源：[src/logging/middleware.ts:160-180]()
### 工具参数过滤
```typescript
private sanitizeToolArgs(toolName: string, args: any): any {
// 检测包含敏感关键词的参数
const sensitiveFields = ['password', 'token', 'secret', 'key', 'auth'];
// 将敏感字段值替换为 [REDACTED]
}
```
## 监控系统
### HealthStatus 系统状态
系统健康状态包含多个检查项：
| 检查项 | 指标 | 阈值 | 状态 |
|--------|------|------|------|
| CPU | 使用率 | >80% 警告, >90% 失败 | pass/warn/fail |
| Memory | 使用率 | >80% 警告, >90% 失败 | pass/warn/fail |
| Error Rate | 错误率 | >1% 警告, >5% 失败 | pass/warn/fail |
资料来源：[src/monitoring/system.ts:80-120]()
### 健康状态响应格式
```typescript
interface HealthStatus {
status: 'healthy' | 'degraded' | 'unhealthy';
checks: {
[key: string]: {
status: 'pass' | 'warn' | 'fail';
description: string;
data: Record;
};
};
timestamp: number;
version: string;
}
```
### 指标收集
监控系统持续收集以下指标：
- **请求计数**：总请求数、成功/失败数
- **响应时长**：平均、最小、最大响应时间
- **错误分类统计**：按错误类型分类的错误计数
- **系统资源**：CPU、内存使用率
- **分类指标**：按工具分类的请求统计
资料来源：[src/monitoring/system.ts:1-50]()
### HTTP 健康检查服务器
监控系统可启动独立的 HTTP 服务器提供健康检查端点：
```typescript
async startMetricsCollection(port: number = 3001): Promise {
// 启动 HTTP 服务器用于健康检查
await this.startHttpServer(port);
}
```
## 日志输出模式
### STDIO 模式
在标准 MCP stdio 通信模式下，日志自动写入文件而非控制台：
> 日志会自动定向到文件（而非控制台），以保持 JSON-RPC 通信的清洁性。
日志文件位置：`~/playwright-mcp-server.log`
资料来源：[README.md:1-30]()
### HTTP 模式
在 HTTP 服务模式下，可通过以下端点访问：
```
GET /health - 健康检查端点
GET /sse - SSE 流式端点
POST /messages - 消息处理端点
GET /mcp - MCP 统一端点
```
资料来源：[examples/http-mode-example.md:1-30]()
## 日志文件管理
### 日志轮转机制
Logger 实现自动日志轮转功能：
1. **大小检查**：每次写入前检查当前文件大小
2. **阈值触发**：超过 `maxFileSize` 触发轮转
3. **文件重命名**：当前日志文件重命名为 `.1` 后缀
4. **序号递进**：现有轮转文件序号递增（`.1` → `.2` → ...）
5. **旧文件清理**：超过 `maxFiles` 数量的最旧文件被删除
```mermaid
graph LR
A[app.log] -->|超过 10MB| B[app.log.1]
B -->|再次轮转| C[app.log.2]
C -->|再次轮转| D[app.log.3]
D -->|超过最大数量| X[删除]
```
资料来源：[src/logging/logger.ts:100-140]()
## 集成使用
### 请求处理中的集成
日志和监控系统通过 `wrapWithMonitoring` 包装器集成到请求处理流程中：
```typescript
const wrapWithMonitoring = (
fn: T,
category: string
): T => {
return (async (...args: any[]) => {
const startTime = Date.now();
let success = true;
try {
const result = await fn(...args);
// 记录成功指标
monitoringSystem.recordRequest(duration, true, category);
return result;
} catch (error) {
// 记录失败指标
monitoringSystem.recordRequest(duration, false, category);
throw error;
}
}) as T;
};
```
资料来源：[src/requestHandler.ts:1-50]()
### 资源暴露
日志系统通过 MCP 资源机制暴露以下信息：
| 资源 URI | 类型 | 内容 |
|----------|------|------|
| `console://logs` | text/plain | 浏览器控制台日志 |
| `screenshot://{name}` | image/png | 已存储的截图 |
```typescript
const resources = [
{
uri: "console://logs",
mimeType: "text/plain",
name: "Browser console logs",
},
...Array.from(getScreenshots().keys()).map(name => ({
uri: `screenshot://${name}`,
mimeType: "image/png",
name: `Screenshot: ${name}`,
})),
];
```
资料来源：[src/requestHandler.ts:60-80]()
## 配置参考
### 日志配置
```typescript
interface LoggerConfig {
level: 'debug' | 'info' | 'warn' | 'error'; // 日志级别
filePath: string; // 日志文件路径
maxFileSize: number; // 单文件最大大小（字节）
maxFiles: number; // 保留的最大文件数
console?: boolean; // 是否输出到控制台
}
```
### 监控配置
```typescript
interface MonitoringConfig {
enabled: boolean; // 是否启用监控
metricsInterval: number; // 指标收集间隔（毫秒）
healthCheckInterval: number; // 健康检查间隔（毫秒）
}
```
## 总结
mcp-playwright 的日志与监控系统提供了企业级的可观测性能力：
- **统一日志层**：通过 LoggingMiddleware 拦截所有请求，提供一致的日志格式和错误处理
- **智能错误分类**：自动识别错误类型并收集丰富的诊断上下文
- **敏感数据保护**：内置敏感字段脱敏，防止日志泄露
- **健康监测**：实时监控系统资源和错误率，及时发现服务异常
- **日志轮转**：自动管理日志文件，避免磁盘空间问题
这套系统确保了 MCP 服务器在生产环境中的可维护性和问题可追溯性。
---
## 故障排除指南
### 相关页面
相关主题：[Docker 容器化部署](#docker-deployment), [日志与监控](#logging-monitoring), [客户端配置指南](#client-configuration)
相关源码文件
以下源码文件用于生成本页说明：
- [DOCKER.md](https://github.com/executeautomation/mcp-playwright/blob/main/DOCKER.md)
- [README.md](https://github.com/executeautomation/mcp-playwright/blob/main/README.md)
- [src/logging/middleware.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/middleware.ts)
- [src/logging/logger.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/logger.ts)
- [src/http-server.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/http-server.ts)
- [src/tools/browser/screenshot.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/screenshot.ts)
- [package.json](https://github.com/executeautomation/mcp-playwright/blob/main/package.json)
# 故障排除指南
本文档提供 mcp-playwright 项目的完整故障排除指南，帮助开发者诊断和解决常见问题。
## 概述
mcp-playwright 是一个基于 Playwright 的 MCP（Model Context Protocol）服务器，为 AI 助手提供浏览器自动化能力。故障排除系统采用多层次错误分类机制，能够自动识别和归类不同类型的错误。 资料来源：[src/logging/middleware.ts:1-50]()
### 错误分类体系
系统支持以下错误类别分类：
| 错误类别 | 触发条件 | 处理建议 |
|---------|---------|---------|
| validation | 包含 invalid、validation、required、missing parameter | 检查参数格式和必填项 |
| resource | 浏览器关闭、连接断开、协议错误 | 重启浏览器会话 |
| system | 超时、元素未找到、导航失败 | 等待元素加载或重试操作 |
| authentication | 未经授权、权限拒绝 | 检查认证信息 |
| rate_limit | 请求过多、限流 | 降低请求频率 |
资料来源：[src/logging/middleware.ts:100-150]()
## 常见问题与解决方案
### 1. 服务器启动问题
#### 1.1 服务无法启动
**症状表现**：
- 终端无响应或报错退出
- 端口 8931 被占用
- 连接被拒绝
**诊断步骤**：
```bash
# 检查端口占用情况
netstat -an | grep 8931
# Windows
netstat -ano | findstr 8931
```
**解决方案**：
1. 确认端口 8931 未被其他进程占用
2. 使用 `--port` 参数指定其他端口
3. 检查配置文件中的 URL 配置是否正确
资料来源：[src/http-server.ts:1-30]()
#### 1.2 HTTP 模式安全限制
**重要说明**：HTTP 服务器默认绑定到 `127.0.0.1`（localhost）以确保安全，外部网络无法直接访问。
```typescript
// 安全绑定配置
const host = '127.0.0.1';
const httpServer = app.listen(port, host, () => {
// 服务器仅接受本地连接
});
```
**远程访问方案**：使用 SSH 隧道连接远程服务器
```bash
ssh -L 8931:localhost:8931 user@remote-server
```
资料来源：[src/http-server.ts:50-70]()
### 2. Docker 相关问题
#### 2.1 容器立即退出
**症状**：容器启动后立即退出
**原因**：MCP 服务器需要通过 stdin/stdout 进行通信，缺少必要的交互参数
**解决方案**：使用 `-i` 参数保持标准输入打开
```bash
docker run -i --rm mcp-playwright:latest
```
| 参数 | 作用 |
|-----|------|
| `-i` | 保持 STDIN 打开以支持交互通信 |
| `--rm` | 容器退出时自动删除 |
| `-v` | 挂载卷以持久化数据 |
资料来源：[DOCKER.md:1-50]()
#### 2.2 浏览器未找到
**症状**：`Browser not found` 或浏览器下载失败
**原因**：Docker 镜像默认跳过浏览器下载以减小体积
**解决方案**：创建自定义 Dockerfile 预安装浏览器
```dockerfile
FROM mcp-playwright:latest
# 安装 Playwright 浏览器
RUN npx playwright install chromium --with-deps
```
或者设置环境变量跳过浏览器下载检查：
```bash
docker run -i --rm \
-e PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 \
mcp-playwright:latest
```
资料来源：[DOCKER.md:60-80]()
#### 2.3 挂载卷权限问题
**症状**：容器内无法读写挂载的目录
**解决方案**：使用 `--user` 参数指定用户身份
```bash
docker run -i --rm \
-v $(pwd)/data:/app/data \
--user $(id -u):$(id -g) \
mcp-playwright:latest
```
资料来源：[DOCKER.md:85-95]()
### 3. 浏览器相关问题
#### 3.1 浏览器自动安装
系统支持浏览器自动安装，首次使用时自动检测并下载缺失的浏览器二进制文件：
```mermaid
graph TD
A[启动服务器] --> B{检测浏览器}
B -->|浏览器缺失| C[自动下载安装]
B -->|浏览器存在| D[继续执行]
C --> E[显示安装进度]
E --> D
```
**手动安装命令**：
```bash
# 安装所有浏览器
npx playwright install
# 安装特定浏览器
npx playwright install chromium
npx playwright install firefox
npx playwright install webkit
```
**浏览器存储位置**：
| 操作系统 | 存储路径 |
|---------|---------|
| Windows | `%USERPROFILE%\AppData\Local\ms-playwright` |
| macOS | `~/Library/Caches/ms-playwright` |
| Linux | `~/.cache/ms-playwright` |
资料来源：[README.md:100-130]()
#### 3.2 浏览器连接断开
**症状**：`Target page, context or browser has been closed`
**错误分类**：`resource` 类型错误
**解决方案**：
1. 检查浏览器实例是否正常启动
2. 避免在页面加载完成前执行操作
3. 使用适当的等待策略
```typescript
// 浏览器上下文捕获示例
private captureBrowserContext(error: Error): Record {
const context: Record = {};
const message = error.message.toLowerCase();
if (message.includes('closed') || message.includes('disconnected')) {
context.browserState = 'disconnected';
} else if (message.includes('timeout')) {
context.browserState = 'timeout';
} else if (message.includes('navigation')) {
context.browserState = 'navigation_error';
}
return context;
}
```
资料来源：[src/logging/middleware.ts:150-200]()
### 4. 工具执行问题
#### 4.1 日志输出配置
在 stdio 模式下，日志自动写入文件而非控制台，以保持 JSON-RPC 通信的清洁性。
**日志文件位置**：`~/playwright-mcp-server.log`
```mermaid
graph LR
A[stdio 模式] --> B[日志写入文件]
C[HTTP 模式] --> D[日志输出控制台]
B --> E[~/playwright-mcp-server.log]
```
资料来源：[README.md:50-60]()
#### 4.2 工具执行流程监控
系统提供完整的工具执行日志记录：
```mermaid
sequenceDiagram
participant C as 客户端
participant M as 日志中间件
participant H as 处理器
participant L as 日志记录器
C->>M: 工具调用请求
M->>L: 记录开始状态
M->>H: 执行处理器
H-->>M: 返回结果
M->>L: 记录完成状态
M-->>C: 返回响应
```
**请求日志上下文**：
```typescript
interface RequestLogContext {
method: 'TOOL_CALL' | 'HTTP_REQUEST';
url: string;
body?: any;
statusCode?: number;
duration?: number;
}
```
资料来源：[src/logging/middleware.ts:10-40]()
#### 4.3 工具名称长度限制
**重要提示**：部分客户端（如 Cursor）对工具名称有 60 字符限制。
服务器名称：`playwright-mcp`
确保工具名称足够简短，避免组合后超过限制。
资料来源：[README.md:140-150]()
### 5. 截图功能问题
#### 5.1 截图存储机制
截图工具支持内存存储和文件存储两种模式：
```mermaid
graph TD
A[截图请求] --> B{storeBase64 参数}
B -->|true| C[存入内存 Map]
B -->|false| D[仅保存文件]
C --> E[触发资源变更通知]
D --> F[返回文件路径]
E --> G[通知 MCP 客户端]
```
**存储配置**：
```typescript
// 截图参数配置
interface ScreenshotArgs {
name?: string; // 截图标识名称
downloadsDir?: string; // 下载目录路径
storeBase64?: boolean; // 是否存入内存，默认为 true
}
```
资料来源：[src/tools/browser/screenshot.ts:20-50]()
#### 5.2 获取已存储截图
```typescript
// 获取所有已存储的截图
getScreenshots(): Map {
return this.screenshots;
}
```
返回内存中所有 Base64 编码的截图数据。
资料来源：[src/tools/browser/screenshot.ts:80-90]()
### 6. 连接问题诊断
#### 6.1 连接问题排查清单
| 检查项 | 验证方法 | 解决方案 |
|-------|---------|---------|
| 端口可用性 | `netstat -an \| grep 8931` | 更换端口或终止占用进程 |
| 本地访问 | `curl http://localhost:8931/health` | 检查服务器状态 |
| 防火墙 | 检查入站规则 | 开放相应端口 |
| 外部访问 | 远程主机测试 | 使用 SSH 隧道 |
资料来源：[README.md:80-100]()
#### 6.2 健康检查端点
```bash
# HTTP 模式健康检查
curl http://localhost:8931/health
```
**响应示例**：
```json
{
"status": "ok",
"version": "1.x.x",
"activeSessions": 0
}
```
资料来源：[src/http-server.ts:30-45]()
### 7. 日志系统调试
#### 7.1 日志级别
```typescript
// 日志方法
info(message: string, context?: Record): void
warn(message: string, context?: Record): void
error(message: string, error?: Error, context?: Record): void
logRequest(message: string, requestContext: RequestLogContext): void
logError(message: string, error: Error, errorContext?: ErrorLogContext): void
```
#### 7.2 错误上下文捕获
系统自动捕获丰富的错误上下文信息：
```typescript
captureErrorContext(error: Error, toolName?: string, args?: any): Record {
return {
errorName: error.name,
errorMessage: error.message,
stack: error.stack,
timestamp: new Date().toISOString(),
nodeVersion: process.version,
platform: process.platform,
arch: process.arch,
memoryUsage: process.memoryUsage(),
uptime: process.uptime(),
toolName,
toolCategory: toolName?.split('_')[0]
};
}
```
资料来源：[src/logging/middleware.ts:180-220]()
### 8. 性能与资源限制
#### 8.1 Docker 资源限制
```yaml
services:
playwright-mcp:
deploy:
resources:
limits:
cpus: '2.0'
memory: 2G
```
#### 8.2 健康检查配置
```yaml
services:
playwright-mcp:
healthcheck:
test: ["CMD", "node", "-e", "process.exit(0)"]
interval: 30s
timeout: 10s
retries: 3
```
资料来源：[DOCKER.md:100-130]()
## 获取帮助
如果问题仍未解决：
1. 查看完整的 [README.md](README.md) 获取一般信息
2. 在 [GitHub Issues](https://github.com/executeautomation/mcp-playwright/issues) 报告问题
3. 为 Docker 相关问题添加 `docker` 标签
4. 使用 `docker scan` 检查镜像安全漏洞
## 依赖版本参考
| 依赖包 | 版本 | 用途 |
|-------|------|------|
| @modelcontextprotocol/sdk | 1.24.3 | MCP 协议实现 |
| playwright | 1.57.0 | 浏览器自动化核心 |
| @playwright/browser-chromium | 1.57.0 | Chromium 浏览器 |
| @playwright/browser-firefox | 1.57.0 | Firefox 浏览器 |
| @playwright/browser-webkit | 1.57.0 | WebKit 浏览器 |
资料来源：[package.json:1-30]()
---
---
## Doramagic 踩坑日志
项目：executeautomation/mcp-playwright
摘要：发现 16 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Playwright is asking for an specific browser version.。
## 1. 安装坑 · 来源证据：Playwright is asking for an specific browser version.
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Playwright is asking for an specific browser version.
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_38465ac94a9d4fb0bd352ba5209096ac | https://github.com/executeautomation/mcp-playwright/issues/117 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 2. 安全/权限坑 · 来源证据：How to configure proxy and storageState when launching browser in Playwright MCP?
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：How to configure proxy and storageState when launching browser in Playwright MCP?
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_a2f7e4a410994d4195a9af9f139e0caa | https://github.com/executeautomation/mcp-playwright/issues/203 | 来源类型 github_issue 暴露的待验证使用条件。
## 3. 配置坑 · 可能修改宿主 AI 配置
- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
- 证据：capability.host_targets | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | host_targets=mcp_host, claude, cursor
## 4. 配置坑 · 来源证据：Add Clarvia AEO score badge to README (AEO 32/100)
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Add Clarvia AEO score badge to README (AEO 32/100)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_74959d07d5f74165bcd9cae829d384ce | https://github.com/executeautomation/mcp-playwright/issues/212 | 来源类型 github_issue 暴露的待验证使用条件。
## 5. 配置坑 · 来源证据：Add policy enforcement for browser automation and HTTP request tools
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Add policy enforcement for browser automation and HTTP request tools
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_23a30d245f794b8db40c1d031b8be565 | https://github.com/executeautomation/mcp-playwright/issues/216 | 来源类型 github_issue 暴露的待验证使用条件。
## 6. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | README/documentation is current enough for a first validation pass.
## 7. 运行坑 · 来源证据：How to pass in the `--ignore-https-errors` parameter?
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：How to pass in the `--ignore-https-errors` parameter?
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_47d5e333819d49b4b8ce2abb9484b23d | https://github.com/executeautomation/mcp-playwright/issues/202 | 来源类型 github_issue 暴露的待验证使用条件。
## 8. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | last_activity_observed missing
## 9. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | no_demo; severity=medium
## 10. 安全/权限坑 · 存在安全注意事项
- 严重度：medium
- 证据强度：source_linked
- 发现：No sandbox install has been executed yet; downstream must verify before user use.
- 对用户的影响：用户安装前需要知道权限边界和敏感操作。
- 建议检查：转成明确权限清单和安全审查提示。
- 防护动作：安全注意事项必须面向用户前置展示。
- 证据：risks.safety_notes | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | No sandbox install has been executed yet; downstream must verify before user use.
## 11. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | no_demo; severity=medium
## 12. 安全/权限坑 · 来源证据：Feature Request: Add browser context persistence for login state (userDataDir/storageState)
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature Request: Add browser context persistence for login state (userDataDir/storageState)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_3632e6a11e044dda870b3267ccfa3040 | https://github.com/executeautomation/mcp-playwright/issues/201 | 来源类型 github_issue 暴露的待验证使用条件。
## 13. 安全/权限坑 · 来源证据：Free MCP security scan report for @executeautomation/playwright-mcp-server
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Free MCP security scan report for @executeautomation/playwright-mcp-server
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_9720dc9967444ed08710cdb0660a212a | https://github.com/executeautomation/mcp-playwright/issues/211 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 14. 安全/权限坑 · 来源证据：Security Advisory: SSRF, Prompt Injection, and Arbitrary JavaScript Execution via Browser Automation Tools
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security Advisory: SSRF, Prompt Injection, and Arbitrary JavaScript Execution via Browser Automation Tools
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_ced642164084421f84bbb63681653057 | https://github.com/executeautomation/mcp-playwright/issues/209 | 来源类型 github_issue 暴露的待验证使用条件。
## 15. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | issue_or_pr_quality=unknown
## 16. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | release_recency=unknown