# https://github.com/microsoft/playwright-mcp 项目说明书

生成时间：2026-05-14 08:48:11 UTC

## 目录

- [Playwright MCP 简介](#page-introduction)
- [Playwright MCP vs Playwright CLI](#page-comparison)
- [快速入门](#page-quickstart)
- [客户端集成指南](#page-client-integration)
- [核心架构](#page-core-architecture)
- [MCP 工具与能力](#page-tools-capabilities)
- [浏览器配置文件管理](#page-browser-profiles)
- [初始状态配置](#page-initial-state)
- [安全与网络配置](#page-security-config)
- [部署选项](#page-deployment)

<a id='page-introduction'></a>

## Playwright MCP 简介

### 相关页面

相关主题：[Playwright MCP vs Playwright CLI](#page-comparison), [快速入门](#page-quickstart)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/microsoft/playwright-mcp/blob/main/README.md)
- [package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)
- [config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)
- [cli.js](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)
- [index.js](https://github.com/microsoft/playwright-mcp/blob/main/index.js)
- [CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)
- [server.json](https://github.com/microsoft/playwright-mcp/blob/main/server.json)
</details>

# Playwright MCP 简介

## 项目概述

Playwright MCP（Model Context Protocol）是一个为 MCP（Model Context Protocol）协议提供 Playwright 工具的官方实现。该项目由 Microsoft 开发维护，为大语言模型（LLM）代理提供浏览器自动化能力，使其能够与网页进行交互、操作 DOM 元素、执行网络请求等操作。

Playwright MCP 作为 MCP 服务器运行，通过标准输入输出（stdio）传输协议与 MCP 客户端通信 资料来源：[server.json:1-13]()。

### 核心特性

| 特性 | 描述 |
|------|------|
| MCP 协议兼容 | 符合 Model Context Protocol 规范 |
| 多浏览器支持 | Chromium、Firefox、WebKit |
| 工具化能力 | 将 Playwright API 暴露为 MCP 工具 |
| 可配置性 | 支持丰富的运行时配置选项 |
| 安全沙箱 | 支持浏览器隔离和来源限制 |

## 架构设计

### 系统架构

```mermaid
graph TD
    A[MCP 客户端] -->|stdio| B[Playwright MCP 服务器]
    B --> C[Playwright Core]
    C --> D[Chromium]
    C --> E[Firefox]
    C --> F[WebKit]
    B --> G[工具注册表]
    G --> H[Core 工具]
    G --> I[Navigation 工具]
    G --> J[Input 工具]
    G --> K[Network 工具]
    G --> L[Testing 工具]
    G --> M[Vision 工具]
```

### 源码位置

> [!WARNING]
> Playwright MCP 的核心代码已迁移至 [Playwright 主仓库](https://github.com/microsoft/playwright)。当前仓库主要用于打包和发布。

核心源码位于 `packages/playwright/src/mcp` 目录下 资料来源：[CONTRIBUTING.md:1-20]()。

### 模块导出

主入口文件通过 `playwright-core/lib/coreBundle` 导出 `createConnection` 函数：

```javascript
const { tools } = require('playwright-core/lib/coreBundle');
module.exports = { createConnection: tools.createConnection };
```

资料来源：[index.js:1-24]()

## 工具能力体系

Playwright MCP 将功能组织为多个能力（Capability）模块，每个模块提供一组相关的 MCP 工具。

### 能力类型定义

```typescript
export type ToolCapability =
  'config' |        // 配置管理
  'core' |          // 核心功能
  'core-navigation' | // 导航功能
  'core-tabs' |     // 标签页管理
  'core-input' |    // 输入操作
  'core-install' |  // 安装功能
  'network' |       // 网络请求
  'pdf' |           // PDF 生成
  'storage' |       // 存储管理
  'testing' |       // 测试功能
  'vision' |        // 视觉功能
  'devtools';       // 开发者工具
```

资料来源：[config.d.ts:1-20]()

### 工具注册机制

工具信息通过 `update-readme.js` 脚本从编译后的模块中提取，并自动生成 README 文档：

```javascript
async function updateTools(content) {
  console.log('Loading tool information from compiled modules...');
  // 按能力分组列出工具
  for (const [capability, tools] of Object.entries(toolsByCapability)) {
    generatedLines.push(`<details>\n<summary><b>${capability}</b></summary>`);
    // ...
  }
}
```

资料来源：[update-readme.js:1-80]()

## 配置选项

Playwright MCP 提供丰富的配置选项，通过 `Config` 类型定义。

### 基础配置结构

```typescript
export type Config = {
  browser?: {
    browserName?: 'chromium' | 'firefox' | 'webkit';
    isolated?: boolean;
    userDataDir?: string;
    // 浏览器启动选项
  };
  capabilities?: ToolCapability[];
  saveSession?: boolean;
  sharedBrowserContext?: boolean;
  secrets?: Record<string, string>;
  outputDir?: string;
  console?: {
    level?: 'error' | 'warning' | 'info' | 'debug';
  };
  network?: {
    allowedOrigins?: string[];
    blockedOrigins?: string[];
  };
  testIdAttribute?: string;
  timeouts?: {
    action?: number;
    navigation?: number;
    expect?: number;
  };
  imageResponses?: 'allow' | 'omit';
  snapshot?: { /* 快照配置 */ };
};
```

资料来源：[config.d.ts:20-100]()

### 浏览器配置

| 参数 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `browserName` | string | - | 浏览器类型：`chromium`、`firefox`、`webkit` |
| `isolated` | boolean | - | 是否在内存中保持浏览器配置文件 |
| `userDataDir` | string | 临时目录 | 浏览器配置文件保存路径 |

### 超时配置

| 参数 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `timeouts.action` | number | 5000ms | 默认操作超时 |
| `timeouts.navigation` | number | 60000ms | 默认导航超时 |
| `timeouts.expect` | number | 5000ms | 默认断言超时 |

### 网络安全配置

| 参数 | 类型 | 描述 |
|------|------|------|
| `network.allowedOrigins` | string[] | 允许浏览器请求的来源列表 |
| `network.blockedOrigins` | string[] | 阻止浏览器请求的来源列表 |

支持的来源格式：
- 完整来源：`https://example.com:8080`
- 通配符端口：`http://localhost:*`

资料来源：[config.d.ts:50-75]()

## CLI 命令行工具

### 入口脚本

`cli.js` 是 MCP 服务器的命令行入口，负责解析参数并启动服务：

```javascript
const { program } = require('playwright-core/lib/utilsBundle');
const { tools, libCli } = require('playwright-core/lib/coreBundle');

if (process.argv.includes('install-browser')) {
  const argv = process.argv.map(arg => arg === 'install-browser' ? 'install' : arg);
  libCli.decorateProgram(program);
  void program.parseAsync(argv);
  return;
}

const packageJSON = require('./package.json');
const p = program.version('Version ' + packageJSON.version).name('Playwright MCP');
tools.decorateMCPCommand(p, packageJSON.version);

void program.parseAsync(process.argv);
```

资料来源：[cli.js:1-35]()

### 可用命令

| 命令 | 描述 |
|------|------|
| `playwright-mcp install-browser` | 安装浏览器依赖 |
| `playwright-mcp --help` | 显示帮助信息 |
| `playwright-mcp --version` | 显示版本信息 |

### npm 脚本

| 脚本 | 描述 |
|------|------|
| `npm run lint` | 运行代码检查 |
| `npm test` | 运行完整测试套件 |
| `npm run ctest` | 仅运行 Chrome 测试 |
| `npm run ftest` | 仅运行 Firefox 测试 |
| `npm run wtest` | 仅运行 WebKit 测试 |
| `npm run roll` | 更新 Playwright 版本 |

资料来源：[package.json:1-40]()

## 开发与测试

### 环境搭建

由于核心代码已迁移至 Playwright 主仓库，开发需克隆主仓库：

```bash
git clone https://github.com/microsoft/playwright
cd playwright
npm ci
npm run watch
npx playwright install
```

资料来源：[CONTRIBUTING.md:20-35]()

### 测试执行

#### 快速测试（仅 Chromium）

```bash
npm run mcp-ctest
```

#### 完整测试（三浏览器）

```bash
npm run mcp-test
```

#### Docker 环境测试

```bash
npm run dtest  # MCP_IN_DOCKER=1 playwright test --project=chromium-docker
```

资料来源：[CONTRIBUTING.md:60-80]()

### 代码规范

代码风格由 `eslint.config.mjs` 定义，提交前应运行：

```bash
npm run flint
```

资料来源：[CONTRIBUTING.md:40-45]()

## 版本管理

### 当前版本

```json
{
  "name": "@playwright/mcp",
  "version": "0.0.75"
}
```

资料来源：[package.json:1-5]()

### 版本更新流程

1. 运行 `node roll.js` 更新 `playwright`、`playwright-core` 和 `@playwright/test` 依赖
2. 创建分支：`git checkout -b roll-pw-<version-suffix>`
3. 运行测试：`npm test`
4. 提交并推送 PR

分支命名规范：`roll-pw-<版本后缀>`

资料来源：[CLAUDE.md:15-25]()

## 提交规范

### 提交信息格式

```
label(namespace): 标题

描述（可选）

Footer（可选）
```

### 标签类型

| 标签 | 用途 |
|------|------|
| `fix` | 错误修复 |
| `feat` | 新功能 |
| `docs` | 文档更改 |
| `test` | 测试更改 |
| `devops` | CI 或构建更改 |
| `chore` | 其他更改 |

资料来源：[CONTRIBUTING.md:1-30]()

### 示例

```
fix(proxy): handle SOCKS proxy authentication

Fixes: https://github.com/microsoft/playwright/issues/39562
```

## 贡献指南

### 提交流程

1. **创建 Issue**：任何贡献都需要先创建对应的 Issue（文档修复除外）
2. **获取分配**：等待维护者分配任务
3. **开发实现**：遵循代码规范进行开发
4. **编写测试**：确保新功能有对应的测试
5. **提交 PR**：保持 PR 小而精炼，便于审查

### PR 要求

- 必须关联已创建并分配的 Issue
- 需要通过所有测试
- 代码风格需符合 ESLint 规则
- 提交信息遵循语义化规范

> [!WARNING]
> 未关联 Issue 或未获批准的 PR 将被关闭。

资料来源：[CONTRIBUTING.md:80-110]()

## 总结

Playwright MCP 为大语言模型代理提供了强大的浏览器自动化能力，通过 MCP 协议将 Playwright 的丰富功能工具化。其配置灵活、支持多种浏览器，并提供完整的安全控制机制。随着代码迁移至 Playwright 主仓库，该项目作为 npm 包发布渠道继续为社区提供支持。

---

<a id='page-comparison'></a>

## Playwright MCP vs Playwright CLI

### 相关页面

相关主题：[Playwright MCP 简介](#page-introduction)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)
- [CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)
- [CLAUDE.md](https://github.com/microsoft/playwright-mcp/blob/main/CLAUDE.md)
- [update-readme.js](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)
- [cli.js](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)
- [index.js](https://github.com/microsoft/playwright-mcp/blob/main/index.js)
- [config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)
- [server.json](https://github.com/microsoft/playwright-mcp/blob/main/server.json)
</details>

# Playwright MCP vs Playwright CLI

## 概述

Playwright MCP (Model Context Protocol) 和 Playwright CLI 是 Playwright 生态系统中的两个不同入口点，它们服务于不同的使用场景和集成模式。

**Playwright MCP** 是一个基于 Model Context Protocol 的服务器实现，允许 AI 模型通过标准化的 MCP 协议与 Playwright 浏览器自动化功能进行交互。它以 npm 包 `@playwright/mcp` 的形式发布，版本为 `0.0.75`，MCP 名称为 `io.github.microsoft/playwright-mcp` 资料来源：[package.json:1-20]()

**Playwright CLI** 是传统的命令行工具，通过终端命令直接调用 Playwright 的各项功能，如启动浏览器、安装浏览器、执行测试等。资料来源：[cli.js:1-35]()

> **重要说明**：Playwright MCP 的核心代码已迁移至 [Playwright 主仓库](https://github.com/microsoft/playwright)，位于 `packages/playwright/src/mcp` 目录。资料来源：[CONTRIBUTING.md:1-10]()

---

## 架构对比

### Playwright MCP 架构

```mermaid
graph TD
    A[AI Model] -->|MCP Protocol| B[Playwright MCP Server]
    B -->|Tool Calls| C[playwright-core<br/>lib/coreBundle]
    C --> D[Browser Automation]
    E[Configuration] --> B
    F[Capabilities] --> B
```

Playwright MCP 基于 MCP 协议工作，核心连接功能通过 `playwright-core/lib/coreBundle` 中的 `createConnection` 方法导出：

```javascript
const { tools } = require('playwright-core/lib/coreBundle');
module.exports = { createConnection: tools.createConnection };
```

资料来源：[index.js:15-20]()

### Playwright CLI 架构

```mermaid
graph TD
    A[Terminal/Command] -->|CLI Args| B[cli.js]
    B -->|Commands| C[playwright-core<br/>lib/utilsBundle]
    C -->|Program| D[libCli]
    D --> E[playwright-core<br/>lib/coreBundle]
    E --> F[Browser Automation]
```

CLI 入口整合了多个模块：

```javascript
const { program } = require('playwright-core/lib/utilsBundle');
const { tools, libCli } = require('playwright-core/lib/coreBundle');
```

资料来源：[cli.js:19-25]()

---

## 功能能力对比

| 能力维度 | Playwright MCP | Playwright CLI |
|---------|---------------|----------------|
| **集成目标** | AI 模型交互 | 开发者直接使用 |
| **通信协议** | MCP (STDIO) | 命令行参数 |
| **交互模式** | 请求-响应工具调用 | 批处理命令执行 |
| **状态管理** | 持久化会话支持 | 临时会话 |
| **配置方式** | config.d.ts 类型定义 | 命令行参数 |

---

## Playwright MCP 配置系统

Playwright MCP 通过 `config.d.ts` 提供完整的类型化配置：

```typescript
export type Config = {
  browser?: {
    browserName?: 'chromium' | 'firefox' | 'webkit';
    isolated?: boolean;
    userDataDir?: string;
    launchOptions?: any;
    initPage?: string[];
    initScript?: string[];
  },
  extension?: boolean;
  server?: {
    port?: number;
    host?: string;
    allowedHosts?: string[];
  },
  capabilities?: ToolCapability[];
  saveSession?: boolean;
  sharedBrowserContext?: boolean;
  secrets?: Record<string, string>;
  outputDir?: string;
  console?: { level?: 'error' | 'warning' | 'info' | 'debug' };
  network?: {
    allowedOrigins?: string[];
    blockedOrigins?: string[];
  };
};
```

资料来源：[config.d.ts:20-85]()

### 工具能力类型

```typescript
export type ToolCapability =
  'config' |
  'core' |
  'core-navigation' |
  'core-tabs' |
  'core-input' |
  'core-install' |
  'network' |
  'pdf' |
  'storage' |
  'testing' |
  'vision' |
  'devtools';
```

资料来源：[config.d.ts:16-27]()

---

## Playwright CLI 命令行接口

### cli.js 入口点

cli.js 是 MCP 服务器的主入口，支持两种工作模式：

```mermaid
graph TD
    A[cli.js] --> B{参数判断}
    B -->|包含 install-browser| C[libCli<br/>install 命令]
    B -->|其他情况| D[tools.decorateMCPCommand<br/>MCP 模式]
```

关键实现逻辑：

```javascript
if (process.argv.includes('install-browser')) {
  const argv = process.argv.map(arg => arg === 'install-browser' ? 'install' : arg);
  libCli.decorateProgram(program);
  void program.parseAsync(argv);
  return;
}

const packageJSON = require('./package.json');
const p = program.version('Version ' + packageJSON.version).name('Playwright MCP');
tools.decorateMCPCommand(p, packageJSON.version);
```

资料来源：[cli.js:22-35]()

### 可用命令

| 命令 | 功能 | 来源模块 |
|-----|------|---------|
| `install-browser` | 安装 Playwright 浏览器 | libCli |
| MCP Tools | 浏览器自动化工具集 | tools |
| `--help` | 显示帮助信息 | program |

---

## MCP 服务器配置

server.json 定义了 MCP 服务器的元数据：

```json
{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.github.microsoft/playwright-mcp",
  "description": "Playwright Tools for MCP",
  "version": "0.0.75",
  "packages": [{
    "registryType": "npm",
    "identifier": "@playwright/mcp",
    "version": "0.0.75",
    "transport": { "type": "stdio" }
  }]
}
```

资料来源：[server.json:1-20]()

---

## 自动化工具生成

`update-readme.js` 脚本负责从编译后的模块中提取工具信息并生成文档：

```mermaid
graph LR
    A[编译模块] --> B[update-readme.js]
    B --> C[工具信息提取]
    C --> D[formatToolForReadme]
    D --> E[README.md<br/>自动更新]
```

工具格式化函数提取每个工具的：

- **名称** (name)
- **标题** (title)
- **描述** (description)
- **参数** (parameters)
- **是否只读** (read-only)

资料来源：[update-readme.js:1-150]()

---

## 包结构与导出

### 入口点配置

package.json 定义了导出结构：

```json
{
  "exports": {
    "./package.json": "./package.json",
    ".": { "types": "./index.d.ts" }
  },
  "mcpName": "io.github.microsoft/playwright-mcp"
}
```

资料来源：[package.json:25-32]()

### 版本与依赖

| 项目 | 值 |
|-----|---|
| 包名 | @playwright/mcp |
| 版本 | 0.0.75 |
| Node 要求 | >=18 |
| 许可证 | Apache-2.0 |
| 作者 | Microsoft Corporation |

---

## 发布与维护流程

### 更新 Playwright 版本

根据 CLAUDE.md，维护者需要运行 `roll.js` 脚本：

1. 执行 `npm run roll` 更新 Playwright 版本
2. 从主仓库复制 `config.d.ts`
3. 刷新 README 文档
4. 提交更新并创建 PR

```javascript
function doRoll(version) {
  updatePlaywrightVersion(version);
  copyConfig();
  execSync('npm run lint', { cwd: __dirname, stdio: 'inherit' });
}
```

资料来源：[roll.js:1-50]()

### 测试配置

项目使用 Playwright 自身进行测试：

```typescript
export default defineConfig<TestOptions>({
  testDir: './tests',
  fullyParallel: true,
  reporter: 'list',
  projects: [
    { name: 'chrome' },
    // Docker 测试配置
  ],
});
```

资料来源：[playwright.config.ts:1-30]()

---

## 使用场景选择

```mermaid
graph TD
    A[开始] --> B{使用场景}
    B -->|AI 模型集成| C[Playwright MCP]
    B -->|开发者自动化| D[Playwright CLI]
    B -->|脚本批处理| E[Playwright CLI]
    B -->|测试执行| F[Playwright CLI / Test]
```

### 选择 Playwright MCP 的场景

- AI 代理需要浏览器自动化能力
- 通过标准化协议集成多个工具
- 需要 MCP 生态系统兼容性

### 选择 Playwright CLI 的场景

- 终端直接操作浏览器
- CI/CD 管道集成
- 快速调试和原型开发
- 安装和管理浏览器

---

## 总结

| 特性 | Playwright MCP | Playwright CLI |
|-----|----------------|----------------|
| **设计目标** | AI 代理集成 | 开发者工具 |
| **协议** | Model Context Protocol | 命令行参数 |
| **传输** | STDIO | 标准输入/输出 |
| **状态** | 持久化、可共享 | 临时会话 |
| **配置复杂度** | 高（完整类型系统） | 低（命令行参数） |
| **适用人群** | AI 开发者、系统集成商 | 开发者、测试工程师 |

两者本质上是同一底层能力的不同封装形式，Playwright MCP 建立在 Playwright CLI 的基础之上，通过 MCP 协议提供更高级别的抽象，使 AI 模型能够以结构化的方式调用浏览器自动化功能。

---

<a id='page-quickstart'></a>

## 快速入门

### 相关页面

相关主题：[客户端集成指南](#page-client-integration), [部署选项](#page-deployment)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/microsoft/playwright-mcp/blob/main/README.md)
- [package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)
- [config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)
- [cli.js](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)
- [index.js](https://github.com/microsoft/playwright-mcp/blob/main/index.js)
- [CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)
</details>

# 快速入门

## 概述

Playwright MCP（Model Context Protocol）是由微软开发的Playwright工具集，通过MCP协议为大型语言模型提供浏览器自动化能力。该项目允许AI代理通过标准化的工具接口执行网页导航、元素交互、截图捕获等浏览器操作。资料来源：[README.md](https://github.com/microsoft/playwright-mcp/blob/main/README.md)

> [!IMPORTANT]
> Playwright MCP的核心代码已迁移至 [Playwright 主仓库](https://github.com/microsoft/playwright)，源代码位于 `packages/playwright/src/mcp` 目录。资料来源：[CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)

## 环境要求

| 要求项 | 最低版本 | 说明 |
|--------|----------|------|
| Node.js | >= 18 | 运行时环境 |
| npm | 最新稳定版 | 包管理器 |
| 浏览器 | Chromium/Firefox/WebKit | 测试浏览器（按需安装） |

## 安装步骤

### 1. 克隆仓库

由于核心代码已迁移至Playwright主仓库，推荐从主仓库克隆：

```bash
git clone https://github.com/microsoft/playwright
cd playwright
```

资料来源：[CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)

### 2. 安装依赖并构建

```bash
# 安装项目依赖
npm ci

# 以监视模式运行构建
npm run watch

# 安装浏览器（根据需要选择）
npx playwright install
```

### 3. 验证安装

运行快速测试验证安装是否成功：

```bash
# 仅在Chromium中运行MCP测试（快速路径）
npm run mcp-ctest

# 在三个浏览器中运行完整测试（慢速路径）
npm run mcp-test
```

## 项目结构

```
playwright/
├── packages/
│   └── playwright/
│       └── src/
│           └── mcp/          # MCP核心源代码
├── tests/
│   └── mcp/                  # MCP测试套件
├── config.d.ts               # 配置类型定义
├── playwright.config.ts     # 测试配置
└── package.json             # 项目配置
```

## 可用工具分类

Playwright MCP提供以下能力类别：

| 能力类别 | 说明 |
|----------|------|
| `config` | 配置管理 |
| `core` | 核心浏览器操作 |
| `core-navigation` | 页面导航 |
| `core-tabs` | 标签页管理 |
| `core-input` | 输入操作 |
| `core-install` | 浏览器安装 |
| `network` | 网络请求监控 |
| `pdf` | PDF生成 |
| `storage` | 存储管理 |
| `testing` | 测试相关功能 |
| `vision` | 视觉相关（截图、可视化） |
| `devtools` | 开发者工具 |

资料来源：[config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)

## 配置选项

### 浏览器配置

```typescript
{
  browser: {
    browserName?: 'chromium' | 'firefox' | 'webkit';
    isolated?: boolean;        // 是否保持浏览器配置在内存中
    userDataDir?: string;      // 用户数据目录路径
  };
}
```

### 超时配置

```typescript
{
  timeouts: {
    action?: number;      // 默认操作超时，默认5000ms
    navigation?: number;  // 默认导航超时，默认60000ms
    expect?: number;      // 默认expect超时，默认5000ms
  };
}
```

### 网络配置

```typescript
{
  network: {
    allowedOrigins?: string[];   // 允许的请求来源
    blockedOrigins?: string[];   // 阻止的请求来源
  };
}
```

资料来源：[config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)

## 命令行工具

项目提供以下npm脚本命令：

| 命令 | 说明 |
|------|------|
| `npm run mcp-ctest` | 在Chromium中运行所有MCP测试 |
| `npm run mcp-test` | 在三个浏览器中运行所有MCP测试 |
| `npm run lint` | 运行代码检查和更新README |
| `npm run watch` | 监视模式构建 |
| `npm run flint` | 运行完整代码检查 |

资料来源：[package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)

### 直接使用CLI

```bash
# 启动MCP服务器
node index.js

# 安装浏览器
node cli.js install-browser

# 获取帮助
node cli.js --help
```

资料来源：[cli.js](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)，[index.js](https://github.com/microsoft/playwright-mcp/blob/main/index.js)

## 测试运行流程

```mermaid
graph TD
    A[开始测试] --> B{环境变量CI}
    B -->|是| C[设置2个workers]
    B -->|否| D[使用全部CPU核心]
    C --> E[运行playwright test]
    D --> E
    E --> F{测试结果}
    F -->|通过| G[测试完成]
    F -->|失败| H[报告错误]
```

## 开发工作流

### 提交规范

项目使用语义化提交信息格式：

```
label(namespace): 标题

描述

footer
```

可用标签：

| 标签 | 用途 |
|------|------|
| `fix` | 错误修复 |
| `feat` | 新功能 |
| `docs` | 文档更改 |
| `test` | 测试相关 |
| `devops` | CI或构建相关 |
| `chore` | 其他杂项 |

资料来源：[CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)

### 分支命名

- 错误修复：`fix-<issue-number>`
- Playwright版本滚动：`roll-pw-<version-suffix>`

### 代码规范

- 代码风格定义在 `eslint.config.mjs`
- 提交前运行代码检查：`npm run flint`
- 注释应有明确目的，避免冗余
- 代码应尽可能自解释

资料来源：[CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)

## 常见问题

### Q: 测试无法通过怎么办？

1. 确保所有依赖已正确安装：`npm ci`
2. 确保浏览器已安装：`npx playwright install`
3. 清除缓存后重试

### Q: 如何仅测试特定浏览器？

```bash
# 仅Chrome
npm run ctest

# 仅Firefox
npm run ftest

# 仅WebKit
npm run wtest
```

### Q: 如何在Docker中运行测试？

```bash
MCP_IN_DOCKER=1 npm run dtest
```

## 下一步

- 阅读完整 [README.md](https://github.com/microsoft/playwright-mcp/blob/main/README.md) 了解所有可用工具
- 查看 [tests/mcp](https://github.com/microsoft/playwright/blob/main/tests/mcp) 目录中的测试示例
- 参考 [Playwright 官方文档](https://playwright.dev/docs/api/class-page) 了解底层API

---

<a id='page-client-integration'></a>

## 客户端集成指南

### 相关页面

相关主题：[快速入门](#page-quickstart), [部署选项](#page-deployment)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)
- [update-readme.js](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)
- [config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)
- [package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)
- [cli.js](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)
- [server.json](https://github.com/microsoft/playwright-mcp/blob/main/server.json)
- [CLAUDE.md](https://github.com/microsoft/playwright-mcp/blob/main/CLAUDE.md)
- [playwright.config.ts](https://github.com/microsoft/playwright-mcp/blob/main/playwright.config.ts)
</details>

# 客户端集成指南

## 概述

Playwright MCP (Model Context Protocol) 是微软提供的 Playwright 浏览器自动化工具的 MCP（Model Context Protocol）实现。它允许 AI 模型通过标准化协议与浏览器进行交互，执行网页自动化、测试和内容抓取等任务。

核心代码已迁移至 [Playwright 主仓库](https://github.com/microsoft/playwright)，位于 `packages/playwright/src/mcp` 目录。资料来源：[CONTRIBUTING.md:43]()

## 架构概览

```mermaid
graph TD
    A[AI Client / MCP Host] -->|MCP Protocol| B[Playwright MCP Server]
    B -->|STDIO Transport| C[Browser Automation]
    C -->|Playwright API| D[Chromium / Firefox / WebKit]
    B --> E[Local Browser]
    B --> F[Docker Container]
    
    G[Config File / CLI Args] --> B
    H[Environment Variables] --> B
```

服务器通过 STDIO 传输协议与 MCP Host 进行通信，支持本地浏览器启动和 Docker 容器模式。资料来源：[server.json:12]()

## 安装与依赖

### 系统要求

- **Node.js**: 需要版本 >= 18
- **浏览器**: 支持 Chromium、Firefox、WebKit

### 安装步骤

```bash
npm install @playwright/mcp
```

或从源码构建：

```bash
git clone https://github.com/microsoft/playwright
cd playwright
npm ci
npm run watch
npx playwright install
```

资料来源：[CONTRIBUTING.md:51-60]()

### Docker 部署

```bash
# 构建镜像
npm run docker-build

# 运行容器
npm run docker-run
```

资料来源：[package.json:25-27]()

## 配置选项

Playwright MCP 支持丰富的配置选项，定义在 `config.d.ts` 中。

### 配置类型定义

```typescript
export type Config = {
  browser?: {
    browserName?: 'chromium' | 'firefox' | 'webkit';
    isolated?: boolean;
    userDataDir?: string;
    // 浏览器启动选项
  };
  allowedOrigins?: string[];      // 允许的请求来源
  blockedOrigins?: string[];      // 阻止的请求来源
  testIdAttribute?: string;       // 测试 ID 属性，默认 "data-testid"
  timeouts?: {
    action?: number;              // 操作超时，默认 5000ms
    navigation?: number;         // 导航超时，默认 60000ms
    expect?: number;              // 断言超时，默认 5000ms
  };
  imageResponses?: 'allow' | 'omit' | 'auto';
};
```

资料来源：[config.d.ts:31-85]()

### 工具能力列表

| 能力分类 | 标识符 | 说明 | 启用方式 |
|---------|--------|------|---------|
| 核心能力 | `core` | 基础浏览器操作 | 默认启用 |
| 导航能力 | `core-navigation` | 页面导航相关 | 默认启用 |
| 标签页能力 | `core-tabs` | 多标签页管理 | 默认启用 |
| 输入能力 | `core-input` | 表单输入操作 | 默认启用 |
| 安装能力 | `core-install` | 浏览器安装 | 默认启用 |
| 网络能力 | `network` | 网络请求拦截 | `--caps=network` |
| PDF 能力 | `pdf` | PDF 生成 | `--caps=pdf` |
| 存储能力 | `storage` | 本地存储管理 | `--caps=storage` |
| 测试能力 | `testing` | 测试断言 | `--caps=testing` |
| 视觉能力 | `vision` | 视觉对比 | `--caps=vision` |
| 开发者工具 | `devtools` | DevTools 协议 | `--caps=devtools` |

资料来源：[config.d.ts:12-25]()

### 来源过滤配置

#### 允许来源 (allowedOrigins)

```typescript
allowedOrigins?: string[];
```

支持的格式：

| 格式 | 示例 | 匹配范围 |
|------|------|---------|
| 完整来源 | `https://example.com:8080` | 仅该来源 |
| 通配符协议 | `*://example.com` | http 和 https |
| 通配符子域 | `https://*.example.com` | 所有子域 |
| 通配符端口 | `http://localhost:*` | localhost 所有端口 |

资料来源：[config.d.ts:38-45]()

#### 阻止来源 (blockedOrigins)

```typescript
blockedOrigins?: string[];
```

同时匹配 `allowedOrigins` 和 `blockedOrigins` 的来源将被阻止。

## 命令行接口

### CLI 入口点

服务器通过 `cli.js` 启动，使用 `playwright-core` 的命令行框架：

```bash
node cli.js [options]
```

资料来源：[cli.js:1-32]()

### 可用命令

| 命令 | 说明 |
|------|------|
| `node cli.js --help` | 显示帮助信息 |
| `node cli.js --version` | 显示版本信息 |
| `node cli.js install-browser` | 安装浏览器 |

### 主要选项

| 选项 | 说明 | 环境变量 |
|------|------|---------|
| `--caps` | 启用的能力列表 | `PLAYWRIGHT_MCP_CAPS` |
| `--secrets` | 密钥文件路径 | `PLAYWRIGHT_MCP_SECRETS_FILE` |
| `--browser` | 指定浏览器类型 | `PLAYWRIGHT_MCP_BROWSER` |
| `--headless` | 无头模式运行 | `PLAYWRIGHT_MCP_HEADLESS` |

环境变量格式为 `PLAYWRIGHT_MCP_` 前缀加上选项名称的大写形式，中划线替换为下划线。

资料来源：[update-readme.js:1-60]()

### 特殊命令

#### install-browser

```bash
node cli.js install-browser
```

该命令实际上是 `playwright install` 的别名，用于安装必要的浏览器二进制文件。

## 工具能力详解

### 核心能力 (core)

默认启用的核心工具集，提供基础的浏览器操作能力：

| 工具 | 说明 | 只读 |
|------|------|------|
| 导航工具 | 页面跳转、前进后退 | ✓ |
| 点击工具 | 元素点击交互 | ✗ |
| 填充工具 | 表单填充 | ✗ |
| 截图工具 | 页面截图 | ✓ |

### 网络能力 (network)

通过 `--caps=network` 启用，提供网络请求拦截和管理功能：

```mermaid
graph LR
    A[Browser Request] --> B{MCP Network Filter}
    B -->|Allowed| C[Network]
    B -->|Blocked| D[Blocked Response]
```

### 测试能力 (testing)

通过 `--caps=testing` 启用，提供测试断言功能：

- `expect`: 断言验证
- `toHaveTitle`: 标题验证
- `toContainText`: 文本内容验证
- `toBeVisible`: 元素可见性验证

资料来源：[update-readme.js:70-100]()

## 环境变量

| 环境变量 | 对应选项 | 说明 |
|----------|---------|------|
| `PLAYWRIGHT_MCP_CAPS` | `--caps` | 启用的能力列表 |
| `PLAYWRIGHT_MCP_SECRETS_FILE` | `--secrets` | 密钥文件路径 |
| `PLAYWRIGHT_MCP_BROWSER` | `--browser` | 默认浏览器类型 |
| `MCP_IN_DOCKER` | - | Docker 模式标志 |

## 测试指南

### 运行测试

```bash
# 快速测试（仅 Chromium）
npm run ctest

# 完整测试（三浏览器）
npm run test

# Firefox 专项测试
npm run ftest

# WebKit 专项测试
npm run wtest

# Docker 模式测试
npm run dtest
```

资料来源：[package.json:20-24]()

### 测试配置

测试配置文件位于 `playwright.config.ts`：

```typescript
export default defineConfig<TestOptions>({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  workers: process.env.CI ? 2 : undefined,
  reporter: 'list',
  projects: [
    { name: 'chrome' },
  ],
});
```

测试文件位于 `tests/mcp` 目录。资料来源：[playwright.config.ts:1-30]()

### 测试要求

- 测试必须是**自包含的**，不依赖外部服务
- 测试必须在三个平台都能运行：macOS、Linux、Windows
- 新功能必须包含对应的测试用例
- 纯重构可以例外

资料来源：[CONTRIBUTING.md:90-95]()

## 集成示例

### 基本集成配置

```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"],
      "env": {
        "PLAYWRIGHT_MCP_CAPS": "core,network",
        "PLAYWRIGHT_MCP_BROWSER": "chromium"
      }
    }
  }
}
```

### 使用 Docker 模式

```bash
npm run docker-build
npm run docker-run
```

Docker 模式会启动隔离的容器环境运行浏览器。

## 版本管理

### 版本信息

当前版本：`0.0.75`

资料来源：[package.json:3]()

### 滚动更新

使用 `roll.js` 脚本更新 Playwright 版本：

```bash
npm run roll
```

该脚本会：
1. 更新 `package.json` 中的 Playwright 依赖版本
2. 从 Playwright 主仓库复制 `config.d.ts`
3. 重新生成 README 文档

更新后需要创建分支并提交 PR：

```bash
git checkout -b roll-pw-<version-suffix>
npm test
git commit -m "chore: roll Playwright to <version>"
```

资料来源：[CLAUDE.md:14-23]()

## 贡献指南

### 提交流流程

```mermaid
graph TD
    A[创建 Issue] --> B{是否需要新功能?}
    B -->|是| C[描述问题并申请处理]
    B -->|否| D[找到已有 Issue]
    C --> E{是否分配给你?}
    D --> E
    E -->|否| F[等待分配]
    E -->|是| G[创建分支 fix-<issue-number>]
    G --> H[开发并添加测试]
    H --> I[提交 PR]
    I --> J[代码审查]
    J -->|通过| K[合并]
    J -->|拒绝| L[修改后重新提交]
```

### 提交规范

提交信息必须遵循 Semantic Commit Messages 格式：

```
<label>(<namespace>): <title>

<description>

<footer>
```

标签类型：
- `fix`: Bug 修复
- `feat`: 新功能
- `docs`: 文档更改
- `test`: 测试更改
- `devops`: CI/构建更改
- `chore`: 其他更改

### PR 要求

- PR 必须关联一个 Issue 或经过批准
- PR 必须通过所有测试
- 代码必须通过 lint 检查：`npm run lint`
- PR 内容应保持小而可读

资料来源：[CONTRIBUTING.md:1-40]()

## 常见问题

### 浏览器无法启动

确保已安装浏览器：
```bash
npx playwright install
```

### 测试超时

调整配置中的超时设置：
```typescript
timeouts: {
  action: 10000,      // 增加操作超时
  navigation: 120000 // 增加导航超时
}
```

### 网络请求被阻止

检查 `allowedOrigins` 和 `blockedOrigins` 配置，确保目标域名在允许列表中。

---

<a id='page-core-architecture'></a>

## 核心架构

### 相关页面

相关主题：[MCP 工具与能力](#page-tools-capabilities), [浏览器配置文件管理](#page-browser-profiles)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [index.js](https://github.com/microsoft/playwright-mcp/blob/main/index.js)
- [cli.js](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)
- [config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)
- [package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)
- [roll.js](https://github.com/microsoft/playwright-mcp/blob/main/roll.js)
- [update-readme.js](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)
</details>

# 核心架构

## 概述

playwright-mcp 是 Microsoft Playwright 的 MCP（Model Context Protocol）实现，为大语言模型提供浏览器自动化能力。该项目作为 Playwright 与 MCP 协议之间的桥梁，使 AI Agent 能够通过标准化的 MCP 接口控制浏览器执行自动化任务。

核心架构采用模块化设计，核心功能依赖于 playwright-core 库，并通过 CLI 和 API 两种方式暴露能力。

## 系统架构图

```mermaid
graph TD
    subgraph 客户端层
        MCP_Client[MCP 客户端]
    end
    
    subgraph 核心模块
        Connection[createConnection]
        Tools[工具集合]
        CLI[CLI 入口]
    end
    
    subgraph Playwright 核心
        CoreBundle[coreBundle]
        Browser[浏览器自动化]
        Page[页面控制]
    end
    
    subgraph 配置系统
        Config[Config 类型定义]
        EnvVars[环境变量映射]
    end
    
    MCP_Client --> Connection
    Connection --> Tools
    Connection --> CoreBundle
    Tools --> Browser
    CoreBundle --> Browser
    CLI --> CoreBundle
    Config --> Connection
```

## 入口点设计

### API 入口：index.js

主入口文件负责导出 MCP 连接工厂函数，供外部系统集成使用。

资料来源：[index.js:25-27]()

```javascript
const { tools } = require('playwright-core/lib/coreBundle');
module.exports = { createConnection: tools.createConnection };
```

**设计特点**：
- 极简导出设计，仅暴露 `createConnection` 函数
- 底层实现委托给 playwright-core 的 coreBundle
- 支持 Node.js 和 ES Module 环境

### CLI 入口：cli.js

命令行入口点，支持多种操作模式。

资料来源：[cli.js:1-34]()

```javascript
const { program } = require('playwright-core/lib/utilsBundle');
const { tools, libCli } = require('playwright-core/lib/coreBundle');

if (process.argv.includes('install-browser')) {
  const argv = process.argv.map(arg => arg === 'install-browser' ? 'install' : arg);
  libCli.decorateProgram(program);
  void program.parseAsync(argv);
  return;
}

const packageJSON = require('./package.json');
const p = program.version('Version ' + packageJSON.version).name('Playwright MCP');
tools.decorateMCPCommand(p, packageJSON.version);
```

**CLI 功能**：
| 命令 | 说明 | 资料来源 |
|------|------|----------|
| `playwright-mcp install-browser` | 安装浏览器驱动 | cli.js:13 |
| MCP 工具命令 | 通过 playwright-core 提供 | cli.js:28 |

## 工具能力体系

### 能力分类

工具按照功能被组织为多个能力类别（ToolCapability）。

资料来源：[config.d.ts:6-20]()

```typescript
export type ToolCapability =
  'config' |
  'core' |
  'core-navigation' |
  'core-tabs' |
  'core-input' |
  'core-install' |
  'network' |
  'pdf' |
  'storage' |
  'testing' |
  'vision' |
  'devtools';
```

### 能力详情表

| 能力标识 | 功能描述 |
|----------|----------|
| config | 配置管理 |
| core | 核心浏览器自动化 |
| core-navigation | 页面导航控制 |
| core-tabs | 多标签页管理 |
| core-input | 输入交互处理 |
| core-install | 浏览器安装 |
| network | 网络请求拦截 |
| pdf | PDF 生成操作 |
| storage | 存储状态管理 |
| testing | 测试相关功能 |
| vision | 视觉坐标交互 |
| devtools | 开发者工具 |

## 配置系统

### 配置类型定义

配置系统采用 TypeScript 类型定义，提供完整的类型安全配置。

资料来源：[config.d.ts:23-150]()

**核心配置结构**：

```typescript
export type Config = {
  browser?: {
    browserName?: 'chromium' | 'firefox' | 'webkit';
    isolated?: boolean;
    userDataDir?: string;
    launchOptions?: Record<string, any>;
    initPage?: string[];
    initScript?: string[];
  },
  extension?: boolean;
  server?: {
    port?: number;
    host?: string;
    allowedHosts?: string[];
  },
  capabilities?: ToolCapability[];
  saveSession?: boolean;
  sharedBrowserContext?: boolean;
  secrets?: Record<string, string>;
  origins?: {
    allowedOrigins?: string[];
    blockedOrigins?: string[];
  };
  testIdAttribute?: string;
  timeouts?: {
    action?: number;
    navigation?: number;
    expect?: number;
  };
  imageResponses?: 'allow' | 'omit' | 'auto';
  snapshot?: /* ... */;
}
```

### 配置项分类表

| 分类 | 配置项 | 默认值 | 说明 |
|------|--------|--------|------|
| **浏览器** | browserName | - | 浏览器类型：chromium/firefox/webkit |
| | isolated | false | 是否保持浏览器隔离 |
| | userDataDir | 临时目录 | 用户数据目录路径 |
| **服务器** | port | - | SSE/MCP 传输监听端口 |
| | host | localhost | 服务器绑定地址 |
| | allowedHosts | 同 host | 允许服务的主机列表 |
| **功能开关** | capabilities | - | 启用的工具能力列表 |
| | saveSession | false | 是否保存 Playwright 会话 |
| | sharedBrowserContext | false | 跨客户端共享浏览器上下文 |
| **超时配置** | timeouts.action | 5000ms | 默认动作超时 |
| | timeouts.navigation | 60000ms | 默认导航超时 |
| | timeouts.expect | 5000ms | 默认断言超时 |
| **安全** | secrets | - | 密钥配置映射 |
| | origins.allowedOrigins | - | 允许的请求来源 |
| | origins.blockedOrigins | - | 阻止的请求来源 |

### 环境变量映射

CLI 选项自动映射为环境变量，提供灵活的部署配置。

资料来源：[update-readme.js:66-85]()

| CLI 选项 | 环境变量 | 说明 |
|----------|----------|------|
| --secrets | PLAYWRIGHT_MCP_SECRETS_FILE | 密钥文件路径 |
| --port | PLAYWRIGHT_MCP_PORT | 服务端口 |
| --host | PLAYWRIGHT_MCP_HOST | 服务主机 |
| 其他选项 | PLAYWRIGHT_MCP_<选项大写> | 标准前缀映射 |

## 模块依赖关系

```mermaid
graph LR
    subgraph 依赖层
        playwright-core
        playwright
        @playwright/test
    end
    
    subgraph 本项目
        index.js
        cli.js
        config.d.ts
    end
    
    playwright --> playwright-core
    @playwright/test --> playwright-core
    
    index.js --> playwright-core
    cli.js --> playwright-core
```

资料来源：[package.json:17-40]()

```json
{
  "name": "@playwright/mcp",
  "version": "0.0.75",
  "mcpName": "io.github.microsoft/playwright-mcp",
  "scripts": {
    "build": "echo OK",
    "test": "playwright test"
  },
  "dependencies": {
    "playwright-core": "..."
  },
  "devDependencies": {
    "@playwright/test": "...",
    "playwright": "..."
  }
}
```

## 构建与发布流程

### 版本管理机制

项目使用 roll.js 脚本同步 Playwright 依赖版本。

资料来源：[roll.js:1-35]()

```javascript
function copyConfig() {
  const src = path.join(__dirname, '..', 'playwright', 'packages', 'playwright-core', 'src', 'tools', 'mcp', 'config.d.ts');
  const dst = path.join(__dirname, 'config.d.ts');
  // 复制并替换导入路径
  content = content.replace(
    "import type * as playwright from 'playwright-core';",
    "import type * as playwright from 'playwright';"
  );
}

function updatePlaywrightVersion(version) {
  // 更新 package.json 中的依赖版本
}

function doRoll(version) {
  updatePlaywrightVersion(version);
  copyConfig();
  execSync('npm run lint', { cwd: __dirname });
}
```

### 版本更新流程

```mermaid
flowchart TD
    A[运行 npm run roll] --> B[updatePlaywrightVersion]
    B --> C[copyConfig 同步 config.d.ts]
    C --> D[npm install 安装依赖]
    D --> E[npm run lint 更新 README]
    E --> F[生成新版本提交]
```

### npm Scripts 说明

| 脚本 | 命令 | 用途 |
|------|------|------|
| build | `echo OK` | 构建检查（无编译步骤） |
| lint | `node update-readme.js` | 更新自动生成的 README |
| test | `playwright test` | 运行完整测试套件 |
| ctest | `playwright test --project=chrome` | 仅 Chrome 测试 |
| ftest | `playwright test --project=firefox` | 仅 Firefox 测试 |
| wtest | `playwright test --project=webkit` | 仅 WebKit 测试 |
| roll | `node roll.js` | 同步 Playwright 版本 |

## MCP 工具注册机制

### 工具装饰器模式

工具通过 playwright-core 提供的装饰器注册到 MCP 命令系统。

资料来源：[cli.js:28]()

```javascript
tools.decorateMCPCommand(p, packageJSON.version);
```

### README 自动生成

update-readme.js 脚本从编译后的模块自动提取工具信息并生成文档。

资料来源：[update-readme.js:130-150]()

```javascript
async function updateTools(content) {
  const generatedLines = [];
  for (const [capability, tools] of Object.entries(toolsByCapability)) {
    generatedLines.push(`<details>`);
    generatedLines.push(`<summary><b>${capability}</b></summary>`);
    for (const tool of tools)
      generatedLines.push(...formatToolForReadme(tool.schema));
    generatedLines.push(`</details>`);
  }
  // 使用标记替换机制更新 README
}
```

## 测试架构

### 测试配置

项目使用 @playwright/test 定义测试配置。

资料来源：[playwright.config.ts:1-40]()

```typescript
export default defineConfig<TestOptions>({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  workers: process.env.CI ? 2 : undefined,
  reporter: 'list',
  projects: [
    { name: 'chrome' },
    ...process.env.MCP_IN_DOCKER ? [{
      name: 'chromium-docker',
      grep: /browser_navigate|browser_click/,
      use: {
        mcpBrowser: 'chromium',
        mcpMode: 'docker' as const
      }
    }] : [],
  ],
});
```

### 测试项目矩阵

| 项目名称 | 浏览器 | 环境 | 说明 |
|----------|--------|------|------|
| chrome | Chromium | 标准 | 主要测试环境 |
| chromium-docker | Chromium | Docker | Docker 环境测试 |

## 数据流向

```mermaid
sequenceDiagram
    participant MCP as MCP 客户端
    participant Server as MCP 服务器
    participant Tools as 工具层
    participant PW as Playwright Core
    participant Browser as 浏览器实例
    
    MCP->>Server: MCP 请求
    Server->>Tools: 调用工具
    Tools->>PW: Playwright API
    PW->>Browser: 浏览器控制
    Browser-->>PW: 执行结果
    PW-->>Tools: 返回结果
    Tools-->>Server: 格式化响应
    Server-->>MCP: MCP 响应
```

## 安全机制

### 来源控制

支持细粒度的请求来源控制。

资料来源：[config.d.ts:88-100]()

```typescript
origins?: {
  /**
   * 允许浏览器请求的来源列表
   * 支持格式：
   * - 完整来源: `https://example.com:8080`
   * - 通配符端口: `http://localhost:*`
   */
  allowedOrigins?: string[];

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

### 密钥管理

通过 secrets 配置支持敏感信息的安全传递。

| 配置项 | 说明 |
|--------|------|
| secrets | 密钥名称到值的映射，用于环境变量注入 |

## 与 Playwright 主仓库的关系

根据 CLAUDE.md 和 CONTRIBUTING.md 的说明：

> [!WARNING]
> The core of the Playwright MCP was moved to the [Playwright monorepo](https://github.com/microsoft/playwright).

当前仓库作为 Playwright 主仓库的 MCP 能力抽象层：

| 职责 | 仓库位置 |
|------|----------|
| 核心实现 | [packages/playwright/src/mcp](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/mcp) |
| 测试代码 | [tests/mcp](https://github.com/microsoft/playwright/blob/main/tests/mcp) |
| 本仓库 | 独立打包和分发 |

## 总结

playwright-mcp 的核心架构具有以下特点：

1. **极简入口设计**：仅通过 `createConnection` 暴露核心功能
2. **委托实现模式**：核心逻辑委托给 playwright-core
3. **类型安全配置**：完整的 TypeScript 类型定义
4. **自动化文档**：从源码自动生成 README
5. **版本同步机制**：与 Playwright 主仓库保持同步
6. **灵活部署**：支持环境变量、CLI 参数和编程式配置

---

<a id='page-tools-capabilities'></a>

## MCP 工具与能力

### 相关页面

相关主题：[核心架构](#page-core-architecture), [初始状态配置](#page-initial-state)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/microsoft/playwright-mcp/blob/main/README.md)
- [config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)
- [package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)
- [cli.js](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)
- [index.js](https://github.com/microsoft/playwright-mcp/blob/main/index.js)
</details>

# MCP 工具与能力

## 概述

Playwright MCP (Model Context Protocol) 是微软官方提供的 Playwright 工具集，为大语言模型 (LLM) 提供浏览器自动化能力。该项目通过 MCP 协议暴露一系列可调用的工具，使 AI Agent 能够执行网页导航、元素交互、网络监控、PDF 操作等浏览器自动化任务。

根据 `config.d.ts` 中的定义，MCP 工具被组织为多个**能力域 (Capability)**，每个能力域包含一组相关的工具函数。资料来源：[config.d.ts:20-33]()

## 架构概览

Playwright MCP 的源代码已迁移至 [Playwright 主仓库](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/mcp)，当前的 `playwright-mcp` 仓库作为依赖包装和分发层存在。资料来源：[CONTRIBUTING.md:1-10]()

```mermaid
graph TD
    A[LLM / AI Agent] -->|MCP Protocol| B[Playwright MCP Server]
    B -->|工具调用| C[playwright-core]
    C --> D[Browser Automation]
    
    E[CLI / Config] -->|配置| B
    F[config.d.ts] -->|类型定义| E
```

## 能力域 (Tool Capabilities)

Playwright MCP 将工具划分为以下能力域，每个能力域对应不同的功能模块：

| 能力域 | 说明 | 典型工具示例 |
|--------|------|-------------|
| `config` | 配置管理 | 服务端配置读取 |
| `core` | 核心浏览器操作 | 导航、元素操作 |
| `core-navigation` | 页面导航 | 打开 URL、前进/后退 |
| `core-tabs` | 多标签页管理 | 创建/关闭标签页、切换 |
| `core-input` | 输入处理 | 填写表单、键盘输入 |
| `core-install` | 浏览器安装 | 安装浏览器驱动 |
| `network` | 网络监控 | 请求拦截、响应捕获 |
| `pdf` | PDF 生成 | 页面导出为 PDF |
| `storage` | 存储管理 | Cookie、LocalStorage |
| `testing` | 测试断言 | 元素存在性验证 |
| `vision` | 视觉交互 | 坐标点击、截图 |
| `devtools` | 开发者工具 | Chrome DevTools 协议 |

资料来源：[config.d.ts:20-33]()

## 配置选项详解

### 基本配置结构

```typescript
type Config = {
  browser?: BrowserConfig;
  capabilities?: ToolCapability[];
  saveSession?: boolean;
  sharedBrowserContext?: boolean;
  secrets?: Record<string, string>;
  outputDir?: string;
  console?: ConsoleConfig;
  network?: NetworkConfig;
  testIdAttribute?: string;
  timeouts?: TimeoutsConfig;
  imageResponses?: 'allow' | 'omit' | 'auto';
  snapshot?: SnapshotConfig;
};
```

资料来源：[config.d.ts:36-120]()

### 浏览器配置

```typescript
browser?: {
  browserName?: 'chromium' | 'firefox' | 'webkit';
  isolated?: boolean;
  userDataDir?: string;
  // ... launch options
}
```

| 参数 | 类型 | 说明 |
|------|------|------|
| `browserName` | `chromium` \| `firefox` \| `webkit` | 指定使用的浏览器引擎 |
| `isolated` | `boolean` | 是否保持浏览器配置文件在内存中，不写入磁盘 |
| `userDataDir` | `string` | 浏览器用户数据目录路径，默认为临时目录 |

### 超时配置

```typescript
timeouts?: {
  action?: number;      // 默认动作超时，默认 5000ms
  navigation?: number;  // 默认导航超时，默认 60000ms
  expect?: number;      // 默认断言超时，默认 5000ms
}
```

资料来源：[config.d.ts:60-74]()

### 网络安全配置

```typescript
network?: {
  allowedOrigins?: string[];   // 允许的请求来源
  blockedOrigins?: string[];  // 阻止的请求来源
}
```

**支持的格式：**

| 格式 | 示例 | 匹配范围 |
|------|------|----------|
| 完整来源 | `https://example.com:8080` | 仅匹配该精确来源 |
| 通配符端口 | `http://localhost:*` | localhost 上任意端口的 HTTP 请求 |

资料来源：[config.d.ts:84-95]()

### 控制台配置

```typescript
console?: {
  level?: 'error' | 'warning' | 'info' | 'debug';
}
```

| 级别 | 包含的消息 |
|------|-----------|
| `error` | 仅错误消息 |
| `warning` | 错误 + 警告 |
| `info` | 警告 + 信息（默认） |
| `debug` | 所有消息 |

### 图片响应配置

```typescript
imageResponses?: 'allow' | 'omit' | 'auto';
```

| 值 | 说明 |
|----|------|
| `allow` | 始终发送图片响应 |
| `omit` | 从不发送图片响应 |
| `auto` | 如果客户端能显示则发送（默认） |

资料来源：[config.d.ts:76-79]()

## MCP 工具生成机制

README 文档中的工具列表通过 `update-readme.js` 脚本自动生成。脚本从编译后的模块加载工具信息，生成格式化的 Markdown 文档。资料来源：[update-readme.js:1-100]()

```mermaid
graph LR
    A[编译后的模块] -->|加载工具| B[update-readme.js]
    B -->|生成 Markdown| C[README.md]
    
    D[cli.js --help] -->|CLI 选项| B
    E[config.d.ts] -->|配置类型| B
```

### 工具描述格式

每个工具在 README 中以折叠块形式展示：

```markdown
<details>
<summary><b>能力域名称</b></summary>

<!-- NOTE: This has been generated via update-readme.js -->

- **tool_name**
  - Title: 工具标题
  - Description: 工具描述
  - Parameters:
    - `param_name` (type, optional): 参数描述
  - Read-only: **true/false**
```

资料来源：[update-readme.js:170-190]()

## 命令行接口

MCP 服务通过 CLI 启动，支持以下操作模式：

| 命令 | 说明 |
|------|------|
| `npm run ctest` | 仅在 Chromium 中运行测试 |
| `npm run ftest` | 仅在 Firefox 中运行测试 |
| `npm run wtest` | 仅在 WebKit 中运行测试 |
| `npm run dtest` | 在 Docker 容器中运行 Chromium 测试 |
| `npm run roll` | 更新 Playwright 版本 |

资料来源：[package.json:14-24]()

### CLI 入口点

CLI 通过 `cli.js` 实现，集成了 `playwright-core` 的命令处理：

```javascript
const { tools, libCli } = require('playwright-core/lib/coreBundle');
tools.decorateMCPCommand(p, packageJSON.version);
```

特殊命令 `install-browser` 被映射为标准的 `playwright install`：

```javascript
if (process.argv.includes('install-browser')) {
  const argv = process.argv.map(arg => arg === 'install-browser' ? 'install' : arg);
  libCli.decorateProgram(program);
}
```

资料来源：[cli.js:24-32]()

## 核心入口点

MCP 的主入口通过 `index.js` 导出 `createConnection` 函数：

```javascript
const { tools } = require('playwright-core/lib/coreBundle');
module.exports = { createConnection: tools.createConnection };
```

这使得其他 MCP 客户端能够通过标准的方式连接到 Playwright MCP 服务。资料来源：[index.js:26-27]()

## 版本更新机制

`roll.js` 脚本负责更新 Playwright 依赖版本：

1. 从 Playwright 主仓库复制 `config.d.ts`
2. 更新 `package.json` 中的 `playwright`、`playwright-core`、`@playwright/test` 版本
3. 执行 `npm install` 安装新版本
4. 运行 `npm run lint` 更新 README 文档

```javascript
function doRoll(version) {
  updatePlaywrightVersion(version);
  copyConfig();
  execSync('npm run lint', { cwd: __dirname });
}
```

资料来源：[roll.js:1-40]()

## 会话管理

| 配置项 | 说明 |
|--------|------|
| `saveSession` | 是否将会话保存到输出目录 |
| `sharedBrowserContext` | 是否在所有 HTTP 客户端间共享浏览器上下文 |
| `secrets` | 敏感信息替换映射，防止 LLM 意外暴露 |

> **注意**：`secrets` 功能是便利性措施而非安全特性，客户端仍需自行审查传入和传出的数据。

资料来源：[config.d.ts:96-107]()

## 测试框架

测试配置位于 `playwright.config.ts`，支持多浏览器测试：

```typescript
projects: [
  { name: 'chrome' },
  ...process.env.MCP_IN_DOCKER ? [{
    name: 'chromium-docker',
    grep: /browser_navigate|browser_click/,
    use: {
      mcpBrowser: 'chromium',
      mcpMode: 'docker' as const
    }
  }] : [],
]
```

资料来源：[playwright.config.ts:22-32]()

## 总结

Playwright MCP 通过模块化的**能力域**设计，将浏览器自动化功能组织为可配置的逻辑单元。开发者可以通过 `config.d.ts` 中定义的类型精确配置所需功能，包括浏览器选择、超时策略、网络安全、存储管理等。这种设计使得 MCP 工具既保持了灵活性，又通过类型系统确保了配置的正确性。

---

<a id='page-browser-profiles'></a>

## 浏览器配置文件管理

### 相关页面

相关主题：[初始状态配置](#page-initial-state), [核心架构](#page-core-architecture)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)
- [playwright.config.ts](https://github.com/microsoft/playwright-mcp/blob/main/playwright.config.ts)
- [package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)
- [cli.js](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)
- [README.md](https://github.com/microsoft/playwright-mcp/blob/main/README.md)
- [index.js](https://github.com/microsoft/playwright-mcp/blob/main/index.js)
</details>

# 浏览器配置文件管理

## 概述

浏览器配置文件管理是 Playwright MCP 的核心功能之一，允许用户通过配置对象自定义浏览器的启动行为、会话持久化方式以及浏览器上下文的安全策略。该模块通过 `config.d.ts` 中定义的 `Config` 类型提供类型安全的配置接口，支持多种浏览器引擎（Chromium、Firefox、WebKit）的灵活配置与管理。

Playwright MCP 的浏览器配置文件管理主要负责以下职责：

| 职责 | 说明 |
|------|------|
| 浏览器选择 | 指定使用哪种浏览器引擎 |
| 会话持久化 | 管理浏览器用户数据目录，支持会话恢复 |
| 安全策略 | 控制浏览器请求的来源限制（允许/阻止的域名） |
| 隔离模式 | 支持内存级浏览器配置文件，防止数据持久化 |
| 启动参数 | 传递自定义浏览器启动选项 |

资料来源：[config.d.ts:29-62]()

## 配置结构

### 顶级配置对象

Playwright MCP 的配置通过 `Config` 类型定义，核心结构如下：

```typescript
export type Config = {
  browser?: {
    browserName?: 'chromium' | 'firefox' | 'webkit';
    isolated?: boolean;
    userDataDir?: string;
    // 浏览器启动选项
  };
  // ... 其他配置项
};
```

资料来源：[config.d.ts:35-45]()

### 配置参数详解

#### 浏览器配置（browser）

浏览器配置对象包含以下可选参数：

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `browserName` | `'chromium' \| 'firefox' \| 'webkit'` | `'chromium'` | 指定要使用的浏览器引擎 |
| `isolated` | `boolean` | `undefined` | 是否在内存中运行浏览器，不保存配置文件到磁盘 |
| `userDataDir` | `string` | `undefined` | 自定义浏览器用户数据目录路径 |

```typescript
// 浏览器配置示例
const config = {
  browser: {
    browserName: 'chromium',
    isolated: true,
    userDataDir: '/path/to/custom/profile'
  }
};
```

资料来源：[config.d.ts:35-62]()

#### 起源安全策略（network）

浏览器网络请求的安全策略通过 `network` 配置项管理：

| 参数 | 类型 | 说明 |
|------|------|------|
| `allowedOrigins` | `string[]` | 允许浏览器请求的来源列表，支持完整域名和通配符端口 |
| `blockedOrigins` | `string[]` | 阻止浏览器请求的来源列表，同时匹配两个列表的请求将被阻止 |

支持的来源格式：

- **完整域名**：`https://example.com:8080` - 仅匹配该具体地址
- **通配符端口**：`http://localhost:*` - 匹配 localhost 上任意端口的 HTTP 请求

```typescript
const config = {
  network: {
    allowedOrigins: ['https://trusted-site.com'],
    blockedOrigins: ['https://untrusted-site.com']
  }
};
```

资料来源：[config.d.ts:103-126]()

#### 浏览器上下文配置（browserContext）

用于配置浏览器的上下文级设置：

| 参数 | 类型 | 说明 |
|------|------|------|
| `screenSize` | `{ width: number, height: number }` | 浏览器视口尺寸 |
| `timezoneId` | `string` | 浏览器的时区设置 |
| `locale` | `string` | 浏览器的区域设置 |
| `permissions` | `string[]` | 授予的浏览器权限列表 |
| `viewport` | `{ width: number, height: number }` | 默认视口大小 |

#### 测试标识属性（testIdAttribute）

指定用于测试 ID 的 HTML 属性，默认值为 `"data-testid"`：

```typescript
const config = {
  testIdAttribute: 'data-testid'
};
```

资料来源：[config.d.ts:71-77]()

#### 超时配置（timeouts）

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `action` | `number` | `5000` | 操作超时时间（毫秒） |
| `navigation` | `number` | `60000` | 导航超时时间（毫秒） |
| `expect` | `number` | `5000` | 断言超时时间（毫秒） |

```typescript
const config = {
  timeouts: {
    action: 5000,
    navigation: 60000,
    expect: 5000
  }
};
```

资料来源：[config.d.ts:79-94]()

## 浏览器配置文件生命周期

### 配置文件创建流程

```mermaid
graph TD
    A[配置对象创建] --> B{userDataDir 设置?}
    B -->|是| C[使用指定目录]
    B -->|否| D{isolated 为 true?}
    D -->|是| E[创建临时内存目录]
    D -->|否| F[创建临时持久化目录]
    C --> G[浏览器启动]
    E --> G
    F --> G
    G --> H[浏览器上下文创建]
    H --> I[会话就绪]
```

### 会话持久化策略

Playwright MCP 支持三种会话持久化模式：

| 模式 | `isolated` | `userDataDir` | 行为 |
|------|------------|---------------|------|
| 完全隔离 | `true` | 未设置 | 浏览器配置存储在内存中，进程结束后丢失 |
| 临时持久化 | `false` | 未设置 | 临时目录存储配置，进程结束后自动清理 |
| 自定义持久化 | 任意 | 已设置 | 使用指定目录存储配置，可跨会话复用 |

```typescript
// 完全隔离模式示例
const isolatedConfig = {
  browser: {
    browserName: 'chromium',
    isolated: true
  }
};

// 跨会话复用配置示例
const persistentConfig = {
  browser: {
    browserName: 'chromium',
    userDataDir: '/path/to/persistent/profile'
  }
};
```

资料来源：[config.d.ts:35-56]()

## 架构集成

### 组件关系图

```mermaid
graph TD
    subgraph "MCP 服务器层"
        A[index.js - createConnection]
        B[cli.js - 命令行解析]
    end
    
    subgraph "配置管理层"
        C[config.d.ts - 类型定义]
        D[Config 验证器]
    end
    
    subgraph "Playwright 核心"
        E[playwright-core]
        F[浏览器引擎]
    end
    
    A --> B
    B --> D
    C --> D
    D --> E
    E --> F
    
    style C fill:#e1f5fe
    style F fill:#fff3e0
```

### 配置文件加载流程

```mermaid
sequenceDiagram
    participant CLI as 命令行接口
    participant Config as 配置加载器
    participant Playwright as Playwright Core
    participant Browser as 浏览器引擎

    CLI->>Config: 解析用户配置
    Config->>Config: 验证配置类型
    Config->>Playwright: 传递配置参数
    Playwright->>Browser: 初始化浏览器
    Browser-->>Playwright: 浏览器实例
    Playwright-->>Config: 会话就绪
    Config-->>CLI: MCP 服务启动
```

资料来源：[index.js:1-28]()

## 工具能力与浏览器配置

浏览器配置文件管理与 MCP 工具能力紧密集成，支持通过 `capabilities` 配置启用或禁用特定功能：

| 能力标识 | 说明 | 默认状态 |
|----------|------|----------|
| `core` | 核心浏览器操作 | 默认启用 |
| `core-navigation` | 页面导航功能 | 默认启用 |
| `core-tabs` | 多标签页管理 | 默认启用 |
| `core-input` | 输入操作 | 默认启用 |
| `core-install` | 浏览器安装 | 默认启用 |
| `network` | 网络请求拦截 | 需显式启用 |
| `pdf` | PDF 生成 | 需显式启用 |
| `storage` | 存储管理 | 需显式启用 |
| `testing` | 测试断言 | 需显式启用 |
| `vision` | 视觉交互 | 需显式启用 |
| `devtools` | 开发者工具 | 需显式启用 |

```typescript
const config = {
  browser: {
    browserName: 'chromium'
  },
  capabilities: ['core', 'network', 'pdf']
};
```

资料来源：[config.d.ts:28-32]()

## 使用示例

### 基础配置

```typescript
import { createConnection } from '@playwright/mcp';

const server = createConnection({
  browser: {
    browserName: 'chromium'
  }
});
```

### 高级配置

```typescript
import { createConnection } from '@playwright/mcp';

const server = createConnection({
  browser: {
    browserName: 'firefox',
    isolated: false,
    userDataDir: '/home/user/.playwright-profiles/firefox',
  },
  network: {
    allowedOrigins: ['https://example.com'],
    blockedOrigins: ['https://ads.example.com']
  },
  timeouts: {
    action: 10000,
    navigation: 120000
  },
  testIdAttribute: 'data-testid',
  outputDir: '/tmp/playwright-output'
});
```

资料来源：[config.d.ts:35-140]()

### 命令行配置

Playwright MCP 通过 `cli.js` 提供命令行接口，支持通过命令行参数配置浏览器行为：

```bash
# 使用指定浏览器
npx playwright-mcp --browser=chromium

# 安装浏览器
npx playwright-mcp install-browser

# 查看帮助
npx playwright-mcp --help
```

资料来源：[cli.js:1-31]()

## 相关源码文件索引

| 文件路径 | 作用 |
|----------|------|
| `config.d.ts` | 配置类型定义，包含所有浏览器配置接口 |
| `index.js` | MCP 连接入口，导出 `createConnection` |
| `cli.js` | 命令行工具，处理用户输入和参数解析 |
| `playwright.config.ts` | 测试框架配置，用于项目内部测试 |
| `package.json` | 包元数据，定义 MCP 服务名称和版本 |

## 配置验证

Playwright MCP 在启动时会验证配置对象的有效性。配置验证主要包括：

1. **类型检查**：确保所有配置项符合 TypeScript 类型定义
2. **值域验证**：检查枚举值（如浏览器类型）是否有效
3. **路径验证**：验证 `userDataDir` 等路径是否存在或可创建

配置验证失败时，MCP 服务器将抛出类型错误并拒绝启动，确保用户能够及时发现配置问题。

资料来源：[config.d.ts:1-140]()

---

<a id='page-initial-state'></a>

## 初始状态配置

### 相关页面

相关主题：[浏览器配置文件管理](#page-browser-profiles), [MCP 工具与能力](#page-tools-capabilities)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)
- [package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)
- [update-readme.js](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)
- [cli.js](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)
- [playwright.config.ts](https://github.com/microsoft/playwright-mcp/blob/main/playwright.config.ts)
- [CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)
</details>

# 初始状态配置

## 概述

初始状态配置（Initial State Configuration）是指 Playwright MCP Server 启动时的各项运行时参数与选项。这些配置项决定了浏览器的启动方式、会话管理策略、网络安全策略、超时行为等核心功能。配置文件采用 TypeScript 类型定义，统一存放在 `config.d.ts` 中，并通过 CLI 参数、环境变量或编程方式传递给服务端。

## 配置架构

```mermaid
graph TD
    A[Playwright MCP Server] --> B[配置加载层]
    B --> C[CLI 参数]
    B --> D[环境变量]
    B --> E[配置文件]
    
    C --> F[配置合并与验证]
    D --> F
    E --> F
    
    F --> G[Config 对象]
    
    G --> H[browser 配置]
    G --> I[capabilities 配置]
    G --> J[network 配置]
    G --> K[timeouts 配置]
    G --> L[其他选项]
    
    H --> M[Playwright Browser]
    I --> N[可用工具集]
    J --> O[网络请求过滤]
    K --> P[超时策略]
```

## 核心配置项

### 浏览器配置

浏览器配置通过 `browser` 字段定义，控制浏览器实例的创建与生命周期管理。

| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `browserName` | `'chromium' \| 'firefox' \| 'webkit'` | - | 指定使用的浏览器类型 |
| `isolated` | `boolean` | `true` | 是否将浏览器配置文件保存在内存中，不写入磁盘 |
| `userDataDir` | `string` | 临时目录 | 浏览器用户数据目录的路径，用于持久化浏览器状态 |

**isolated 模式说明**：`isolated` 为 `true` 时，浏览器配置不会保存到磁盘，所有会话数据存储在内存中，浏览器关闭后自动清除。设置为 `false` 并配合 `userDataDir` 可实现浏览器状态的持久化保存。

### 能力配置

`capabilities` 数组定义了 MCP Server 暴露给客户端的工具能力集。

```typescript
export type ToolCapability =
  'config' |
  'core' |
  'core-navigation' |
  'core-tabs' |
  'core-input' |
  'core-install' |
  'network' |
  'pdf' |
  'storage' |
  'testing' |
  'vision' |
  'devtools';
```

| 能力标识 | 说明 | 必需 |
|----------|------|------|
| `core` | 核心功能 | 默认启用 |
| `core-navigation` | 页面导航功能 | 可选 |
| `core-tabs` | 多标签页管理 | 可选 |
| `core-input` | 输入处理功能 | 可选 |
| `core-install` | 浏览器安装功能 | 可选 |
| `network` | 网络请求拦截与修改 | 可选 |
| `pdf` | PDF 生成功能 | 可选 |
| `storage` | 存储管理功能 | 可选 |
| `testing` | 测试断言功能 | 可选 |
| `vision` | 视觉识别功能 | 可选 |
| `devtools` | 开发者工具集成 | 可选 |

## 网络安全配置

`network` 字段用于控制浏览器可访问的网络来源，实现请求来源的白名单与黑名单管理。

```typescript
network?: {
  allowedOrigins?: string[];
  blockedOrigins?: string[];
};
```

### 支持的格式

| 格式类型 | 示例 | 匹配范围 |
|----------|------|----------|
| 完整 origin | `https://example.com:8080` | 仅匹配该特定地址 |
| 协议通配符 | `http://localhost:*` | localhost 任意端口的 HTTP 请求 |

**匹配优先级**：当某个 origin 同时匹配 `allowedOrigins` 和 `blockedOrigins` 时，该请求将被**阻止**。

## 超时配置

`timeouts` 对象定义了各类操作的默认超时时间。

```typescript
timeouts?: {
  action?: number;      // 默认: 5000ms
  navigation?: number; // 默认: 60000ms
  expect?: number;      // 默认: 5000ms
};
```

| 配置项 | 默认值 | 说明 | 相关文档 |
|--------|--------|------|----------|
| `action` | 5000ms | 默认操作超时 | [page.setDefaultTimeout](https://playwright.dev/docs/api/class-page#page-set-default-timeout) |
| `navigation` | 60000ms | 默认导航超时 | [page.setDefaultNavigationTimeout](https://playwright.dev/docs/api/class-page#page-set-default-navigation-timeout) |
| `expect` | 5000ms | 默认断言超时 | [test timeouts](https://playwright.dev/docs/test-timeouts#expect-timeout) |

## 会话与上下文管理

### 会话保存

| 配置项 | 类型 | 说明 |
|--------|------|------|
| `saveSession` | `boolean` | 是否将 Playwright 会话保存到输出目录 |

### 浏览器上下文共享

| 配置项 | 类型 | 说明 |
|--------|------|------|
| `sharedBrowserContext` | `boolean` | 是否在所有连接的 HTTP 客户端之间重用同一个浏览器上下文 |

## 安全配置

### 密钥管理

```typescript
secrets?: Record<string, string>;
```

`secrets` 用于替换工具响应中的匹配明文文本，防止 LLM 意外获取敏感数据。

> 注意：这是便利性功能而非安全特性，客户端仍需始终检查传入和来自工具的信息。

### 图片响应控制

```typescript
imageResponses?: 'allow' | 'omit' | 'auto';
```

| 值 | 说明 |
|----|------|
| `allow` | 始终发送图片响应 |
| `omit` | 始终省略图片响应 |
| `auto` | 如果客户端能显示图片则发送（默认行为） |

## 其他配置项

### 测试 ID 属性

```typescript
testIdAttribute?: string;
```

指定用于测试 ID 的属性，默认为 `data-testid`。

### 输出目录

```typescript
outputDir?: string;
```

保存输出文件的目录路径。

### 控制台日志级别

```typescript
console?: {
  level?: 'error' | 'warning' | 'info' | 'debug';
};
```

每种级别包含更严重级别的消息：`debug` < `info` < `warning` < `error`。

## 配置传递方式

Playwright MCP 支持多种配置传递方式：

### 1. CLI 参数

通过命令行启动时传递参数：

```bash
npx playwright-mcp --browser-name=chromium --output-dir=/tmp/pw-output
```

### 2. 环境变量

每个 CLI 参数都有对应的环境变量：

| CLI 参数前缀 | 环境变量前缀 |
|--------------|--------------|
| `--browser-name` | `PLAYWRIGHT_MCP_BROWSER_NAME` |
| `--output-dir` | `PLAYWRIGHT_MCP_OUTPUT_DIR` |
| `--secrets` | `PLAYWRIGHT_MCP_SECRETS_FILE` |

环境变量通过 `update-readme.js` 脚本自动从 CLI 定义生成。资料来源：[update-readme.js:62-67](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)

### 3. 编程配置

通过 `Config` 类型定义配置对象：

```typescript
import type { Config } from '@playwright/mcp';

const config: Config = {
  browser: {
    browserName: 'chromium',
    isolated: true
  },
  capabilities: ['core', 'network'],
  timeouts: {
    action: 10000,
    navigation: 30000
  }
};
```

## 配置类型定义

完整的 `Config` 类型定义如下：

```typescript
export type Config = {
  browser?: {
    browserName?: 'chromium' | 'firefox' | 'webkit';
    isolated?: boolean;
    userDataDir?: string;
    // ... 其他启动选项
  };
  capabilities?: ToolCapability[];
  saveSession?: boolean;
  sharedBrowserContext?: boolean;
  secrets?: Record<string, string>;
  outputDir?: string;
  console?: {
    level?: 'error' | 'warning' | 'info' | 'debug';
  };
  network?: {
    allowedOrigins?: string[];
    blockedOrigins?: string[];
  };
  testIdAttribute?: string;
  timeouts?: {
    action?: number;
    navigation?: number;
    expect?: number;
  };
  imageResponses?: 'allow' | 'omit' | 'auto';
  snapshot?: /* Snapshot 配置 */;
};
```

资料来源：[config.d.ts:1-100](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)

## 测试配置

对于测试场景，Playwright MCP 使用独立的 `playwright.config.ts` 配置文件：

```typescript
export default defineConfig<TestOptions>({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  workers: process.env.CI ? 2 : undefined,
  reporter: 'list',
  projects: [
    { name: 'chrome' },
  ],
});
```

资料来源：[playwright.config.ts:1-30](https://github.com/microsoft/playwright-mcp/blob/main/playwright.config.ts)

## 配置验证流程

```mermaid
graph LR
    A[输入配置] --> B[类型检查]
    B --> C{合法?}
    C -->|是| D[应用配置]
    C -->|否| E[抛出错误]
    
    D --> F[浏览器启动]
    D --> G[工具注册]
    D --> H[网络策略应用]
    D --> I[超时设置]
```

## 最佳实践

1. **隔离环境**：使用 `isolated: true` 避免浏览器状态污染
2. **超时设置**：根据网络环境调整 `timeouts` 数值
3. **网络安全**：生产环境应明确设置 `allowedOrigins` 白名单
4. **密钥保护**：通过 `secrets` 配置敏感信息，避免硬编码
5. **能力精简**：仅启用必需的 `capabilities`，减少攻击面

---

<a id='page-security-config'></a>

## 安全与网络配置

### 相关页面

相关主题：[MCP 工具与能力](#page-tools-capabilities), [部署选项](#page-deployment)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)
- [SECURITY.md](https://github.com/microsoft/playwright-mcp/blob/main/SECURITY.md)
- [cli.js](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)
- [package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)
- [update-readme.js](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)
- [CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)
- [CLAUDE.md](https://github.com/microsoft/playwright-mcp/blob/main/CLAUDE.md)
</details>

# 安全与网络配置

Playwright MCP 提供了全面的安全与网络配置功能，允许用户精细控制浏览器的网络请求、敏感信息处理以及浏览器实例的安全策略。本文档详细介绍这些配置选项的用途、使用方法和最佳实践。

## 概述

Playwright MCP 是一个为 MCP（Model Context Protocol）协议提供 Playwright 工具的项目。它允许 AI 助手通过标准化的接口控制浏览器执行各种自动化任务，包括导航、点击、输入、网络请求拦截等操作。资料来源：[package.json:1-10]()

为了确保在自动化浏览器操作过程中的安全性，项目提供了多层次的安全配置机制：

- **网络请求控制**：通过 `allowedOrigins` 和 `blockedOrigins` 白名单/黑名单机制
- **敏感信息保护**：通过 `secrets` 配置实现敏感数据的自动替换
- **浏览器隔离**：通过 `browser.isolated` 等选项控制浏览器实例的生命周期

资料来源：[config.d.ts:1-150]()

## 网络配置

### 源地址过滤

Playwright MCP 提供了精细的网络请求控制功能，允许管理员指定允许或阻止的请求源地址。

#### allowedOrigins（允许的源地址）

| 属性 | 类型 | 说明 |
|------|------|------|
| 类型 | `string[]` | 允许浏览器请求的源地址列表 |
| 默认值 | 全部允许 | 若未配置，默认允许所有源地址的请求 |

支持的匹配格式：

| 格式 | 示例 | 匹配范围 |
|------|------|----------|
| 完整源地址 | `https://example.com:8080` | 仅匹配指定协议、域名和端口的请求 |
| 通配符端口 | `http://localhost:*` | 匹配 localhost 上任意端口的 HTTP 请求 |

当请求同时匹配 `allowedOrigins` 和 `blockedOrigins` 时，该请求将被阻止。

资料来源：[config.d.ts:50-75]()

#### blockedOrigins（阻止的源地址）

| 属性 | 类型 | 说明 |
|------|------|------|
| 类型 | `string[]` | 阻止浏览器请求的源地址列表 |
| 默认值 | 空数组 | 若未配置，默认不阻止任何源地址 |

```mermaid
graph TD
    A[浏览器发起请求] --> B{检查 blockedOrigins}
    B -->|匹配黑名单| C[阻止请求]
    B -->|未匹配黑名单| D{检查 allowedOrigins}
    D -->|已配置且匹配| E[允许请求]
    D -->|已配置但未匹配| C
    D -->|未配置| E
```

**配置示例**：

```typescript
{
  network: {
    // 允许所有本地开发服务器
    allowedOrigins: [
      'http://localhost:3000',
      'http://localhost:8080',
      'http://127.0.0.1:*'
    ],
    // 阻止所有外部 API 请求
    blockedOrigins: [
      'https://api.external-service.com'
    ]
  }
}
```

资料来源：[config.d.ts:60-90]()

### 网络配置结构

完整的网络配置类型定义如下：

```typescript
network?: {
  allowedOrigins?: string[];
  blockedOrigins?: string[];
};
```

## 浏览器配置与安全隔离

### 浏览器实例选项

Playwright MCP 支持配置浏览器实例的各项参数，以满足不同的安全需求。

| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `browser.browserName` | `'chromium' \| 'firefox' \| 'webkit'` | `'chromium'` | 指定使用的浏览器类型 |
| `browser.isolated` | `boolean` | `true` | 浏览器配置文件是否仅保留在内存中，不写入磁盘 |
| `browser.userDataDir` | `string` | 系统临时目录 | 浏览器配置文件的存储路径 |

#### 隔离模式（isolated）

启用隔离模式后，浏览器不会将任何持久化数据（如 Cookie、缓存、本地存储）写入磁盘。这对于安全性要求较高的自动化场景特别有用。

```typescript
{
  browser: {
    browserName: 'chromium',
    isolated: true  // 启用内存隔离模式
  }
}
```

资料来源：[config.d.ts:30-55]()

### 用户数据目录管理

通过 `userDataDir` 可以自定义浏览器配置文件的存储位置。默认情况下，系统会创建临时目录存储浏览器数据。

| 模式 | userDataDir | 行为 |
|------|-------------|------|
| 临时模式 | 未指定 | 创建临时目录，测试结束后自动清理 |
| 持久模式 | 指定路径 | 使用指定目录，可在多次运行间保持浏览器状态 |

资料来源：[config.d.ts:35-45]()

## 敏感信息安全

### Secrets 配置

Playwright MCP 提供了 `secrets` 配置选项，用于在工具响应中自动替换敏感信息，防止大语言模型意外获取敏感数据。

> **重要提示**：secrets 功能是便利性功能而非安全特性。它主要用于防止 LLM 意外泄露敏感数据，但不应将其视为真正的安全加密手段。请确保始终对客户端传入的信息进行仔细检查。

资料来源：[config.d.ts:110-120]()

#### Secrets 配置结构

```typescript
secrets?: Record<string, string>;
```

#### 使用方式

```typescript
{
  secrets: {
    // key: 要替换的敏感值
    // value: 替换后的显示值
    'my-api-key-12345': '[REDACTED]',
    'Bearer token_xyz': '[REDACTED]'
  }
}
```

#### 替换机制

当工具响应中包含匹配 `secrets` 中定义的键值时，对应的敏感信息会被替换为预设的显示值：

```mermaid
graph LR
    A[工具响应生成] --> B{检查 secrets 配置}
    B -->|发现敏感信息| C[替换为预设值]
    B -->|无敏感信息| D[保持原样]
    C --> E[返回处理后的响应]
    D --> E
```

资料来源：[update-readme.js:80-95]()

### Console 日志级别控制

通过 `console.level` 配置可以控制返回给客户端的日志消息级别：

| 级别 | 包含消息 | 使用场景 |
|------|----------|----------|
| `error` | 仅错误信息 | 生产环境，减少数据量 |
| `warning` | 错误 + 警告 | 标准生产环境 |
| `info` | 警告 + 信息 | 开发调试 |
| `debug` | 所有消息 | 详细调试 |

```typescript
{
  console: {
    level: 'info'  // 默认值
  }
}
```

资料来源：[config.d.ts:125-135]()

## 配置选项参考

### 完整配置类型定义

```typescript
export type Config = {
  browser?: {
    browserName?: 'chromium' | 'firefox' | 'webkit';
    isolated?: boolean;
    userDataDir?: string;
    launchOptions?: Record<string, any>;
  };

  capabilities?: ToolCapability[];
  saveSession?: boolean;
  sharedBrowserContext?: boolean;
  secrets?: Record<string, string>;
  outputDir?: string;

  console?: {
    level?: 'error' | 'warning' | 'info' | 'debug';
  };

  network?: {
    allowedOrigins?: string[];
    blockedOrigins?: string[];
  };

  testIdAttribute?: string;

  timeouts?: {
    action?: number;
    navigation?: number;
    expect?: number;
  };

  imageResponses?: 'allow' | 'omit' | 'auto';
  snapshot?: Record<string, any>;
};
```

资料来源：[config.d.ts:95-145]()

### CLI 环境变量映射

CLI 选项与环境变量的映射关系：

| CLI 选项 | 环境变量 | 说明 |
|----------|----------|------|
| `--secrets` | `PLAYWRIGHT_MCP_SECRETS_FILE` | secrets 文件路径 |
| `--browser` | `PLAYWRIGHT_MCP_BROWSER` | 浏览器类型 |
| `--output-dir` | `PLAYWRIGHT_MCP_OUTPUT_DIR` | 输出目录 |
| 其他选项 | `PLAYWRIGHT_MCP_<OPTION>` | 通用前缀映射 |

资料来源：[update-readme.js:60-80]()

## 安全最佳实践

### 开发环境配置

```typescript
// 开发环境配置示例
{
  browser: {
    browserName: 'chromium',
    isolated: false  // 开发环境可复用浏览器状态
  },
  network: {
    allowedOrigins: ['http://localhost:*'],
    blockedOrigins: ['https://production-api.example.com']
  },
  console: {
    level: 'debug'
  }
}
```

### 生产环境配置

```typescript
// 生产环境配置示例
{
  browser: {
    browserName: 'chromium',
    isolated: true  // 生产环境启用隔离
  },
  network: {
    allowedOrigins: [
      'https://app.example.com',
      'https://cdn.example.com'
    ],
    blockedOrigins: ['*']
  },
  secrets: {
    'api-key-xxx': '[REDACTED]',
    'session-token': '[REDACTED]'
  },
  console: {
    level: 'error'  // 仅返回错误信息
  }
}
```

### 安全检查清单

在部署 Playwright MCP 之前，建议检查以下安全配置：

| 检查项 | 推荐配置 | 说明 |
|--------|----------|------|
| 浏览器隔离 | `isolated: true` | 防止数据持久化泄露 |
| 网络白名单 | 配置明确的 allowedOrigins | 限制仅访问必要的域 |
| 敏感信息 | 配置 secrets | 防止 LLM 意外获取敏感数据 |
| Console 日志 | 生产环境使用 `error` 级别 | 减少敏感信息泄露风险 |
| 临时文件 | 使用默认临时目录 | 避免在持久化存储中遗留数据 |

## 安全漏洞报告

微软对软件产品的安全性非常重视，包括所有通过 GitHub 组织管理的源代码仓库。

### 报告流程

**请勿通过公开的 GitHub Issues 报告安全漏洞。**

应按照以下方式向 Microsoft Security Response Center (MSRC) 报告：

1. 访问：[https://msrc.microsoft.com/create-report](https://aka.ms/security.md/msrc/create-report)
2. 或发送邮件至：[secure@microsoft.com](mailto:secure@microsoft.com)
3. 如可能，请使用 PGP 密钥加密消息（可从 Microsoft Security Response Center PGP Key 页面下载）

通常情况下，您将在 24 小时内收到回复。

资料来源：[SECURITY.md:1-30]()

### 报告内容建议

在报告时，请尽可能提供以下信息以帮助我们更好地理解和处理问题：

- 问题类型
- 完整的产品路径
- 受影响的组件
- 复现步骤
- 建议的修复方案（可选）

## 相关文档

| 文档 | 说明 |
|------|------|
| [配置参考](./config.md) | 完整的配置选项详细说明 |
| [工具列表](./tools.md) | 可用工具及其参数说明 |
| [CLI 使用指南](./cli.md) | 命令行工具使用方法 |
| [测试指南](../tests/mcp) | 测试用例编写规范 |

## 贡献指南

如果发现安全相关问题或希望为项目贡献代码，请注意以下事项：

1. **问题优先**：在提交 PR 之前，请先提交或查找相关的问题（issue）
2. **提交规范**：提交信息应遵循语义化提交规范（Semantic Commit Messages）
3. **分支命名**：问题修复的分支命名格式为 `fix-<issue-number>`

资料来源：[CONTRIBUTING.md:1-50]()

```bash
# 创建修复分支示例
git checkout -b fix-39562

# 提交修复
git commit -m "fix(proxy): handle SOCKS proxy authentication"
```

资料来源：[CLAUDE.md:1-40]()

---

<a id='page-deployment'></a>

## 部署选项

### 相关页面

相关主题：[快速入门](#page-quickstart)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)
- [cli.js](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)
- [Dockerfile](https://github.com/microsoft/playwright-mcp/blob/main/Dockerfile)
- [playwright.config.ts](https://github.com/microsoft/playwright-mcp/blob/main/playwright.config.ts)
- [config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)
- [update-readme.js](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)
</details>

# 部署选项

Playwright MCP 提供了多种部署方式，以适应不同的使用场景和环境需求。本页面详细介绍如何通过 Node.js 环境、Docker 容器以及 CLI 命令行工具等方式部署和运行 Playwright MCP。

## 概述

Playwright MCP 是一个基于 Model Context Protocol (MCP) 的浏览器自动化工具，它将 Playwright 的强大功能封装为一组 MCP 工具，供 AI 代理和自动化系统使用。部署选项的设计目标是为开发者提供灵活的选择，无论是本地开发、测试环境还是生产环境，都能找到合适的部署方式。

根据 package.json 中的配置，Playwright MCP 需要 Node.js 18 或更高版本运行环境，并通过 npm 进行包管理 资料来源：[package.json:8]()

## Node.js 环境部署

### 环境要求

| 组件 | 最低版本 | 说明 |
|------|----------|------|
| Node.js | >= 18 | JavaScript 运行时环境 |
| npm | 内置 | Node.js 包管理器 |
| Playwright 浏览器 | 自动安装 | 通过 `npx playwright install` 安装 |

### 安装步骤

在 Node.js 环境中部署 Playwright MCP 的标准流程如下：

```bash
# 克隆仓库
git clone https://github.com/microsoft/playwright-mcp
cd playwright-mcp

# 安装依赖
npm ci

# 安装浏览器（Chromium、Firefox、WebKit）
npx playwright install
```

### 运行 MCP 服务器

Playwright MCP 提供了两种运行模式：通过 CLI 直接运行或作为模块导入使用。

#### CLI 模式

直接使用 CLI 运行 MCP 服务器：

```bash
# 查看可用选项
npm run lint

# 运行测试
npm test

# 仅运行 Chromium 测试
npm run ctest
```

#### 模块导入模式

在 JavaScript 或 TypeScript 项目中作为模块使用：

```javascript
const { createConnection } = require('@playwright/mcp');
// 或 ESM
import { createConnection } from '@playwright/mcp';
```

资料来源：[index.js:25]()

### MCP 测试配置

在 playwright.config.ts 中，测试配置支持多种运行方式：

```typescript
export default defineConfig<TestOptions>({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  workers: process.env.CI ? 2 : undefined,
  reporter: 'list',
  projects: [
    { name: 'chrome' },
  ],
});
```

资料来源：[playwright.config.ts:20-30]()

## Docker 容器部署

Docker 部署提供了一致的运行环境，特别适合 CI/CD 场景和需要隔离环境的开发团队。

### Dockerfile 构建

Playwright MCP 提供了预配置的 Dockerfile 用于构建容器镜像：

```bash
# 构建镜像
npm run docker-build

# 运行容器
npm run docker-run
```

手动构建命令：

```bash
docker build --no-cache -t playwright-mcp-dev:latest .
```

### 容器运行参数

| 参数 | 说明 |
|------|------|
| `-it` | 交互式终端模式 |
| `-p 8080:8080` | 端口映射（主机:容器） |
| `--name playwright-mcp-dev` | 容器命名 |
| `playwright-mcp-dev:latest` | 镜像名称 |

### Docker 测试模式

在 Docker 环境中运行测试需要设置特定的环境变量：

```bash
# 在 Docker 中运行 Chromium 测试
npm run dtest
```

内部实现使用 `MCP_IN_DOCKER=1` 环境变量触发特殊配置：

```bash
MCP_IN_DOCKER=1 playwright test --project=chromium-docker
```

playwright.config.ts 中 Docker 测试配置：

```typescript
...process.env.MCP_IN_DOCKER ? [{
  name: 'chromium-docker',
  grep: /browser_navigate|browser_click/,
  use: {
    mcpBrowser: 'chromium',
    mcpMode: 'docker' as const
  }
}] : [],
```

资料来源：[playwright.config.ts:21-27]()

### 容器生命周期管理

```bash
# 构建镜像
npm run docker-build

# 运行容器
npm run docker-run

# 停止并删除容器
npm run docker-rm
```

资料来源：[package.json:15-17]()

## CLI 命令行工具

### CLI 入口点

CLI 通过 cli.js 实现，基于 commander.js 构建：

```javascript
const { program } = require('playwright-core/lib/utilsBundle');
const { tools, libCli } = require('playwright-core/lib/coreBundle');
```

资料来源：[cli.js:15-16]()

### install-browser 命令

CLI 支持通过 `install-browser` 别名安装浏览器：

```bash
npx playwright-mcp install-browser
# 或
node cli.js install-browser
```

内部实现将 `install-browser` 转换为 `install` 命令：

```javascript
if (process.argv.includes('install-browser')) {
  const argv = process.argv.map(arg => arg === 'install-browser' ? 'install' : arg);
  libCli.decorateProgram(program);
  void program.parseAsync(argv);
  return;
}
```

资料来源：[cli.js:12-18]()

### MCP 命令装饰

CLI 使用 Playwright Core 的 MCP 工具装饰功能：

```javascript
const packageJSON = require('./package.json');
const p = program.version('Version ' + packageJSON.version).name('Playwright MCP');
tools.decorateMCPCommand(p, packageJSON.version);
```

资料来源：[cli.js:21-24]()

## 配置选项

### 配置类型定义

Playwright MCP 的配置通过 TypeScript 类型定义在 config.d.ts 中，支持多种配置选项。

资料来源：[config.d.ts:1-100]()

### 浏览器配置

| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `browser.browserName` | `chromium \| firefox \| webkit` | - | 指定浏览器类型 |
| `browser.isolated` | `boolean` | - | 保持浏览器配置在内存中，不保存到磁盘 |
| `browser.userDataDir` | `string` | - | 浏览器配置持久化目录 |

### 超时配置

```typescript
timeouts?: {
  action?: number;      // 默认操作超时，默认 5000ms
  navigation?: number; // 默认导航超时，默认 60000ms
  expect?: number;     // 默认 expect 超时，默认 5000ms
};
```

### 来源控制配置

Playwright MCP 支持细粒度的来源控制：

| 选项 | 说明 |
|------|------|
| `allowedOrigins` | 允许浏览器请求的来源列表 |
| `blockedOrigins` | 阻止浏览器请求的来源列表 |

支持的格式：
- 完整来源：`https://example.com:8080` - 仅匹配该来源
- 通配符端口：`http://localhost:*` - 匹配 localhost 上任意端口的 HTTP 请求

### 图像响应配置

```typescript
imageResponses?: 'allow' | 'omit' | 'auto';
// 默认值为 "auto"，如果客户端可以显示则发送图像
```

### 测试 ID 属性

```typescript
testIdAttribute?: string;
// 指定用于测试 ID 的属性，默认为 "data-testid"
```

### 快照配置

```typescript
snapshot?: {
  // 快照相关配置选项
};
```

## 功能模块与部署关系

### 可用功能模块

Playwright MCP 将工具按功能模块组织，不同的模块可能需要不同的部署配置：

| 模块标识 | 功能描述 | 部署要求 |
|----------|----------|----------|
| `config` | 配置管理 | 基础部署 |
| `core` | 核心功能 | 基础部署 |
| `core-navigation` | 导航操作 | 浏览器实例 |
| `core-tabs` | 标签页管理 | 浏览器实例 |
| `core-input` | 输入处理 | 浏览器实例 |
| `core-install` | 安装功能 | 系统依赖 |
| `network` | 网络请求 | 浏览器实例 |
| `pdf` | PDF 生成 | 浏览器实例 |
| `storage` | 存储管理 | 浏览器实例 |
| `testing` | 测试断言 | Playwright Test |
| `vision` | 视觉功能 | 浏览器实例 |
| `devtools` | 开发者工具 | 浏览器实例 |

Opt-in 模块可通过 `--caps` 参数启用：

```bash
--caps=network,pdf,storage
```

资料来源：[config.d.ts:13-28]()

## 部署架构图

```mermaid
graph TD
    A[开发者环境] --> B[Node.js 部署]
    A --> C[Docker 容器部署]
    A --> D[CLI 工具部署]
    
    B --> B1[直接运行]
    B --> B2[模块导入]
    
    C --> C1[容器构建]
    C --> C2[容器运行]
    C --> C3[测试模式]
    
    D --> D1[install-browser]
    D --> D2[MCP 命令]
    
    B1 --> E[playwright-core]
    B2 --> E
    C2 --> E
    E --> F[浏览器实例]
    
    F --> G[Chromium]
    F --> H[Firefox]
    F --> I[WebKit]
```

## 环境变量

| 环境变量 | 说明 | 使用场景 |
|----------|------|----------|
| `MCP_IN_DOCKER` | 标记运行在 Docker 环境中 | Docker 测试 |
| `CI` | 标记 CI 环境 | 持续集成 |
| `PRINT_ENV` | 打印环境变量配置 | 调试 |

## 最佳实践

### 开发环境

- 使用 `npm ci` 安装依赖确保构建一致性
- 本地运行 `npx playwright install` 安装所需浏览器
- 使用 `npm run ctest` 快速验证 Chromium 功能

### CI/CD 环境

- 优先使用 Docker 容器确保环境一致性
- 设置 `CI=true` 以启用严格的测试模式
- 使用 `npm test` 运行完整测试套件

### 生产环境

- 考虑使用 `browser.isolated` 选项提高安全性
- 根据需求配置 `allowedOrigins` 和 `blockedOrigins`
- 设置合适的 `timeouts` 值避免长时间等待

## 故障排查

### 常见问题

| 问题 | 解决方案 |
|------|----------|
| 浏览器未安装 | 运行 `npx playwright install` |
| 端口冲突 | 修改 `-p` 参数使用其他端口 |
| 权限错误 | 确保 Docker 有足够的系统权限 |
| 超时错误 | 调整 config 中的 `timeouts` 配置 |

### 诊断命令

```bash
# 检查 Node.js 版本
node --version

# 检查 Playwright 安装
npx playwright --version

# 查看 CLI 帮助
node cli.js --help

---

---

## Doramagic 踩坑日志

项目：microsoft/playwright-mcp

摘要：发现 21 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

## 1. 身份坑 · 仓库名和安装名不一致

- 严重度：medium
- 证据强度：runtime_trace
- 发现：仓库名 `playwright-mcp` 与安装入口 `@playwright/mcp@latest` 不完全一致。
- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。
- 复现命令：`npx @playwright/mcp@latest`
- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。
- 证据：identity.distribution | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | repo=playwright-mcp; install=@playwright/mcp@latest

## 2. 安装坑 · 来源证据：Bad entrypoint in docker example

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bad entrypoint in docker example
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_948f818745694481b19e883b3992d78b | https://github.com/microsoft/playwright-mcp/issues/1609 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 3. 安装坑 · 来源证据：v0.0.72

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.0.72
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_2e67eb76e3c643e0a52a97e42eca4cb8 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.72 | 来源类型 github_release 暴露的待验证使用条件。

## 4. 配置坑 · 来源证据：v0.0.69

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.0.69
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_6767d649d4934031b85ab0c5ffc2b324 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.69 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 5. 配置坑 · 来源证据：v0.0.71

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.0.71
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_d5bcb1704c0e4a6fb375b18cda153fdd | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.71 | 来源类型 github_release 暴露的待验证使用条件。

## 6. 配置坑 · 来源证据：v0.0.73

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.0.73
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_a0d6aead61ad4c52ab738c6b556f2e27 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.73 | 来源类型 github_release 暴露的待验证使用条件。

## 7. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | README/documentation is current enough for a first validation pass.

## 8. 运行坑 · 来源证据：[Bug] Running multiple parallel async browsers in --isolated mode leaves orphan browsers. This has started happening af…

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[Bug] Running multiple parallel async browsers in --isolated mode leaves orphan browsers. This has started happening after Release v0.0.69.
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_e8f29958fbbe48ce8381daa23333bdf4 | https://github.com/microsoft/playwright-mcp/issues/1607 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 9. 运行坑 · 来源证据：v0.0.67

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.0.67
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_3b13c720c21346bab9c08783c91acb95 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.67 | 来源类型 github_release 暴露的待验证使用条件。

## 10. 运行坑 · 来源证据：v0.0.68

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.0.68
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_c53eae5fa6a94d2e86bc60cf6b164d16 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.68 | 来源类型 github_release 暴露的待验证使用条件。

## 11. 运行坑 · 来源证据：v0.0.74

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.0.74
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_2c41b3bf29434fb48d51cb9ffc766fc2 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.74 | 来源类型 github_release 暴露的待验证使用条件。

## 12. 运行坑 · 来源证据：v0.0.75

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.0.75
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_4e21e73e13dc471f90365f431d541143 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.75 | 来源类型 github_release 暴露的待验证使用条件。

## 13. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | last_activity_observed missing

## 14. 安全/权限坑 · 下游验证发现风险项

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | no_demo; severity=medium

## 15. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | no_demo; severity=medium

## 16. 安全/权限坑 · 来源证据：VS Code installation buttons don't seem to work

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：VS Code installation buttons don't seem to work
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_37c3461084f34d05856db207d12f8d9a | https://github.com/microsoft/playwright-mcp/issues/1608 | 来源类型 github_issue 暴露的待验证使用条件。

## 17. 安全/权限坑 · 来源证据：[Bug]: Windows taskkill output can pollute MCP stdio transport

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: Windows taskkill output can pollute MCP stdio transport
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_789c261c74274d9d9a84d4b1fbf30d14 | https://github.com/microsoft/playwright-mcp/issues/1611 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

## 18. 安全/权限坑 · 来源证据：[Disclosure] Clarify browser/network action boundary in Playwright MCP server docs

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Disclosure] Clarify browser/network action boundary in Playwright MCP server docs
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_fc2b3d242d67495f81f1bb1877e22f84 | https://github.com/microsoft/playwright-mcp/issues/1617 | 来源类型 github_issue 暴露的待验证使用条件。

## 19. 安全/权限坑 · 来源证据：[Feature Request] Support clientCertificates option for mTLS authentication

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature Request] Support clientCertificates option for mTLS authentication
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_b6f82bec73944aa5869030ad7db55b0c | https://github.com/microsoft/playwright-mcp/issues/1456 | 来源类型 github_issue 暴露的待验证使用条件。

## 20. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | issue_or_pr_quality=unknown

## 21. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | release_recency=unknown

<!-- canonical_name: microsoft/playwright-mcp; human_manual_source: deepwiki_human_wiki -->