项目概览与系统架构

项目定位与目标

mcp-playwright（npm 包名 @executeautomation/playwright-mcp-server）是一个基于 Model Context Protocol (MCP) 标准的服务器，将 Playwright 的浏览器自动化能力与 HTTP 客户端能力以一组 MCP 工具的形式暴露给大语言模型客户端（如 Claude Desktop、Claude Code、VS Code Copilot 等）。其核心目标是把"驱动浏览器"和"发起 HTTP 请求"这两类传统上需要脚本或框架才能完成的任务，统一成可通过自然语言调用的 MCP 工具集。

从依赖层面看，服务器运行在 Node.js 之上，绑定了 @modelcontextprotocol/[email protected] 与 [email protected]，并显式声明了三家浏览器引擎的二进制包（Chromium / Firefox / WebKit）。资料来源：package.json:15-30。这意味着项目既强调协议兼容性，也强调多浏览器覆盖——在 CHANGELOG 中 1.0.2 版本正式加入的 "Multi-Browser Support" 印证了这一点。资料来源：CHANGELOG.md:36-42。

社区方面，README 明确提供了 npm、Smithery、VS Code CLI、Claude Code 多种安装路径，说明其面向的是需要"开箱即用"接入到各类 MCP 客户端的用户群。资料来源：README.md:7-35。

核心组件分层

项目的源码组织呈现出清晰的"协议层 → 工具编排层 → 浏览器/API 实现层 → 基础设施层（监控/日志）"的分层结构。

graph TB
    subgraph "协议层"
        MCP[MCP SDK 1.24.3<br/>stdio / HTTP 传输]
    end
    subgraph "工具编排层"
        Tools[src/tools.ts<br/>BROWSER_TOOLS / API_TOOLS / CODEGEN_TOOLS]
    end
    subgraph "实现层"
        BrowserTools[src/tools/browser/<br/>BrowserToolBase]
        ApiTools[src/tools/api/<br/>ApiToolBase + requests.ts]
    end
    subgraph "基础设施"
        Logger[src/logging/logger.ts]
        Monitor[src/monitoring/types.ts]
    end
    MCP --> Tools
    Tools --> BrowserTools
    Tools --> ApiTools
    BrowserTools -.日志/监控.-> Logger
    ApiTools -.日志/监控.-> Monitor

关键抽象位于 src/tools/common/types.ts，其中定义了所有工具必须遵守的 ToolHandler 接口与统一的 ToolResponse 响应结构（含 content 与 isError 字段），并通过 createSuccessResponse / createErrorResponse 工厂函数规范返回值。资料来源：src/tools/common/types.ts:6-44。

在该统一接口之上，浏览器类工具继承 BrowserToolBase 抽象基类。基类通过 ensurePage / validatePageAvailable 强制要求 ToolContext 中必须存在可用的 Page 对象，并在 safeExecute 中统一封装异常处理逻辑，避免每个工具重复实现样板代码。资料来源：src/tools/browser/base.ts:6-72。API 工具侧则使用 ApiToolBase + BaseRequestArgs / RequestWithBodyArgs 接口，配合 parseJsonSafely 与 buildHeaders 辅助函数实现 JSON 解析与请求头合并。资料来源：src/tools/api/requests.ts:14-50。

工具集与执行模型

src/tools.ts 集中维护了所有 MCP 工具的元数据与分组：

资料来源：src/tools.ts:90-115。这种"按需启动"的执行模型来自 BrowserToolBase 中的 context.page 校验：若页面尚未初始化，工具会以错误响应要求用户先调用 playwright_navigate 或类似入口。资料来源：src/tools/browser/base.ts:28-50。社区 issue #155 反馈的"Chromium 异常退出导致进程卡住"现象，正是源自该执行链路中浏览器状态未被及时清理。资料来源：GitHub Issue #155。

API 工具的请求体解析同时支持字符串与对象两种形态——parseJsonSafely 会先尝试 JSON.parse，失败时回退为原始字符串并打印 console.warn，确保不会因格式问题直接抛出未捕获异常。资料来源：src/tools/api/requests.ts:26-40。该策略也与 buildHeaders 中"自定义 Authorization 头会覆盖 token 参数"的设计一致，给上层提示但不阻断请求。资料来源：src/tools/api/requests.ts:42-58。

