项目概述

mcp-playwright 是一个开源的 MCP 服务器实现，它将 Playwright 浏览器自动化能力通过 MCP 协议暴露给 AI 助手和开发工具。该项目由 ExecuteAutomation 维护，支持多浏览器引擎（Chromium、Firefox、WebKit），并提供 stdio 和 HTTP 两种通信模式。

核心特性：

环境要求

在开始之前，请确保您的系统满足以下要求：

• Node.js: 20.x 或更高版本
• 操作系统: Windows、macOS、Linux
• 网络: 能够访问 npm registry 下载依赖包

您可以通过以下命令检查 Node.js 版本：

node --version

安装方式

mcp-playwright 提供多种安装方式，您可以根据使用场景选择最合适的一种。

方式一：使用 npm 全局安装

这是最直接的安装方式：

npm install -g @executeautomation/playwright-mcp-server

安装完成后，可执行文件 playwright-mcp-server 将全局可用。资料来源：README.md:54

方式二：使用 npx 免安装运行

如果您不想全局安装，可以使用 npx 直接运行：

npx -y @executeautomation/playwright-mcp-server

这种方式每次都会下载最新版本，适合临时使用或测试场景。资料来源：README.md:42

方式三：使用 mcp-get 安装

mcp-get 是专门为 MCP 服务器设计的包管理工具：

npx @michaellatman/mcp-get@latest install @executeautomation/playwright-mcp-server

方式四：使用 Smithery 自动安装

Smithery 提供了针对 Claude Desktop 的自动化安装：

npx @smithery/cli install @executeautomation/playwright-mcp-server --client claude

方式五：Docker 部署

对于容器化环境，可以使用 Docker 运行：

docker run -i --rm mcp-playwright:latest

Docker 部署的详细配置请参考 DOCKER.md。资料来源：DOCKER.md:1

配置 AI 客户端

安装完成后，您需要在 AI 客户端中配置 MCP 服务器连接。以下是常见客户端的配置方法。

Claude Desktop 配置

配置文件位置：

stdio 模式配置（推荐）：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@executeautomation/playwright-mcp-server"]
    }
  }
}

HTTP 模式配置：

如果您使用 HTTP 模式运行服务器，可以配置如下：

{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp"
    }
  }
}

注意：Claude Desktop 目前需要 stdio 模式。如果您需要 HTTP 模式，建议使用 VS Code 或其他自定义客户端。资料来源：README.md:25-35

Claude Code 配置

使用 Claude Code 时，可以通过命令行添加 MCP 服务器：

claude mcp add --transport stdio playwright npx @executeautomation/playwright-mcp-server

VS Code MCP 扩展配置

对于 VS Code 用户，可以使用以下配置：

{
  "name": "playwright",
  "command": "npx",
  "args": ["-y", "@executeautomation/playwright-mcp-server"]
}

运行模式

mcp-playwright 支持两种运行模式，您可以根据需求选择。

stdio 模式（标准输入输出）

stdio 模式是 Claude Desktop 的推荐模式。在此模式下，MCP 服务器通过标准输入和标准输出与客户端通信。

启动方式：

npx -y @executeautomation/playwright-mcp-server

配置说明：

在 stdio 模式下，日志会自动写入文件而非控制台，以确保 JSON-RPC 通信的清洁性。日志文件位置为 ~/playwright-mcp-server.log。资料来源：README.md:30

HTTP 模式（独立服务器）

HTTP 模式适合以下场景：

• 在无显示环境的系统中运行有头浏览器
• 从 IDE 工作进程调用
• 需要远程部署
• VS Code 用户

启动 HTTP 服务器：

# 使用 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=<id>
- MCP (unified):  GET  http://localhost:8931/mcp
- MCP (unified):  POST http://localhost:8931/mcp?sessionId=<id>
- Health Check:   GET  http://localhost:8931/health

资料来源：README.md:38-52

健康检查：

curl http://localhost:8931/health

浏览器安装

自动安装（推荐）

mcp-playwright 会在首次使用时自动安装浏览器。当服务器检测到缺少浏览器时，会自动：

1. 下载并安装所需浏览器（Chromium、Firefox 或 WebKit）
2. 在控制台显示安装进度
3. 安装完成后自动重试您的请求

无需手动操作！

手动安装

如果您偏好手动安装或遇到自动安装问题：

# 安装所有浏览器
npx playwright install

# 或安装特定浏览器
npx playwright install chromium
npx playwright install firefox
npx playwright install webkit

浏览器存储位置：

资料来源：README.md:57-72

项目架构

下面通过 Mermaid 图展示 mcp-playwright 的整体架构：

