zijiren
043fe1f581
feat: add github mcp (#278)
|
il y a 6 mois | |
|---|---|---|
| .. | ||
| README.cn.md | il y a 6 mois | |
| README.md | il y a 6 mois | |
| init.go | il y a 6 mois | |
README.cn.md
Playwright MCP
一个模型上下文协议 (MCP) 服务器，使用 Playwright 提供浏览器自动化功能。该服务器使 LLM 能够通过结构化的无障碍快照与网页交互，无需截图或视觉调优模型。
主要特性
- 快速且轻量级。使用 Playwright 的无障碍树，而非基于像素的输入。
- LLM 友好。无需视觉模型，纯粹基于结构化数据操作。
- 确定性工具应用。避免了基于截图方法常见的模糊性。
系统要求
- Node.js 18 或更新版本
- VS Code、Cursor、Windsurf、Claude Desktop 或任何其他 MCP 客户端
快速开始
首先，在您的客户端中安装 Playwright MCP 服务器。典型配置如下：
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp@latest"
]
}
}
}
在 VS Code 中安装
您也可以使用 VS Code CLI 安装 Playwright MCP 服务器： ```bash # 对于 VS Code code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}' ``` 安装后，Playwright MCP 服务器将可在 VS Code 中与您的 GitHub Copilot 代理一起使用。在 Cursor 中安装
#### 点击按钮安装 [](https://cursor.com/install-mcp?name=playwright&config=eyJjb21tYW5kIjoibnB4IEBwbGF5d3JpZ2h0L21jcEBsYXRlc3QifQ%3D%3D) #### 或手动安装 前往 `Cursor Settings` -> `MCP` -> `Add new MCP Server`。随意命名，使用 `command` 类型，命令为 `npx @playwright/mcp`。您也可以通过点击 `Edit` 验证配置或添加命令行参数。 ```js { "mcpServers": { "playwright": { "command": "npx", "args": [ "@playwright/mcp@latest" ] } } } ```在 Windsurf 中安装
参考 Windsurf MCP [文档](https://docs.windsurf.com/windsurf/cascade/mcp)。使用以下配置： ```js { "mcpServers": { "playwright": { "command": "npx", "args": [ "@playwright/mcp@latest" ] } } } ```在 Claude Desktop 中安装
参考 MCP 安装[指南](https://modelcontextprotocol.io/quickstart/user)，使用以下配置： ```js { "mcpServers": { "playwright": { "command": "npx", "args": [ "@playwright/mcp@latest" ] } } } ```在 Qodo Gen 中安装
在 VSCode 或 IntelliJ 中打开 [Qodo Gen](https://docs.qodo.ai/qodo-documentation/qodo-gen) 聊天面板 → Connect more tools → + Add new MCP → 粘贴以下配置： ```js { "mcpServers": { "playwright": { "command": "npx", "args": [ "@playwright/mcp@latest" ] } } } ``` 点击Save。
配置
Playwright MCP 服务器支持以下参数。它们可以在上述 JSON 配置中作为 "args" 列表的一部分提供：
> npx @playwright/mcp@latest --help
--allowed-origins <origins> 允许浏览器请求的源列表，用分号分隔。默认允许所有。
--blocked-origins <origins> 阻止浏览器请求的源列表，用分号分隔。阻止列表在允许列表之前评估。如果在没有允许列表的情况下使用，不匹配阻止列表的请求仍然被允许。
--block-service-workers 阻止 service workers
--browser <browser> 要使用的浏览器或 chrome 频道，可能的值：chrome、firefox、webkit、msedge。
--browser-agent <endpoint> 使用浏览器代理（实验性）。
--caps <caps> 要启用的功能列表，用逗号分隔，可能的值：tabs、pdf、history、wait、files、install。默认是全部。
--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" 或 "auto"。默认为 "auto"，如果客户端可以显示图像则发送。
--no-sandbox 为通常沙盒化的所有进程类型禁用沙盒。
--output-dir <path> 输出文件的目录路径。
--port <port> SSE 传输监听的端口。
--proxy-bypass <bypass> 绕过代理的域列表，用逗号分隔，例如 ".com,chromium.org,.domain.com"
--proxy-server <proxy> 指定代理服务器，例如 "http://myproxy:3128" 或 "socks5://myproxy:8080"
--save-trace 是否将会话的 Playwright Trace 保存到输出目录。
--storage-state <path> 隔离会话的存储状态文件路径。
--user-agent <ua string> 指定用户代理字符串
--user-data-dir <path> 用户数据目录的路径。如果未指定，将创建临时目录。
--viewport-size <size> 指定浏览器视口大小（像素），例如 "1280, 720"
--vision 运行使用截图的服务器（默认使用 Aria 快照）
用户配置文件
您可以使用持久配置文件（默认）像常规浏览器一样运行 Playwright MCP，或者在隔离上下文中用于测试会话。
持久配置文件
所有登录信息都将存储在持久配置文件中，如果您想清除离线状态，可以在会话之间删除它。
持久配置文件位于以下位置，您可以使用 --user-data-dir 参数覆盖它。
# 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 参数向浏览器提供初始存储状态。在这里了解更多关于存储状态的信息。
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp@latest",
"--isolated",
"--storage-state={path/to/storage.json}"
]
}
}
}
配置文件
Playwright MCP 服务器可以使用 JSON 配置文件进行配置。您可以使用 --config 命令行选项指定配置文件：
npx @playwright/mcp@latest --config path/to/config.json
配置文件架构
```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< 'core' | // 核心浏览器自动化 'tabs' | // 标签页管理 'pdf' | // PDF 生成 'history' | // 浏览器历史 'wait' | // 等待工具 'files' | // 文件处理 'install' | // 浏览器安装 'testing' // 测试 >; // 启用视觉模式（截图而非无障碍快照） vision?: boolean; // 输出文件目录 outputDir?: string; // 网络配置 network?: { // 允许浏览器请求的源列表。默认允许所有。同时匹配 `allowedOrigins` 和 `blockedOrigins` 的源将被阻止。 allowedOrigins?: string[]; // 阻止浏览器请求的源列表。同时匹配 `allowedOrigins` 和 `blockedOrigins` 的源将被阻止。 blockedOrigins?: string[]; }; /** * 不向客户端发送图像响应。 */ noImageResponses?: boolean; } ```独立 MCP 服务器
当在没有显示器的系统上运行有头浏览器或从 IDE 的工作进程运行时，
从具有 DISPLAY 的环境运行 MCP 服务器并传递 --port 标志以启用 SSE 传输。
npx @playwright/mcp@latest --port 8931
然后在 MCP 客户端配置中，将 url 设置为 SSE 端点：
{
"mcpServers": {
"playwright": {
"url": "http://localhost:8931/sse"
}
}
}
Docker
**注意：** Docker 实现目前仅支持无头 chromium。 ```js { "mcpServers": { "playwright": { "command": "docker", "args": ["run", "-i", "--rm", "--init", "--pull=always", "mcr.microsoft.com/playwright/mcp"] } } } ``` 您可以自己构建 Docker 镜像。 ``` docker build -t mcr.microsoft.com/playwright/mcp . ```编程使用
```js import http from 'http'; import { createConnection } from '@playwright/mcp'; import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js'; http.createServer(async (req, res) => { // ... // 创建一个无头 Playwright MCP 服务器与 SSE 传输 const connection = await createConnection({ browser: { launchOptions: { headless: true } } }); const transport = new SSEServerTransport('/messages', res); await connection.sever.connect(transport); // ... }); ```工具
工具有两种模式可用：
- 快照模式（默认）：使用无障碍快照以获得更好的性能和可靠性
- 视觉模式：使用截图进行基于视觉的交互
要使用视觉模式，在启动服务器时添加 --vision 标志：
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp@latest",
"--vision"
]
}
}
}
视觉模式最适合能够基于提供的截图使用 X Y 坐标空间与元素交互的计算机使用模型。