传输、可观测性与版本演进

README 显示服务器同时支持 stdio（标准模式）与 HTTP 模式：HTTP 模式通过 Express 提供 /mcp 端点，并附带一个动态端口分配的监控子系统，用于无头环境、VS Code Copilot 集成和远程调试场景。资料来源：README.md:50-95。src/monitoring/types.ts 定义了 Metrics、HealthStatus、MonitoringConfig 三类核心数据结构，涵盖请求计数、活跃浏览器实例数、内存使用、限流违规等维度。资料来源：src/monitoring/types.ts:5-50。

日志侧采用单例 + 工厂模式（Logger.getInstance / Logger.createDefaultConfig），配置项支持 LOG_LEVEL、LOG_FORMAT、LOG_OUTPUTS 等环境变量，输出目标可在 console 与 file 之间组合，并具备文件大小与保留数量的轮转参数。资料来源：src/logging/logger.ts:1-50。

从版本演进看，1.0.12 加入了"自动浏览器二进制安装"能力（installBrowsers 函数 + 2 分钟超时保护），解决了社区 issue #117 中"Playwright 要求特定浏览器版本"导致首次启动失败的痛点。资料来源：CHANGELOG.md:5-22。同期升级了 MCP SDK（1.11.1 → 1.24.3）以引入流式 HTTP 传输，从而支撑 issue #168 / #181 中长期被社区要求的 HTTP 模式。资料来源：CHANGELOG.md:24-28、GitHub Issue #168。

测试方面，项目使用 Jest 套件并通过独立的 tsconfig.test.json 放宽类型检查，以便测试代码中频繁使用 any/null 场景下的浏览器状态模拟。资料来源：tsconfig.test.json:1-9。

See Also

• 工具注册与分组（src/tools.ts）
• 工具统一接口与响应类型（src/tools/common/types.ts）
• 浏览器工具基类（src/tools/browser/base.ts）
• HTTP API 请求工具（src/tools/api/requests.ts）
• 监控指标类型定义（src/monitoring/types.ts）
• 结构化日志（src/logging/logger.ts）

工具目录、浏览器引擎与设备仿真

概述

mcp-playwright 通过 Model Context Protocol（MCP）将 Playwright 的浏览器自动化能力与 HTTP 请求能力以约 34 个 playwright_* 工具的形式暴露给大语言模型客户端（如 Claude Desktop、VS Code Copilot、Claude Code）。所有工具的注册表与能力清单集中在 src/tools.ts，执行派发则由 src/toolHandler.ts 统一调度。系统按工具对浏览器或网络上下文的依赖将其划分为 BROWSER_TOOLS 与 API_TOOLS 两组，并在工具首次被调用时按需懒加载 Chromium/Firefox/WebKit 引擎。

工具目录与注册机制

能力清单

工具清单通过数组常量和 JSON Schema 形式集中维护在 src/tools.ts 的 BROWSER_TOOLS 与导出列表中，覆盖导航、交互、断言、输出、内容提取等类别。例如 playwright_navigate、playwright_click、playwright_fill、playwright_evaluate、playwright_save_as_pdf、playwright_click_and_switch_tab 等都通过 as const satisfies Tool[] 进行类型约束的注册。下方表格节选了与浏览器引擎强相关的工具入口：

资料来源：src/tools.ts

响应与上下文模型

所有工具统一实现 src/tools/common/types.ts 中的 ToolHandler 接口，并返回符合 MCP CallToolResult 的 ToolResponse。上下文 ToolContext 持有懒加载的 page、browser、apiContext，使浏览器工具与 HTTP API 工具复用同一调度管线。createErrorResponse 与 createSuccessResponse 两个工厂方法保证错误与成功响应结构一致，便于客户端解析。

浏览器引擎与生命周期管理

三引擎懒加载

src/toolHandler.ts 通过 import { chromium, firefox, webkit, request } from 'playwright' 引入三大浏览器引擎，并按 browserType 参数按需创建实例；自 v1.0.2 起，Chromium/Firefox/WebKit 均受支持（参见 CHANGELOG.md）。

连接断开与状态复位