graph TD
    A[AI 客户端<br/>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

组件说明

常用工作流程

基本导航流程

graph LR
    A[启动服务器] --> B[配置客户端]
    B --> C[打开浏览器]
    C --> D[导航到 URL]
    D --> E[执行交互]
    E --> F[获取结果]

Docker 部署流程

如果您选择 Docker 部署，典型的工作流程如下：

graph TD
    A[编写 docker-compose.yml] --> B[配置环境变量]
    B --> C[配置卷挂载]
    C --> D[启动容器]
    D --> E[配置 AI 客户端连接]
    E --> F[开始使用]

示例 docker-compose.yml：

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

环境变量

您可以通过环境变量配置服务器行为：

Docker 中设置环境变量：

docker run -i --rm \
  -e PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 \
  mcp-playwright:latest

资料来源：DOCKER.md:26-31

故障排除

容器立即退出

MCP 服务器需要通过 stdin 接收输入，确保使用 -i 标志：

docker run -i --rm mcp-playwright:latest

浏览器未找到

Docker 镜像默认跳过浏览器下载以减小体积。如需预安装浏览器，创建自定义 Dockerfile：

FROM mcp-playwright:latest
RUN npx playwright install chromium --with-deps

权限问题

如果遇到挂载卷权限问题：

docker run -i --rm \
  -v $(pwd)/data:/app/data \
  --user $(id -u):$(id -g) \
  mcp-playwright:latest

日志位置

stdio 模式下，日志文件位置为：~/playwright-mcp-server.log

下一步

完成快速入门后，您可以：

• 阅读完整的 API 文档
• 了解支持的 设备配置
• 参考 调整提示指南
• 查看 GitHub Issues 获取帮助

资源链接

概述

mcp-playwright 是一个基于 Model Context Protocol (MCP) 的 Playwright 自动化服务器，为 AI 助手提供浏览器自动化能力。该项目采用模块化架构设计，支持两种运行模式：stdio（标准输入输出）和 HTTP 模式。 资料来源：package.json

核心架构组件

组件架构图

graph TB
    subgraph "传输层"
        STDIO[STDIO 传输]
        HTTP[HTTP 服务器]
        SSE[SSE 流]
    end
    
    subgraph "核心层"
        MCP_SDK[MCP SDK<br/>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

graph LR
    Client[Claude Desktop<br/>或其他 MCP 客户端] <--> STDIO
    STDIO --> Server[主服务器进程]
    Server --> Logger[文件日志<br/>playwright-mcp-server.log]

HTTP 模式

HTTP 模式提供独立的 HTTP 服务器，支持远程访问和 VS Code 等 IDE 集成。服务器绑定到 127.0.0.1（仅本地），提供 SSE 流式传输和消息接口。 资料来源：src/http-server.ts:1-50

graph LR
    subgraph "HTTP 端点"
        SSE[SSE Stream<br/>GET /sse]
        Messages[Messages<br/>POST /messages]
        MCP[MCP 统一接口<br/>GET/POST /mcp]
        Health[Health Check<br/>GET /health]
    end
    
    Client[外部客户端] --> HTTP_Server[HTTP 服务器<br/>127.0.0.1:8931]
    HTTP_Server --> SSE
    HTTP_Server --> Messages
    HTTP_Server --> MCP
    HTTP_Server --> Health

HTTP 端点配置

请求处理流程

请求生命周期

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

核心职责包括：

• 解析 MCP 协议消息格式
• 验证请求参数
• 路由工具调用到对应的处理器
• 处理错误和异常情况

工具系统架构

工具分类

所有工具定义统一在 src/tools.ts 中声明，分为以下几类： 资料来源：src/tools.ts

浏览器启动条件

工具系统使用条件启动机制，仅在需要时启动浏览器： 资料来源：src/tools.ts

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

graph TB
    subgraph "ToolHandler"
        BrowserManager[浏览器管理器]
        ToolRegistry[工具注册表]
        SessionManager[会话管理器]
    end
    
    ToolRegistry -->|执行| BrowserManager
    SessionManager -->|状态| BrowserManager

日志系统架构

日志中间件

日志中间件（LoggingMiddleware）拦截所有工具调用请求，记录详细的执行上下文和错误信息。 资料来源：src/logging/middleware.ts

graph LR
    Request[请求] --> Middleware[日志中间件]
    Middleware --> Sanitize[参数脱敏]
    Middleware --> LogStart[记录开始]
    Request -->|执行| Handler[工具处理器]
    Handler -->|结果| Middleware
    Middleware --> LogComplete[记录完成]
    Middleware --> LogError[记录错误]
    Middleware --> Response[响应]

日志级别和上下文

日志上下文包含丰富的系统信息： 资料来源：src/logging/logger.ts

• 错误名称和消息
• 堆栈跟踪
• 时间戳
• Node.js 版本
• 平台和架构信息
• 内存使用情况
• 运行时间

错误分类

日志中间件实现了智能错误分类功能： 资料来源：src/logging/middleware.ts

多浏览器支持

浏览器类型

项目支持三种浏览器引擎，通过 browserType 参数指定： 资料来源：CHANGELOG.md

浏览器依赖版本

所有浏览器包版本统一为 1.57.0，核心 Playwright 版本也保持一致。 资料来源：package.json

{
  "@playwright/browser-chromium": "1.57.0",
  "@playwright/browser-firefox": "1.57.0",
  "@playwright/browser-webkit": "1.57.0",
  "playwright": "1.57.0"
}

服务器启动流程

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

graph LR
    Node[Node.js] --> Index[index.ts]
    Index --> ParseArgs[解析 --port 参数]
    ParseArgs -->|有端口参数| HTTP[HTTP 模式]
    ParseArgs -->|无端口参数| STDIO[STDIO 模式]

HTTP 服务器初始化

HTTP 服务器使用 Express 框架，绑定到本地主机（安全考虑）： 资料来源：src/http-server.ts

// 安全配置：仅绑定本地主机
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

graph LR
    Client[客户端] -->|建立连接| SSE[SSE 服务器]
    SSE -->|事件流| Client
    HTTP_Server[HTTP 服务器] -->|管理| SSE

会话管理

SSE 服务器支持多会话管理，每个会话通过 sessionId 标识：

• /sse - 建立 SSE 连接
• /messages?sessionId=<id> - 发送消息到指定会话
• /mcp - MCP 统一接口（支持 sessionId 参数）

安全特性

安全设计原则

参数脱敏规则

日志中间件自动识别并脱敏以下敏感字段： 资料来源：src/logging/middleware.ts

const sensitiveFields = ['password', 'token', 'secret', 'key', 'auth'];

依赖关系图

核心依赖

测试架构

测试框架

项目使用 Jest 作为测试框架，测试文件位于 src/__tests__ 目录： 资料来源：README.md

# 运行测试
npm test

# 带覆盖率
npm run test:coverage

# 自定义测试脚本
node run-tests.cjs

评估测试

使用 mcp-eval 包进行 AI 能力评估：

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. 日志层：完善的日志记录和错误追踪机制

该架构确保了系统的可扩展性、可维护性和安全性，同时提供了灵活的部署选项。

1. 工具系统概述

1.1 架构设计

MCP Playwright 的工具系统采用模块化分层架构，将不同类型的工具按功能域划分为独立的模块。

graph TD
    A[MCP Client<br/>Claude/Copilot] --> B[Tool Handler<br/>handleToolCall]
    B --> C[Browser Tools<br/>浏览器操作]
    B --> D[API Tools<br/>API 测试]
    B --> E[Codegen Tools<br/>代码生成]
    
    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

1.2 工具分类

1.3 工具依赖关系

浏览器操作类工具需要启动浏览器实例，系统通过 BROWSER_TOOLS 数组标识这些工具：

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

概述

设备模拟功能是 MCP Playwright 服务器的核心特性之一，允许 AI 助手和自动化测试工具在真实的设备配置下测试 Web 应用程序。该功能通过 playwright_resize 工具实现，支持 143 种真实设备预设，涵盖 iPhone、iPad、Pixel、Galaxy 以及主流桌面浏览器。

设备模拟功能的核心价值在于：

• 无需物理设备即可在真实设备配置下进行测试
• 自动模拟设备的视口尺寸、用户代理字符串、触摸事件和设备像素比
• 支持横竖屏切换
• 与 AI 助手自然语言交互

资料来源：README.md

架构设计

组件关系

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 触摸支持]

执行流程

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

export class ResizeTool extends BrowserToolBase {
  async execute(args: any, context: ToolContext): Promise<ToolResponse> {
    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;
      
      // 设备预设解析逻辑
      // ...
    });
  }
}

