{"_id":"playwright-parallel-mcp","_rev":"3-d647596d1d33ffa174d5aeca71fd2d9e","name":"playwright-parallel-mcp","dist-tags":{"latest":"0.3.0"},"versions":{"0.1.0":{"name":"playwright-parallel-mcp","version":"0.1.0","keywords":["mcp","model-context-protocol","browser-automation","playwright","claude","ai-agent","parallel","isolated-sessions"],"author":{"name":"sumyapp"},"license":"MIT","_id":"playwright-parallel-mcp@0.1.0","maintainers":[{"name":"sumyapp","email":"sumysolonet@gmail.com"}],"homepage":"https://github.com/sumyapp/playwright-parallel-mcp#readme","bugs":{"url":"https://github.com/sumyapp/playwright-parallel-mcp/issues"},"bin":{"playwright-parallel-mcp":"dist/index.js"},"dist":{"shasum":"24b647872b32d4a8183b979312417989097ca1a9","tarball":"https://registry.npmjs.org/playwright-parallel-mcp/-/playwright-parallel-mcp-0.1.0.tgz","fileCount":8,"integrity":"sha512-rXVrP4S1hJgm2snhZYaUAZ4rTpfjMktJdy2lVkK6VLseWtss2lyAmdeZjgeUwdoikmMVNUEvLJDZ9oEoCVdpYA==","signatures":[{"sig":"MEUCIDkwNJmziac95EIy5wkQYrbEnGizhgmMdi4nlrrq8YSdAiEA1nFljsS/1TKxNTUY2CvggxgmEexUXYN+5X2q9rkLwGE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":197967},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20"},"gitHead":"a345fe7b6b9ce939f45b586c6bb39d77eaa439c2","scripts":{"dev":"tsup --watch","test":"vitest","build":"tsup","start":"node dist/index.js","typecheck":"tsc --noEmit","prepublishOnly":"pnpm build"},"_npmUser":{"name":"sumyapp","email":"sumysolonet@gmail.com"},"repository":{"url":"git+https://github.com/sumyapp/playwright-parallel-mcp.git","type":"git"},"_npmVersion":"11.6.2","description":"MCP server for parallel browser automation with isolated Playwright sessions","directories":{},"_nodeVersion":"25.2.1","dependencies":{"zod":"^3.24.0","playwright":"^1.49.0","zod-to-json-schema":"^3.25.1","@modelcontextprotocol/sdk":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.0","vitest":"^2.1.0","typescript":"^5.7.0","@types/node":"^22.10.0"},"_npmOperationalInternal":{"tmp":"tmp/playwright-parallel-mcp_0.1.0_1767062836688_0.4223562831033427","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"playwright-parallel-mcp","version":"0.2.0","keywords":["mcp","model-context-protocol","browser-automation","playwright","claude","ai-agent","parallel","isolated-sessions"],"author":{"name":"sumyapp"},"license":"MIT","_id":"playwright-parallel-mcp@0.2.0","maintainers":[{"name":"sumyapp","email":"sumysolonet@gmail.com"}],"homepage":"https://github.com/sumyapp/playwright-parallel-mcp#readme","bugs":{"url":"https://github.com/sumyapp/playwright-parallel-mcp/issues"},"bin":{"playwright-parallel-mcp":"dist/index.js"},"dist":{"shasum":"e92c893a9597c45efa394359d6834a32be9a1618","tarball":"https://registry.npmjs.org/playwright-parallel-mcp/-/playwright-parallel-mcp-0.2.0.tgz","fileCount":8,"integrity":"sha512-CPIkJwpv4++OajTbj7fQxLBPhOpjvcqDYYOuSbuxU7mvjl3XF8k+NUCeHme4uztaRCJ0P3BMU0Tfj+Z3Osq6cw==","signatures":[{"sig":"MEQCIACalGXfl+3hktWAVOH/d7+FZA2Ntz42NabdfxYicXouAiBHdiVkDA5dXcGSFspVek+/udVE3la+W1QmGKZ+xpXLkQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":216248},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20"},"gitHead":"3f583b4a483295757ac6911cabd6d1b1b616cf85","scripts":{"dev":"tsup --watch","test":"vitest","build":"tsup","start":"node dist/index.js","typecheck":"tsc --noEmit","prepublishOnly":"pnpm build"},"_npmUser":{"name":"sumyapp","email":"sumysolonet@gmail.com"},"repository":{"url":"git+https://github.com/sumyapp/playwright-parallel-mcp.git","type":"git"},"_npmVersion":"11.6.2","description":"MCP server for parallel browser automation with isolated Playwright sessions","directories":{},"_nodeVersion":"25.2.1","dependencies":{"zod":"^3.24.0","playwright":"^1.49.0","zod-to-json-schema":"^3.25.1","@modelcontextprotocol/sdk":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.0","vitest":"^2.1.0","typescript":"^5.7.0","@types/node":"^22.10.0","@vitest/coverage-v8":"^2.1.9"},"_npmOperationalInternal":{"tmp":"tmp/playwright-parallel-mcp_0.2.0_1767260249054_0.3093477642104894","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"playwright-parallel-mcp","version":"0.3.0","description":"MCP server for parallel browser automation with isolated Playwright sessions","type":"module","bin":{"playwright-parallel-mcp":"dist/index.js"},"main":"./dist/index.js","types":"./dist/index.d.ts","scripts":{"build":"tsup","dev":"tsup --watch","start":"node dist/index.js","test":"vitest","typecheck":"tsc --noEmit","prepublishOnly":"pnpm build"},"keywords":["mcp","model-context-protocol","browser-automation","playwright","claude","ai-agent","parallel","isolated-sessions"],"author":{"name":"sumyapp"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/sumyapp/playwright-parallel-mcp.git"},"engines":{"node":">=20"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","zod":"^3.24.0"},"devDependencies":{"@types/node":"^22.10.0","@vitest/coverage-v8":"^2.1.9","tsup":"^8.3.0","typescript":"^5.7.0","vitest":"^2.1.0"},"gitHead":"3f583b4a483295757ac6911cabd6d1b1b616cf85","_id":"playwright-parallel-mcp@0.3.0","bugs":{"url":"https://github.com/sumyapp/playwright-parallel-mcp/issues"},"homepage":"https://github.com/sumyapp/playwright-parallel-mcp#readme","_nodeVersion":"25.2.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-H05m17H0xg0cNzI1sARko9m4O/kmDJau0ZyGLBKi3gXqZ0wNlvYOAfWvTtbzOQkMpCL/O5mJZMHhV+rjdDs5IA==","shasum":"1c7988e6e0ed8bd66afb54548f4d4a333b9525bc","tarball":"https://registry.npmjs.org/playwright-parallel-mcp/-/playwright-parallel-mcp-0.3.0.tgz","fileCount":8,"unpackedSize":93366,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCn0RxjjTzsa9djJEB+M7cdKYEYgJuTGqV2yW1oMDSq6AIgDsHHLGMyuv4M0/hK/FZUHWFEllCTJX5xnRWAijCoaOc="}]},"_npmUser":{"name":"sumyapp","email":"sumysolonet@gmail.com"},"directories":{},"maintainers":[{"name":"sumyapp","email":"sumysolonet@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/playwright-parallel-mcp_0.3.0_1767283297205_0.22742592589553046"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-30T02:47:16.590Z","modified":"2026-01-01T16:01:37.598Z","0.1.0":"2025-12-30T02:47:16.843Z","0.2.0":"2026-01-01T09:37:29.227Z","0.3.0":"2026-01-01T16:01:37.398Z"},"bugs":{"url":"https://github.com/sumyapp/playwright-parallel-mcp/issues"},"author":{"name":"sumyapp"},"license":"MIT","homepage":"https://github.com/sumyapp/playwright-parallel-mcp#readme","keywords":["mcp","model-context-protocol","browser-automation","playwright","claude","ai-agent","parallel","isolated-sessions"],"repository":{"type":"git","url":"git+https://github.com/sumyapp/playwright-parallel-mcp.git"},"description":"MCP server for parallel browser automation with isolated Playwright sessions","maintainers":[{"name":"sumyapp","email":"sumysolonet@gmail.com"}],"readme":"# playwright-parallel-mcp\n\n[![CI](https://github.com/sumyapp/playwright-parallel-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/sumyapp/playwright-parallel-mcp/actions/workflows/ci.yml)\n[![Coverage Status](https://coveralls.io/repos/github/sumyapp/playwright-parallel-mcp/badge.svg?branch=main)](https://coveralls.io/github/sumyapp/playwright-parallel-mcp?branch=main)\n[![npm version](https://badge.fury.io/js/playwright-parallel-mcp.svg)](https://www.npmjs.com/package/playwright-parallel-mcp)\n\n[English](README.md) | [日本語](README.ja.md) | **[中文](README.zh.md)**\n\n一个MCP（Model Context Protocol）服务器，使AI代理能够并行控制**多个独立的浏览器实例**。\n\n## 安全警告\n\n> **此MCP服务器提供强大的浏览器自动化功能，如果暴露给不受信任的用户可能会被滥用。**\n\n- **`run_script`**：在浏览器上下文中执行任意JavaScript\n- **`upload_file`**：访问文件系统进行文件上传\n- **`generate_pdf`** / **`add_init_script`**：（仅Full模式）额外的文件系统访问和脚本注入功能\n\n**请勿将此服务器暴露给不受信任的用户或AI代理。** 仅在您信任所有可连接客户端的受控环境中使用。\n\n## 问题\n\n现有的浏览器自动化MCP服务器（Chrome DevTools MCP、Playwright MCP）在所有会话之间共享单个浏览器实例，当多个AI代理尝试同时使用时会导致冲突。\n\n## 解决方案\n\nplaywright-parallel-mcp为**每个会话创建隔离的浏览器实例**，实现真正的并行浏览器自动化。\n\n## 会话隔离保证\n\n**每个会话100%隔离。** 这在架构层面得到保证，并通过全面的测试进行验证。\n\n### 架构\n\n```\n会话A                        会话B                        会话C\n    │                            │                            │\n    ▼                            ▼                            ▼\n┌─────────┐                ┌─────────┐                ┌─────────┐\n│ 浏览器  │                │ 浏览器  │                │ 浏览器  │\n│  进程   │                │  进程   │                │  进程   │\n│  (OS)   │                │  (OS)   │                │  (OS)   │\n└────┬────┘                └────┬────┘                └────┬────┘\n     │                          │                          │\n     ▼                          ▼                          ▼\n┌─────────┐                ┌─────────┐                ┌─────────┐\n│  上下文  │                │  上下文  │                │  上下文  │\n│(Cookie) │                │(Cookie) │                │(Cookie) │\n└────┬────┘                └────┬────┘                └────┬────┘\n     │                          │                          │\n     ▼                          ▼                          ▼\n┌─────────┐                ┌─────────┐                ┌─────────┐\n│  页面   │                │  页面   │                │  页面   │\n│ (DOM)   │                │ (DOM)   │                │ (DOM)   │\n└─────────┘                └─────────┘                └─────────┘\n```\n\n### 隔离的资源\n\n| 资源 | 隔离? | 方式 |\n|------|-------|------|\n| 浏览器进程 | ✅ 是 | 每个会话独立的OS进程 |\n| Cookie | ✅ 是 | 独立的BrowserContext |\n| localStorage | ✅ 是 | 独立的BrowserContext |\n| sessionStorage | ✅ 是 | 独立的BrowserContext |\n| DOM | ✅ 是 | 独立的Page实例 |\n| 导航历史 | ✅ 是 | 独立的Page实例 |\n| 控制台日志 | ✅ 是 | 按会话存储 |\n| 网络日志 | ✅ 是 | 按会话存储 |\n\n### 测试覆盖\n\n会话隔离通过**17个专用测试**进行验证：\n\n- 浏览器进程隔离\n- 导航隔离\n- DOM隔离\n- Cookie隔离\n- localStorage/sessionStorage隔离\n- 控制台日志隔离\n- 网络日志隔离\n- 并发操作安全性\n- 会话ID唯一性（UUID v4）\n\n运行 `pnpm test` 验证隔离保证。\n\n## 特性\n\n- **并行会话** - 每个会话拥有自己的浏览器实例\n- **多浏览器支持** - 支持Chromium、Firefox、WebKit\n- **22个工具** - 基本的浏览器自动化功能（Full模式63个）\n- **低上下文使用量** - 约14k令牌（与@playwright/mcp相当）\n- **控制台日志** - 捕获控制台输出用于调试\n- **对话框处理** - 处理alert、confirm、prompt对话框\n- **无障碍快照** - ARIA快照格式（Playwright 1.49+）\n- **免费且本地** - 无需云服务\n\n## 安装\n\n### 与Claude Code一起使用\n\n添加到MCP设置：\n\n```json\n{\n  \"mcpServers\": {\n    \"playwright-parallel\": {\n      \"command\": \"npx\",\n      \"args\": [\"playwright-parallel-mcp\"]\n    }\n  }\n}\n```\n\n### 使用npm\n\n```bash\nnpm install -g playwright-parallel-mcp\nplaywright-parallel-mcp\n```\n\n## 可用工具（22个）\n\n### 会话管理（3个）\n| 工具 | 描述 |\n|------|------|\n| `create_session` | 创建新的隔离浏览器会话（chromium/firefox/webkit） |\n| `close_session` | 关闭浏览器会话 |\n| `list_sessions` | 列出所有活动会话 |\n\n### 导航（4个）\n| 工具 | 描述 |\n|------|------|\n| `navigate` | 导航到URL |\n| `go_back` | 浏览器历史后退 |\n| `reload` | 重新加载当前页面 |\n| `get_url` | 获取当前URL和页面标题 |\n\n### 页面检查（2个）\n| 工具 | 描述 |\n|------|------|\n| `snapshot` | 获取无障碍树（ARIA快照格式） |\n| `screenshot` | 截图（PNG/JPEG，全页或元素） |\n\n### 用户交互（6个）\n| 工具 | 描述 |\n|------|------|\n| `click` | 点击元素（左/右/中键） |\n| `fill` | 向表单输入框填充文本 |\n| `type` | 模拟真实的逐键输入 |\n| `press_key` | 按键盘键（如Enter、Control+A） |\n| `hover` | 悬停在元素上 |\n| `select_option` | 从下拉菜单选择 |\n\n### 其他工具（7个）\n| 工具 | 描述 |\n|------|------|\n| `wait_for_timeout` | 等待指定时间 |\n| `set_dialog_handler` | 配置自动对话框处理（接受/拒绝） |\n| `upload_file` | 向文件输入元素上传文件 |\n| `drag_and_drop` | 拖放元素到另一个元素 |\n| `run_script` | 在浏览器上下文中执行JavaScript |\n| `get_console_logs` | 获取控制台日志（log/info/warn/error/debug） |\n| `set_viewport` | 更改视口大小 |\n\n## 使用示例\n\n### 基本导航\n\n```\n用户：打开example.com并截图\n\nClaude：我将创建一个浏览器会话并导航到example.com。\n\n[create_session] -> sessionId: \"abc123\"\n[navigate sessionId=\"abc123\" url=\"https://example.com\"]\n[screenshot sessionId=\"abc123\"]\n```\n\n### 并行会话\n\n```\n用户：并排比较两个网站的主页\n\nClaude：我将并行创建两个浏览器会话。\n\n[create_session] -> sessionId: \"session-a\"\n[create_session] -> sessionId: \"session-b\"\n[navigate sessionId=\"session-a\" url=\"https://example.com\"]\n[navigate sessionId=\"session-b\" url=\"https://google.com\"]\n[snapshot sessionId=\"session-a\"]\n[snapshot sessionId=\"session-b\"]\n```\n\n### 表单交互\n\n```\n用户：填写登录表单\n\nClaude：我将填写表单字段并提交。\n\n[fill sessionId=\"abc123\" selector=\"input[name='email']\" value=\"user@example.com\"]\n[fill sessionId=\"abc123\" selector=\"input[name='password']\" value=\"***\"]\n[click sessionId=\"abc123\" selector=\"button[type='submit']\"]\n```\n\n### 控制台日志\n\n```\n用户：检查页面的控制台输出\n\nClaude：我将检查控制台日志和错误。\n\n[get_console_logs sessionId=\"abc123\" types=[\"error\", \"warn\"]]\n```\n\n### 对话框处理\n\n```\n用户：处理确认对话框\n\nClaude：我将设置自动对话框处理。\n\n[set_dialog_handler sessionId=\"abc123\" autoRespond=true accept=true]\n[click sessionId=\"abc123\" selector=\"#delete-button\"]\n```\n\n## 工具参考\n\n### create_session\n\n创建新的隔离浏览器会话。\n\n**参数：**\n- `browser`（可选）：\"chromium\" | \"firefox\" | \"webkit\"（默认：\"chromium\"）\n- `headless`（可选）：boolean（默认：true）\n- `viewport`（可选）：{ width: number, height: number }\n\n**返回：** `{ sessionId, browser, createdAt }`\n\n### navigate\n\n导航到URL。\n\n**参数：**\n- `sessionId`：string\n- `url`：string（有效URL）\n- `waitUntil`（可选）：\"load\" | \"domcontentloaded\" | \"networkidle\"（默认：\"load\"）\n\n**返回：** `{ url, title, status }`\n\n### snapshot\n\n获取ARIA快照格式的无障碍树。\n\n**参数：**\n- `sessionId`：string\n\n**返回：** YAML格式的无障碍树\n\n### run_script\n\n在浏览器上下文中执行JavaScript。\n\n**参数：**\n- `sessionId`：string\n- `expression`：要评估的JavaScript表达式\n\n**返回：** `{ success: boolean, result?: any, error?: string }`\n\n## 比较\n\n| 功能 | Chrome DevTools MCP | Playwright MCP | **本项目** |\n|------|---------------------|----------------|-----------|\n| 并行会话 | 无 | 无 | **有** |\n| 会话隔离 | 无 | 无 | **有（API级别）** |\n| 工具数量 | 约26 | 约22 | **22（Lite）/ 63（Full）** |\n| 上下文令牌 | 约17k | 约14k | **约14k（Lite）/ 约40k（Full）** |\n| 控制台日志 | 有 | 有 | **有** |\n| 对话框处理 | 有 | 无 | **有** |\n| JavaScript执行 | 有 | 有 | **有** |\n| 文件上传 | 无 | 有 | **有** |\n| 费用 | 免费 | 免费 | **免费** |\n\n### 上下文令牌使用量（实测）\n\n在Claude Code中作为MCP工具加载时的令牌消耗（`/context`命令）：\n\n| MCP服务器 | 工具数 | 总令牌 | 平均/工具 |\n|----------|--------|--------|----------|\n| **playwright-parallel-mcp (Lite)** | 22 | 约14,000 | 640 |\n| **playwright-parallel-mcp (Full)** | 63 | 40,343 | 640 |\n| [@playwright/mcp](https://github.com/microsoft/playwright-mcp) | 22 | 14,534 | 661 |\n| [chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp) | 26 | 17,668 | 680 |\n\n> **Lite模式（默认）** 提供与@playwright/mcp相同的工具数量和相当的令牌使用量，同时添加了用于并行执行的会话隔离。\n\n## 环境变量\n\n| 变量 | 默认值 | 描述 |\n|------|--------|------|\n| `PLAYWRIGHT_PARALLEL_MODE` | `lite` | 模式：`lite`（22个工具）或 `full`（63个工具） |\n| `MAX_SESSIONS` | 10 | 最大并发浏览器会话数 |\n| `SESSION_TIMEOUT_MS` | 3600000 | 会话不活动超时（1小时） |\n\n## 要求\n\n- Node.js 20+\n- Playwright浏览器（自动安装）\n\n## 开发\n\n```bash\ngit clone https://github.com/sumyapp/playwright-parallel-mcp\ncd playwright-parallel-mcp\npnpm install\npnpm build\npnpm start\n```\n\n### 运行测试\n\n```bash\npnpm test\n```\n\n### 项目结构\n\n```\nsrc/\n  index.ts          # MCP服务器入口点，所有工具定义\n  session-manager.ts # 浏览器会话生命周期管理\n```\n\n## Full模式\n\nFull模式提供**无法用`run_script`替代**的功能，对特定用例至关重要。\n\n### 何时使用Full模式\n\n| 用例 | 所需工具 | 为什么run_script无法替代 |\n|------|----------|------------------------|\n| **API监控** | `get_network_logs` | 捕获所有HTTP请求/响应，包括头信息、时间和状态码 |\n| **性能分析** | `get_metrics` | 访问Navigation Timing API、内存使用、绘制指标 |\n| **PDF报告生成** | `generate_pdf` | 带页面格式选项的浏览器级PDF渲染 |\n| **iframe自动化** | `frame_click`, `frame_fill` | 访问JavaScript无法触及的跨域iframe |\n| **JS错误检测** | `get_page_errors` | 在丢失之前捕获未捕获的异常 |\n| **无障碍审计** | `get_accessibility_tree` | 用于合规测试的完整ARIA树结构 |\n\n### 示例：使用网络日志进行API测试\n\n```\n用户：测试登录API并验证响应\n\nClaude：我将监控登录期间的网络请求。\n\n[get_network_logs sessionId=\"abc\" resourceTypes=[\"fetch\",\"xhr\"]]\n→ 捕获：POST /api/login (200, 145ms, 响应体可用)\n```\n\n这是`run_script`无法做到的，因为：\n- Fetch/XHR拦截需要在请求之前设置\n- 响应体在完成后无法访问\n- 时间信息会丢失\n\n### 配置\n\n```json\n{\n  \"mcpServers\": {\n    \"playwright-parallel\": {\n      \"command\": \"npx\",\n      \"args\": [\"playwright-parallel-mcp\"],\n      \"env\": {\n        \"PLAYWRIGHT_PARALLEL_MODE\": \"full\"\n      }\n    }\n  }\n}\n```\n\n### 额外工具（41个，约40k令牌）\n\n<details>\n<summary>点击展开完整工具列表</summary>\n\n- **导航**：go_forward\n- **页面检查**：get_content, get_html\n- **用户交互**：check, uncheck\n- **等待工具**：wait_for_selector, wait_for_load_state, wait_for_url, wait_for_function\n- **对话框**：get_dialogs\n- **元素状态**：get_element_state, get_attribute, get_bounding_box, count_elements, get_all_texts\n- **滚动**：scroll, scroll_into_view\n- **鼠标**：mouse_move, mouse_click, mouse_down, mouse_up, mouse_wheel\n- **模拟**：set_geolocation, set_offline, set_extra_http_headers\n- **存储/Cookie**：get_cookies, set_cookies, get_storage, set_storage\n- **网络**：get_network_logs\n- **PDF/Frame**：generate_pdf, list_frames, frame_click, frame_fill, frame_get_content\n- **调试**：get_page_errors, clear_logs, expose_function, add_init_script, get_metrics, get_accessibility_tree\n\n</details>\n\n## 许可证\n\nMIT\n","readmeFilename":"README.zh.md"}