浏览器进程在长时间运行或客户端异常退出时容易断开，NavigationTool 与 VisibleTextTool 都会先调用 browser.isConnected() 与 page.isClosed() 进行健康检查；一旦发现已断开，会调用 resetBrowserState() 强制下次重建上下文并返回友好错误。错误分支同时识别 Target page, context or browser has been closed、Target closed、Browser has been disconnected 三类典型异常（参见 src/tools/browser/navigation.ts）。

全局页面引用切换

ClickAndSwitchTabTool 通过 page.context().waitForEvent('page') 监听新 Tab 后，调用 setGlobalPage(newPage) 切换全局页面引用，实现多 Tab 会话追踪（参见 src/tools/browser/interaction.ts）。

flowchart TD
    A[LLM 调用 playwright_*] --> B{工具属于 BROWSER_TOOLS?}
    B -- 否 --> C[APIRequestContext 执行]
    B -- 是 --> D{浏览器已连接?}
    D -- 否 --> E[resetBrowserState 并报错]
    D -- 是 --> F{页面有效?}
    F -- 否 --> G[返回错误并提示重试]
    F -- 是 --> H[safeExecute 调用 Playwright]
    H --> I[createSuccess/createError 返回 MCP 结果]

设备仿真与视口控制

src/tools/browser/resize.ts 通过 playwright_resize 暴露设备仿真能力：若提供 device 参数则从 Playwright 内置 devices 表中匹配，否则按 width/height 自定义视口；当设备名拼写错误时，工具会列出 iPhone 13、iPad Pro 11、Pixel 7、Galaxy S24 等热门预设作为建议。匹配成功后，工具同时下发 viewport、userAgent、isMobile、hasTouch、deviceScaleFactor 五个字段，使浏览器同时模拟移动端特性与像素比。CustomUserAgentTool（src/tools/browser/useragent.ts）则用于在浏览器已启动后校验当前 navigator.userAgent 是否与请求一致——若不一致返回错误提示，由 LLM 决策是否重置引擎后再启动。

工具基类、错误处理与社区反馈

BrowserToolBase（src/tools/browser/base.ts）与 ApiToolBase（src/tools/api/base.ts）分别承担浏览器与 API 工具的公共职责：ensurePage/ensureApiContext 校验上下文，validatePageAvailable 返回结构化错误，safeExecute 包裹执行业务并统一异常处理。parseJsonSafely 与 buildHeaders（src/tools/api/requests.ts）则为 GET/POST/PUT/PATCH/DELETE 提供 JSON 解析与 Bearer token/自定义 Header 合并能力，并对自定义 Header 覆盖 Authorization 给出警告。

社区讨论集中在几个长期痛点：

• 浏览器版本不匹配（#117）：@executeautomation/playwright-mcp-server 通过 npx -y 拉取的 Playwright 版本可能与本地 chromium-XXXX 修订号不一致，需保持 npm install playwright 与 MCP 包版本同步。
• Chromium 静默断开导致 LLM 卡死（#155）：playwright_close() 与异常关闭场景需要返回明确错误，safeExecute 与 resetBrowserState 即为对此的防护。
• HTTPS 证书错误（#202）：当前未直接暴露 --ignore-https-errors，需在启动时通过额外参数注入。
• 代理与 storageState（#203）：浏览器启动阶段未原生支持预加载 Cookie 与代理，仍依赖 Playwright 工程化能力扩展。

See Also

• HTTP 传输与监控
• API Reference
• Device Quick Reference
• CHANGELOG

部署、传输协议与客户端配置

1. 概述与作用域

@executeautomation/playwright-mcp-server 是一个基于 Model Context Protocol (MCP) 的服务端实现，充当大型语言模型（LLM）客户端与 Playwright 浏览器自动化引擎之间的桥接层。该包的最新发布版本为 1.0.12，入口命令为 playwright-mcp-server（映射到 dist/index.js），其部署形态对部署环境、传输协议选择以及客户端接入方式有明确约束（资料来源：package.json:2-12）。

本页聚焦以下三个核心维度：

• 部署（Deployment）：包括本地 npm 全局安装、Docker 容器化以及 npx 临时调用。
• 传输协议（Transports）：服务器同时支持 stdio（标准输入/输出）与 http（基于 HTTP/SSE 的流式传输）两种 MCP 传输方式。
• 客户端配置（Client Configuration）：涵盖 Claude Desktop、VS Code、Claude Code、Smithery 等常见 MCP 客户端的接入。