设备预设处理逻辑

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

API 参考

工具名称

playwright_resize

输入参数

参数优先级

1. 若指定 device，优先使用设备预设配置
2. 若未指定 device，使用自定义 width 和 height
3. orientation 参数仅在 device 模式下生效，用于切换横竖屏

设备预设 vs 自定义尺寸

使用示例

基础设备模拟

// 测试 iPhone 13
await playwright_resize({ device: "iPhone 13" });

横竖屏切换

// iPad Pro 横屏模式
await playwright_resize({ device: "iPad Pro 11", orientation: "landscape" });

// iPhone 14 竖屏模式（默认）
await playwright_resize({ device: "iPhone 14", orientation: "portrait" });

桌面浏览器

// Chrome 桌面视图
await playwright_resize({ device: "Desktop Chrome" });

// Firefox 桌面视图
await playwright_resize({ device: "Desktop Firefox" });

自定义视口尺寸

// 自定义 1920x1080 分辨率
await playwright_resize({ width: 1920, height: 1080 });

支持的设备列表

设备模拟功能支持 Playwright 内置的完整设备库，包含 143 种设备预设。

设备分类

热门设备建议

当用户输入不存在的设备名时，系统会返回热门设备建议列表：

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

设备配置属性

每个设备预设包含以下属性：

示例：iPhone 13 配置

{
  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

自定义尺寸模式

资料来源：src/tools/browser/resize.ts:103-112

AI 助手自然语言集成

设备模拟功能设计为与 AI 助手无缝集成，支持自然语言命令：

支持的命令模式

资料来源：README.md

错误处理

常见错误及解决方案

错误响应格式

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Device \"iPhone 99\" not found. Popular devices: iPhone 13, iPhone 13 Pro..."
    }
  ]
}

与其他工具的配合

推荐的工具调用顺序

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 - 执行测试操作

性能注意事项

相关工具

资料来源：src/tools.ts

概述

测试代码生成（Code Generation）是 MCP Playwright 提供的一项高级功能，允许开发者通过 MCP 工具执行自动化操作，并自动记录这些操作，最终生成可重用的 Playwright 测试脚本。

该功能的核心价值在于：

• 将手动录制的用户操作自动转化为可执行的测试代码
• 支持从记录的会话中生成结构化的 Playwright 测试用例
• 提供灵活的配置选项以满足不同项目的测试需求

资料来源：src/tools/codegen/index.ts:1-20

架构设计

核心组件

测试代码生成模块由三个主要组件构成：

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 文件定义了核心数据结构：

资料来源：src/tools/codegen/types.ts

工作流程

整体流程

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 接口提供以下可配置项：

