@ai-coding-labs/playwright-mcp-plus/README.zh.md

Enhanced Playwright Tools for MCP with Project Session Isolation

<div align="center">

# Playwright MCP Plus

**🌐 Language / 语言:** [English](README.md) | [中文](README.zh.md)

</div>

---

### 🎭 看看区别！

#### 😫 没有 Playwright Plus MCP
> **单浏览器限制：** 一次只能运行一个浏览器自动化会话。会话冲突会破坏你的工作流程...

**📹 演示视频：**

[![修复前：持续重新登录的挫败感](docs/images/before-use-playwright-plus-mcp.gif)](https://github.com/ai-coding-labs/playwright-plus-mcp/raw/main/docs/images/before-use-playwright-plus-mcp.mp4)

#### 🚀 使用 Playwright Plus MCP
> **🎯 游戏规则改变者：同时打开多个浏览器进行并发自动化测试！**
>
> 体验**并行浏览器自动化**的强大力量 - 同时在不同项目中运行多个自动化测试，每个都有自己的持久会话！

**📹 演示视频：**

[![修复后：流畅的持久会话](docs/images/after-use-playwright-plus-mcp.gif)](https://github.com/ai-coding-labs/playwright-plus-mcp/raw/main/docs/images/after-use-playwright-plus-mcp.mp4)

> **💡 注意：** 这些视频展示了革命性的差异 - 从单浏览器限制到**无限并发浏览器自动化**。

**🔥 你刚刚见证的：**
- 😫 **修复前：** 只能一个浏览器。打开新项目 = 会话被销毁。每次都要手动重新登录。
- 🚀 **修复后：** **无限并发浏览器！** 同时打开 5、10、20+ 个浏览器自动化会话。每个项目都保持自己的持久状态。**真正的大规模并行自动化测试！**

## Playwright MCP Plus

一个**增强版**的模型上下文协议（MCP）服务器，使用 [Playwright](https://playwright.dev) 提供浏览器自动化功能。

### 🎯 **核心创新：项目级会话隔离**

**⚡ 我们解决的问题：**
- **单浏览器瓶颈：** 常规 Playwright MCP = 一次只能运行一个浏览器自动化会话
- 打开多个项目窗口会导致灾难性的会话冲突
- 每个新的自动化任务都会**销毁之前的浏览器会话**
- **自动化测试在规模化时变得不可能** - 你无法运行并行测试
- 持续的重新认证会扼杀生产力并破坏 CI/CD 工作流程

**🚀 我们的革命性解决方案：**
**🎯 无限并发浏览器自动化** - 在不同项目中同时运行多个自动化测试，每个都有隔离的持久会话！

**✨ 这为你解锁了什么：**
- 🚀 **并发自动化测试** - 同时运行 10+ 个浏览器自动化会话而不冲突
- 🔄 **再也不会丢失登录状态** - 每个项目都维护自己的认证会话
- 🪟 **并行项目工作流** - 同时在多个项目中自动化测试
- 🧪 **可扩展的测试自动化** - 你的测试套件并行运行，更快更可靠
- 💾 **会话在 IDE 重启后持久保存** - 关闭并重新打开项目，所有会话仍然完好
- 🎯 **零配置要求** - 开箱即用，具有智能默认设置

### 🚀 增强功能（相比官方 Playwright MCP）

这个增强版本保持与官方 Playwright MCP **100% 向后兼容**，同时解锁**无限并发浏览器自动化**：

#### **🎯 并发自动化测试**
- **🚀 无限并行浏览器**：同时运行多个浏览器自动化会话而不冲突
- **⚡ 可扩展测试自动化**：在多个项目中并发执行自动化测试
- **🔄 零会话干扰**：每个浏览器会话完全与其他会话隔离

#### **🔒 项目会话隔离**
- **🏗️ 自动项目检测**：每个项目都有自己的隔离浏览器会话
- **💾 持久登录状态**：在 IDE 重启和窗口切换时保持登录状态
- **🚪 不再重新认证**：你的自动化测试和工作流程不间断运行
- **📁 清洁项目目录**：默认情况下项目文件夹中没有会话文件
- **🌍 跨平台支持**：为 Windows、macOS、Linux 智能选择存储位置

#### **🛠️ 多种存储策略**
- `system`：存储在操作系统缓存目录（推荐，用户不可见）
- `project`：存储在项目目录（传统行为）
- `custom`：存储在自定义位置

#### **⚙️ 配置参数**
- `--project-isolation`：启用项目级会话隔离（默认：禁用）
- `--project-isolation-session-strategy`：选择存储策略（默认："system"）
- `--project-isolation-session-root-dir`：会话存储的自定义根目录

#### **✅ 相比官方版本的革命性优势**
- 🚀 **无限并发浏览器**：同时运行多个浏览器自动化会话（相比单会话限制）
- ⚡ **并行自动化测试**：同时在多个项目中执行自动化测试
- ✅ **100% 向后兼容**：官方版本的直接替代品
- ✅ **多项目工作流**：在多个项目上工作而不会话冲突
- ✅ **持久认证**：会话之间永不丢失登录状态
- ✅ **可扩展测试自动化**：消除重新登录开销并启用并行测试执行
- ✅ **清洁工作空间**：默认情况下项目目录中没有会话文件
- ✅ **无冲突**：使用官方 Playwright 路径结构避免冲突
- ✅ **零维护**：自动清理和管理会话数据

### 核心功能

- **🚀 并发浏览器自动化**。运行无限并行浏览器会话进行可扩展的自动化测试。
- **🧩 Chrome 扩展管理**。以编程方式安装、卸载和管理 Chrome 扩展，支持自动浏览器重启。
- **快速轻量**。使用 Playwright 的可访问性树，而不是基于像素的输入。
- **LLM 友好**。不需要视觉模型，纯粹基于结构化数据操作。
- **确定性工具应用**。避免基于截图方法常见的歧义。
- **🆕 项目级隔离**。每个项目都有独立的浏览器会话和智能存储管理。

### 要求
- Node.js 18 或更新版本
- VS Code、Cursor、Windsurf、Claude Desktop、Goose 或任何其他 MCP 客户端

### 开始使用

首先，在你的客户端中安装 Playwright MCP 服务器。

**标准配置**（与官方 Playwright MCP 100% 兼容）：

```js
{
  "mcpServers": {
    "playwright-plus": {
      "command": "npx",
      "args": [
        "-y",
        "@ai-coding-labs/playwright-mcp-plus@latest"
      ]
    }
  }
}
```

**增强配置**，带项目隔离（推荐）：

```js
{
  "mcpServers": {
    "playwright-plus": {
      "command": "npx",
      "args": [
        "-y",
        "@ai-coding-labs/playwright-mcp-plus@latest",
        "--project-isolation"
      ]
    }
  }
}
```

**高级配置**，带自定义会话存储：

```js
{
  "mcpServers": {
    "playwright-plus": {
      "command": "npx",
      "args": [
        "-y",
        "@ai-coding-labs/playwright-mcp-plus@latest",
        "--project-isolation",
        "--project-isolation-session-strategy=custom",
        "--project-isolation-session-root-dir=/custom/session/path"
      ]
    }
  }
}
```

**💡 多项目工作流专业提示：**

一旦启用 `--project-isolation`，你的每个项目都会自动获得自己的浏览器会话。当你调用任何浏览器工具时，只需包含项目参数：

```javascript
// 每个项目自动获得隔离的会话
browser_navigate({
  url: "https://yourapp.com",
  projectDrive: "/",                    // macOS/Linux: "/"，Windows: "C:"
  projectPath: "/path/to/your/project"  // 项目目录的绝对路径
})
```

这确保你的登录状态、cookies 和浏览器数据在不同项目之间永不干扰！

### 🎬 真实世界使用场景

**修复前（官方 Playwright MCP）：**
```bash
# 在项目 A 上工作 - 登录管理面板
browser_navigate("https://myapp-staging.com/admin")
# 用凭据登录，做一些测试...

# 切换到项目 B 窗口 - 会话丢失！😱
browser_navigate("https://different-app.com/dashboard")
# 项目 A 的所有登录状态都消失了，必须重新登录

# 切换回项目 A - 登录又丢失了！😱
# 每次都必须重新认证
```

**修复后（带项目隔离）：**
```bash
# 项目 A - 登录一次，永远保持登录
browser_navigate({
  url: "https://myapp-staging.com/admin",
  projectDrive: "/",
  projectPath: "/Users/you/projects/project-a"
})

# 项目 B - 完全独立的会话
browser_navigate({
  url: "https://different-app.com/dashboard",
  projectDrive: "/",
  projectPath: "/Users/you/projects/project-b"
})

# 切换回项目 A - 仍然登录！✨
# 无需重新认证，会话完美保存
```

**结果：** 你的自动化测试运行速度提高 10 倍，开发工作流程不被中断，你可以同时在多个项目上工作而不会丢失认证状态。

### 🧩 Chrome 扩展管理

Playwright MCP Plus 包含强大的 Chrome 扩展管理功能，允许你以编程方式安装、卸载和管理 Chrome 扩展，并支持自动浏览器重启以立即生效。

**核心功能：**
- **🚀 一键安装**：直接从 Chrome 网上应用店 URL 或扩展 ID 安装扩展
- **🔄 自动浏览器重启**：安装后扩展立即可用
- **🗑️ 干净卸载**：完全移除扩展并自动清理
- **📋 扩展注册表**：跟踪所有已安装扩展的详细信息
- **🏠 本地管理**：扩展存储在本地 `~/.mcp-extensions/` 目录中

**使用示例：**

```javascript
// 通过 URL 安装扩展并立即加载
browser_extension_install({
  extensionUrl: "https://chromewebstore.google.com/detail/json-formatter/bcjindcccaagfpapjjmafapmmgkkhgoa",
  loadImmediately: true,
  projectDrive: "/",
  projectPath: "/path/to/your/project"
})

// 通过 ID 安装扩展
browser_extension_install({
  extensionId: "chklaanhfefbnpoihckbnefhakgolnmc",
  loadImmediately: true
})

// 列出所有已安装的扩展
browser_extension_list()

// 卸载扩展并立即生效
browser_extension_uninstall({
  extensionId: "bcjindcccaagfpapjjmafapmmgkkhgoa",
  restartImmediately: true
})
```

**完美适用于：**
- **🧪 自动化测试**：为测试套件安装测试扩展
- **🛠️ 开发工作流**：快速设置带有所需扩展的开发环境
- **🔧 CI/CD 流水线**：在自动化工作流中以编程方式管理浏览器扩展
- **📊 网页抓取**：安装增强数据提取能力的扩展

[<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="在 VS Code 中安装">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D) [<img alt="在 VS Code Insiders 中安装" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D)

<details>
<summary>Claude Code</summary>

使用 Claude Code CLI 添加增强版 Playwright MCP 服务器：

**标准版本：**
```bash
claude mcp add playwright-plus npx -y @ai-coding-labs/playwright-mcp-plus@latest
```

**带项目隔离（推荐）：**
```bash
claude mcp add playwright-plus npx -y @ai-coding-labs/playwright-mcp-plus@latest --project-isolation
```
</details>

<details>
<summary>Claude Desktop</summary>

按照 MCP 安装[指南](https://modelcontextprotocol.io/quickstart/user)，使用上面的标准配置。

</details>

<details>
<summary>Cursor</summary>

#### 点击按钮安装：

[![安装 MCP 服务器](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=playwright-plus&config=eyJjb21tYW5kIjoibnB4IEBwbGF5d3JpZ2h0L21jcEBsYXRlc3QifQ%3D%3D)

#### 或手动安装：

转到 `Cursor Settings` -> `MCP` -> `Add new MCP Server`。随意命名，使用 `command` 类型，命令为 `npx -y @ai-coding-labs/playwright-mcp-plus --project-isolation`。你也可以通过点击 `Edit` 验证配置或添加命令参数。

</details>

<details>
<summary>Gemini CLI</summary>

按照 MCP 安装[指南](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md#configure-the-mcp-server-in-settingsjson)，使用上面的标准配置。

</details>

<details>
<summary>Goose</summary>

#### 点击按钮安装：

[![在 Goose 中安装](https://block.github.io/goose/img/extension-install-dark.svg)](https://block.github.io/goose/extension?cmd=npx&arg=%40playwright%2Fmcp%40latest&id=playwright-plus&name=Playwright&description=Interact%20with%20web%20pages%20through%20structured%20accessibility%20snapshots%20using%20Playwright)

#### 或手动安装：

转到 `Advanced settings` -> `Extensions` -> `Add custom extension`。随意命名，使用类型 `STDIO`，将 `command` 设置为 `npx -y @ai-coding-labs/playwright-mcp-plus --project-isolation`。点击 "Add Extension"。
</details>

<details>
<summary>LM Studio</summary>

#### 点击按钮安装：

[![将 MCP 服务器 playwright-plus 添加到 LM Studio](https://files.lmstudio.ai/deeplink/mcp-install-light.svg)](https://lmstudio.ai/install-mcp?name=playwright-plus&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJAcGxheXdyaWdodC9tY3BAbGF0ZXN0Il19)

#### 或手动安装：

转到右侧边栏的 `Program` -> `Install` -> `Edit mcp.json`。使用上面的标准配置。
</details>

<details>
<summary>Qodo Gen</summary>

在 VSCode 或 IntelliJ 中打开 [Qodo Gen](https://docs.qodo.ai/qodo-documentation/qodo-gen) 聊天面板 → Connect more tools → + Add new MCP → 粘贴上面的标准配置。

点击 <code>Save</code>。
</details>

<details>
<summary>VS Code</summary>

#### 点击按钮安装：

[<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="在 VS Code 中安装">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D) [<img alt="在 VS Code Insiders 中安装" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D)

#### 或手动安装：

按照 MCP 安装[指南](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server)，使用上面的标准配置。你也可以使用 VS Code CLI 安装 Playwright MCP 服务器：

```bash
# 对于 VS Code
code --add-mcp '{"name":"playwright-plus","command":"npx","args":["-y","@ai-coding-labs/playwright-mcp-plus@latest","--project-isolation"]}'
```

安装后，Playwright MCP 服务器将可用于 VS Code 中的 GitHub Copilot 代理。
</details>

<details>
<summary>Windsurf</summary>

按照 Windsurf MCP [文档](https://docs.windsurf.com/windsurf/cascade/mcp)。使用上面的标准配置。

</details>

### 配置

Playwright MCP 服务器支持以下参数。它们可以在上面的 JSON 配置中作为 `"args"` 列表的一部分提供：

<!--- 由 update-readme.js 生成的选项 -->

```
> npx @ai-coding-labs/playwright-mcp-plus@latest --help
  --allowed-origins <origins>                      允许浏览器请求的源的分号分隔列表。默认允许所有。
  --blocked-origins <origins>                      阻止浏览器请求的源的分号分隔列表。阻止列表在允许列表之前评估。如果在没有允许列表的情况下使用，不匹配阻止列表的请求仍然被允许。
  --block-service-workers                          阻止 service workers
  --browser <browser>                              要使用的浏览器或 chrome 频道，可能的值：chrome、firefox、webkit、msedge。
  --caps <caps>                                    要启用的附加功能的逗号分隔列表，可能的值：vision、pdf。
  --cdp-endpoint <endpoint>                        要连接的 CDP 端点。
  --config <path>                                  配置文件的路径。
  --device <device>                                要模拟的设备，例如："iPhone 15"
  --executable-path <path>                         浏览器可执行文件的路径。
  --headless                                       在无头模式下运行浏览器，默认有头
  --host <host>                                    绑定服务器的主机。默认是 localhost。使用 0.0.0.0 绑定到所有接口。
  --ignore-https-errors                            忽略 https 错误
  --isolated                                       将浏览器配置文件保存在内存中，不保存到磁盘。
  --image-responses <mode>                         是否向客户端发送图像响应。可以是 "allow" 或 "omit"，默认为 "allow"。
  --no-sandbox                                     为通常沙盒化的所有进程类型禁用沙盒。
  --output-dir <path>                              输出文件目录的路径。
  --port <port>                                    SSE 传输监听的端口。
  --project-isolation                              使用来自 MCP 上下文的项目路径启用项目级会话隔离。
  --project-isolation-session-strategy <strategy>  项目隔离的会话目录策略：system、project、custom。默认为 "system"。(default: "system")
  --project-isolation-session-root-dir <path>      使用项目隔离时会话存储的自定义根目录（仅在 --project-isolation-session-strategy=custom 时使用）。
  --proxy-bypass <bypass>                          绕过代理的逗号分隔域，例如 ".com,chromium.org,.domain.com"
  --proxy-server <proxy>                           指定代理服务器，例如 "http://myproxy:3128" 或 "socks5://myproxy:8080"
  --save-session                                   是否将 Playwright MCP 会话保存到输出目录。
  --save-trace                                     是否将会话的 Playwright Trace 保存到输出目录。
  --storage-state <path>                           隔离会话的存储状态文件路径。
  --user-agent <ua string>                         指定用户代理字符串
  --user-data-dir <path>                           用户数据目录的路径。如果未指定，将创建临时目录。
  --viewport-size <size>                           指定浏览器视口大小（像素），例如 "1280, 720"
```

<!--- 选项生成部分结束 -->

### 用户配置文件

你可以像常规浏览器一样使用持久配置文件运行 Playwright MCP（默认），或在隔离上下文中进行测试会话。

**持久配置文件**

所有登录信息都将存储在持久配置文件中，如果你想清除离线状态，可以在会话之间删除它。
持久配置文件位于以下位置，你可以使用 `--user-data-dir` 参数覆盖它。

```bash
# Windows
%USERPROFILE%\AppData\Local\ms-playwright\mcp-{channel}-profile

# macOS
- ~/Library/Caches/ms-playwright/mcp-{channel}-profile

# Linux
- ~/.cache/ms-playwright/mcp-{channel}-profile
```

**隔离**

在隔离模式下，每个会话都在隔离配置文件中启动。每次你要求 MCP 关闭浏览器时，
会话都会关闭，此会话的所有存储状态都会丢失。你可以通过配置的 `contextOptions` 或通过 `--storage-state` 参数向浏览器提供初始存储状态。在[这里](https://playwright.dev/docs/auth)了解更多关于存储状态的信息。

```js
{
  "mcpServers": {
    "playwright-plus": {
      "command": "npx",
      "args": [
        "@ai-coding-labs/playwright-mcp-plus@latest",
        "--isolated",
        "--storage-state={path/to/storage.json}"
      ]
    }
  }
}
```

### 🔒 项目隔离（增强功能）

**项目隔离**允许每个项目维护自己独立的浏览器会话，具有独立的登录状态、cookies 和 localStorage。这可以防止跨项目干扰，同时保持工作空间清洁。

#### **默认行为（向后兼容）**
没有任何隔离标志时，会话在所有项目之间共享（与官方 Playwright MCP 相同）：

```js
{
  "mcpServers": {
    "playwright-plus": {
      "command": "npx",
      "args": ["@ai-coding-labs/playwright-mcp-plus@latest"]
    }
  }
}
```

#### **推荐：系统策略（零配置）**
启用项目隔离，会话存储在操作系统缓存目录中（对用户不可见）：

```js
{
  "mcpServers": {
    "playwright-plus": {
      "command": "npx",
      "args": [
        "@ai-coding-labs/playwright-mcp-plus@latest",
        "--project-isolation"
      ]
    }
  }
}
```

**按操作系统的存储位置：**
- **Windows:** `%LOCALAPPDATA%/ms-playwright/mcp-chrome-profile/playwright-plus-mcp/project-hash/`
- **macOS:** `~/Library/Caches/ms-playwright/mcp-chrome-profile/playwright-plus-mcp/project-hash/`
- **Linux:** `~/.cache/ms-playwright/mcp-chrome-profile/playwright-plus-mcp/project-hash/`

#### **项目策略**
在项目目录中存储会话（创建 `.user-session-data-directory/`）：

```js
{
  "mcpServers": {
    "playwright-plus": {
      "command": "npx",
      "args": [
        "@ai-coding-labs/playwright-mcp-plus@latest",
        "--project-isolation",
        "--project-isolation-session-strategy=project"
      ]
    }
  }
}
```

#### **自定义策略**
在自定义位置存储会话：

```js
{
  "mcpServers": {
    "playwright-plus": {
      "command": "npx",
      "args": [
        "@ai-coding-labs/playwright-mcp-plus@latest",
        "--project-isolation",
        "--project-isolation-session-strategy=custom",
        "--project-isolation-session-root-dir=/custom/sessions"
      ]
    }
  }
}
```

#### **策略比较**

| 配置 | 会话位置 | 项目目录 | 用户可见性 | 使用场景 |
|------|----------|----------|------------|----------|
| **无隔离**（默认） | 共享缓存 | 清洁 | 隐藏 | 向后兼容 |
| **系统**（隔离默认） | 操作系统缓存目录 | 清洁 | 隐藏 | 最佳用户体验 |
| **项目** | `.user-session-data-directory/` | 有会话文件 | 可见 | 传统/调试 |
| **自定义** | 自定义路径 | 清洁 | 隐藏 | 高级设置 |

### 配置文件

Playwright MCP 服务器可以使用 JSON 配置文件进行配置。你可以使用 `--config` 命令行选项指定配置文件：

```bash
npx @ai-coding-labs/playwright-mcp-plus@latest --config path/to/config.json
```

<details>
<summary>配置文件架构</summary>

```typescript
{
  // 浏览器配置
  browser?: {
    // 要使用的浏览器类型（chromium、firefox 或 webkit）
    browserName?: 'chromium' | 'firefox' | 'webkit';

    // 将浏览器配置文件保存在内存中，不保存到磁盘。
    isolated?: boolean;

    // 浏览器配置文件持久化的用户数据目录路径
    userDataDir?: string;

    // 浏览器启动选项（参见 Playwright 文档）
    // @see https://playwright.dev/docs/api/class-browsertype#browser-type-launch
    launchOptions?: {
      channel?: string;        // 浏览器频道（例如 'chrome'）
      headless?: boolean;      // 在无头模式下运行
      executablePath?: string; // 浏览器可执行文件路径
      // ... 其他 Playwright 启动选项
    };

    // 浏览器上下文选项
    // @see https://playwright.dev/docs/api/class-browser#browser-new-context
    contextOptions?: {
      viewport?: { width: number, height: number };
      // ... 其他 Playwright 上下文选项
    };

    // 用于连接到现有浏览器的 CDP 端点
    cdpEndpoint?: string;

    // 远程 Playwright 服务器端点
    remoteEndpoint?: string;
  },

  // 服务器配置
  server?: {
    port?: number;  // 监听端口
    host?: string;  // 绑定主机（默认：localhost）
  },

  // 附加功能列表
  capabilities?: Array<
    'tabs' |    // 标签管理
    'install' | // 浏览器安装
    'pdf' |     // PDF 生成
    'vision' |  // 基于坐标的交互
  >;

  // 输出文件目录
  outputDir?: string;

  // 网络配置
  network?: {
    // 允许浏览器请求的源列表。默认允许所有。同时匹配 `allowedOrigins` 和 `blockedOrigins` 的源将被阻止。
    allowedOrigins?: string[];

    // 阻止浏览器请求的源列表。同时匹配 `allowedOrigins` 和 `blockedOrigins` 的源将被阻止。
    blockedOrigins?: string[];
  };

  /**
   * 是否向客户端发送图像响应。可以是 "allow" 或 "omit"。
   * 默认为 "allow"。
   */
  imageResponses?: 'allow' | 'omit';

  /**
   * 使用来自 MCP 上下文的项目路径启用项目级会话隔离。
   * 启用时，每个项目都有自己的隔离浏览器会话。
   * 默认为 false（共享会话，与官方 Playwright MCP 兼容）。
   */
  projectIsolation?: boolean;

  /**
   * 项目隔离的会话目录存储策略。
   * 仅在启用 projectIsolation 时使用。
   * - 'system'：存储在操作系统缓存目录（推荐，用户不可见）
   * - 'project'：存储在项目目录（传统行为）
   * - 'custom'：存储在 projectIsolationSessionRootDir 指定的自定义位置
   * 默认为 "system"。
   */
  projectIsolationSessionStrategy?: 'system' | 'project' | 'custom';

  /**
   * 使用项目隔离时会话存储的自定义根目录。
   * 仅在 projectIsolationSessionStrategy 为 'custom' 时使用。
   * 示例："/custom/session/storage/path"
   */
  projectIsolationSessionRootDir?: string;
}
```
</details>

### 独立 MCP 服务器

在没有显示器的系统上运行有头浏览器或从 IDE 的工作进程运行时，
从具有 DISPLAY 的环境运行 MCP 服务器并传递 `--port` 标志以启用 HTTP 传输。

```bash
npx @ai-coding-labs/playwright-mcp-plus@latest --port 8931
```

然后在 MCP 客户端配置中，将 `url` 设置为 HTTP 端点：

```js
{
  "mcpServers": {
    "playwright-plus": {
      "url": "http://localhost:8931/mcp"
    }
  }
}
```

<details>
<summary><b>Docker</b></summary>

**注意：** Docker 实现目前仅支持无头 chromium。

```js
{
  "mcpServers": {
    "playwright-plus": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "--pull=always", "mcr.microsoft.com/playwright/mcp"]
    }
  }
}
```

你可以自己构建 Docker 镜像。

```
docker build -t mcr.microsoft.com/playwright/mcp .
```
</details>

<details>
<summary><b>编程使用</b></summary>

```js
import http from 'http';

import { createConnection } from '@ai-coding-labs/playwright-mcp-plus';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';

http.createServer(async (req, res) => {
  // ...

  // 创建带有 SSE 传输的无头 Playwright MCP 服务器
  const connection = await createConnection({ browser: { launchOptions: { headless: true } } });
  const transport = new SSEServerTransport('/messages', res);
  await connection.sever.connect(transport);

  // ...
});
```
</details>

### 工具

<!--- 由 update-readme.js 生成的工具 -->

<details>
<summary><b>核心自动化</b></summary>

<!-- 注意：这是通过 update-readme.js 生成的 -->

- **browser_click**
  - 标题：点击
  - 描述：在网页上执行点击操作
  - 参数：
    - `element` (string)：用于获得与元素交互权限的人类可读元素描述
    - `ref` (string)：来自页面快照的确切目标元素引用
    - `doubleClick` (boolean, 可选)：是否执行双击而不是单击
    - `button` (string, 可选)：要点击的按钮，默认为左键
  - 只读：**false**

<!-- 注意：这是通过 update-readme.js 生成的 -->

- **browser_close**
  - 标题：关闭浏览器
  - 描述：关闭页面
  - 参数：
    - `projectDrive` (string, 可选)：用于会话隔离的项目驱动器字母或根目录（例如，"C:"，"/"）
    - `projectPath` (string, 可选)：用于会话隔离的项目根目录的绝对路径
  - 只读：**true**

<!-- 注意：这是通过 update-readme.js 生成的 -->

- **browser_console_messages**
  - 标题：获取控制台消息
  - 描述：返回所有控制台消息
  - 参数：无
  - 只读：**true**

<!-- 注意：这是通过 update-readme.js 生成的 -->

- **browser_drag**
  - 标题：拖拽鼠标
  - 描述：在两个元素之间执行拖放操作
  - 参数：
    - `startElement` (string)：用于获得与元素交互权限的人类可读源元素描述
    - `startRef` (string)：来自页面快照的确切源元素引用
    - `endElement` (string)：用于获得与元素交互权限的人类可读目标元素描述
    - `endRef` (string)：来自页面快照的确切目标元素引用
  - 只读：**false**

<!-- 注意：这是通过 update-readme.js 生成的 -->

- **browser_evaluate**
  - 标题：执行 JavaScript
  - 描述：在页面或元素上执行 JavaScript 表达式
  - 参数：
    - `function` (string)：() => { /* 代码 */ } 或当提供元素时 (element) => { /* 代码 */ }
    - `element` (string, 可选)：用于获得与元素交互权限的人类可读元素描述
    - `ref` (string, 可选)：来自页面快照的确切目标元素引用
  - 只读：**false**

<!-- 注意：这是通过 update-readme.js 生成的 -->

- **browser_file_upload**
  - 标题：上传文件
  - 描述：上传一个或多个文件
  - 参数：
    - `paths` (array)：要上传的文件的绝对路径。可以是单个文件或多个文件。
  - 只读：**false**

<!-- 注意：这是通过 update-readme.js 生成的 -->

- **browser_handle_dialog**
  - 标题：处理对话框
  - 描述：处理对话框
  - 参数：
    - `accept` (boolean)：是否接受对话框。
    - `promptText` (string, 可选)：在提示对话框情况下的提示文本。
  - 只读：**false**

<!-- 注意：这是通过 update-readme.js 生成的 -->

- **browser_hover**
  - 标题：悬停鼠标
  - 描述：在页面上悬停在元素上
  - 参数：
    - `element` (string)：用于获得与元素交互权限的人类可读元素描述
    - `ref` (string)：来自页面快照的确切目标元素引用
  - 只读：**true**

<!-- 注意：这是通过 update-readme.js 生成的 -->

- **browser_navigate**
  - 标题：导航到 URL
  - 描述：导航到 URL
  - 参数：
    - `url` (string)：要导航到的 URL
    - `projectDrive` (string, 可选)：用于会话隔离的项目驱动器字母或根目录（例如，"C:"，"/"）
    - `projectPath` (string, 可选)：用于会话隔离的项目根目录的绝对路径
  - 只读：**false**

<!-- 注意：这是通过 update-readme.js 生成的 -->

- **browser_navigate_back**
  - 标题：后退
  - 描述：返回到上一页
  - 参数：无
  - 只读：**true**

<!-- 注意：这是通过 update-readme.js 生成的 -->

- **browser_navigate_forward**
  - 标题：前进
  - 描述：前进到下一页
  - 参数：无
  - 只读：**true**

<!-- 注意：这是通过 update-readme.js 生成的 -->

- **browser_network_requests**
  - 标题：列出网络请求
  - 描述：返回自加载页面以来的所有网络请求
  - 参数：无
  - 只读：**true**

<!-- 注意：这是通过 update-readme.js 生成的 -->

- **browser_press_key**
  - 标题：按键
  - 描述：在键盘上按键
  - 参数：
    - `key` (string)：要按的键的名称或要生成的字符，例如 `ArrowLeft` 或 `a`
  - 只读：**false**

<!-- 注意：这是通过 update-readme.js 生成的 -->

- **browser_resize**
  - 标题：调整浏览器窗口大小
  - 描述：调整浏览器窗口大小
  - 参数：
    - `width` (number)：浏览器窗口的宽度
    - `height` (number)：浏览器窗口的高度
  - 只读：**true**

<!-- 注意：这是通过 update-readme.js 生成的 -->

- **browser_select_option**
  - 标题：选择选项
  - 描述：在下拉菜单中选择选项
  - 参数：
    - `element` (string)：用于获得与元素交互权限的人类可读元素描述
    - `ref` (string)：来自页面快照的确切目标元素引用
    - `values` (array)：在下拉菜单中选择的值数组。可以是单个值或多个值。
  - 只读：**false**

<!-- 注意：这是通过 update-readme.js 生成的 -->

- **browser_snapshot**
  - 标题：页面快照
  - 描述：捕获当前页面的可访问性快照，这比截图更好
  - 参数：
    - `projectDrive` (string, 可选)：用于会话隔离的项目驱动器字母或根目录（例如，"C:"，"/"）
    - `projectPath` (string, 可选)：用于会话隔离的项目根目录的绝对路径
  - 只读：**true**

<!-- 注意：这是通过 update-readme.js 生成的 -->

- **browser_take_screenshot**
  - 标题：截图
  - 描述：对当前页面进行截图。你不能基于截图执行操作，请使用 browser_snapshot 进行操作。
  - 参数：
    - `type` (string, 可选)：截图的图像格式。默认为 png。
    - `filename` (string, 可选)：保存截图的文件名。如果未指定，默认为 `page-{timestamp}.{png|jpeg}`。
    - `element` (string, 可选)：用于获得截图元素权限的人类可读元素描述。如果未提供，将截取视口。如果提供了 element，也必须提供 ref。
    - `ref` (string, 可选)：来自页面快照的确切目标元素引用。如果未提供，将截取视口。如果提供了 ref，也必须提供 element。
    - `fullPage` (boolean, 可选)：当为 true 时，截取完整可滚动页面的截图，而不是当前可见的视口。不能与元素截图一起使用。
  - 只读：**true**

<!-- 注意：这是通过 update-readme.js 生成的 -->

- **browser_type**
  - 标题：输入文本
  - 描述：在可编辑元素中输入文本
  - 参数：
    - `element` (string)：用于获得与元素交互权限的人类可读元素描述
    - `ref` (string)：来自页面快照的确切目标元素引用
    - `text` (string)：要输入到元素中的文本
    - `submit` (boolean, 可选)：是否提交输入的文本（之后按 Enter）
    - `slowly` (boolean, 可选)：是否一次输入一个字符。对于触发页面中的键处理程序很有用。默认情况下，整个文本一次性填入。
  - 只读：**false**

<!-- 注意：这是通过 update-readme.js 生成的 -->

- **browser_wait_for**
  - 标题：等待
  - 描述：等待文本出现或消失或指定时间过去
  - 参数：
    - `time` (number, 可选)：等待的时间（秒）
    - `text` (string, 可选)：要等待的文本
    - `textGone` (string, 可选)：要等待消失的文本
    - `projectDrive` (string, 可选)：用于会话隔离的项目驱动器字母或根目录（例如，"C:"，"/"）
    - `projectPath` (string, 可选)：用于会话隔离的项目根目录的绝对路径
  - 只读：**true**

</details>

<details>
<summary><b>标签管理</b></summary>

<!-- 注意：这是通过 update-readme.js 生成的 -->

- **browser_tab_close**
  - 标题：关闭标签
  - 描述：关闭标签
  - 参数：
    - `index` (number, 可选)：要关闭的标签的索引。如果未提供，则关闭当前标签。
  - 只读：**false**

<!-- 注意：这是通过 update-readme.js 生成的 -->

- **browser_tab_list**
  - 标题：列出标签
  - 描述：列出浏览器标签
  - 参数：
    - `projectDrive` (string, 可选)：用于会话隔离的项目驱动器字母或根目录（例如，"C:"，"/"）
    - `projectPath` (string, 可选)：用于会话隔离的项目根目录的绝对路径
  - 只读：**true**

<!-- 注意：这是通过 update-readme.js 生成的 -->

- **browser_tab_new**
  - 标题：打开新标签
  - 描述：打开新标签
  - 参数：
    - `url` (string, 可选)：在新标签中导航到的 URL。如果未提供，新标签将为空白。
    - `projectDrive` (string, 可选)：用于会话隔离的项目驱动器字母或根目录（例如，"C:"，"/"）
    - `projectPath` (string, 可选)：用于会话隔离的项目根目录的绝对路径
  - 只读：**true**

<!-- 注意：这是通过 update-readme.js 生成的 -->

- **browser_tab_select**
  - 标题：选择标签
  - 描述：按索引选择标签
  - 参数：
    - `index` (number)：要选择的标签的索引
  - 只读：**true**

</details>

<details>
<summary><b>浏览器安装</b></summary>

<!-- 注意：这是通过 update-readme.js 生成的 -->

- **browser_install**
  - 标题：安装配置中指定的浏览器
  - 描述：安装配置中指定的浏览器。如果你收到关于浏览器未安装的错误，请调用此功能。
  - 参数：
    - `projectDrive` (string, 可选)：用于会话隔离的项目驱动器字母或根目录（例如，"C:"，"/"）
    - `projectPath` (string, 可选)：用于会话隔离的项目根目录的绝对路径
  - 只读：**false**

</details>

<details>
<summary><b>基于坐标（通过 --caps=vision 选择加入）</b></summary>

<!-- 注意：这是通过 update-readme.js 生成的 -->

- **browser_mouse_click_xy**
  - 标题：点击
  - 描述：在给定位置点击鼠标左键
  - 参数：
    - `element` (string)：用于获得与元素交互权限的人类可读元素描述
    - `x` (number)：X 坐标
    - `y` (number)：Y 坐标
  - 只读：**false**

<!-- 注意：这是通过 update-readme.js 生成的 -->

- **browser_mouse_drag_xy**
  - 标题：拖拽鼠标
  - 描述：将鼠标左键拖拽到给定位置
  - 参数：
    - `element` (string)：用于获得与元素交互权限的人类可读元素描述
    - `startX` (number)：起始 X 坐标
    - `startY` (number)：起始 Y 坐标
    - `endX` (number)：结束 X 坐标
    - `endY` (number)：结束 Y 坐标
  - 只读：**false**

<!-- 注意：这是通过 update-readme.js 生成的 -->

- **browser_mouse_move_xy**
  - 标题：移动鼠标
  - 描述：将鼠标移动到给定位置
  - 参数：
    - `element` (string)：用于获得与元素交互权限的人类可读元素描述
    - `x` (number)：X 坐标
    - `y` (number)：Y 坐标
  - 只读：**true**

</details>

<details>
<summary><b>Chrome 扩展管理</b></summary>

<!-- 注意：这是通过 update-readme.js 生成的 -->

- **browser_extension_install**
  - 标题：安装 Chrome 扩展
  - 描述：通过下载并本地管理从 Chrome 网上应用店安装 Chrome 扩展
  - 参数：
    - `extensionId` (string, 可选)：Chrome 扩展 ID（例如，"cjpalhdlnbpafiamejdnhcphjbkeiagm"）
    - `extensionUrl` (string, 可选)：扩展的完整 Chrome 网上应用店 URL
    - `waitForInstall` (boolean, 可选)：是否等待安装完成（默认：true）
    - `loadImmediately` (boolean, 可选)：是否重启浏览器以立即加载扩展（默认：true）
    - `projectDrive` (string, 可选)：用于会话隔离的项目驱动器字母或根目录（例如，"C:"，"/"）
    - `projectPath` (string, 可选)：用于会话隔离的项目根目录的绝对路径
  - 只读：**false**

<!-- 注意：这是通过 update-readme.js 生成的 -->

- **browser_extension_uninstall**
  - 标题：卸载 Chrome 扩展
  - 描述：从 MCP 管理中卸载 Chrome 扩展并重启浏览器
  - 参数：
    - `extensionId` (string)：要卸载的 Chrome 扩展 ID（例如，"bcjindcccaagfpapjjmafapmmgkkhgoa"）
    - `restartImmediately` (boolean, 可选)：是否在卸载后立即重启浏览器（默认：true）
    - `projectDrive` (string, 可选)：用于会话隔离的项目驱动器字母或根目录（例如，"C:"，"/"）
    - `projectPath` (string, 可选)：用于会话隔离的项目根目录的绝对路径
  - 只读：**false**

<!-- 注意：这是通过 update-readme.js 生成的 -->

- **browser_extension_list**
  - 标题：列出已安装的扩展
  - 描述：列出所有 MCP 管理的 Chrome 扩展
  - 参数：
    - `projectDrive` (string, 可选)：用于会话隔离的项目驱动器字母或根目录（例如，"C:"，"/"）
    - `projectPath` (string, 可选)：用于会话隔离的项目根目录的绝对路径
  - 只读：**true**

</details>

<details>
<summary><b>PDF 生成（通过 --caps=pdf 选择加入）</b></summary>

<!-- 注意：这是通过 update-readme.js 生成的 -->

- **browser_pdf_save**
  - 标题：保存为 PDF
  - 描述：将页面保存为 PDF
  - 参数：
    - `filename` (string, 可选)：保存 PDF 的文件名。如果未指定，默认为 `page-{timestamp}.pdf`。
  - 只读：**true**

</details>


<!--- 工具生成部分结束 -->

### 配置文件

Playwright MCP 服务器可以使用 JSON 配置文件进行配置。你可以使用 `--config` 命令行选项指定配置文件：

```bash
npx @ai-coding-labs/playwright-mcp-plus@latest --config path/to/config.json
```

<details>
<summary>配置文件架构</summary>

```typescript
{
  // 浏览器配置
  browser?: {
    // 要使用的浏览器类型（chromium、firefox 或 webkit）
    browserName?: 'chromium' | 'firefox' | 'webkit';

    // 将浏览器配置文件保存在内存中，不保存到磁盘。
    isolated?: boolean;

    // 浏览器配置文件持久化的用户数据目录路径
    userDataDir?: string;

    // 浏览器启动选项（参见 Playwright 文档）
    // @see https://playwright.dev/docs/api/class-browsertype#browser-type-launch
    launchOptions?: {
      channel?: string;        // 浏览器频道（例如 'chrome'）
      headless?: boolean;      // 在无头模式下运行
      executablePath?: string; // 浏览器可执行文件路径
      // ... 其他 Playwright 启动选项
    };

    // 浏览器上下文选项
    // @see https://playwright.dev/docs/api/class-browser#browser-new-context
    contextOptions?: {
      viewport?: { width: number, height: number };
      // ... 其他 Playwright 上下文选项
    };

    // 用于连接到现有浏览器的 CDP 端点
    cdpEndpoint?: string;

    // 远程 Playwright 服务器端点
    remoteEndpoint?: string;
  },

  // 服务器配置
  server?: {
    port?: number;  // 监听端口
    host?: string;  // 绑定主机（默认：localhost）
  },

  // 附加功能列表
  capabilities?: Array<
    'tabs' |    // 标签管理
    'install' | // 浏览器安装
    'pdf' |     // PDF 生成
    'vision' |  // 基于坐标的交互
  >;

  // 输出文件目录
  outputDir?: string;

  // 网络配置
  network?: {
    // 允许浏览器请求的源列表。默认允许所有。同时匹配 `allowedOrigins` 和 `blockedOrigins` 的源将被阻止。
    allowedOrigins?: string[];

    // 阻止浏览器请求的源列表。同时匹配 `allowedOrigins` 和 `blockedOrigins` 的源将被阻止。
    blockedOrigins?: string[];
  };

  /**
   * 是否向客户端发送图像响应。可以是 "allow" 或 "omit"。
   * 默认为 "allow"。
   */
  imageResponses?: 'allow' | 'omit';

  /**
   * 使用来自 MCP 上下文的项目路径启用项目级会话隔离。
   * 启用时，每个项目都有自己的隔离浏览器会话。
   * 默认为 false（共享会话，与官方 Playwright MCP 兼容）。
   */
  projectIsolation?: boolean;

  /**
   * 项目隔离的会话目录存储策略。
   * 仅在启用 projectIsolation 时使用。
   * - 'system'：存储在操作系统缓存目录（推荐，用户不可见）
   * - 'project'：存储在项目目录（传统行为）
   * - 'custom'：存储在 projectIsolationSessionRootDir 指定的自定义位置
   * 默认为 "system"。
   */
  projectIsolationSessionStrategy?: 'system' | 'project' | 'custom';

  /**
   * 使用项目隔离时会话存储的自定义根目录。
   * 仅在 projectIsolationSessionStrategy 为 'custom' 时使用。
   * 示例："/custom/session/storage/path"
   */
  projectIsolationSessionRootDir?: string;
}
```
</details>

### 独立 MCP 服务器

在没有显示器的系统上运行有头浏览器或从 IDE 的工作进程运行时，
从具有 DISPLAY 的环境运行 MCP 服务器并传递 `--port` 标志以启用 HTTP 传输。

```bash
npx @ai-coding-labs/playwright-mcp-plus@latest --port 8931
```

然后在 MCP 客户端配置中，将 `url` 设置为 HTTP 端点：

```js
{
  "mcpServers": {
    "playwright-plus": {
      "url": "http://localhost:8931/mcp"
    }
  }
}
```

<details>
<summary><b>Docker</b></summary>

**注意：** Docker 实现目前仅支持无头 chromium。

```js
{
  "mcpServers": {
    "playwright-plus": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "--pull=always", "mcr.microsoft.com/playwright/mcp"]
    }
  }
}
```

你可以自己构建 Docker 镜像。

```
docker build -t mcr.microsoft.com/playwright/mcp .
```
</details>

<details>
<summary><b>编程使用</b></summary>

```js
import http from 'http';

import { createConnection } from '@ai-coding-labs/playwright-mcp-plus';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';

http.createServer(async (req, res) => {
  // ...

  // 创建带有 SSE 传输的无头 Playwright MCP 服务器
  const connection = await createConnection({ browser: { launchOptions: { headless: true } } });
  const transport = new SSEServerTransport('/messages', res);
  await connection.sever.connect(transport);

  // ...
});
```
</details>