graph LR
    A[LLM 客户端<br/>Claude Desktop / VS Code] -->|stdio| B[playwright-mcp-server]
    A -->|http+sessionId| B
    B --> C[Playwright Browser<br/>chromium/firefox/webkit]
    B --> D[MonitoringSystem<br/>动态端口]
    B --> E[Logger<br/>控制台/文件]

2. 传输协议（Transports）

2.1 stdio 模式（默认）

stdio 模式通过 npx @executeautomation/playwright-mcp-server 直接启动，由 MCP 客户端通过标准输入输出与服务器通信（资料来源：README.md）。该模式是 Claude Desktop 的推荐方式——README 明确指出 “For Claude Desktop, continue using stdio mode (Standard Mode above) for now”。stdio 的优势在于无需端口管理、无网络暴露面，适合单机开发与隐私敏感场景。

2.2 HTTP 模式

服务器同时支持 HTTP 传输，默认绑定到 localhost:8931/mcp 端点（资料来源：README.md）。该模式在 README 中标注的典型使用场景包括：

• 无显示器环境（远程服务器）下运行有头浏览器；
• 与 VS Code GitHub Copilot 集成；
• 作为后台服务运行并支持多客户端访问；
• 通过 /health 端点进行调试。

2.3 监控与日志子系统

MonitoringSystem（位于 src/monitoring/system.ts）以动态分配端口方式启动 HTTP 端点，避免与现有服务冲突；实际的监控端口会输出到控制台。该类维护 Metrics 与 HealthStatus 数据结构，记录 requestCount、errorCount、averageResponseTime、activeBrowsers、activeConnections、rateLimitViolations 等关键指标（资料来源：src/monitoring/types.ts:5-17）。日志方面，Logger 单例支持 LOG_LEVEL、LOG_FORMAT、LOG_OUTPUTS、LOG_FILE_PATH 等环境变量配置，可同时输出到控制台与文件（资料来源：src/logging/logger.ts:39-48）。

2.4 常见错误：会话未注册

当使用 HTTP 模式时，客户端必须显式声明 "type": "http"，否则会触发 400 Bad Request: No transport found for sessionId。正确的客户端 JSON 配置示例（资料来源：README.md）：

{
  "url": "http://localhost:8931/mcp",
  "type": "http"
}

服务器端的成功握手日志应当按顺序包含：Incoming request → Transport registered (含 sessionId) → POST message received (相同 sessionId)。

3. 客户端配置

3.1 Claude Desktop

通过 Smithery 自动安装：

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

或手动在 Claude Desktop 配置中加入（资料来源：README.md）：

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

3.2 Claude Code

通过官方 CLI 一行命令完成注册（资料来源：README.md）：

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

3.3 VS Code / VS Code Insiders

README 提供了两种 “Install Server” 徽章链接，指向 vscode:mcp/install?... 协议 URL。底层使用同一份配置 npx -y @executeautomation/playwright-mcp-server，点击后会通过 vscode.dev/redirect 中转并写入 VS Code 的 MCP 配置（资料来源：README.md）。

3.4 mcp-get

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

3.5 工具注册与启动

服务器在启动时按条件分组工具：BROWSER_TOOLS（如 playwright_navigate、playwright_screenshot、playwright_click_and_switch_tab 等）需要先启动浏览器实例；API_TOOLS（playwright_get / _post / _put / _delete / _patch）创建 APIRequestContext；CODEGEN_TOOLS（start_codegen_session 等）用于录制回放（资料来源：src/tools.ts:1-50）。这种分层结构使得 HTTP/stdio 客户端可以按需冷启动对应的执行环境。

4. 部署考量与社区关注点

4.1 浏览器自动安装

自 1.0.12 起，服务器在首次启动时自动检测并安装缺失的浏览器二进制（Chromium / Firefox / WebKit），具有 2 分钟超时保护与降级提示（资料来源：CHANGELOG.md:1-9）。这一变更直接回应了社区问题 issue #117 中用户遇到的“Playwright 提示需要特定浏览器版本”的体验问题。