const DEFAULT_OPTIONS: Required<CodegenOptions> = {
  outputPath: 'tests',
  testNamePrefix: 'MCP',
  includeComments: true,
};

资料来源：src/tools/codegen/generator.ts:10-15

自定义配置示例

{
  "options": {
    "outputPath": "/path/to/e2e",
    "testNamePrefix": "E2E",
    "includeComments": true
  }
}

MCP 工具接口

start_codegen_session

启动一个新的代码生成会话。

参数：

返回值：包含会话 ID 和状态的对象

资料来源：src/tools/codegen/index.ts:35-50

record_action

记录单个工具调用操作到当前会话。

参数：

generate_playwright_test

根据记录的会话生成 Playwright 测试代码。

参数：

返回值：CodegenResult，包含生成的代码和文件路径

资料来源：src/tools/codegen/generator.ts:30-45

get_codegen_session

获取指定会话的信息和已记录的操作。

参数：

cleanup_codegen_session

清理指定会话，释放相关资源。

参数：

PlaywrightGenerator 类

PlaywrightGenerator 是核心的测试代码生成器类，负责将操作记录转化为 Playwright 测试代码。

export class PlaywrightGenerator {
  private static readonly DEFAULT_OPTIONS: Required<CodegenOptions> = {
    outputPath: 'tests',
    testNamePrefix: 'MCP',
    includeComments: true,
  };

  private options: Required<CodegenOptions>;
}

公共方法

生成流程

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 方法确保配置选项的类型正确：

如果选项类型不匹配，将抛出相应的验证错误。

资料来源：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

常见错误场景

资料来源：src/tools/codegen/generator.ts:25-40

使用示例

基本使用流程

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: 返回测试代码

完整配置示例

{
  "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

全局状态管理

代码生成模块使用全局变量存储浏览器和页面实例：

declare global {
  var browser: Browser | undefined;
  var page: Page | undefined;
}

这允许在工具调用之间共享 Playwright 浏览器和页面上下文。

资料来源：src/tools/codegen/index.ts:14-20

与其他模块的关系

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 模式示例
• Docker 部署指南
• 主要工具文档

概述

HTTP/SSE 传输模式是 Playwright MCP Server 在 1.0.7 版本中引入的一种独立 HTTP 服务器部署方式。该模式允许将传统的 stdio 通信方式替换为基于 HTTP 和 Server-Sent Events (SSE) 的网络传输架构，适用于在无显示环境的系统中运行有头浏览器、从 IDE 工作进程发起连接，或需要支持多个并发客户端的场景。

此传输模式的核心价值在于将 MCP 协议适配到标准的 HTTP 协议栈上，使得客户端可以通过 RESTful API 与 MCP 服务器进行交互，同时利用 SSE 机制实现服务端向客户端的实时事件推送。

系统架构

整体架构图

graph TB
    subgraph "MCP 客户端"
        A[Claude Desktop / VS Code]
        B[自定义 HTTP 客户端]
        C[curl / Postman]
    end
    
    subgraph "HTTP/SSE 服务器"
        D[Express Server<br/>端口: 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

核心组件

启动服务器

基本启动命令

# 使用 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=<id>
- MCP (unified):  GET  http://localhost:8931/mcp
- MCP (unified):  POST http://localhost:8931/mcp?sessionId=<id>
- Health Check:   GET  http://localhost:8931/health

资料来源：examples/http-mode-example.md:1-20

环境变量配置

API 端点详解

健康检查端点

GET http://localhost:8931/health

用于验证服务器运行状态，返回服务器健康状态信息。

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=<id>
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=<id>  # 指定会话的 MCP 请求

统一端点将 SSE 流和消息发送合并为一个简洁的接口，是推荐使用的端点。

客户端配置

Claude Desktop 配置

Claude Desktop 目前需要使用 stdio 模式，不支持 HTTP 模式。如需远程访问，推荐通过 SSH 隧道方式连接。

自定义客户端配置

{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp"
    }
  }
}

资料来源：examples/http-mode-example.md:18-24

会话管理

会话生命周期

stateDiagram-v2
    [*] --> 创建会话: 首次连接
    创建会话 --> 活跃: 开始通信
    活跃 --> 活跃: 发送请求
    活跃 --> 心跳: 空闲超时
    心跳 --> 活跃: 收到消息
    心跳 --> 关闭: 超时
    活跃 --> 关闭: 客户端断开
    关闭 --> [*]: 清理资源

会话标识

每个客户端连接通过 sessionId 参数进行标识，支持多个客户端并发连接。服务器自动管理会话的创建、维护和销毁。

安全特性

本地绑定

服务器默认绑定到 127.0.0.1（localhost），防止外部网络访问：

安全说明：服务器默认仅监听本地回环地址，这可以防止意外的网络暴露和未授权访问。

资料来源：README.md:40-45

SSH 隧道远程访问

如需从远程机器访问，建议使用 SSH 隧道：

ssh -L 8931:localhost:8931 user@server-host

这种方式可以在保持服务器本地绑定的同时，实现安全的远程访问。

日志与监控

请求日志中间件

src/logging/middleware.ts 实现了完整的请求日志系统：

日志级别

系统支持以下日志级别，按优先级从低到高：

1. debug - 调试信息
2. info - 一般信息
3. warn - 警告信息
4. error - 错误信息

文件日志

日志默认写入文件而非控制台，以保证 stdio 模式下的 JSON-RPC 通信不被干扰。日志文件位置：~/playwright-mcp-server.log

错误处理

错误分类系统

错误上下文捕获

错误对象包含丰富的上下文信息：

{
  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 模式特别有用：

docker run -i --rm \
  -p 8931:8931 \
  mcp-playwright:latest

容器内运行需要使用 -i 标志保持 STDIN 开放，以便 MCP 服务器正常工作。

Docker Compose 配置

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

资源限制

docker run -i --rm \
  --cpus="2.0" \
  --memory="2g" \
  -p 8931:8931 \
  mcp-playwright:latest

与 Stdio 模式对比

故障排除

容器立即退出

MCP 服务器需要通过 STDIN 接收输入。确保使用 -i 标志：

docker run -i --rm mcp-playwright:latest

浏览器未找到

Docker 镜像默认跳过浏览器下载以减小体积。如需预装浏览器，创建自定义 Dockerfile：

FROM mcp-playwright:latest
RUN npx playwright install chromium --with-deps

端口占用

如果 8931 端口被占用，使用其他端口：

npx @executeautomation/playwright-mcp-server --port 8932

版本历史

资料来源：CHANGELOG.md:1-25

概述

MCP Playwright 项目提供了完整的 Docker 容器化解决方案，使 Playwright MCP 服务器能够在隔离的容器环境中运行。该部署方案具有以下核心特性：

• 隔离执行环境：通过 Docker 容器提供一致的运行时环境
• 简化依赖管理：所有依赖在镜像构建时预装
• 易于部署分发：支持 Docker Compose 一键启动
• MCP 协议支持：通过 stdio 或 HTTP 模式与 MCP 客户端通信

资料来源：DOCKER.md

架构概览

graph TD
    subgraph "宿主机 (Host)"
        A[MCP 客户端<br/>Claude Desktop / VS Code]
        B[Docker 守护进程]
    end
    
    subgraph "Docker 容器"
        C[Node.js 运行环境]
        D[Playwright MCP Server<br/>dist/index.js]
        E[Playwright 浏览器<br/>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)
2. 项目已通过 TypeScript 编译
3. 已安装生产环境依赖

构建流程

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：

chmod +x docker-build.sh
./docker-build.sh

该脚本会自动执行以下操作：

1. 安装生产依赖 (npm install --omit=dev)
2. 编译 TypeScript 代码 (npm run build)
3. 构建 Docker 镜像

手动构建

手动构建需要分步执行：

# 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 服务器通过标准输入输出与客户端通信：

docker run -i --rm mcp-playwright:latest

Docker Compose 模式

项目提供了 docker-compose.yml 配置文件：

# 启动服务
docker compose run --rm playwright-mcp

# 或先构建后运行
docker compose build
docker compose run --rm playwright-mcp

docker-compose.yml 核心配置：

资料来源：docker-compose.yml

MCP 客户端集成

Claude Desktop 配置

对于 Claude Desktop 用户，需要修改配置文件：

配置文件位置：

配置示例：

{
  "mcpServers": {
    "playwright-docker": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "mcp-playwright:latest"]
    }
  }
}

VS Code MCP 扩展配置

对于 VS Code MCP 扩展：

{
  "name": "playwright-docker",
  "command": "docker",
  "args": ["run", "-i", "--rm", "mcp-playwright:latest"]
}

环境变量配置

命令行设置环境变量

docker run -i --rm \
  -e PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 \
  -e NODE_ENV=production \
  mcp-playwright:latest

docker-compose.yml 设置环境变量

services:
  playwright-mcp:
    environment:
      - PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
      - NODE_ENV=production

资料来源：DOCKER.md:50-80

数据持久化

卷挂载配置

如需与容器共享文件或持久化数据，可使用 volume 挂载：

docker run -i --rm \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/screenshots:/app/screenshots \
  mcp-playwright:latest

docker-compose.yml 卷配置

services:
  playwright-mcp:
    volumes:
      - ./data:/app/data
      - ./screenshots:/app/screenshots

注意：挂载的目录路径必须是绝对路径或使用 $(pwd) 获取当前目录。

故障排除

容器立即退出

问题：容器启动后立即退出

原因：MCP 服务器需要通过 stdin 接收输入，未使用 -i 标志

解决方案：

# 错误
docker run --rm mcp-playwright:latest

# 正确
docker run -i --rm mcp-playwright:latest

浏览器未找到

问题：运行时报错找不到浏览器

原因：Docker 镜像默认跳过浏览器下载以减小体积

解决方案：创建自定义 Dockerfile 预装浏览器

FROM mcp-playwright:latest

# 安装 Playwright 浏览器
RUN npx playwright install chromium --with-deps

权限问题

问题：挂载卷出现权限拒绝

解决方案：以指定用户身份运行

docker run -i --rm \
  -v $(pwd)/data:/app/data \
  --user $(id -u):$(id -g) \
  mcp-playwright:latest

资料来源：DOCKER.md:100-130

高级配置

资源限制

docker run -i --rm \
  --cpus="2.0" \
  --memory="2g" \
  mcp-playwright:latest

docker-compose.yml 资源限制配置

services:
  playwright-mcp:
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 2G

健康检查配置