4.2 HTTP 暴露与远程访问

社区对 HTTP 模式的需求集中在 issue #168（HTTP/Streamable 支持）与 issue #181（维护活跃度）。README 当前明确：默认仅绑定 localhost，外部访问需通过 SSH 隧道转发：

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

此设计是出于安全考虑——服务器暴露了约 34 个高权限工具（含 playwright_evaluate 任意 JS 执行、API 工具任意 HTTP 请求），社区在 issue #209 与 issue #216 中讨论了 SSRF、Prompt Injection 与策略强制执行风险。

4.3 Kubernetes 与容器化

社区在 issue #175 中提出了 Helm Chart 的需求，目前官方仓库提供 Dockerfile、docker-compose.yml 与 docker-build.sh 三个容器化资产（资料来源：README.md），可直接作为 Kubernetes Deployment 的镜像来源，但需要自行处理 stdio 与 HTTP 模式的探针与 Service 暴露。

5. 故障排查速查表

See Also

• Tools, API and Browser Modules — playwright_* 工具的实现与分组
• Logging & Monitoring — Logger 与 MonitoringSystem 的详细字段
• Security Considerations — SSRF / Prompt Injection 缓解策略

1. 运行时架构与可观测性

服务器暴露的 MCP 工具集合在 src/tools.ts 中明确分三组：浏览器工具 BROWSER_TOOLS（如 playwright_navigate、playwright_click、playwright_evaluate）、HTTP API 工具 API_TOOLS（playwright_get/post/put/patch/delete）以及代码生成工具 CODEGEN_TOOLS（start_codegen_session 等） 资料来源：src/tools.ts。这意味着服务器同时承担浏览器自动化与任意 HTTP 出站请求两类高权限操作。

可观测性由两个独立子系统支撑：

• 结构化日志：src/logging/logger.ts 实现单例 Logger，支持 debug/info/warn/error 四级与 json / text 两种格式，可输出到控制台或文件，并按 maxFileSize / maxFiles 进行轮转 资料来源：src/logging/logger.ts。日志条目结构 LogEntry 包含 requestId、userId、可选 stack，便于跨工具关联 资料来源：src/logging/types.ts。
• 系统监控：src/monitoring/system.ts 中的 MonitoringSystem 记录 requestCount、errorCount、averageResponseTime、activeBrowsers、memoryUsage、activeConnections 与 rateLimitViolations 等指标，并启动一个内部 Express HTTP 服务用于健康检查；端口动态分配以避免冲突 资料来源：src/monitoring/system.ts。配置项 MonitoringConfig 控制采集与健康检查间隔以及内存 / 响应时间阈值 资料来源：src/monitoring/types.ts。

2. 安全态势

服务器在设计上提供的是“带外网出站能力”的工具集，本身并未在源码中实现鉴权、来源白名单或代理控制。社区安全审计（Issue #209）明确指出三类风险：

flowchart LR
    A[MCP 客户端] -->|tool call| B[playwright-mcp-server]
    B -->|playwright_evaluate| C[目标网站 DOM/JS]
    B -->|playwright_get/post/put/patch/delete| D[任意内网/外网 URL]
    B -->|playwright_fill| E[任意表单提交]
    C -.SSRF / Prompt Injection.-> F[(内部服务 / 数据外泄)]
    D -.SSRF.-> F
    E -.凭据外泄.-> F

具体可观察到的代码事实：

• playwright_evaluate 之类工具通过 BrowserToolBase.safeExecute 传递原始 page 对象，并无沙箱或 CSP 注入 资料来源：src/tools/browser/base.ts。
• API 工具允许调用方完全控制 url 与 headers：buildHeaders 允许 customHeaders 覆盖 Authorization，且会发出警告但不阻断 资料来源：src/tools/api/requests.ts。
• 当浏览器断开时，VisibleTextTool 仅在错误信息中提示“连接已重置”，并未阻止后续潜在的危险调用 资料来源：src/tools/browser/visiblePage.ts。
• 当前没有暴露代理（proxy）与预加载 storageState 的官方接口，社区已在 Issue #203 中提出此缺口。
• 同样缺少 --ignore-https-errors 透传通道（Issue #202），用户无法在工具调用层忽略证书错误。