services:
  playwright-mcp:
    healthcheck:
      test: ["CMD", "node", "-e", "process.exit(0)"]
      interval: 30s
      timeout: 10s
      retries: 3

自定义网络配置

# 创建网络
docker network create mcp-network

# 在指定网络中运行
docker run -i --rm --network mcp-network mcp-playwright:latest

从源码构建 Docker 镜像

如果希望完全在 Docker 内构建（不使用本地预编译的 dist）：

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 用户运行

FROM mcp-playwright:latest
USER node

只读根文件系统

docker run -i --rm --read-only mcp-playwright:latest

安全扫描

docker scan mcp-playwright:latest

镜像优化

当前 Dockerfile 优化策略：

当前镜像大小：约 200MB（不含浏览器）

资料来源：DOCKER.md:180-200

快速入门命令汇总

# 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
• 问题反馈：GitHub Issues（请添加 docker 标签）
• 标准模式部署：请参阅 README.md 了解 stdio 模式配置
• HTTP 模式部署：请参阅 examples/http-mode-example.md 了解独立服务器部署

概述

Playwright MCP Server 支持多种客户端配置方式，以满足不同开发环境和部署场景的需求。本指南涵盖 stdio 模式（Claude Desktop 等）、HTTP 模式（VS Code、自定义客户端等）以及 Docker 部署的完整配置说明。

架构概览

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 配置

配置文件位置：

配置示例：

{
  "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 工作进程中的有头浏览器运行场景。

服务器启动

# 使用 npx 启动
npx @executeautomation/playwright-mcp-server --port 8931

# 全局安装后启动
npm install -g @executeautomation/playwright-mcp-server
playwright-mcp-server --port 8931

资料来源：README.md:22-27

端点说明

资料来源：src/http-server.ts:1-50

HTTP 服务器安全配置

服务器默认绑定到 127.0.0.1（localhost），防止外部网络访问：

graph LR
    A[客户端] -->|localhost| B[127.0.0.1:8931]
    C[外部请求] -.->|✗ 已阻止| B

资料来源：src/http-server.ts:35-36

Claude Desktop HTTP 配置

{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp"
    }
  }
}

资料来源：examples/http-mode-example.md:1-15

健康检查

curl http://localhost:8931/health

响应示例：

{
  "status": "ok",
  "version": "1.x.x",
  "activeSessions": 0
}

Docker 部署配置

Docker 运行

基本命令：

docker run -i --rm mcp-playwright:latest

参数说明：

资料来源：DOCKER.md:40-50

Docker Compose 配置：

services:
  playwright-mcp:
    image: mcp-playwright:latest

启动命令：

# 启动服务
docker compose run --rm playwright-mcp

# 构建并运行
docker compose build
docker compose run --rm playwright-mcp

Docker 客户端配置

Claude Desktop Docker 配置：

{
  "mcpServers": {
    "playwright-docker": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "mcp-playwright:latest"]
    }
  }
}

资料来源：DOCKER.md:10-20

VS Code MCP Extension 配置：

{
  "name": "playwright-docker",
  "command": "docker",
  "args": ["run", "-i", "--rm", "mcp-playwright:latest"]
}

资料来源：DOCKER.md:22-28

环境变量配置

Docker 环境变量

通过 -e 参数传递环境变量：

docker run -i --rm \
  -e PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 \
  -e NODE_ENV=production \
  mcp-playwright:latest

常用环境变量：

资料来源：DOCKER.md:30-45

Docker Compose 环境变量

services:
  playwright-mcp:
    environment:
      - PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
      - NODE_ENV=production

存储卷挂载

数据持久化

docker run -i --rm \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/screenshots:/app/screenshots \
  mcp-playwright:latest

Docker Compose 卷配置

services:
  playwright-mcp:
    volumes:
      - ./data:/app/data
      - ./screenshots:/app/screenshots

资料来源：DOCKER.md:48-55

高级配置

资源限制

docker run -i --rm \
  --cpus="2.0" \
  --memory="2g" \
  mcp-playwright:latest

Docker Compose 配置：

services:
  playwright-mcp:
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 2G

资料来源：DOCKER.md:130-140

自定义网络

docker network create mcp-network
docker run -i --rm --network mcp-network mcp-playwright:latest

用户权限配置

解决挂载卷权限问题：

docker run -i --rm \
  -v $(pwd)/data:/app/data \
  --user $(id -u):$(id -g) \
  mcp-playwright:latest

健康检查配置

services:
  playwright-mcp:
    healthcheck:
      test: ["CMD", "node", "-e", "process.exit(0)"]
      interval: 30s
      timeout: 10s
      retries: 3

故障排查

容器立即退出

问题原因： MCP 服务器需要通过 stdin 接收输入。

解决方案： 确保使用 -i 参数：

docker run -i --rm mcp-playwright:latest

资料来源：DOCKER.md:60-65

浏览器未找到

Docker 镜像默认跳过浏览器下载以减小体积。首次使用时 Playwright 会自动下载浏览器。

预安装浏览器（自定义 Dockerfile）：

FROM mcp-playwright:latest

# 安装 Playwright 浏览器
RUN npx playwright install chromium --with-deps

资料来源：DOCKER.md:70-75

完整配置示例

最小化配置（Stdio 模式）

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@executeautomation/playwright-mcp-server"]
    }
  }
}

生产环境配置（HTTP 模式）

{
  "mcpServers": {
    "playwright": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--cpus=2.0",
        "--memory=2g",
        "-e", "NODE_ENV=production",
        "mcp-playwright:latest"
      ]
    }
  }
}

Docker Compose 完整配置

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：

依赖版本：

资料来源：package.json:1-30

概述

mcp-playwright 的日志与监控系统为 MCP 服务器提供了一套完整的请求追踪、错误分类和系统健康监测能力。该系统通过统一的日志记录层捕获所有工具调用请求、响应状态和错误信息，同时结合健康检查机制确保服务稳定运行。

核心功能包括：

• 请求日志记录：追踪所有工具调用的生命周期
• 错误分类与增强上下文：自动识别错误类型并收集诊断信息
• 敏感数据脱敏：防止日志中泄露密码、Token 等敏感信息
• 系统健康监控：实时监测 CPU、内存、错误率等关键指标
• 日志轮转：自动管理日志文件大小和数量

架构设计

系统组件关系

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]

日志层级

日志级别通过配置控制，低于配置级别的日志不会输出。 资料来源：src/logging/logger.ts:156-162

日志系统

Logger 核心功能

Logger 是日志系统的核心组件，支持以下功能：

资料来源：src/logging/logger.ts:1-60

日志格式化

每条日志条目包含以下结构化数据：

interface LogEntry {
  timestamp: string;      // ISO 8601 格式时间戳
  level: 'debug' | 'info' | 'warn' | 'error';
  message: string;       // 日志消息
  requestId?: string;     // 请求唯一标识
  context?: Record<string, any>; // 附加上下文
}

请求日志上下文

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 请求，提供统一的日志记录和错误处理能力：

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: 返回响应

错误分类

中间件能够自动识别并分类错误类型：

资料来源：src/logging/middleware.ts:80-110

错误上下文捕获

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

敏感数据保护

脱敏策略

日志中间件包含智能数据脱敏功能，防止敏感信息泄露：

资料来源：src/logging/middleware.ts:160-180

工具参数过滤

private sanitizeToolArgs(toolName: string, args: any): any {
  // 检测包含敏感关键词的参数
  const sensitiveFields = ['password', 'token', 'secret', 'key', 'auth'];
  // 将敏感字段值替换为 [REDACTED]
}

监控系统

HealthStatus 系统状态

系统健康状态包含多个检查项：

资料来源：src/monitoring/system.ts:80-120

健康状态响应格式

interface HealthStatus {
  status: 'healthy' | 'degraded' | 'unhealthy';
  checks: {
    [key: string]: {
      status: 'pass' | 'warn' | 'fail';
      description: string;
      data: Record<string, any>;
    };
  };
  timestamp: number;
  version: string;
}

指标收集

监控系统持续收集以下指标：

• 请求计数：总请求数、成功/失败数
• 响应时长：平均、最小、最大响应时间
• 错误分类统计：按错误类型分类的错误计数
• 系统资源：CPU、内存使用率
• 分类指标：按工具分类的请求统计

资料来源：src/monitoring/system.ts:1-50

HTTP 健康检查服务器

监控系统可启动独立的 HTTP 服务器提供健康检查端点：