因此，推荐将本服务器视作“受信开发者工具”，仅在受信主机、受信 MCP 客户端上下文中使用，必要时借助宿主层（容器网络策略、出口代理）补足隔离。

3. 常见故障模式

根据源码逻辑与社区反馈，可归纳出以下高频失败场景：

4. 部署与运行模式

服务器同时支持 stdio 与 HTTP/Streamable 两种传输。HTTP 模式适合远程调试、后台服务与 VS Code Copilot 集成；stdio 仍是 Claude Desktop 的推荐方式 资料来源：README.md。HTTP 模式下服务器默认仅绑定 localhost，外部访问需通过 SSH 端口转发。

由于当前版本号已发布至 1.0.x（CHANGELOG.md 记录至 1.0.10，新增设备预设 playwright_resize），同时社区存在 Issue #181 对维护活跃度的关注，运维方在依赖该服务器时，应将“可能存在未及时修复的边缘错误”纳入变更与回滚预案。

See Also

• Tool Reference
• HTTP/Streamable Transport
• Browser Lifecycle Management
• 社区议题：#117 · #155 · #168 · #202 · #203 · #209 · #216

Pitfall Log / 踩坑日志

项目：executeautomation/mcp-playwright

摘要：发现 16 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Playwright is asking for an specific browser version.。

1. 安装坑 · 来源证据：Playwright is asking for an specific browser version.

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Playwright is asking for an specific browser version.
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/executeautomation/mcp-playwright/issues/117 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

2. 安全/权限坑 · 来源证据：How to configure proxy and storageState when launching browser in Playwright MCP?

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：How to configure proxy and storageState when launching browser in Playwright MCP?
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/executeautomation/mcp-playwright/issues/203 | 来源类型 github_issue 暴露的待验证使用条件。

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

• 严重度：medium
• 证据强度：runtime_trace
• 发现：仓库名 mcp-playwright 与安装入口 playwright 不完全一致。
• 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
• 复现命令：npx playwright
• 证据：identity.distribution | https://github.com/executeautomation/mcp-playwright | repo=mcp-playwright; install=playwright

4. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/executeautomation/mcp-playwright | host_targets=mcp_host, claude, cursor, claude_code

5. 配置坑 · 来源证据：Add Clarvia AEO score badge to README (AEO 32/100)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Add Clarvia AEO score badge to README (AEO 32/100)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/executeautomation/mcp-playwright/issues/212 | 来源类型 github_issue 暴露的待验证使用条件。

6. 配置坑 · 来源证据：Add policy enforcement for browser automation and HTTP request tools

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Add policy enforcement for browser automation and HTTP request tools
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/executeautomation/mcp-playwright/issues/216 | 来源类型 github_issue 暴露的待验证使用条件。

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

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/executeautomation/mcp-playwright | README/documentation is current enough for a first validation pass.

8. 运行坑 · 来源证据：How to pass in the `--ignore-https-errors` parameter?

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：How to pass in the --ignore-https-errors parameter?
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/executeautomation/mcp-playwright/issues/202 | 来源类型 github_issue 暴露的待验证使用条件。

9. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/executeautomation/mcp-playwright | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/executeautomation/mcp-playwright | no_demo; severity=medium

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/executeautomation/mcp-playwright | no_demo; severity=medium

12. 安全/权限坑 · 来源证据：Add behavioral trust badge to README

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add behavioral trust badge to README
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/executeautomation/mcp-playwright/issues/220 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

13. 安全/权限坑 · 来源证据：Free MCP security scan report for @executeautomation/playwright-mcp-server

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Free MCP security scan report for @executeautomation/playwright-mcp-server
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/executeautomation/mcp-playwright/issues/211 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

14. 安全/权限坑 · 来源证据：Security Advisory: SSRF, Prompt Injection, and Arbitrary JavaScript Execution via Browser Automation Tools

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security Advisory: SSRF, Prompt Injection, and Arbitrary JavaScript Execution via Browser Automation Tools
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/executeautomation/mcp-playwright/issues/209 | 来源类型 github_issue 暴露的待验证使用条件。

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

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/executeautomation/mcp-playwright | issue_or_pr_quality=unknown

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

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/executeautomation/mcp-playwright | release_recency=unknown