async startMetricsCollection(port: number = 3001): Promise<void> {
  // 启动 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 数量的最旧文件被删除

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 包装器集成到请求处理流程中：

const wrapWithMonitoring = <T extends Function>(
  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 资源机制暴露以下信息：

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

配置参考

日志配置

interface LoggerConfig {
  level: 'debug' | 'info' | 'warn' | 'error';  // 日志级别
  filePath: string;                            // 日志文件路径
  maxFileSize: number;                         // 单文件最大大小（字节）
  maxFiles: number;                            // 保留的最大文件数
  console?: boolean;                           // 是否输出到控制台
}

监控配置

interface MonitoringConfig {
  enabled: boolean;            // 是否启用监控
  metricsInterval: number;     // 指标收集间隔（毫秒）
  healthCheckInterval: number; // 健康检查间隔（毫秒）
}

总结

mcp-playwright 的日志与监控系统提供了企业级的可观测性能力：

• 统一日志层：通过 LoggingMiddleware 拦截所有请求，提供一致的日志格式和错误处理
• 智能错误分类：自动识别错误类型并收集丰富的诊断上下文
• 敏感数据保护：内置敏感字段脱敏，防止日志泄露
• 健康监测：实时监控系统资源和错误率，及时发现服务异常
• 日志轮转：自动管理日志文件，避免磁盘空间问题

这套系统确保了 MCP 服务器在生产环境中的可维护性和问题可追溯性。

概述

mcp-playwright 是一个基于 Playwright 的 MCP（Model Context Protocol）服务器，为 AI 助手提供浏览器自动化能力。故障排除系统采用多层次错误分类机制，能够自动识别和归类不同类型的错误。 资料来源：src/logging/middleware.ts:1-50

错误分类体系

系统支持以下错误类别分类：

资料来源：src/logging/middleware.ts:100-150

常见问题与解决方案

1. 服务器启动问题

#### 1.1 服务无法启动

症状表现：

• 终端无响应或报错退出
• 端口 8931 被占用
• 连接被拒绝

诊断步骤：

# 检查端口占用情况
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）以确保安全，外部网络无法直接访问。

// 安全绑定配置
const host = '127.0.0.1';
const httpServer = app.listen(port, host, () => {
  // 服务器仅接受本地连接
});

远程访问方案：使用 SSH 隧道连接远程服务器

ssh -L 8931:localhost:8931 user@remote-server

资料来源：src/http-server.ts:50-70

2. Docker 相关问题

#### 2.1 容器立即退出

症状：容器启动后立即退出

原因：MCP 服务器需要通过 stdin/stdout 进行通信，缺少必要的交互参数

解决方案：使用 -i 参数保持标准输入打开

docker run -i --rm mcp-playwright:latest

资料来源：DOCKER.md:1-50

#### 2.2 浏览器未找到

症状：Browser not found 或浏览器下载失败

原因：Docker 镜像默认跳过浏览器下载以减小体积

解决方案：创建自定义 Dockerfile 预安装浏览器

FROM mcp-playwright:latest

# 安装 Playwright 浏览器
RUN npx playwright install chromium --with-deps

或者设置环境变量跳过浏览器下载检查：

docker run -i --rm \
  -e PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 \
  mcp-playwright:latest

资料来源：DOCKER.md:60-80

#### 2.3 挂载卷权限问题

症状：容器内无法读写挂载的目录

解决方案：使用 --user 参数指定用户身份

docker run -i --rm \
  -v $(pwd)/data:/app/data \
  --user $(id -u):$(id -g) \
  mcp-playwright:latest

资料来源：DOCKER.md:85-95

3. 浏览器相关问题

#### 3.1 浏览器自动安装

系统支持浏览器自动安装，首次使用时自动检测并下载缺失的浏览器二进制文件：

graph TD
    A[启动服务器] --> B{检测浏览器}
    B -->|浏览器缺失| C[自动下载安装]
    B -->|浏览器存在| D[继续执行]
    C --> E[显示安装进度]
    E --> D

手动安装命令：

# 安装所有浏览器
npx playwright install

# 安装特定浏览器
npx playwright install chromium
npx playwright install firefox
npx playwright install webkit

浏览器存储位置：

资料来源：README.md:100-130

#### 3.2 浏览器连接断开

症状：Target page, context or browser has been closed

错误分类：resource 类型错误

解决方案：

1. 检查浏览器实例是否正常启动
2. 避免在页面加载完成前执行操作
3. 使用适当的等待策略

// 浏览器上下文捕获示例
private captureBrowserContext(error: Error): Record<string, any> {
  const context: Record<string, any> = {};
  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

graph LR
    A[stdio 模式] --> B[日志写入文件]
    C[HTTP 模式] --> D[日志输出控制台]
    B --> E[~/playwright-mcp-server.log]

资料来源：README.md:50-60

#### 4.2 工具执行流程监控

系统提供完整的工具执行日志记录：

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: 返回响应

请求日志上下文：

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 截图存储机制

截图工具支持内存存储和文件存储两种模式：

graph TD
    A[截图请求] --> B{storeBase64 参数}
    B -->|true| C[存入内存 Map]
    B -->|false| D[仅保存文件]
    C --> E[触发资源变更通知]
    D --> F[返回文件路径]
    E --> G[通知 MCP 客户端]

存储配置：

// 截图参数配置
interface ScreenshotArgs {
  name?: string;           // 截图标识名称
  downloadsDir?: string;    // 下载目录路径
  storeBase64?: boolean;   // 是否存入内存，默认为 true
}

资料来源：src/tools/browser/screenshot.ts:20-50

#### 5.2 获取已存储截图

// 获取所有已存储的截图
getScreenshots(): Map<string, string> {
  return this.screenshots;
}

返回内存中所有 Base64 编码的截图数据。

资料来源：src/tools/browser/screenshot.ts:80-90

6. 连接问题诊断

#### 6.1 连接问题排查清单

资料来源：README.md:80-100

#### 6.2 健康检查端点

# HTTP 模式健康检查
curl http://localhost:8931/health

响应示例：

{
  "status": "ok",
  "version": "1.x.x",
  "activeSessions": 0
}

资料来源：src/http-server.ts:30-45

7. 日志系统调试

#### 7.1 日志级别

// 日志方法
info(message: string, context?: Record<string, any>): void
warn(message: string, context?: Record<string, any>): void
error(message: string, error?: Error, context?: Record<string, any>): void
logRequest(message: string, requestContext: RequestLogContext): void
logError(message: string, error: Error, errorContext?: ErrorLogContext): void

#### 7.2 错误上下文捕获

系统自动捕获丰富的错误上下文信息：

captureErrorContext(error: Error, toolName?: string, args?: any): Record<string, any> {
  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 资源限制

services:
  playwright-mcp:
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 2G

#### 8.2 健康检查配置

services:
  playwright-mcp:
    healthcheck:
      test: ["CMD", "node", "-e", "process.exit(0)"]
      interval: 30s
      timeout: 10s
      retries: 3

资料来源：DOCKER.md:100-130

获取帮助

如果问题仍未解决：

1. 查看完整的 README.md 获取一般信息
2. 在 GitHub Issues 报告问题
3. 为 Docker 相关问题添加 docker 标签
4. 使用 docker scan 检查镜像安全漏洞

依赖版本参考

资料来源：package.json:1-30

Pitfall Log / 踩坑日志

项目：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