{
"canonical_name": "executeautomation/mcp-playwright",
"compilation_id": "pack_17d0a5c0ef014c96a381a9f747fc5cdd",
"created_at": "2026-05-13T07:44:09.450160+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `npm install -g @executeautomation/playwright-mcp-server` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "npm install -g @executeautomation/playwright-mcp-server",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_9a9097066dab40c087774c0278318a55"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_912bd7b56991af6d0d3cfe53eff810c2",
"canonical_name": "executeautomation/mcp-playwright",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/executeautomation/mcp-playwright",
"slug": "mcp-playwright",
"source_packet_id": "phit_fdf3dd806aa24898a57c59fec49fc279",
"source_validation_id": "dval_f8a266e7fd954a8a844a96cb7b062319"
},
"merchandising": {
"best_for": "需要工具连接与集成能力，并使用 mcp_host的用户",
"github_forks": 510,
"github_stars": 5509,
"one_liner_en": "Playwright Model Context Protocol Server - Tool to automate Browsers and APIs in Claude Desktop, Cline, Cursor IDE and More 🔌",
"one_liner_zh": "Playwright Model Context Protocol Server - Tool to automate Browsers and APIs in Claude Desktop, Cline, Cursor IDE and More 🔌",
"primary_category": {
"category_id": "tool-integrations",
"confidence": "high",
"name_en": "Tool Integrations",
"name_zh": "工具连接与集成",
"reason": "matched_keywords:mcp, api, server"
},
"target_user": "使用 mcp_host, claude, cursor 等宿主 AI 的用户",
"title_en": "mcp-playwright",
"title_zh": "mcp-playwright 能力包",
"visible_tags": [
{
"label_en": "Browser Agents",
"label_zh": "浏览器 Agent",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-browser-agents",
"type": "product_domain"
},
{
"label_en": "Web Task Automation",
"label_zh": "网页任务自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-web-task-automation",
"type": "user_job"
},
{
"label_en": "Natural-language Web Actions",
"label_zh": "自然语言网页操作",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-natural-language-web-actions",
"type": "core_capability"
},
{
"label_en": "Node-based Workflow",
"label_zh": "节点式流程编排",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-node-based-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_fdf3dd806aa24898a57c59fec49fc279",
"page_model": {
"artifacts": {
"artifact_slug": "mcp-playwright",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "npm install -g @executeautomation/playwright-mcp-server",
"label": "Node.js / npm · 官方安装入口",
"source": "https://github.com/executeautomation/mcp-playwright#readme",
"verified": true
}
],
"display_tags": [
"浏览器 Agent",
"网页任务自动化",
"自然语言网页操作",
"节点式流程编排",
"评测体系"
],
"eyebrow": "工具连接与集成",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要工具连接与集成能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Playwright Model Context Protocol Server - Tool to automate Browsers and APIs in Claude Desktop, Cline, Cursor IDE and More 🔌"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host, claude, cursor",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Playwright is asking for an specific browser version.",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_38465ac94a9d4fb0bd352ba5209096ac | https://github.com/executeautomation/mcp-playwright/issues/117 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Playwright is asking for an specific browser version.",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：How to configure proxy and storageState when launching browser in Playwright MCP?",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_a2f7e4a410994d4195a9af9f139e0caa | https://github.com/executeautomation/mcp-playwright/issues/203 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：How to configure proxy and storageState when launching browser in Playwright MCP?",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。",
"category": "配置坑",
"evidence": [
"capability.host_targets | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | host_targets=mcp_host, claude, cursor"
],
"severity": "medium",
"suggested_check": "列出会写入的配置文件、目录和卸载/回滚步骤。",
"title": "可能修改宿主 AI 配置",
"user_impact": "安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Add Clarvia AEO score badge to README (AEO 32/100)",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_74959d07d5f74165bcd9cae829d384ce | https://github.com/executeautomation/mcp-playwright/issues/212 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Add Clarvia AEO score badge to README (AEO 32/100)",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Add policy enforcement for browser automation and HTTP request tools",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_23a30d245f794b8db40c1d031b8be565 | https://github.com/executeautomation/mcp-playwright/issues/216 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Add policy enforcement for browser automation and HTTP request tools",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：How to pass in the `--ignore-https-errors` parameter?",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_47d5e333819d49b4b8ce2abb9484b23d | https://github.com/executeautomation/mcp-playwright/issues/202 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：How to pass in the `--ignore-https-errors` parameter?",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "No sandbox install has been executed yet; downstream must verify before user use.",
"category": "安全/权限坑",
"evidence": [
"risks.safety_notes | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | No sandbox install has been executed yet; downstream must verify before user use."
],
"severity": "medium",
"suggested_check": "转成明确权限清单和安全审查提示。",
"title": "存在安全注意事项",
"user_impact": "用户安装前需要知道权限边界和敏感操作。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature Request: Add browser context persistence for login state (userDataDir/storageState)",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_3632e6a11e044dda870b3267ccfa3040 | https://github.com/executeautomation/mcp-playwright/issues/201 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Feature Request: Add browser context persistence for login state (userDataDir/storageState)",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Free MCP security scan report for @executeautomation/playwright-mcp-server",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_9720dc9967444ed08710cdb0660a212a | https://github.com/executeautomation/mcp-playwright/issues/211 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Free MCP security scan report for @executeautomation/playwright-mcp-server",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security Advisory: SSRF, Prompt Injection, and Arbitrary JavaScript Execution via Browser Automation Tools",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_ced642164084421f84bbb63681653057 | https://github.com/executeautomation/mcp-playwright/issues/209 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Security Advisory: SSRF, Prompt Injection, and Arbitrary JavaScript Execution via Browser Automation Tools",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 16 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Playwright is asking for an specific browser version.。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 34,
"forks": 510,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 5509
},
"source_url": "https://github.com/executeautomation/mcp-playwright",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Playwright Model Context Protocol Server - Tool to automate Browsers and APIs in Claude Desktop, Cline, Cursor IDE and More 🔌",
"title": "mcp-playwright 能力包",
"trial_prompt": "# mcp-playwright - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 mcp-playwright 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client / claude / Cursor\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Playwright Model Context Protocol Server - Tool to automate Browsers and APIs in Claude Desktop, Cline, Cursor IDE and More 🔌 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. getting-started：快速入门指南。围绕“快速入门指南”模拟一次用户任务，不展示安装或运行结果。\n2. architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. tool-reference：工具参考手册。围绕“工具参考手册”模拟一次用户任务，不展示安装或运行结果。\n4. http-transport：HTTP/SSE 传输模式。围绕“HTTP/SSE 传输模式”模拟一次用户任务，不展示安装或运行结果。\n5. client-configuration：客户端配置指南。围绕“客户端配置指南”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. getting-started\n输入：用户提供的“快速入门指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. tool-reference\n输入：用户提供的“工具参考手册”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. http-transport\n输入：用户提供的“HTTP/SSE 传输模式”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. client-configuration\n输入：用户提供的“客户端配置指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / getting-started：Step 1 必须围绕“快速入门指南”形成一个小中间产物，并等待用户确认。\n- Step 2 / architecture：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / tool-reference：Step 3 必须围绕“工具参考手册”形成一个小中间产物，并等待用户确认。\n- Step 4 / http-transport：Step 4 必须围绕“HTTP/SSE 传输模式”形成一个小中间产物，并等待用户确认。\n- Step 5 / client-configuration：Step 5 必须围绕“客户端配置指南”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/executeautomation/mcp-playwright\n- https://github.com/executeautomation/mcp-playwright#readme\n- README.md\n- package.json\n- mcp-config.json\n- src/index.ts\n- src/http-server.ts\n- src/requestHandler.ts\n- src/toolHandler.ts\n- src/sse/server.ts\n- src/tools.ts\n- src/tools/index.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 mcp-playwright 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: Add policy enforcement for browser automation and HTTP request tools（https://github.com/executeautomation/mcp-playwright/issues/216）；github/github_issue: Add Clarvia AEO score badge to README (AEO 32/100)（https://github.com/executeautomation/mcp-playwright/issues/212）；github/github_issue: Free MCP security scan report for @executeautomation/playwright-mcp-serv（https://github.com/executeautomation/mcp-playwright/issues/211）；github/github_issue: How to configure proxy and storageState when launching browser in Playwr（https://github.com/executeautomation/mcp-playwright/issues/203）；github/github_issue: Security Advisory: SSRF, Prompt Injection, and Arbitrary JavaScript Exec（https://github.com/executeautomation/mcp-playwright/issues/209）；github/github_issue: Playwright is asking for an specific browser version.（https://github.com/executeautomation/mcp-playwright/issues/117）；github/github_issue: How to pass in the `--ignore-https-errors` parameter?（https://github.com/executeautomation/mcp-playwright/issues/202）；github/github_issue: Feature Request: Add browser context persistence for login state (userDa（https://github.com/executeautomation/mcp-playwright/issues/201）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "Add policy enforcement for browser automation and HTTP request tools",
"url": "https://github.com/executeautomation/mcp-playwright/issues/216"
},
{
"kind": "github_issue",
"source": "github",
"title": "Add Clarvia AEO score badge to README (AEO 32/100)",
"url": "https://github.com/executeautomation/mcp-playwright/issues/212"
},
{
"kind": "github_issue",
"source": "github",
"title": "Free MCP security scan report for @executeautomation/playwright-mcp-serv",
"url": "https://github.com/executeautomation/mcp-playwright/issues/211"
},
{
"kind": "github_issue",
"source": "github",
"title": "How to configure proxy and storageState when launching browser in Playwr",
"url": "https://github.com/executeautomation/mcp-playwright/issues/203"
},
{
"kind": "github_issue",
"source": "github",
"title": "Security Advisory: SSRF, Prompt Injection, and Arbitrary JavaScript Exec",
"url": "https://github.com/executeautomation/mcp-playwright/issues/209"
},
{
"kind": "github_issue",
"source": "github",
"title": "Playwright is asking for an specific browser version.",
"url": "https://github.com/executeautomation/mcp-playwright/issues/117"
},
{
"kind": "github_issue",
"source": "github",
"title": "How to pass in the `--ignore-https-errors` parameter?",
"url": "https://github.com/executeautomation/mcp-playwright/issues/202"
},
{
"kind": "github_issue",
"source": "github",
"title": "Feature Request: Add browser context persistence for login state (userDa",
"url": "https://github.com/executeautomation/mcp-playwright/issues/201"
}
],
"status": "已收录 8 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "工具连接与集成",
"desc": "Playwright Model Context Protocol Server - Tool to automate Browsers and APIs in Claude Desktop, Cline, Cursor IDE and More 🔌",
"effort": "安装已验证",
"forks": 510,
"icon": "link",
"name": "mcp-playwright 能力包",
"risk": "可发布",
"slug": "mcp-playwright",
"stars": 5509,
"tags": [
"浏览器 Agent",
"网页任务自动化",
"自然语言网页操作",
"节点式流程编排",
"评测体系"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/executeautomation/mcp-playwright 项目说明书\n\n生成时间：2026-05-13 07:26:04 UTC\n\n## 目录\n\n- [快速入门指南](#getting-started)\n- [系统架构](#architecture)\n- [工具参考手册](#tool-reference)\n- [设备模拟功能](#device-emulation)\n- [测试代码生成](#code-generation)\n- [HTTP/SSE 传输模式](#http-transport)\n- [Docker 容器化部署](#docker-deployment)\n- [客户端配置指南](#client-configuration)\n- [日志与监控](#logging-monitoring)\n- [故障排除指南](#troubleshooting)\n\n\n\n## 快速入门指南\n\n### 相关页面\n\n相关主题：[系统架构](#architecture), [工具参考手册](#tool-reference), [客户端配置指南](#client-configuration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/executeautomation/mcp-playwright/blob/main/README.md)\n- [package.json](https://github.com/executeautomation/mcp-playwright/blob/main/package.json)\n- [DOCKER.md](https://github.com/executeautomation/mcp-playwright/blob/main/DOCKER.md)\n- [examples/http-mode-example.md](https://github.com/executeautomation/mcp-playwright/blob/main/examples/http-mode-example.md)\n- [CLAUDE_DESKTOP_CONFIG.md](https://github.com/executeautomation/mcp-playwright/blob/main/CLAUDE_DESKTOP_CONFIG.md)\n \n\n# 快速入门指南\n\n本指南将帮助您快速上手 **mcp-playwright** 项目，这是一个基于 Model Context Protocol (MCP) 的 Playwright 自动化服务器。通过本指南，您将了解如何安装、配置并开始使用该服务器进行浏览器自动化操作。\n\n## 项目概述\n\nmcp-playwright 是一个开源的 MCP 服务器实现，它将 Playwright 浏览器自动化能力通过 MCP 协议暴露给 AI 助手和开发工具。该项目由 ExecuteAutomation 维护，支持多浏览器引擎（Chromium、Firefox、WebKit），并提供 stdio 和 HTTP 两种通信模式。\n\n**核心特性：**\n\n| 特性 | 说明 |\n|------|------|\n| 协议支持 | Model Context Protocol (MCP) |\n| 浏览器支持 | Chromium、Firefox、WebKit |\n| 通信模式 | stdio（标准输入输出）、HTTP Server |\n| 安装方式 | npm、mcp-get、Smithery、Docker |\n| 日志管理 | 自动写入文件（stdio 模式） |\n\n## 环境要求\n\n在开始之前，请确保您的系统满足以下要求：\n\n- **Node.js**: 20.x 或更高版本\n- **操作系统**: Windows、macOS、Linux\n- **网络**: 能够访问 npm registry 下载依赖包\n\n您可以通过以下命令检查 Node.js 版本：\n\n```bash\nnode --version\n```\n\n## 安装方式\n\nmcp-playwright 提供多种安装方式，您可以根据使用场景选择最合适的一种。\n\n### 方式一：使用 npm 全局安装\n\n这是最直接的安装方式：\n\n```bash\nnpm install -g @executeautomation/playwright-mcp-server\n```\n\n安装完成后，可执行文件 `playwright-mcp-server` 将全局可用。资料来源：[README.md:54]()\n\n### 方式二：使用 npx 免安装运行\n\n如果您不想全局安装，可以使用 npx 直接运行：\n\n```bash\nnpx -y @executeautomation/playwright-mcp-server\n```\n\n这种方式每次都会下载最新版本，适合临时使用或测试场景。资料来源：[README.md:42]()\n\n### 方式三：使用 mcp-get 安装\n\nmcp-get 是专门为 MCP 服务器设计的包管理工具：\n\n```bash\nnpx @michaellatman/mcp-get@latest install @executeautomation/playwright-mcp-server\n```\n\n### 方式四：使用 Smithery 自动安装\n\nSmithery 提供了针对 Claude Desktop 的自动化安装：\n\n```bash\nnpx @smithery/cli install @executeautomation/playwright-mcp-server --client claude\n```\n\n### 方式五：Docker 部署\n\n对于容器化环境，可以使用 Docker 运行：\n\n```bash\ndocker run -i --rm mcp-playwright:latest\n```\n\nDocker 部署的详细配置请参考 [DOCKER.md](DOCKER.md)。资料来源：[DOCKER.md:1]()\n\n## 配置 AI 客户端\n\n安装完成后，您需要在 AI 客户端中配置 MCP 服务器连接。以下是常见客户端的配置方法。\n\n### Claude Desktop 配置\n\n**配置文件位置：**\n\n| 操作系统 | 配置文件路径 |\n|----------|--------------|\n| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Windows | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| Linux | `~/.config/Claude/claude_desktop_config.json` |\n\n**stdio 模式配置（推荐）：**\n\n```json\n{\n \"mcpServers\": {\n \"playwright\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@executeautomation/playwright-mcp-server\"]\n }\n }\n}\n```\n\n**HTTP 模式配置：**\n\n如果您使用 HTTP 模式运行服务器，可以配置如下：\n\n```json\n{\n \"mcpServers\": {\n \"playwright\": {\n \"url\": \"http://localhost:8931/mcp\"\n }\n }\n}\n```\n\n> **注意**：Claude Desktop 目前需要 stdio 模式。如果您需要 HTTP 模式，建议使用 VS Code 或其他自定义客户端。资料来源：[README.md:25-35]()\n\n### Claude Code 配置\n\n使用 Claude Code 时，可以通过命令行添加 MCP 服务器：\n\n```bash\nclaude mcp add --transport stdio playwright npx @executeautomation/playwright-mcp-server\n```\n\n### VS Code MCP 扩展配置\n\n对于 VS Code 用户，可以使用以下配置：\n\n```json\n{\n \"name\": \"playwright\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@executeautomation/playwright-mcp-server\"]\n}\n```\n\n## 运行模式\n\nmcp-playwright 支持两种运行模式，您可以根据需求选择。\n\n### stdio 模式（标准输入输出）\n\nstdio 模式是 Claude Desktop 的推荐模式。在此模式下，MCP 服务器通过标准输入和标准输出与客户端通信。\n\n**启动方式：**\n\n```bash\nnpx -y @executeautomation/playwright-mcp-server\n```\n\n**配置说明：**\n\n| 参数 | 说明 |\n|------|------|\n| `-i` | 保持 STDIN 打开以接收输入 |\n| `--rm` | 容器退出时自动删除 |\n\n在 stdio 模式下，日志会自动写入文件而非控制台，以确保 JSON-RPC 通信的清洁性。日志文件位置为 `~/playwright-mcp-server.log`。资料来源：[README.md:30]()\n\n### HTTP 模式（独立服务器）\n\nHTTP 模式适合以下场景：\n\n- 在无显示环境的系统中运行有头浏览器\n- 从 IDE 工作进程调用\n- 需要远程部署\n- VS Code 用户\n\n**启动 HTTP 服务器：**\n\n```bash\n# 使用 npx\nnpx @executeautomation/playwright-mcp-server --port 8931\n\n# 或使用全局安装后\nplaywright-mcp-server --port 8931\n```\n\n服务器启动后将显示可用端点：\n\n```\n==============================================\nPlaywright MCP Server (HTTP Mode)\n==============================================\nPort: 8931\n\nENDPOINTS:\n- SSE Stream: GET http://localhost:8931/sse\n- Messages: POST http://localhost:8931/messages?sessionId=\n- MCP (unified): GET http://localhost:8931/mcp\n- MCP (unified): POST http://localhost:8931/mcp?sessionId=\n- Health Check: GET http://localhost:8931/health\n```\n\n资料来源：[README.md:38-52]()\n\n**健康检查：**\n\n```bash\ncurl http://localhost:8931/health\n```\n\n## 浏览器安装\n\n### 自动安装（推荐）\n\nmcp-playwright **会在首次使用时自动安装浏览器**。当服务器检测到缺少浏览器时，会自动：\n\n1. 下载并安装所需浏览器（Chromium、Firefox 或 WebKit）\n2. 在控制台显示安装进度\n3. 安装完成后自动重试您的请求\n\n无需手动操作！\n\n### 手动安装\n\n如果您偏好手动安装或遇到自动安装问题：\n\n```bash\n# 安装所有浏览器\nnpx playwright install\n\n# 或安装特定浏览器\nnpx playwright install chromium\nnpx playwright install firefox\nnpx playwright install webkit\n```\n\n**浏览器存储位置：**\n\n| 操作系统 | 路径 |\n|----------|------|\n| Windows | `%USERPROFILE%\\AppData\\Local\\ms-playwright` |\n| macOS | `~/Library/Caches/ms-playwright` |\n| Linux | `~/.cache/ms-playwright` |\n\n资料来源：[README.md:57-72]()\n\n## 项目架构\n\n下面通过 Mermaid 图展示 mcp-playwright 的整体架构：\n\n```mermaid\ngraph TD\n A[AI 客户端
Claude Desktop/VS Code] -->|stdio 或 HTTP| B[MCP 协议层]\n B --> C[Playwright MCP Server]\n C --> D[Playwright 核心]\n D --> E[Chromium]\n D --> F[Firefox]\n D --> G[WebKit]\n \n H[日志系统] --> C\n \n style A fill:#e1f5fe\n style C fill:#fff3e0\n style D fill:#e8f5e9\n```\n\n### 组件说明\n\n| 组件 | 说明 | 源码位置 |\n|------|------|----------|\n| MCP 协议层 | 处理 JSON-RPC 通信协议 | `@modelcontextprotocol/sdk` |\n| 工具处理器 | 执行浏览器自动化操作 | `src/tools/` |\n| 日志中间件 | 请求日志和错误追踪 | `src/logging/middleware.ts` |\n| Playwright 核心 | 跨浏览器自动化引擎 | `playwright@1.57.0` |\n\n## 常用工作流程\n\n### 基本导航流程\n\n```mermaid\ngraph LR\n A[启动服务器] --> B[配置客户端]\n B --> C[打开浏览器]\n C --> D[导航到 URL]\n D --> E[执行交互]\n E --> F[获取结果]\n```\n\n### Docker 部署流程\n\n如果您选择 Docker 部署，典型的工作流程如下：\n\n```mermaid\ngraph TD\n A[编写 docker-compose.yml] --> B[配置环境变量]\n B --> C[配置卷挂载]\n C --> D[启动容器]\n D --> E[配置 AI 客户端连接]\n E --> F[开始使用]\n```\n\n**示例 docker-compose.yml：**\n\n```yaml\nservices:\n playwright-mcp:\n image: mcp-playwright:latest\n environment:\n - PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1\n - NODE_ENV=production\n volumes:\n - ./data:/app/data\n - ./screenshots:/app/screenshots\n```\n\n资料来源：[DOCKER.md:38-48]()\n\n## 环境变量\n\n您可以通过环境变量配置服务器行为：\n\n| 变量名 | 说明 | 默认值 |\n|--------|------|--------|\n| `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD` | 跳过浏览器自动下载 | `1`（Docker 中默认） |\n| `NODE_ENV` | 运行环境 | `production` |\n\n**Docker 中设置环境变量：**\n\n```bash\ndocker run -i --rm \\\n -e PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 \\\n mcp-playwright:latest\n```\n\n资料来源：[DOCKER.md:26-31]()\n\n## 故障排除\n\n### 容器立即退出\n\nMCP 服务器需要通过 stdin 接收输入，确保使用 `-i` 标志：\n\n```bash\ndocker run -i --rm mcp-playwright:latest\n```\n\n### 浏览器未找到\n\nDocker 镜像默认跳过浏览器下载以减小体积。如需预安装浏览器，创建自定义 Dockerfile：\n\n```dockerfile\nFROM mcp-playwright:latest\nRUN npx playwright install chromium --with-deps\n```\n\n### 权限问题\n\n如果遇到挂载卷权限问题：\n\n```bash\ndocker run -i --rm \\\n -v $(pwd)/data:/app/data \\\n --user $(id -u):$(id -g) \\\n mcp-playwright:latest\n```\n\n### 日志位置\n\nstdio 模式下，日志文件位置为：`~/playwright-mcp-server.log`\n\n## 下一步\n\n完成快速入门后，您可以：\n\n- 阅读完整的 [API 文档](https://executeautomation.github.io/mcp-playwright/docs/playwright-web/Supported-Tools)\n- 了解支持的 [设备配置](https://executeautomation.github.io/mcp-playwright/docs/playwright-web/Device-Quick-Reference)\n- 参考 [调整提示指南](https://executeautomation.github.io/mcp-playwright/docs/playwright-web/Resize-Prompts-Guide)\n- 查看 [GitHub Issues](https://github.com/executeautomation/mcp-playwright/issues) 获取帮助\n\n## 资源链接\n\n| 资源 | 链接 |\n|------|------|\n| 官方文档 | https://executeautomation.github.io/mcp-playwright/ |\n| API 参考 | https://executeautomation.github.io/mcp-playwright/docs/playwright-web/Supported-Tools |\n| GitHub 仓库 | https://github.com/executeautomation/mcp-playwright |\n| 问题反馈 | https://github.com/executeautomation/mcp-playwright/issues |\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[快速入门指南](#getting-started), [HTTP/SSE 传输模式](#http-transport), [日志与监控](#logging-monitoring)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/index.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/index.ts)\n- [src/http-server.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/http-server.ts)\n- [src/requestHandler.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/requestHandler.ts)\n- [src/toolHandler.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/toolHandler.ts)\n- [src/sse/server.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/sse/server.ts)\n- [src/logging/middleware.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/middleware.ts)\n- [src/logging/logger.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/logger.ts)\n- [src/tools.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools.ts)\n \n\n# 系统架构\n\n## 概述\n\nmcp-playwright 是一个基于 Model Context Protocol (MCP) 的 Playwright 自动化服务器，为 AI 助手提供浏览器自动化能力。该项目采用模块化架构设计，支持两种运行模式：stdio（标准输入输出）和 HTTP 模式。 资料来源：[package.json](https://github.com/executeautomation/mcp-playwright/blob/main/package.json)\n\n## 核心架构组件\n\n### 组件架构图\n\n```mermaid\ngraph TB\n subgraph \"传输层\"\n STDIO[STDIO 传输]\n HTTP[HTTP 服务器]\n SSE[SSE 流]\n end\n \n subgraph \"核心层\"\n MCP_SDK[MCP SDK
1.24.3]\n RequestHandler[请求处理器]\n ToolHandler[工具处理器]\n end\n \n subgraph \"工具层\"\n BrowserTools[浏览器工具]\n InteractionTools[交互工具]\n OutputTools[输出工具]\n ContentTools[内容提取工具]\n end\n \n subgraph \"浏览器层\"\n Chromium[@playwright/browser-chromium]\n Firefox[@playwright/browser-firefox]\n WebKit[@playwright/browser-webkit]\n end\n \n subgraph \"日志层\"\n Logger[日志记录器]\n Middleware[日志中间件]\n end\n \n STDIO --> MCP_SDK\n HTTP --> SSE\n HTTP --> RequestHandler\n MCP_SDK --> RequestHandler\n RequestHandler --> ToolHandler\n ToolHandler --> BrowserTools\n ToolHandler --> InteractionTools\n ToolHandler --> OutputTools\n ToolHandler --> ContentTools\n \n BrowserTools --> Chromium\n BrowserTools --> Firefox\n BrowserTools --> WebKit\n \n RequestHandler --> Middleware\n Middleware --> Logger\n```\n\n## 传输层架构\n\n### STDIO 模式\n\nSTDIO 模式是 MCP 协议的默认传输方式，适用于 Claude Desktop 等本地客户端。服务器通过标准输入输出进行 JSON-RPC 通信，日志自动写入 `~/playwright-mcp-server.log` 文件。 资料来源：[README.md](https://github.com/executeautomation/mcp-playwright/blob/main/README.md)\n\n```mermaid\ngraph LR\n Client[Claude Desktop
或其他 MCP 客户端] <--> STDIO\n STDIO --> Server[主服务器进程]\n Server --> Logger[文件日志
playwright-mcp-server.log]\n```\n\n### HTTP 模式\n\nHTTP 模式提供独立的 HTTP 服务器，支持远程访问和 VS Code 等 IDE 集成。服务器绑定到 `127.0.0.1`（仅本地），提供 SSE 流式传输和消息接口。 资料来源：[src/http-server.ts:1-50](https://github.com/executeautomation/mcp-playwright/blob/main/src/http-server.ts)\n\n```mermaid\ngraph LR\n subgraph \"HTTP 端点\"\n SSE[SSE Stream
GET /sse]\n Messages[Messages
POST /messages]\n MCP[MCP 统一接口
GET/POST /mcp]\n Health[Health Check
GET /health]\n end\n \n Client[外部客户端] --> HTTP_Server[HTTP 服务器
127.0.0.1:8931]\n HTTP_Server --> SSE\n HTTP_Server --> Messages\n HTTP_Server --> MCP\n HTTP_Server --> Health\n```\n\n### HTTP 端点配置\n\n| 端点 | 方法 | 路径 | 说明 |\n|------|------|------|------|\n| SSE Stream | GET | `/sse` | 服务器发送事件流 |\n| Messages | POST | `/messages?sessionId=` | 发送消息接口 |\n| MCP 统一 | GET/POST | `/mcp` | MCP 协议统一接口 |\n| Health Check | GET | `/health` | 健康检查端点 |\n\n## 请求处理流程\n\n### 请求生命周期\n\n```mermaid\nsequenceDiagram\n participant Client as MCP 客户端\n participant Middleware as 日志中间件\n participant RequestHandler as 请求处理器\n participant ToolHandler as 工具处理器\n participant Tools as 工具实现\n participant Logger as 日志记录器\n\n Client->>Middleware: JSON-RPC 请求\n Middleware->>Logger: 记录请求开始\n Middleware->>RequestHandler: 转发请求\n RequestHandler->>ToolHandler: 分发工具调用\n ToolHandler->>Tools: 执行具体工具\n Tools-->>ToolHandler: 返回结果\n ToolHandler-->>RequestHandler: 返回响应\n RequestHandler-->>Middleware: 返回结果\n Middleware->>Logger: 记录请求完成\n Middleware-->>Client: JSON-RPC 响应\n```\n\n### 请求处理器\n\n请求处理器（RequestHandler）负责接收 MCP 协议的 JSON-RPC 请求，进行参数验证和错误处理，然后分发到相应的工具处理器。 资料来源：[src/requestHandler.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/requestHandler.ts)\n\n核心职责包括：\n\n- 解析 MCP 协议消息格式\n- 验证请求参数\n- 路由工具调用到对应的处理器\n- 处理错误和异常情况\n\n## 工具系统架构\n\n### 工具分类\n\n所有工具定义统一在 `src/tools.ts` 中声明，分为以下几类： 资料来源：[src/tools.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools.ts)\n\n| 类别 | 工具名称 | 说明 |\n|------|----------|------|\n| **浏览器操作** | `playwright_navigate` | 页面导航 |\n| | `playwright_screenshot` | 页面截图 |\n| | `playwright_close` | 关闭浏览器 |\n| **元素交互** | `playwright_click` | 点击元素 |\n| | `playwright_fill` | 填写表单 |\n| | `playwright_select` | 选择下拉选项 |\n| | `playwright_hover` | 悬停元素 |\n| | `playwright_press_key` | 按键操作 |\n| | `playwright_drag` | 拖拽操作 |\n| **内容提取** | `playwright_get_visible_text` | 获取可见文本 |\n| | `playwright_get_visible_html` | 获取 HTML 内容 |\n| **输出工具** | `playwright_save_as_pdf` | 保存为 PDF |\n| **API 测试** | `playwright_expect_response` | 期望响应验证 |\n| | `playwright_assert_response` | 断言响应 |\n| **IFrame** | `playwright_iframe_click` | IFrame 点击 |\n| | `playwright_iframe_fill` | IFrame 填写 |\n\n### 浏览器启动条件\n\n工具系统使用条件启动机制，仅在需要时启动浏览器： 资料来源：[src/tools.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools.ts)\n\n```typescript\nexport const BROWSER_TOOLS = [\n \"playwright_navigate\",\n \"playwright_screenshot\",\n \"playwright_click\",\n \"playwright_iframe_click\",\n \"playwright_iframe_fill\",\n \"playwright_fill\",\n \"playwright_select\",\n \"playwright_hover\",\n \"playwright_upload_file\",\n \"playwright_evaluate\",\n \"playwright_resize\",\n \"playwright_close\",\n \"playwright_expect_response\",\n \"playwright_assert_response\",\n \"playwright_custom_user_agent\",\n \"playwright_get_visible_text\",\n ...\n];\n```\n\n### 工具处理器\n\n工具处理器（ToolHandler）负责管理浏览器实例的生命周期和执行具体工具调用。 资料来源：[src/toolHandler.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/toolHandler.ts)\n\n```mermaid\ngraph TB\n subgraph \"ToolHandler\"\n BrowserManager[浏览器管理器]\n ToolRegistry[工具注册表]\n SessionManager[会话管理器]\n end\n \n ToolRegistry -->|执行| BrowserManager\n SessionManager -->|状态| BrowserManager\n```\n\n## 日志系统架构\n\n### 日志中间件\n\n日志中间件（LoggingMiddleware）拦截所有工具调用请求，记录详细的执行上下文和错误信息。 资料来源：[src/logging/middleware.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/middleware.ts)\n\n```mermaid\ngraph LR\n Request[请求] --> Middleware[日志中间件]\n Middleware --> Sanitize[参数脱敏]\n Middleware --> LogStart[记录开始]\n Request -->|执行| Handler[工具处理器]\n Handler -->|结果| Middleware\n Middleware --> LogComplete[记录完成]\n Middleware --> LogError[记录错误]\n Middleware --> Response[响应]\n```\n\n### 日志级别和上下文\n\n| 方法 | 用途 |\n|------|------|\n| `info()` | 一般信息日志 |\n| `warn()` | 警告信息日志 |\n| `error()` | 错误信息日志 |\n| `logRequest()` | 请求详情日志 |\n| `logError()` | 错误详情日志 |\n\n日志上下文包含丰富的系统信息： 资料来源：[src/logging/logger.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/logger.ts)\n\n- 错误名称和消息\n- 堆栈跟踪\n- 时间戳\n- Node.js 版本\n- 平台和架构信息\n- 内存使用情况\n- 运行时间\n\n### 错误分类\n\n日志中间件实现了智能错误分类功能： 资料来源：[src/logging/middleware.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/middleware.ts)\n\n| 错误类型 | 触发条件 |\n|----------|----------|\n| `validation` | 参数验证失败、缺少必填字段 |\n| `resource` | 浏览器/页面连接断开、协议错误 |\n| `authentication` | 未授权访问、权限不足 |\n| `rate_limit` | 请求频率限制 |\n| `system` | 超时、元素未找到、导航失败 |\n\n## 多浏览器支持\n\n### 浏览器类型\n\n项目支持三种浏览器引擎，通过 `browserType` 参数指定： 资料来源：[CHANGELOG.md](https://github.com/executeautomation/mcp-playwright/blob/main/CHANGELOG.md)\n\n| 浏览器 | 参数值 | 包依赖 |\n|--------|--------|--------|\n| Chromium | `chromium` | `@playwright/browser-chromium` |\n| Firefox | `firefox` | `@playwright/browser-firefox` |\n| WebKit | `webkit` | `@playwright/browser-webkit` |\n\n### 浏览器依赖版本\n\n所有浏览器包版本统一为 `1.57.0`，核心 Playwright 版本也保持一致。 资料来源：[package.json](https://github.com/executeautomation/mcp-playwright/blob/main/package.json)\n\n```json\n{\n \"@playwright/browser-chromium\": \"1.57.0\",\n \"@playwright/browser-firefox\": \"1.57.0\",\n \"@playwright/browser-webkit\": \"1.57.0\",\n \"playwright\": \"1.57.0\"\n}\n```\n\n## 服务器启动流程\n\n```mermaid\ngraph TB\n Start[启动] --> Args[解析命令行参数]\n Args --> Mode{运行模式}\n Mode -->|stdio| STDIO_Init[STDIO 模式初始化]\n Mode -->|http| HTTP_Init[HTTP 模式初始化]\n \n STDIO_Init --> SDK_Init[MCP SDK 初始化]\n HTTP_Init --> Express[Express 服务器]\n Express --> Routes[注册路由]\n Routes --> SSE_Init[SSE 服务初始化]\n SSE_Init --> SSE_Ready[SSE 就绪]\n \n SDK_Init --> RegisterTools[注册工具]\n RegisterTools --> Loop[事件循环]\n Loop -->|请求| Handle[处理请求]\n Handle -->|调用| Execute[执行工具]\n Execute --> Response[返回结果]\n Response --> Loop\n```\n\n## 入口点架构\n\n### src/index.ts 主入口\n\n主入口文件负责根据命令行参数选择运行模式： 资料来源：[src/index.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/index.ts)\n\n```mermaid\ngraph LR\n Node[Node.js] --> Index[index.ts]\n Index --> ParseArgs[解析 --port 参数]\n ParseArgs -->|有端口参数| HTTP[HTTP 模式]\n ParseArgs -->|无端口参数| STDIO[STDIO 模式]\n```\n\n### HTTP 服务器初始化\n\nHTTP 服务器使用 Express 框架，绑定到本地主机（安全考虑）： 资料来源：[src/http-server.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/http-server.ts)\n\n```typescript\n// 安全配置：仅绑定本地主机\nconst host = '127.0.0.1';\nconst httpServer = app.listen(port, host, () => {\n logger.info(`Playwright MCP HTTP server listening on ${host}:${port}`);\n});\n```\n\n## SSE 服务器架构\n\n### SSE 服务端点\n\nSSE（Server-Sent Events）服务器负责将服务器端事件推送到客户端。 资料来源：[src/sse/server.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/sse/server.ts)\n\n```mermaid\ngraph LR\n Client[客户端] -->|建立连接| SSE[SSE 服务器]\n SSE -->|事件流| Client\n HTTP_Server[HTTP 服务器] -->|管理| SSE\n```\n\n### 会话管理\n\nSSE 服务器支持多会话管理，每个会话通过 `sessionId` 标识：\n\n- `/sse` - 建立 SSE 连接\n- `/messages?sessionId=` - 发送消息到指定会话\n- `/mcp` - MCP 统一接口（支持 sessionId 参数）\n\n## 安全特性\n\n### 安全设计原则\n\n| 特性 | 说明 |\n|------|------|\n| 本地绑定 | HTTP 服务器仅绑定 `127.0.0.1`，防止外部访问 |\n| 日志脱敏 | 工具参数自动脱敏，移除敏感字段 |\n| STDIO 隔离 | stdio 模式下日志仅写入文件 |\n\n### 参数脱敏规则\n\n日志中间件自动识别并脱敏以下敏感字段： 资料来源：[src/logging/middleware.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/middleware.ts)\n\n```typescript\nconst sensitiveFields = ['password', 'token', 'secret', 'key', 'auth'];\n```\n\n## 依赖关系图\n\n### 核心依赖\n\n| 包名 | 版本 | 用途 |\n|------|------|------|\n| `@modelcontextprotocol/sdk` | 1.24.3 | MCP 协议实现 |\n| `express` | ^4.21.1 | HTTP 服务器框架 |\n| `cors` | ^2.8.5 | 跨域资源共享 |\n| `playwright` | 1.57.0 | 浏览器自动化核心 |\n| `uuid` | 11.1.0 | 会话 ID 生成 |\n\n## 测试架构\n\n### 测试框架\n\n项目使用 Jest 作为测试框架，测试文件位于 `src/__tests__` 目录： 资料来源：[README.md](https://github.com/executeautomation/mcp-playwright/blob/main/README.md)\n\n```bash\n# 运行测试\nnpm test\n\n# 带覆盖率\nnpm run test:coverage\n\n# 自定义测试脚本\nnode run-tests.cjs\n```\n\n### 评估测试\n\n使用 `mcp-eval` 包进行 AI 能力评估：\n\n```bash\nOPENAI_API_KEY=your-key npx mcp-eval src/evals/evals.ts src/tools/codegen/index.ts\n```\n\n## 总结\n\nmcp-playwright 采用清晰的层次化架构设计：\n\n1. **传输层**：支持 STDIO 和 HTTP 两种模式，适配不同客户端需求\n2. **协议层**：基于 MCP SDK 实现标准化的工具调用协议\n3. **处理层**：请求处理器和工具处理器分离，职责明确\n4. **工具层**：模块化的浏览器自动化工具集，支持多浏览器\n5. **日志层**：完善的日志记录和错误追踪机制\n\n该架构确保了系统的可扩展性、可维护性和安全性，同时提供了灵活的部署选项。\n\n---\n\n\n\n## 工具参考手册\n\n### 相关页面\n\n相关主题：[快速入门指南](#getting-started), [设备模拟功能](#device-emulation), [测试代码生成](#code-generation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tools.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools.ts)\n- [src/tools/index.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/index.ts)\n- [src/tools/browser/index.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/index.ts)\n- [src/tools/browser/screenshot.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/screenshot.ts)\n- [src/tools/browser/visiblePage.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/visiblePage.ts)\n- [src/logging/middleware.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/middleware.ts)\n- [package.json](https://github.com/executeautomation/mcp-playwright/blob/main/package.json)\n \n\n# 工具参考手册\n\nPlaywright MCP Server 提供了一套完整的浏览器自动化工具集，通过 MCP（Model Context Protocol）协议暴露给 AI 助手使用。本工具手册详细介绍了所有可用工具的功能、参数配置及使用方法。\n\n## 1. 工具系统概述\n\n### 1.1 架构设计\n\nMCP Playwright 的工具系统采用模块化分层架构，将不同类型的工具按功能域划分为独立的模块。\n\n```mermaid\ngraph TD\n A[MCP Client
Claude/Copilot] --> B[Tool Handler
handleToolCall]\n B --> C[Browser Tools
浏览器操作]\n B --> D[API Tools
API 测试]\n B --> E[Codegen Tools
代码生成]\n \n C --> C1[navigate/click/fill]\n C --> C2[screenshot/evaluate]\n C --> C3[resize/hover]\n C --> C4[drag/press_key]\n \n D --> D1[api_request]\n D --> D2[expect_response]\n D --> D3[assert_response]\n \n E --> E1[代码生成工具]\n```\n\n资料来源：[src/tools.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools.ts)\n\n### 1.2 工具分类\n\n| 工具类别 | 前缀命名 | 功能说明 |\n|---------|---------|---------|\n| 浏览器工具 | `playwright_*` | 网页导航、元素交互、内容提取 |\n| API 工具 | `api_*` | HTTP 请求测试、响应验证 |\n| 代码生成工具 | `codegen_*` | 测试代码自动生成 |\n\n### 1.3 工具依赖关系\n\n浏览器操作类工具需要启动浏览器实例，系统通过 `BROWSER_TOOLS` 数组标识这些工具：\n\n```typescript\nexport const BROWSER_TOOLS = [\n \"playwright_navigate\",\n \"playwright_screenshot\",\n \"playwright_click\",\n \"playwright_iframe_click\",\n \"playwright_iframe_fill\",\n \"playwright_fill\",\n \"playwright_select\",\n \"playwright_hover\",\n \"playwright_upload_file\",\n \"playwright_evaluate\",\n \"playwright_resize\",\n \"playwright_close\",\n \"playwright_expect_response\",\n \"playwright_assert_response\",\n \"playwright_custom_user_agent\",\n \"playwright_get_visible_text\",\n];\n```\n\n资料来源：[src/tools.ts:1-16](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools.ts)\n\n---\n\n## 2. 浏览器工具详解\n\n### 2.1 导航与浏览器控制\n\n#### playwright_navigate\n\n打开指定 URL 并启动浏览器会话。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| url | string | 是 | 目标网页 URL |\n| browserType | string | 否 | 浏览器类型：chromium/firefox/webkit，默认 chromium |\n\n```javascript\n// 示例：使用 Firefox 打开网页\nawait playwright_navigate({ \n url: \"https://example.com\",\n browserType: \"firefox\"\n});\n```\n\n#### playwright_close\n\n关闭当前浏览器实例并清理资源。\n\n```javascript\nawait playwright_close();\n```\n\n资料来源：[src/tools/browser/index.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/index.ts)\n\n### 2.2 元素交互工具\n\n#### playwright_click\n\n点击页面上的指定元素。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| selector | string | 是 | CSS 选择器 |\n| button | string | 否 | 鼠标按钮：left/right/middle，默认 left |\n| clickCount | number | 否 | 点击次数：1/2/3 |\n| modifiers | string | 否 | 按住的修饰键：Alt/Control/Meta/Shift |\n\n#### playwright_fill\n\n向输入框填充文本内容。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| selector | string | 是 | CSS 选择器 |\n| value | string | 是 | 要填充的文本值 |\n\n#### playwright_select\n\n从下拉菜单中选择选项。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| selector | string | 是 | select 元素选择器 |\n| value | string | 是 | 选项值或标签 |\n| selectType | string | 否 | 选择类型：value/label/index |\n\n#### playwright_hover\n\n鼠标悬停在指定元素上。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| selector | string | 是 | CSS 选择器 |\n\n#### playwright_drag\n\n将元素从一位置拖拽到另一位置。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| sourceSelector | string | 是 | 源元素选择器 |\n| targetSelector | string | 是 | 目标元素选择器 |\n\n#### playwright_press_key\n\n模拟键盘按键操作。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| key | string | 是 | 按键名称 |\n| selector | string | 否 | 聚焦元素选择器 |\n| modifiers | string | 否 | 组合修饰键 |\n\n#### playwright_click_and_switch_tab\n\n点击链接并切换到新打开的标签页。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| selector | string | 是 | 链接选择器 |\n\n资料来源：[src/tools.ts:20-80](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools.ts)\n\n### 2.3 截图与内容提取\n\n#### playwright_screenshot\n\n对当前页面或指定元素进行截图。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| name | string | 否 | 截图名称标识（默认 screenshot） |\n| selector | string | 否 | 元素选择器，指定则截取元素而非全页 |\n| fullPage | boolean | 否 | 是否截取整个可滚动页面 |\n| storeBase64 | boolean | 否 | 是否存储 base64 副本到内存 |\n| downloadsDir | string | 否 | 保存目录路径 |\n\n```javascript\n// 全页面截图\nawait playwright_screenshot({ \n name: \"homepage\",\n fullPage: true \n});\n\n// 元素截图\nawait playwright_screenshot({ \n selector: \"#banner\",\n name: \"banner-element\"\n});\n```\n\n截图后，系统自动将 base64 数据存储到内存中供后续访问：\n\n```typescript\nif (args.storeBase64 !== false) {\n this.screenshots.set(args.name || 'screenshot', base64Screenshot);\n this.server.notification({\n method: \"notifications/resources/list_changed\",\n });\n}\n```\n\n资料来源：[src/tools/browser/screenshot.ts:40-50](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/screenshot.ts)\n\n#### playwright_get_visible_text\n\n提取页面或元素的可见文本内容。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| selector | string | 否 | 元素选择器，不指定则获取整个页面 |\n\n#### playwright_get_visible_html\n\n获取页面或元素的完整 HTML 内容。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| selector | string | 否 | 元素选择器 |\n| removeScripts | boolean | 否 | 移除 script 标签 |\n| removeComments | boolean | 否 | 移除 HTML 注释 |\n| removeStyles | boolean | 否 | 移除 style 标签 |\n| removeMeta | boolean | 否 | 移除 meta 标签 |\n| cleanHtml | boolean | 否 | 应用所有清理选项 |\n| minify | boolean | 否 | 压缩 HTML |\n\n```javascript\n// 获取清理后的 HTML\nawait playwright_get_visible_html({\n selector: \"#content\",\n cleanHtml: true,\n minify: true\n});\n```\n\n资料来源：[src/tools/browser/visiblePage.ts:1-50](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/visiblePage.ts)\n\n### 2.4 设备模拟与视口控制\n\n#### playwright_resize\n\n调整浏览器视口大小或模拟设备。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| width | number | 否 | 视口宽度（像素） |\n| height | number | 否 | 视口高度（像素） |\n| device | string | 否 | 预设设备名称（自动设置 viewport、userAgent） |\n| orientation | string | 否 | 设备方向：portrait/landscape |\n\n支持 143 种预设设备，包括：\n\n- iPhone 系列（iPhone 13, iPhone 15 Pro Max 等）\n- iPad 系列（iPad Pro 11, iPad Mini 等）\n- Pixel 系列（Pixel 7, Pixel 8 等）\n- Samsung Galaxy 系列\n- 桌面浏览器（Desktop Chrome, Firefox, Safari）\n\n```javascript\n// 模拟 iPhone 13\nawait playwright_resize({ device: \"iPhone 13\" });\n\n// 模拟 iPad 横屏\nawait playwright_resize({ \n device: \"iPad Pro 11\", \n orientation: \"landscape\" \n});\n\n// 自定义视口\nawait playwright_resize({ \n width: 1920, \n height: 1080 \n});\n```\n\n资料来源：[README.md:1-30](https://github.com/executeautomation/mcp-playwright/blob/main/README.md)\n\n### 2.5 JavaScript 执行\n\n#### playwright_evaluate\n\n在浏览器上下文中执行任意 JavaScript 代码。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| script | string | 是 | 要执行的 JavaScript 代码 |\n| params | object | 否 | 传递给脚本的参数 |\n\n```javascript\n// 获取页面标题\nconst title = await playwright_evaluate({\n script: \"() => document.title\"\n});\n\n// 带参数执行\nconst links = await playwright_evaluate({\n script: \"(count) => Array.from(document.links).slice(0, count)\",\n params: { count: 10 }\n});\n```\n\n### 2.6 文件操作\n\n#### playwright_upload_file\n\n上传文件到页面中的文件上传控件。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| selector | string | 是 | 文件输入框选择器 |\n| filePaths | string[] | 是 | 文件路径数组 |\n\n```javascript\nawait playwright_upload_file({\n selector: \"input[type='file']\",\n filePaths: [\"/path/to/file.pdf\", \"/path/to/image.png\"]\n});\n```\n\n#### playwright_save_as_pdf\n\n将当前页面保存为 PDF 文件。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| outputPath | string | 是 | 输出文件路径 |\n| format | string | 否 | 页面格式：A4/Letter |\n| printBackground | boolean | 否 | 是否打印背景图形 |\n| margin | object | 否 | 页边距配置 |\n\n```javascript\nawait playwright_save_as_pdf({\n outputPath: \"/tmp/report.pdf\",\n format: \"A4\",\n printBackground: true,\n margin: {\n top: \"1cm\",\n right: \"1cm\",\n bottom: \"1cm\",\n left: \"1cm\"\n }\n});\n```\n\n---\n\n## 3. API 测试工具\n\n### 3.1 API 请求工具\n\n#### api_request\n\n发送 HTTP 请求并进行测试验证。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| url | string | 是 | 请求 URL |\n| method | string | 否 | HTTP 方法：GET/POST/PUT/DELETE/PATCH |\n| headers | object | 否 | 请求头 |\n| body | object | 否 | 请求体 |\n| timeout | number | 否 | 超时时间（毫秒） |\n| authorization | string | 否 | Bearer 认证令牌 |\n\n```javascript\n// 发送 POST 请求\nconst response = await api_request({\n url: \"https://api.example.com/users\",\n method: \"POST\",\n headers: {\n \"Content-Type\": \"application/json\"\n },\n body: {\n name: \"张三\",\n email: \"zhangsan@example.com\"\n },\n authorization: \"Bearer your-token-here\"\n});\n```\n\n### 3.2 响应验证工具\n\n#### playwright_expect_response\n\n设置预期响应模式，验证后续请求的响应。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| urlPattern | string | 是 | URL 匹配模式（正则表达式） |\n| statusCode | number | 否 | 预期状态码 |\n| headers | object | 否 | 预期响应头 |\n| bodyPattern | string | 否 | 预期响应体模式 |\n\n#### playwright_assert_response\n\n对已发生的响应进行断言验证。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| urlPattern | string | 是 | URL 匹配模式 |\n| assertType | string | 是 | 断言类型：status/header/body |\n| expectedValue | any | 是 | 预期值 |\n\n---\n\n## 4. 工具执行流程\n\n### 4.1 请求处理流程\n\n```mermaid\nsequenceDiagram\n participant Client as MCP 客户端\n participant Handler as Tool Handler\n participant Logger as 日志中间件\n participant Browser as Playwright 浏览器\n participant Tools as 工具实现\n \n Client->>Handler: 工具调用请求\n Handler->>Logger: 记录请求开始\n Logger->>Browser: 检查/启动浏览器\n Browser->>Tools: 传递参数\n Tools->>Browser: 执行浏览器操作\n Browser-->>Tools: 返回结果\n Tools-->>Logger: 返回响应\n Logger-->>Client: 返回结果+日志\n```\n\n资料来源：[src/logging/middleware.ts:1-30](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/middleware.ts)\n\n### 4.2 日志记录机制\n\n工具执行中间件提供完整的请求追踪功能：\n\n| 日志阶段 | 记录内容 |\n|---------|---------|\n| 请求开始 | 工具名称、参数、请求 ID |\n| 执行中 | 操作类型、浏览器状态 |\n| 完成 | 状态码、耗时、响应内容 |\n| 错误 | 错误分类、堆栈跟踪、系统上下文 |\n\n错误分类系统：\n\n```typescript\nprivate categorizeToolError(toolName: string, error: Error): ErrorCategory {\n const message = error.message.toLowerCase();\n \n // 资源错误\n if (message.includes('browser') || message.includes('page') || \n message.includes('closed') || message.includes('disconnected')) {\n return 'resource';\n }\n \n // 验证错误\n if (message.includes('invalid') || message.includes('validation')) {\n return 'validation';\n }\n \n // 认证错误\n if (message.includes('unauthorized') || message.includes('forbidden')) {\n return 'authentication';\n }\n \n // 超时错误\n if (message.includes('timeout')) {\n return 'system';\n }\n}\n```\n\n资料来源：[src/logging/middleware.ts:50-100](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/middleware.ts)\n\n---\n\n## 5. 工具命名规范\n\n### 5.1 命名限制\n\n工具名称必须遵循以下约束：\n\n| 限制项 | 最大值 | 原因 |\n|-------|-------|------|\n| 工具名称长度 | 60 字符 | Cursor 等客户端限制 |\n| 服务器前缀 | playwright_ | 区分不同 MCP 服务器 |\n\n完整工具标识符格式：`playwright-mcp:playwright_xxx`\n\n### 5.2 推荐的短命名\n\n| 完整名称 | 用途场景 |\n|---------|---------|\n| playwright_navigate | 导航 |\n| playwright_click | 点击 |\n| playwright_fill | 填充表单 |\n| playwright_screenshot | 截图 |\n| playwright_close | 关闭 |\n\n---\n\n## 6. 错误处理\n\n### 6.1 错误分类\n\n| 错误类型 | 触发条件 | 示例消息 |\n|---------|---------|---------|\n| validation | 参数验证失败 | \"invalid selector\"、\"required parameter missing\" |\n| resource | 浏览器资源问题 | \"browser closed\"、\"target page closed\" |\n| authentication | 认证授权失败 | \"unauthorized\"、\"access denied\" |\n| rate_limit | 请求频率限制 | \"rate limit exceeded\" |\n| system | 超时/系统错误 | \"timeout waiting for element\" |\n\n### 6.2 错误上下文捕获\n\n系统自动捕获并记录以下错误上下文信息：\n\n```typescript\n{\n errorName: string, // 错误类型名称\n errorMessage: string, // 错误消息\n stack: string, // 堆栈跟踪\n timestamp: string, // ISO 时间戳\n nodeVersion: string, // Node.js 版本\n platform: string, // 操作系统平台\n memoryUsage: object, // 内存使用情况\n uptime: number, // 进程运行时间\n toolName: string, // 工具名称\n toolCategory: string, // 工具类别\n browserContext: object // 浏览器上下文\n}\n```\n\n---\n\n## 7. 配置与运行模式\n\n### 7.1 标准模式（stdio）\n\n适合 Claude Desktop 等标准 MCP 客户端：\n\n```json\n{\n \"mcpServers\": {\n \"playwright\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@executeautomation/playwright-mcp-server\"]\n }\n }\n}\n```\n\n### 7.2 HTTP 模式\n\n适合 VS Code、自定义客户端和远程部署：\n\n```bash\nnpx @executeautomation/playwright-mcp-server --port 8931\n```\n\n可用端点：\n\n| 端点 | 方法 | 用途 |\n|-----|------|------|\n| /sse | GET | SSE 流推送 |\n| /messages | POST | 消息接收 |\n| /mcp | GET/POST | MCP 统一接口 |\n| /health | GET | 健康检查 |\n\n### 7.3 Docker 部署\n\n```bash\ndocker run -i --rm mcp-playwright:latest\n```\n\n环境变量配置：\n\n| 变量名 | 说明 | 默认值 |\n|-------|------|-------|\n| PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD | 跳过浏览器自动安装 | false |\n| NODE_ENV | 运行环境 | development |\n\n---\n\n## 8. 快速参考表\n\n### 8.1 常用工具速查\n\n| 功能需求 | 推荐工具 | 必需参数 |\n|---------|---------|---------|\n| 打开网页 | playwright_navigate | url |\n| 点击元素 | playwright_click | selector |\n| 填写表单 | playwright_fill | selector, value |\n| 页面截图 | playwright_screenshot | - |\n| 获取文本 | playwright_get_visible_text | selector |\n| 调整窗口 | playwright_resize | width, height |\n| 模拟设备 | playwright_resize | device |\n| 发送请求 | api_request | url |\n\n### 8.2 参数类型速查\n\n| 类型标识 | 说明 | 示例 |\n|---------|------|------|\n| string | 字符串 | \"hello\" |\n| number | 数字 | 123 |\n| boolean | 布尔值 | true/false |\n| object | 对象 | {key: \"value\"} |\n| string[] | 字符串数组 | [\"a\", \"b\", \"c\"] |\n\n---\n\n## 9. 依赖版本\n\n| 依赖包 | 版本 | 用途 |\n|-------|------|------|\n| playwright | 1.57.0 | 浏览器自动化核心 |\n| @modelcontextprotocol/sdk | 1.24.3 | MCP 协议实现 |\n| @playwright/test | ^1.57.0 | 测试框架 |\n| express | ^4.21.1 | HTTP 服务器（HTTP 模式） |\n\n资料来源：[package.json:1-30](https://github.com/executeautomation/mcp-playwright/blob/main/package.json)\n\n---\n\n\n\n## 设备模拟功能\n\n### 相关页面\n\n相关主题：[工具参考手册](#tool-reference), [快速入门指南](#getting-started)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/browser/resize.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/resize.ts)\n- [src/tools/browser/useragent.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/useragent.ts)\n- [scripts/list-devices.cjs](https://github.com/executeautomation/mcp-playwright/blob/main/scripts/list-devices.cjs)\n- [docs/docs/playwright-web/Device-Quick-Reference.md](https://github.com/executeautomation/mcp-playwright/blob/main/docs/docs/playwright-web/Device-Quick-Reference.md)\n \n\n# 设备模拟功能\n\n## 概述\n\n设备模拟功能是 MCP Playwright 服务器的核心特性之一，允许 AI 助手和自动化测试工具在真实的设备配置下测试 Web 应用程序。该功能通过 `playwright_resize` 工具实现，支持 **143 种真实设备预设**，涵盖 iPhone、iPad、Pixel、Galaxy 以及主流桌面浏览器。\n\n设备模拟功能的核心价值在于：\n\n- 无需物理设备即可在真实设备配置下进行测试\n- 自动模拟设备的视口尺寸、用户代理字符串、触摸事件和设备像素比\n- 支持横竖屏切换\n- 与 AI 助手自然语言交互\n\n资料来源：[README.md](https://github.com/executeautomation/mcp-playwright/blob/main/README.md)\n\n## 架构设计\n\n### 组件关系\n\n```mermaid\ngraph TD\n A[playwright_resize 工具] --> B[ResizeTool 类]\n B --> C[BrowserToolBase 基类]\n B --> D[Playwright devices 模块]\n C --> E[BrowserContext]\n D --> F[设备配置数据]\n \n F --> F1[viewport 视口尺寸]\n F --> F2[userAgent 用户代理]\n F --> F3[deviceScaleFactor 像素比]\n F --> F4[isMobile 移动标识]\n F --> F5[hasTouch 触摸支持]\n```\n\n### 执行流程\n\n```mermaid\nsequenceDiagram\n participant AI as AI 助手\n participant MCP as MCP 服务器\n participant PT as Playwright ResizeTool\n participant PW as Playwright Core\n\n AI->>MCP: playwright_resize({ device: \"iPhone 13\" })\n MCP->>PT: execute(args, context)\n \n alt 使用设备预设\n PT->>PT: 查询 devices['iPhone 13']\n PT->>PT: 提取设备属性\n PT->>PT: 验证设备存在性\n PT->>PW: page.setViewportSize({width, height})\n PT->>PW: page.setExtraHTTPHeaders({User-Agent})\n else 自定义尺寸\n PT->>PT: 验证 width, height 参数\n PT->>PT: 检查分辨率限制 (≤7680x4320)\n PT->>PW: page.setViewportSize({width, height})\n end\n \n alt 设备预设 + 横竖屏\n PT->>PT: 根据 orientation 交换宽高\n end\n \n PT-->>MCP: ToolResponse\n MCP-->>AI: 成功响应\n```\n\n## 核心实现\n\n### ResizeTool 类\n\n`ResizeTool` 继承自 `BrowserToolBase`，负责处理设备模拟的核心逻辑。\n\n资料来源：[src/tools/browser/resize.ts:6-12](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/resize.ts)\n\n```typescript\nexport class ResizeTool extends BrowserToolBase {\n async execute(args: any, context: ToolContext): Promise {\n return this.safeExecute(context, async (page) => {\n let width: number;\n let height: number;\n let deviceName: string | undefined;\n let shouldSetUserAgent = false;\n let userAgent: string | undefined;\n let isMobile = false;\n let hasTouch = false;\n let deviceScaleFactor = 1;\n \n // 设备预设解析逻辑\n // ...\n });\n }\n}\n```\n\n### 设备预设处理逻辑\n\n```mermaid\ngraph TD\n S[开始] --> A{args.device 存在?}\n A -->|是| B[查找设备预设]\n A -->|否| C[使用 width/height 参数]\n \n B --> D{设备存在?}\n D -->|否| E[返回错误 + 热门设备列表]\n D -->|是| F[提取设备属性]\n \n F --> F1[提取 viewport 尺寸]\n F --> F2[提取 userAgent]\n F --> F3[提取 isMobile]\n F --> F4[提取 hasTouch]\n F --> F5[提取 deviceScaleFactor]\n \n F1 --> G{orientation 参数?}\n C --> G\n E --> END[返回]\n \n G -->|landscape| H[交换宽高]\n G -->|portrait| I[保持原尺寸]\n \n H --> J[应用视口配置]\n I --> J\n J --> K[返回成功响应]\n K --> END\n```\n\n资料来源：[src/tools/browser/resize.ts:21-85](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/resize.ts)\n\n## API 参考\n\n### 工具名称\n\n`playwright_resize`\n\n### 输入参数\n\n| 参数名 | 类型 | 必填 | 描述 |\n|--------|------|------|------|\n| `device` | `string` | 否 | 设备预设名称，如 \"iPhone 13\"、\"Desktop Chrome\" |\n| `width` | `number` | 否 | 视口宽度（像素），与 device 二选一 |\n| `height` | `number` | 否 | 视口高度（像素），与 device 二选一 |\n| `orientation` | `string` | 否 | 设备方向：`portrait`（竖屏）或 `landscape`（横屏） |\n\n### 参数优先级\n\n1. 若指定 `device`，优先使用设备预设配置\n2. 若未指定 `device`，使用自定义 `width` 和 `height`\n3. `orientation` 参数仅在 `device` 模式下生效，用于切换横竖屏\n\n### 设备预设 vs 自定义尺寸\n\n| 特性 | 设备预设模式 | 自定义尺寸模式 |\n|------|-------------|---------------|\n| 视口尺寸 | 自动从预设提取 | 手动指定 |\n| 用户代理 | 自动设置为设备 UA | 不修改 |\n| 触摸支持 | 自动启用 | 不启用 |\n| 设备像素比 | 自动设置 | 默认为 1 |\n| 移动端模拟 | 自动标识 | 不标识 |\n| 横竖屏切换 | 支持 | 不支持 |\n\n## 使用示例\n\n### 基础设备模拟\n\n```javascript\n// 测试 iPhone 13\nawait playwright_resize({ device: \"iPhone 13\" });\n```\n\n### 横竖屏切换\n\n```javascript\n// iPad Pro 横屏模式\nawait playwright_resize({ device: \"iPad Pro 11\", orientation: \"landscape\" });\n\n// iPhone 14 竖屏模式（默认）\nawait playwright_resize({ device: \"iPhone 14\", orientation: \"portrait\" });\n```\n\n### 桌面浏览器\n\n```javascript\n// Chrome 桌面视图\nawait playwright_resize({ device: \"Desktop Chrome\" });\n\n// Firefox 桌面视图\nawait playwright_resize({ device: \"Desktop Firefox\" });\n```\n\n### 自定义视口尺寸\n\n```javascript\n// 自定义 1920x1080 分辨率\nawait playwright_resize({ width: 1920, height: 1080 });\n```\n\n## 支持的设备列表\n\n设备模拟功能支持 Playwright 内置的完整设备库，包含 **143 种设备预设**。\n\n### 设备分类\n\n| 类别 | 示例设备 | 数量 |\n|------|----------|------|\n| iPhone 系列 | iPhone 13, iPhone 13 Pro, iPhone 14, iPhone 15 | ~15+ |\n| iPad 系列 | iPad Pro 11, iPad Pro 12.9, iPad Mini | ~10+ |\n| Pixel 系列 | Pixel 5, Pixel 7, Pixel 8 | ~10+ |\n| Galaxy 系列 | Galaxy S9+, Galaxy S21, Galaxy S24 | ~15+ |\n| Kindle 系列 | Kindle Paperwhite, Kindle Fire | ~5+ |\n| 桌面浏览器 | Desktop Chrome, Desktop Firefox, Desktop Safari | 3 |\n\n### 热门设备建议\n\n当用户输入不存在的设备名时，系统会返回热门设备建议列表：\n\n```\nDevice \"xxx\" not found. Popular devices: iPhone 13, iPhone 13 Pro, iPhone 14, \niPhone 15, iPad Pro 11, iPad Pro 12.9, Pixel 5, Pixel 7, Galaxy S9+, Galaxy S24, \nDesktop Chrome, Desktop Firefox, Desktop Safari. \nUse playwright.devices to see all 143 available devices.\n```\n\n资料来源：[src/tools/browser/resize.ts:43-53](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/resize.ts)\n\n## 设备配置属性\n\n每个设备预设包含以下属性：\n\n| 属性 | 类型 | 描述 |\n|------|------|------|\n| `viewport.width` | `number` | 视口宽度（像素） |\n| `viewport.height` | `number` | 视口高度（像素） |\n| `viewport.deviceScaleFactor` | `number` | 设备像素比（通常为 1-3） |\n| `viewport.isMobile` | `boolean` | 是否为移动设备 |\n| `viewport.hasTouch` | `boolean` | 是否支持触摸 |\n| `userAgent` | `string` | HTTP User-Agent 字符串 |\n\n### 示例：iPhone 13 配置\n\n```javascript\n{\n viewport: {\n width: 390,\n height: 844,\n deviceScaleFactor: 3,\n isMobile: true,\n hasTouch: true,\n isLandscape: false\n },\n userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 15_0 like Mac OS X) AppleWebKit/605.1.15'\n}\n```\n\n## 参数验证规则\n\n### 设备预设模式\n\n- 设备名称必须在 Playwright devices 库中存在\n- `orientation` 必须是 `portrait` 或 `landscape`\n\n### 自定义尺寸模式\n\n| 验证项 | 规则 | 错误消息 |\n|--------|------|----------|\n| 参数必填 | `width` 和 `height` 至少提供一个 | \"Width or height parameter is required\" |\n| 正整数验证 | 值必须大于 0 | \"Width and height must be positive integers\" |\n| 分辨率上限 | 不超过 7680x4320 (8K) | \"Width and height must not exceed 7680x4320 (8K resolution)\" |\n\n资料来源：[src/tools/browser/resize.ts:103-112](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/resize.ts)\n\n## AI 助手自然语言集成\n\n设备模拟功能设计为与 AI 助手无缝集成，支持自然语言命令：\n\n### 支持的命令模式\n\n| 自然语言 | 转换为工具调用 |\n|----------|---------------|\n| \"Test on iPhone 13\" | `playwright_resize({ device: \"iPhone 13\" })` |\n| \"Switch to iPad view\" | `playwright_resize({ device: \"iPad Pro 11\" })` |\n| \"Rotate to landscape\" | `playwright_resize({ device: \"iPhone 14\", orientation: \"landscape\" })` |\n| \"Show desktop view\" | `playwright_resize({ device: \"Desktop Chrome\" })` |\n\n资料来源：[README.md](https://github.com/executeautomation/mcp-playwright/blob/main/README.md)\n\n## 错误处理\n\n### 常见错误及解决方案\n\n| 错误类型 | 错误消息 | 解决方案 |\n|----------|----------|----------|\n| 设备不存在 | `Device \"xxx\" not found` | 使用热门设备列表中的设备名 |\n| 尺寸无效 | `Width and height must be positive integers` | 提供正整数值 |\n| 分辨率超限 | `Width and height must not exceed 7680x4320` | 使用合理的分辨率 |\n| 浏览器未启动 | `Browser not launched` | 先调用 `playwright_navigate` 启动浏览器 |\n\n### 错误响应格式\n\n```json\n{\n \"isError\": true,\n \"content\": [\n {\n \"type\": \"text\",\n \"text\": \"Device \\\"iPhone 99\\\" not found. Popular devices: iPhone 13, iPhone 13 Pro...\"\n }\n ]\n}\n```\n\n## 与其他工具的配合\n\n### 推荐的工具调用顺序\n\n```mermaid\ngraph LR\n A[playwright_navigate] --> B[playwright_resize]\n B --> C[playwright_screenshot]\n C --> D[playwright_click]\n D --> E[playwright_fill]\n```\n\n1. **启动浏览器**：`playwright_navigate` - 初始化浏览器上下文\n2. **设置设备**：`playwright_resize` - 应用设备模拟配置\n3. **截图验证**：`playwright_screenshot` - 验证设备视图\n4. **交互操作**：`playwright_click` / `playwright_fill` - 执行测试操作\n\n## 性能注意事项\n\n| 项目 | 建议 |\n|------|------|\n| 设备切换频率 | 避免频繁切换设备，每次切换都有性能开销 |\n| 高分辨率设备 | 8K 以上分辨率可能导致内存问题 |\n| 触摸事件 | `hasTouch: true` 会影响事件分发逻辑 |\n| 设备像素比 | 高像素比（如 3x）会增加截图和渲染开销 |\n\n## 相关工具\n\n| 工具名称 | 功能描述 | 关系 |\n|----------|----------|------|\n| `playwright_navigate` | 启动浏览器并导航到 URL | 前置依赖 |\n| `playwright_screenshot` | 截取页面截图 | 配合使用 |\n| `playwright_custom_user_agent` | 自定义用户代理字符串 | 独立功能 |\n| `playwright_get_visible_text` | 获取页面可见文本 | 配合使用 |\n\n资料来源：[src/tools.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools.ts)\n\n---\n\n\n\n## 测试代码生成\n\n### 相关页面\n\n相关主题：[工具参考手册](#tool-reference)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/codegen/recorder.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/codegen/recorder.ts)\n- [src/tools/codegen/generator.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/codegen/generator.ts)\n- [src/tools/codegen/types.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/codegen/types.ts)\n- [src/tools/codegen/index.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/codegen/index.ts)\n \n\n# 测试代码生成\n\n## 概述\n\n测试代码生成（Code Generation）是 MCP Playwright 提供的一项高级功能，允许开发者通过 MCP 工具执行自动化操作，并自动记录这些操作，最终生成可重用的 Playwright 测试脚本。\n\n该功能的核心价值在于：\n\n- 将手动录制的用户操作自动转化为可执行的测试代码\n- 支持从记录的会话中生成结构化的 Playwright 测试用例\n- 提供灵活的配置选项以满足不同项目的测试需求\n\n资料来源：[src/tools/codegen/index.ts:1-20]()\n\n## 架构设计\n\n### 核心组件\n\n测试代码生成模块由三个主要组件构成：\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| ActionRecorder | `recorder.ts` | 记录 MCP 工具调用操作 |\n| PlaywrightGenerator | `generator.ts` | 根据记录的操作生成测试代码 |\n| 工具接口 | `index.ts` | 提供对外的 MCP 工具入口 |\n\n```mermaid\ngraph TD\n A[MCP 客户端] --> B[start_codegen_session]\n B --> C[ActionRecorder]\n C --> D[CodegenSession]\n D --> E[PlaywrightGenerator]\n E --> F[PlaywrightTestCase]\n F --> G[测试代码文件]\n \n H[record_action] --> C\n C --> I[get_session]\n```\n\n资料来源：[src/tools/codegen/generator.ts:1-10]()\n\n### 类型定义\n\ntypes.ts 文件定义了核心数据结构：\n\n| 类型 | 用途 |\n|------|------|\n| `CodegenAction` | 单个工具调用操作的表示 |\n| `CodegenSession` | 包含多个操作的会话容器 |\n| `CodegenOptions` | 代码生成的配置选项 |\n| `CodegenResult` | 生成的测试代码结果 |\n| `PlaywrightTestCase` | 生成的测试用例结构 |\n\n资料来源：[src/tools/codegen/types.ts]()\n\n## 工作流程\n\n### 整体流程\n\n```mermaid\ngraph LR\n A[开始会话] --> B[执行 MCP 工具]\n B --> C[record_action]\n C --> D{是否结束会话?}\n D -->|否| B\n D -->|是| E[generate_test]\n E --> F[输出测试代码]\n F --> G[保存到文件]\n```\n\n### 会话管理\n\n1. **启动会话**：调用 `start_codegen_session` 初始化新的代码生成会话\n2. **记录操作**：每个 MCP 工具调用通过 `record_action` 自动记录\n3. **生成代码**：调用 `generate_playwright_test` 将会话转化为测试代码\n4. **保存结果**：生成的代码保存到指定的输出目录\n\n资料来源：[src/tools/codegen/index.ts:35-80]()\n\n## 配置选项\n\n`CodegenOptions` 接口提供以下可配置项：\n\n| 选项 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `outputPath` | `string` | `'tests'` | 测试文件输出目录 |\n| `testNamePrefix` | `string` | `'MCP'` | 测试名称前缀 |\n| `includeComments` | `boolean` | `true` | 是否在生成的代码中包含注释 |\n\n```typescript\nconst DEFAULT_OPTIONS: Required = {\n outputPath: 'tests',\n testNamePrefix: 'MCP',\n includeComments: true,\n};\n```\n\n资料来源：[src/tools/codegen/generator.ts:10-15]()\n\n### 自定义配置示例\n\n```json\n{\n \"options\": {\n \"outputPath\": \"/path/to/e2e\",\n \"testNamePrefix\": \"E2E\",\n \"includeComments\": true\n }\n}\n```\n\n## MCP 工具接口\n\n### start_codegen_session\n\n启动一个新的代码生成会话。\n\n**参数**：\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| `options` | `CodegenOptions` | 否 | 代码生成配置选项 |\n\n**返回值**：包含会话 ID 和状态的对象\n\n资料来源：[src/tools/codegen/index.ts:35-50]()\n\n### record_action\n\n记录单个工具调用操作到当前会话。\n\n**参数**：\n\n| 参数名 | 类型 | 说明 |\n|--------|------|------|\n| `toolName` | `string` | 工具名称 |\n| `args` | `object` | 工具参数 |\n| `result` | `object` | 工具执行结果 |\n\n### generate_playwright_test\n\n根据记录的会话生成 Playwright 测试代码。\n\n**参数**：\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| `sessionId` | `string` | 是 | 会话 ID |\n\n**返回值**：`CodegenResult`，包含生成的代码和文件路径\n\n资料来源：[src/tools/codegen/generator.ts:30-45]()\n\n### get_codegen_session\n\n获取指定会话的信息和已记录的操作。\n\n**参数**：\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| `sessionId` | `string` | 是 | 会话 ID |\n\n### cleanup_codegen_session\n\n清理指定会话，释放相关资源。\n\n**参数**：\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| `sessionId` | `string` | 是 | 会话 ID |\n\n## PlaywrightGenerator 类\n\n`PlaywrightGenerator` 是核心的测试代码生成器类，负责将操作记录转化为 Playwright 测试代码。\n\n```typescript\nexport class PlaywrightGenerator {\n private static readonly DEFAULT_OPTIONS: Required = {\n outputPath: 'tests',\n testNamePrefix: 'MCP',\n includeComments: true,\n };\n\n private options: Required;\n}\n```\n\n### 公共方法\n\n| 方法 | 返回类型 | 说明 |\n|------|----------|------|\n| `generateTest(session)` | `Promise` | 生成测试代码 |\n| `createTestCase(session)` | `PlaywrightTestCase` | 创建测试用例对象 |\n| `generateTestCode(testCase)` | `string` | 生成测试代码字符串 |\n| `getOutputFilePath(session)` | `string` | 获取输出文件路径 |\n\n### 生成流程\n\n```mermaid\ngraph TD\n A[generateTest] --> B[验证 session 数据]\n B --> C[createTestCase]\n C --> D[生成测试用例对象]\n D --> E[generateTestCode]\n E --> F[获取输出文件路径]\n F --> G[返回 CodegenResult]\n```\n\n资料来源：[src/tools/codegen/generator.ts:35-55]()\n\n### 选项验证\n\n`validateOptions` 方法确保配置选项的类型正确：\n\n| 验证规则 | 选项 | 类型要求 |\n|----------|------|----------|\n| 1 | `outputPath` | 必须为字符串 |\n| 2 | `testNamePrefix` | 必须为字符串 |\n| 3 | `includeComments` | 必须为布尔值 |\n\n如果选项类型不匹配，将抛出相应的验证错误。\n\n资料来源：[src/tools/codegen/generator.ts:20-30]()\n\n## 错误处理\n\n### 会话验证\n\n- 无效的会话数据将抛出 `Invalid session data` 错误\n- 会话必须包含有效的 `actions` 数组\n\n### 选项验证\n\n- `outputPath` 类型错误抛出 `outputPath must be a string`\n- `testNamePrefix` 类型错误抛出 `testNamePrefix must be a string`\n- `includeComments` 类型错误抛出 `includeComments must be a boolean`\n\n### 常见错误场景\n\n| 错误场景 | 错误信息 |\n|----------|----------|\n| 空 session | `Invalid session data` |\n| actions 非数组 | `Invalid session data` |\n| 选项类型错误 | `{optionName} must be a {type}` |\n\n资料来源：[src/tools/codegen/generator.ts:25-40]()\n\n## 使用示例\n\n### 基本使用流程\n\n```mermaid\nsequenceDiagram\n participant User\n participant MCP as MCP Server\n participant Recorder as ActionRecorder\n participant Generator as PlaywrightGenerator\n\n User->>MCP: start_codegen_session()\n MCP->>Recorder: 创建新会话\n User->>MCP: 导航到页面\n User->>MCP: record_action(\"navigate\", args)\n MCP->>Recorder: 记录操作\n User->>MCP: 执行其他操作\n User->>MCP: generate_playwright_test(sessionId)\n MCP->>Generator: 生成测试代码\n Generator-->>User: 返回测试代码\n```\n\n### 完整配置示例\n\n```json\n{\n \"name\": \"start_codegen_session\",\n \"description\": \"Start a new code generation session to record MCP tool actions\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"options\": {\n \"type\": \"object\",\n \"description\": \"Code generation options\",\n \"properties\": {\n \"outputPath\": { \"type\": \"string\" },\n \"testNamePrefix\": { \"type\": \"string\" },\n \"includeComments\": { \"type\": \"boolean\" }\n }\n }\n }\n }\n}\n```\n\n资料来源：[src/tools/codegen/index.ts:35-60]()\n\n## 全局状态管理\n\n代码生成模块使用全局变量存储浏览器和页面实例：\n\n```typescript\ndeclare global {\n var browser: Browser | undefined;\n var page: Page | undefined;\n}\n```\n\n这允许在工具调用之间共享 Playwright 浏览器和页面上下文。\n\n资料来源：[src/tools/codegen/index.ts:14-20]()\n\n## 与其他模块的关系\n\n```mermaid\ngraph TD\n A[codegen 模块] --> B[logging 模块]\n A --> C[browser 工具]\n A --> D[MCP SDK]\n \n B --> B1[middleware.ts]\n B --> B2[logger.ts]\n \n C --> C1[navigate.ts]\n C --> C2[screenshot.ts]\n C --> C3[click.ts]\n```\n\ncodegen 模块依赖于 logging 模块进行操作记录，并使用 browser 工具执行实际的浏览器操作。\n\n## 最佳实践\n\n1. **会话管理**：在完成操作录制后及时清理会话，避免内存泄漏\n2. **路径配置**：使用绝对路径或确保相对路径相对于工作区根目录\n3. **命名规范**：使用有意义的 `testNamePrefix` 以便识别生成的测试\n4. **注释保留**：在开发阶段保持 `includeComments: true` 以便理解生成的代码\n5. **工具命名**：注意 Cursor 等客户端对工具名称有 60 字符限制\n\n资料来源：[README.md:1-10]()\n\n## 相关文档\n\n- [HTTP 模式示例](../examples/http-mode-example.md)\n- [Docker 部署指南](./DOCKER.md)\n- [主要工具文档](./tools/README.md)\n\n---\n\n\n\n## HTTP/SSE 传输模式\n\n### 相关页面\n\n相关主题：[系统架构](#architecture), [客户端配置指南](#client-configuration), [Docker 容器化部署](#docker-deployment)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/http-server.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/http-server.ts)\n- [src/sse/server.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/sse/server.ts)\n- [src/sse/types.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/sse/types.ts)\n- [src/sse/index.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/sse/index.ts)\n- [examples/http-mode-example.md](https://github.com/executeautomation/mcp-playwright/blob/main/examples/http-mode-example.md)\n \n\n# HTTP/SSE 传输模式\n\n## 概述\n\nHTTP/SSE 传输模式是 Playwright MCP Server 在 1.0.7 版本中引入的一种独立 HTTP 服务器部署方式。该模式允许将传统的 stdio 通信方式替换为基于 HTTP 和 Server-Sent Events (SSE) 的网络传输架构，适用于在无显示环境的系统中运行有头浏览器、从 IDE 工作进程发起连接，或需要支持多个并发客户端的场景。\n\n此传输模式的核心价值在于将 MCP 协议适配到标准的 HTTP 协议栈上，使得客户端可以通过 RESTful API 与 MCP 服务器进行交互，同时利用 SSE 机制实现服务端向客户端的实时事件推送。\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TB\n subgraph \"MCP 客户端\"\n A[Claude Desktop / VS Code]\n B[自定义 HTTP 客户端]\n C[curl / Postman]\n end\n \n subgraph \"HTTP/SSE 服务器\"\n D[Express Server
端口: 8931]\n E[SSE 连接管理器]\n F[Session 管理器]\n G[请求日志中间件]\n end\n \n subgraph \"MCP Server Core\"\n H[工具处理器]\n I[浏览器工具集]\n J[Playwright 引擎]\n end\n \n A -->|\"HTTP POST /mcp\"| D\n B -->|\"HTTP POST /mcp\"| D\n C -->|\"HTTP GET /health\"| D\n D --> G\n G --> F\n F --> E\n E -.->|\"SSE Stream\"| A\n D --> H\n H --> I\n I --> J\n \n style D fill:#e1f5fe\n style E fill:#fff3e0\n style F fill:#e8f5e9\n```\n\n### 核心组件\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| HTTP Server | `src/http-server.ts` | 启动 Express 服务器，路由配置，端点暴露 |\n| SSE Server | `src/sse/server.ts` | 管理 SSE 连接，处理事件流推送 |\n| SSE Types | `src/sse/types.ts` | 定义 SSE 相关的数据类型和接口 |\n| Session Manager | 内置于 `http-server.ts` | 管理多会话生命周期，跟踪连接状态 |\n| 日志中间件 | `src/logging/middleware.ts` | 请求日志记录，错误分类，性能监控 |\n\n## 启动服务器\n\n### 基本启动命令\n\n```bash\n# 使用 npx 启动\nnpx @executeautomation/playwright-mcp-server --port 8931\n\n# 全局安装后启动\nnpm install -g @executeautomation/playwright-mcp-server\nplaywright-mcp-server --port 8931\n```\n\n服务器启动后会显示以下端点信息：\n\n```\n==============================================\nPlaywright MCP Server (HTTP Mode)\n==============================================\nPort: 8931\n\nENDPOINTS:\n- SSE Stream: GET http://localhost:8931/sse\n- Messages: POST http://localhost:8931/messages?sessionId=\n- MCP (unified): GET http://localhost:8931/mcp\n- MCP (unified): POST http://localhost:8931/mcp?sessionId=\n- Health Check: GET http://localhost:8931/health\n```\n\n资料来源：[examples/http-mode-example.md:1-20]()\n\n### 环境变量配置\n\n| 变量名 | 说明 | 默认值 |\n|--------|------|--------|\n| `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD` | 跳过浏览器下载 | `1` |\n| `OPENAI_API_KEY` | API 密钥（用于评估） | - |\n\n## API 端点详解\n\n### 健康检查端点\n\n```\nGET http://localhost:8931/health\n```\n\n用于验证服务器运行状态，返回服务器健康状态信息。\n\n```bash\ncurl http://localhost:8931/health\n```\n\n资料来源：[examples/http-mode-example.md:30]()\n\n### SSE 流端点\n\n```\nGET http://localhost:8931/sse\n```\n\n建立与服务端的 SSE 连接，接收服务端推送的事件流。适用于需要实时接收 MCP 工具执行结果或通知的场景。\n\n### 消息发送端点\n\n```\nPOST http://localhost:8931/messages?sessionId=\nContent-Type: application/json\n\n{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"playwright_navigate\",\n \"arguments\": { \"url\": \"https://example.com\" }\n }\n}\n```\n\n### 统一 MCP 端点\n\n```\nGET http://localhost:8931/mcp # 获取 MCP 连接配置\nPOST http://localhost:8931/mcp # 发送 MCP 请求\nPOST http://localhost:8931/mcp?sessionId= # 指定会话的 MCP 请求\n```\n\n统一端点将 SSE 流和消息发送合并为一个简洁的接口，是推荐使用的端点。\n\n## 客户端配置\n\n### Claude Desktop 配置\n\nClaude Desktop 目前需要使用 stdio 模式，不支持 HTTP 模式。如需远程访问，推荐通过 SSH 隧道方式连接。\n\n### 自定义客户端配置\n\n```json\n{\n \"mcpServers\": {\n \"playwright\": {\n \"url\": \"http://localhost:8931/mcp\"\n }\n }\n}\n```\n\n资料来源：[examples/http-mode-example.md:18-24]()\n\n## 会话管理\n\n### 会话生命周期\n\n```mermaid\nstateDiagram-v2\n [*] --> 创建会话: 首次连接\n 创建会话 --> 活跃: 开始通信\n 活跃 --> 活跃: 发送请求\n 活跃 --> 心跳: 空闲超时\n 心跳 --> 活跃: 收到消息\n 心跳 --> 关闭: 超时\n 活跃 --> 关闭: 客户端断开\n 关闭 --> [*]: 清理资源\n```\n\n### 会话标识\n\n每个客户端连接通过 `sessionId` 参数进行标识，支持多个客户端并发连接。服务器自动管理会话的创建、维护和销毁。\n\n## 安全特性\n\n### 本地绑定\n\n服务器默认绑定到 `127.0.0.1`（localhost），防止外部网络访问：\n\n> **安全说明**：服务器默认仅监听本地回环地址，这可以防止意外的网络暴露和未授权访问。\n\n资料来源：[README.md:40-45]()\n\n### SSH 隧道远程访问\n\n如需从远程机器访问，建议使用 SSH 隧道：\n\n```bash\nssh -L 8931:localhost:8931 user@server-host\n```\n\n这种方式可以在保持服务器本地绑定的同时，实现安全的远程访问。\n\n## 日志与监控\n\n### 请求日志中间件\n\n`src/logging/middleware.ts` 实现了完整的请求日志系统：\n\n| 功能 | 说明 |\n|------|------|\n| 请求 ID 生成 | 为每个请求分配唯一标识符 |\n| 执行时间记录 | 记录工具执行的开始和结束时间 |\n| 参数脱敏 | 自动移除敏感字段（password、token、secret、key、auth） |\n| 错误分类 | 将错误分为 validation、system、resource 等类别 |\n\n### 日志级别\n\n系统支持以下日志级别，按优先级从低到高：\n\n1. `debug` - 调试信息\n2. `info` - 一般信息\n3. `warn` - 警告信息\n4. `error` - 错误信息\n\n### 文件日志\n\n日志默认写入文件而非控制台，以保证 stdio 模式下的 JSON-RPC 通信不被干扰。日志文件位置：`~/playwright-mcp-server.log`\n\n## 错误处理\n\n### 错误分类系统\n\n| 类别 | 触发条件 | 示例消息 |\n|------|----------|----------|\n| `validation` | 参数验证失败 | invalid、validation、required |\n| `resource` | 资源不可用 | browser、page、connection、closed |\n| `authentication` | 认证授权问题 | unauthorized、forbidden、permission |\n| `rate_limit` | 速率限制 | rate limit、too many requests |\n| `system` | 系统级错误 | timeout、element、navigation |\n\n### 错误上下文捕获\n\n错误对象包含丰富的上下文信息：\n\n```typescript\n{\n errorName: string,\n errorMessage: string,\n stack: string,\n timestamp: ISO8601,\n nodeVersion: string,\n platform: string,\n arch: string,\n memoryUsage: object,\n uptime: number,\n toolName?: string,\n toolCategory?: string\n}\n```\n\n资料来源：[src/logging/middleware.ts:100-115]()\n\n## 部署场景\n\n### Docker 部署\n\n在 Docker 容器中运行时，HTTP 模式特别有用：\n\n```bash\ndocker run -i --rm \\\n -p 8931:8931 \\\n mcp-playwright:latest\n```\n\n容器内运行需要使用 `-i` 标志保持 STDIN 开放，以便 MCP 服务器正常工作。\n\n### Docker Compose 配置\n\n```yaml\nservices:\n playwright-mcp:\n image: mcp-playwright:latest\n ports:\n - \"8931:8931\"\n environment:\n - NODE_ENV=production\n healthcheck:\n test: [\"CMD\", \"curl\", \"-f\", \"http://localhost:8931/health\"]\n interval: 30s\n timeout: 10s\n retries: 3\n```\n\n### 资源限制\n\n```bash\ndocker run -i --rm \\\n --cpus=\"2.0\" \\\n --memory=\"2g\" \\\n -p 8931:8931 \\\n mcp-playwright:latest\n```\n\n## 与 Stdio 模式对比\n\n| 特性 | Stdio 模式 | HTTP/SSE 模式 |\n|------|------------|----------------|\n| 通信方式 | 标准输入/输出 | HTTP + SSE |\n| 多客户端 | 不支持 | 支持 |\n| 远程访问 | 不直接支持 | 支持（需 SSH 隧道） |\n| 健康检查 | 无 | 有（`/health`） |\n| Claude Desktop | 支持 | 不支持 |\n| VS Code | 支持 | 支持 |\n| 日志输出 | 文件 | 文件 + 可配置 |\n\n## 故障排除\n\n### 容器立即退出\n\nMCP 服务器需要通过 STDIN 接收输入。确保使用 `-i` 标志：\n\n```bash\ndocker run -i --rm mcp-playwright:latest\n```\n\n### 浏览器未找到\n\nDocker 镜像默认跳过浏览器下载以减小体积。如需预装浏览器，创建自定义 Dockerfile：\n\n```dockerfile\nFROM mcp-playwright:latest\nRUN npx playwright install chromium --with-deps\n```\n\n### 端口占用\n\n如果 8931 端口被占用，使用其他端口：\n\n```bash\nnpx @executeautomation/playwright-mcp-server --port 8932\n```\n\n## 版本历史\n\n| 版本 | 发布日期 | 主要变更 |\n|------|----------|----------|\n| 1.0.9 | 2025-12-09 | 修复 console 输出缓冲问题，使用 `process.stdout.write()` |\n| 1.0.8 | 2025-12-08 | 改善 HTTP 模式下控制台输出可见性 |\n| 1.0.7 | 2025-12-07 | 初始引入 HTTP/SSE 传输模式，多会话支持，健康检查 |\n\n资料来源：[CHANGELOG.md:1-25]()\n\n---\n\n\n\n## Docker 容器化部署\n\n### 相关页面\n\n相关主题：[HTTP/SSE 传输模式](#http-transport), [客户端配置指南](#client-configuration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [Dockerfile](https://github.com/executeautomation/mcp-playwright/blob/main/Dockerfile)\n- [docker-compose.yml](https://github.com/executeautomation/mcp-playwright/blob/main/docker-compose.yml)\n- [docker-build.sh](https://github.com/executeautomation/mcp-playwright/blob/main/docker-build.sh)\n- [DOCKER.md](https://github.com/executeautomation/mcp-playwright/blob/main/DOCKER.md)\n \n\n# Docker 容器化部署\n\n## 概述\n\nMCP Playwright 项目提供了完整的 Docker 容器化解决方案，使 Playwright MCP 服务器能够在隔离的容器环境中运行。该部署方案具有以下核心特性：\n\n- **隔离执行环境**：通过 Docker 容器提供一致的运行时环境\n- **简化依赖管理**：所有依赖在镜像构建时预装\n- **易于部署分发**：支持 Docker Compose 一键启动\n- **MCP 协议支持**：通过 stdio 或 HTTP 模式与 MCP 客户端通信\n\n资料来源：[DOCKER.md]()\n\n## 架构概览\n\n```mermaid\ngraph TD\n subgraph \"宿主机 (Host)\"\n A[MCP 客户端
Claude Desktop / VS Code]\n B[Docker 守护进程]\n end\n \n subgraph \"Docker 容器\"\n C[Node.js 运行环境]\n D[Playwright MCP Server
dist/index.js]\n E[Playwright 浏览器
Chromium/Firefox/WebKit]\n end\n \n A -->|JSON-RPC / HTTP| B\n B -->|docker run -i| C\n C --> D\n D -->|自动化控制| E\n \n F[本地文件系统] -.->|volume mount| C\n G[screenshots] -.->|volume mount| C\n```\n\n## 镜像构建\n\n### 前置条件\n\n在构建 Docker 镜像前，需要确保：\n\n1. 本地已安装 Docker ([Install Docker](https://docs.docker.com/get-docker/))\n2. 项目已通过 TypeScript 编译\n3. 已安装生产环境依赖\n\n### 构建流程\n\n```mermaid\ngraph LR\n A[npm install --omit=dev] --> B[npm run build]\n B --> C[生成 dist/ 和 node_modules/]\n C --> D[docker build -t mcp-playwright:latest .]\n D --> E[Docker 镜像创建完成]\n```\n\n### 使用构建脚本\n\n项目提供了便捷的构建脚本 `docker-build.sh`：\n\n```bash\nchmod +x docker-build.sh\n./docker-build.sh\n```\n\n该脚本会自动执行以下操作：\n\n1. 安装生产依赖 (`npm install --omit=dev`)\n2. 编译 TypeScript 代码 (`npm run build`)\n3. 构建 Docker 镜像\n\n### 手动构建\n\n手动构建需要分步执行：\n\n```bash\n# 1. 安装生产依赖并构建\nnpm install --omit=dev\nnpm run build\n\n# 2. 构建 Docker 镜像\ndocker build -t mcp-playwright:latest .\n\n# 3. 或指定版本标签\ndocker build -t mcp-playwright:1.0.6 .\n```\n\n**重要提示**：Dockerfile 会从本地构建目录复制 `node_modules` 和 `dist`，因此必须先安装 `--omit=dev` 标志的生产依赖，以保持镜像体积最小化。\n\n资料来源：[DOCKER.md:1-50]()\n\n## 容器运行模式\n\n### 标准模式 (stdio)\n\nstdio 模式是 **Claude Desktop 推荐的运行方式**。MCP 服务器通过标准输入输出与客户端通信：\n\n```bash\ndocker run -i --rm mcp-playwright:latest\n```\n\n| 参数 | 说明 |\n|------|------|\n| `-i` | 保持 STDIN 打开，支持交互式通信 |\n| `--rm` | 容器退出时自动删除 |\n| `mcp-playwright:latest` | 镜像名称和标签 |\n\n### Docker Compose 模式\n\n项目提供了 `docker-compose.yml` 配置文件：\n\n```bash\n# 启动服务\ndocker compose run --rm playwright-mcp\n\n# 或先构建后运行\ndocker compose build\ndocker compose run --rm playwright-mcp\n```\n\n`docker-compose.yml` 核心配置：\n\n| 配置项 | 值 | 说明 |\n|--------|-----|------|\n| `stdin_open` | true | 打开标准输入 |\n| `tty` | true | 分配伪终端 |\n| `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD` | 1 | 跳过浏览器下载 |\n\n资料来源：[docker-compose.yml]()\n\n## MCP 客户端集成\n\n### Claude Desktop 配置\n\n对于 Claude Desktop 用户，需要修改配置文件：\n\n**配置文件位置**：\n\n| 操作系统 | 路径 |\n|----------|------|\n| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Windows | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| Linux | `~/.config/Claude/claude_desktop_config.json` |\n\n**配置示例**：\n\n```json\n{\n \"mcpServers\": {\n \"playwright-docker\": {\n \"command\": \"docker\",\n \"args\": [\"run\", \"-i\", \"--rm\", \"mcp-playwright:latest\"]\n }\n }\n}\n```\n\n### VS Code MCP 扩展配置\n\n对于 VS Code MCP 扩展：\n\n```json\n{\n \"name\": \"playwright-docker\",\n \"command\": \"docker\",\n \"args\": [\"run\", \"-i\", \"--rm\", \"mcp-playwright:latest\"]\n}\n```\n\n## 环境变量配置\n\n| 变量名 | 说明 | 默认值 |\n|--------|------|--------|\n| `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD` | 跳过浏览器下载 | 未设置 |\n| `NODE_ENV` | Node.js 运行环境 | `production` |\n\n### 命令行设置环境变量\n\n```bash\ndocker run -i --rm \\\n -e PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 \\\n -e NODE_ENV=production \\\n mcp-playwright:latest\n```\n\n### docker-compose.yml 设置环境变量\n\n```yaml\nservices:\n playwright-mcp:\n environment:\n - PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1\n - NODE_ENV=production\n```\n\n资料来源：[DOCKER.md:50-80]()\n\n## 数据持久化\n\n### 卷挂载配置\n\n如需与容器共享文件或持久化数据，可使用 volume 挂载：\n\n```bash\ndocker run -i --rm \\\n -v $(pwd)/data:/app/data \\\n -v $(pwd)/screenshots:/app/screenshots \\\n mcp-playwright:latest\n```\n\n### docker-compose.yml 卷配置\n\n```yaml\nservices:\n playwright-mcp:\n volumes:\n - ./data:/app/data\n - ./screenshots:/app/screenshots\n```\n\n**注意**：挂载的目录路径必须是绝对路径或使用 `$(pwd)` 获取当前目录。\n\n## 故障排除\n\n### 容器立即退出\n\n**问题**：容器启动后立即退出\n\n**原因**：MCP 服务器需要通过 stdin 接收输入，未使用 `-i` 标志\n\n**解决方案**：\n\n```bash\n# 错误\ndocker run --rm mcp-playwright:latest\n\n# 正确\ndocker run -i --rm mcp-playwright:latest\n```\n\n### 浏览器未找到\n\n**问题**：运行时报错找不到浏览器\n\n**原因**：Docker 镜像默认跳过浏览器下载以减小体积\n\n**解决方案**：创建自定义 Dockerfile 预装浏览器\n\n```dockerfile\nFROM mcp-playwright:latest\n\n# 安装 Playwright 浏览器\nRUN npx playwright install chromium --with-deps\n```\n\n### 权限问题\n\n**问题**：挂载卷出现权限拒绝\n\n**解决方案**：以指定用户身份运行\n\n```bash\ndocker run -i --rm \\\n -v $(pwd)/data:/app/data \\\n --user $(id -u):$(id -g) \\\n mcp-playwright:latest\n```\n\n资料来源：[DOCKER.md:100-130]()\n\n## 高级配置\n\n### 资源限制\n\n```bash\ndocker run -i --rm \\\n --cpus=\"2.0\" \\\n --memory=\"2g\" \\\n mcp-playwright:latest\n```\n\n### docker-compose.yml 资源限制配置\n\n```yaml\nservices:\n playwright-mcp:\n deploy:\n resources:\n limits:\n cpus: '2.0'\n memory: 2G\n```\n\n### 健康检查配置\n\n```yaml\nservices:\n playwright-mcp:\n healthcheck:\n test: [\"CMD\", \"node\", \"-e\", \"process.exit(0)\"]\n interval: 30s\n timeout: 10s\n retries: 3\n```\n\n### 自定义网络配置\n\n```bash\n# 创建网络\ndocker network create mcp-network\n\n# 在指定网络中运行\ndocker run -i --rm --network mcp-network mcp-playwright:latest\n```\n\n## 从源码构建 Docker 镜像\n\n如果希望完全在 Docker 内构建（不使用本地预编译的 dist）：\n\n```dockerfile\nFROM node:20-alpine AS builder\n\nWORKDIR /app\nCOPY package*.json ./\nENV PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1\nRUN npm ci\n\nCOPY src ./src\nCOPY tsconfig.json ./\nRUN npm run build\n\nFROM node:20-alpine\nWORKDIR /app\nCOPY --from=builder /app/dist ./dist\nCOPY --from=builder /app/package*.json ./\nRUN npm ci --only=production\nCMD [\"node\", \"dist/index.js\"]\n```\n\n此多阶段构建方式：\n\n1. **Builder 阶段**：安装依赖并编译 TypeScript\n2. **Runtime 阶段**：仅复制生产文件，减小镜像体积\n\n## 安全最佳实践\n\n### 以非 root 用户运行\n\n```dockerfile\nFROM mcp-playwright:latest\nUSER node\n```\n\n### 只读根文件系统\n\n```bash\ndocker run -i --rm --read-only mcp-playwright:latest\n```\n\n### 安全扫描\n\n```bash\ndocker scan mcp-playwright:latest\n```\n\n## 镜像优化\n\n当前 Dockerfile 优化策略：\n\n| 优化项 | 说明 |\n|--------|------|\n| 基础镜像 | Debian-based slim Node.js (~200MB) |\n| 复制策略 | 复制预编译的 dist 目录 |\n| 依赖策略 | 仅安装生产依赖 |\n| 浏览器 | 默认跳过下载 |\n\n**当前镜像大小**：约 200MB（不含浏览器）\n\n资料来源：[DOCKER.md:180-200]()\n\n## 快速入门命令汇总\n\n```bash\n# 1. 克隆项目\ngit clone https://github.com/executeautomation/mcp-playwright.git\ncd mcp-playwright\n\n# 2. 构建镜像\n./docker-build.sh\n\n# 3. 测试运行\ndocker run -i --rm mcp-playwright:latest\n\n# 4. 配置 Claude Desktop\n# 编辑 ~/.config/Claude/claude_desktop_config.json\n\n# 5. 重启客户端服务\n# 重启 Claude Desktop 使配置生效\n```\n\n## 相关信息\n\n- **项目地址**：[executeautomation/mcp-playwright](https://github.com/executeautomation/mcp-playwright)\n- **问题反馈**：[GitHub Issues](https://github.com/executeautomation/mcp-playwright/issues)（请添加 `docker` 标签）\n- **标准模式部署**：请参阅 [README.md](./README.md) 了解 stdio 模式配置\n- **HTTP 模式部署**：请参阅 [examples/http-mode-example.md](./examples/http-mode-example.md) 了解独立服务器部署\n\n---\n\n\n\n## 客户端配置指南\n\n### 相关页面\n\n相关主题：[快速入门指南](#getting-started), [HTTP/SSE 传输模式](#http-transport), [Docker 容器化部署](#docker-deployment)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/executeautomation/mcp-playwright/blob/main/README.md)\n- [DOCKER.md](https://github.com/executeautomation/mcp-playwright/blob/main/DOCKER.md)\n- [examples/http-mode-example.md](https://github.com/executeautomation/mcp-playwright/blob/main/examples/http-mode-example.md)\n- [src/http-server.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/http-server.ts)\n- [package.json](https://github.com/executeautomation/mcp-playwright/blob/main/package.json)\n \n\n# 客户端配置指南\n\n## 概述\n\nPlaywright MCP Server 支持多种客户端配置方式，以满足不同开发环境和部署场景的需求。本指南涵盖 **stdio 模式**（Claude Desktop 等）、**HTTP 模式**（VS Code、自定义客户端等）以及 **Docker 部署**的完整配置说明。\n\n## 架构概览\n\n```mermaid\ngraph TD\n A[MCP 客户端] --> B{通信模式}\n B -->|stdio| C[标准输入输出]\n B -->|HTTP| D[SSE/Messages 端点]\n \n C --> E[playwright-mcp-server]\n D --> E\n \n E --> F[Playwright 浏览器]\n F --> G[自动化操作]\n \n H[日志文件] -.->|~/playwright-mcp-server.log| E\n```\n\n## Stdio 模式配置\n\nStdio 模式是 MCP 协议的默认通信方式，适用于 Claude Desktop 等支持标准输入输出的客户端。\n\n### Claude Desktop 配置\n\n**配置文件位置：**\n\n| 操作系统 | 配置文件路径 |\n|---------|------------|\n| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Windows | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| Linux | `~/.config/Claude/claude_desktop_config.json` |\n\n**配置示例：**\n\n```json\n{\n \"mcpServers\": {\n \"playwright\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@executeautomation/playwright-mcp-server\"]\n }\n }\n}\n```\n\n资料来源：[README.md:1-15]()\n\n**注意事项：**\n\n- stdio 模式下，日志自动重定向到文件而非控制台，以保持 JSON-RPC 通信的纯净性\n- 日志文件位置：`~/playwright-mcp-server.log` 资料来源：[README.md:18]()\n\n### Cline 与 Cursor 配置\n\n对于 Cline 和 Cursor 等编辑器插件，工具名称长度限制为 60 字符（`server_name:tool_name`）。由于服务器名称为 `playwright-mcp`，请确保自定义工具名称不超过 40 字符。 资料来源：[README.md:5-10]()\n\n## HTTP 模式配置\n\nHTTP 模式适用于无显示环境（如 headless 系统）或 IDE 工作进程中的有头浏览器运行场景。\n\n### 服务器启动\n\n```bash\n# 使用 npx 启动\nnpx @executeautomation/playwright-mcp-server --port 8931\n\n# 全局安装后启动\nnpm install -g @executeautomation/playwright-mcp-server\nplaywright-mcp-server --port 8931\n```\n\n资料来源：[README.md:22-27]()\n\n### 端点说明\n\n| 端点类型 | 方法 | URL 格式 | 用途 |\n|---------|------|---------|------|\n| SSE 流 | GET | `http://localhost:8931/sse` | 服务器发送事件流 |\n| 消息 | POST | `http://localhost:8931/messages?sessionId=` | 发送消息 |\n| MCP 统一 | GET/POST | `http://localhost:8931/mcp` | 统一 MCP 接口 |\n| 健康检查 | GET | `http://localhost:8931/health` | 服务状态检查 |\n\n资料来源：[src/http-server.ts:1-50]()\n\n### HTTP 服务器安全配置\n\n服务器默认绑定到 `127.0.0.1`（localhost），防止外部网络访问：\n\n```mermaid\ngraph LR\n A[客户端] -->|localhost| B[127.0.0.1:8931]\n C[外部请求] -.->|✗ 已阻止| B\n```\n\n资料来源：[src/http-server.ts:35-36]()\n\n### Claude Desktop HTTP 配置\n\n```json\n{\n \"mcpServers\": {\n \"playwright\": {\n \"url\": \"http://localhost:8931/mcp\"\n }\n }\n}\n```\n\n资料来源：[examples/http-mode-example.md:1-15]()\n\n### 健康检查\n\n```bash\ncurl http://localhost:8931/health\n```\n\n响应示例：\n\n```json\n{\n \"status\": \"ok\",\n \"version\": \"1.x.x\",\n \"activeSessions\": 0\n}\n```\n\n## Docker 部署配置\n\n### Docker 运行\n\n**基本命令：**\n\n```bash\ndocker run -i --rm mcp-playwright:latest\n```\n\n参数说明：\n\n| 参数 | 作用 |\n|-----|------|\n| `-i` | 保持 STDIN 打开，支持交互式通信 |\n| `--rm` | 容器退出时自动删除 |\n| `mcp-playwright:latest` | 镜像名称和标签 |\n\n资料来源：[DOCKER.md:40-50]()\n\n**Docker Compose 配置：**\n\n```yaml\nservices:\n playwright-mcp:\n image: mcp-playwright:latest\n```\n\n启动命令：\n\n```bash\n# 启动服务\ndocker compose run --rm playwright-mcp\n\n# 构建并运行\ndocker compose build\ndocker compose run --rm playwright-mcp\n```\n\n### Docker 客户端配置\n\n**Claude Desktop Docker 配置：**\n\n```json\n{\n \"mcpServers\": {\n \"playwright-docker\": {\n \"command\": \"docker\",\n \"args\": [\"run\", \"-i\", \"--rm\", \"mcp-playwright:latest\"]\n }\n }\n}\n```\n\n资料来源：[DOCKER.md:10-20]()\n\n**VS Code MCP Extension 配置：**\n\n```json\n{\n \"name\": \"playwright-docker\",\n \"command\": \"docker\",\n \"args\": [\"run\", \"-i\", \"--rm\", \"mcp-playwright:latest\"]\n}\n```\n\n资料来源：[DOCKER.md:22-28]()\n\n## 环境变量配置\n\n### Docker 环境变量\n\n通过 `-e` 参数传递环境变量：\n\n```bash\ndocker run -i --rm \\\n -e PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 \\\n -e NODE_ENV=production \\\n mcp-playwright:latest\n```\n\n**常用环境变量：**\n\n| 变量名 | 默认值 | 说明 |\n|-------|-------|------|\n| `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD` | 未设置 | 设为 `1` 跳过浏览器下载 |\n| `NODE_ENV` | `production` | Node.js 运行环境 |\n\n资料来源：[DOCKER.md:30-45]()\n\n### Docker Compose 环境变量\n\n```yaml\nservices:\n playwright-mcp:\n environment:\n - PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1\n - NODE_ENV=production\n```\n\n## 存储卷挂载\n\n### 数据持久化\n\n```bash\ndocker run -i --rm \\\n -v $(pwd)/data:/app/data \\\n -v $(pwd)/screenshots:/app/screenshots \\\n mcp-playwright:latest\n```\n\n### Docker Compose 卷配置\n\n```yaml\nservices:\n playwright-mcp:\n volumes:\n - ./data:/app/data\n - ./screenshots:/app/screenshots\n```\n\n资料来源：[DOCKER.md:48-55]()\n\n## 高级配置\n\n### 资源限制\n\n```bash\ndocker run -i --rm \\\n --cpus=\"2.0\" \\\n --memory=\"2g\" \\\n mcp-playwright:latest\n```\n\nDocker Compose 配置：\n\n```yaml\nservices:\n playwright-mcp:\n deploy:\n resources:\n limits:\n cpus: '2.0'\n memory: 2G\n```\n\n资料来源：[DOCKER.md:130-140]()\n\n### 自定义网络\n\n```bash\ndocker network create mcp-network\ndocker run -i --rm --network mcp-network mcp-playwright:latest\n```\n\n### 用户权限配置\n\n解决挂载卷权限问题：\n\n```bash\ndocker run -i --rm \\\n -v $(pwd)/data:/app/data \\\n --user $(id -u):$(id -g) \\\n mcp-playwright:latest\n```\n\n### 健康检查配置\n\n```yaml\nservices:\n playwright-mcp:\n healthcheck:\n test: [\"CMD\", \"node\", \"-e\", \"process.exit(0)\"]\n interval: 30s\n timeout: 10s\n retries: 3\n```\n\n## 故障排查\n\n### 容器立即退出\n\n**问题原因：** MCP 服务器需要通过 stdin 接收输入。\n\n**解决方案：** 确保使用 `-i` 参数：\n\n```bash\ndocker run -i --rm mcp-playwright:latest\n```\n\n资料来源：[DOCKER.md:60-65]()\n\n### 浏览器未找到\n\nDocker 镜像默认跳过浏览器下载以减小体积。首次使用时 Playwright 会自动下载浏览器。\n\n**预安装浏览器（自定义 Dockerfile）：**\n\n```dockerfile\nFROM mcp-playwright:latest\n\n# 安装 Playwright 浏览器\nRUN npx playwright install chromium --with-deps\n```\n\n资料来源：[DOCKER.md:70-75]()\n\n## 完整配置示例\n\n### 最小化配置（Stdio 模式）\n\n```json\n{\n \"mcpServers\": {\n \"playwright\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@executeautomation/playwright-mcp-server\"]\n }\n }\n}\n```\n\n### 生产环境配置（HTTP 模式）\n\n```json\n{\n \"mcpServers\": {\n \"playwright\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"-i\",\n \"--rm\",\n \"--cpus=2.0\",\n \"--memory=2g\",\n \"-e\", \"NODE_ENV=production\",\n \"mcp-playwright:latest\"\n ]\n }\n }\n}\n```\n\n### Docker Compose 完整配置\n\n```yaml\nservices:\n playwright-mcp:\n image: mcp-playwright:latest\n environment:\n - PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1\n - NODE_ENV=production\n volumes:\n - ./data:/app/data\n - ./screenshots:/app/screenshots\n deploy:\n resources:\n limits:\n cpus: '2.0'\n memory: 2G\n healthcheck:\n test: [\"CMD\", \"node\", \"-e\", \"process.exit(0)\"]\n interval: 30s\n timeout: 10s\n retries: 3\n```\n\n## 版本信息\n\n当前稳定版本参考 [CHANGELOG.md](https://github.com/executeautomation/mcp-playwright/blob/main/CHANGELOG.md)：\n\n| 版本 | 发布日期 | 主要特性 |\n|-----|---------|---------|\n| 1.0.2 | 2024-11-10 | 多浏览器支持（Chromium、Firefox、WebKit） |\n| 1.0.0 | 2024-11-01 | 首个主要版本，重构工具结构 |\n\n**依赖版本：**\n\n| 包名 | 版本 |\n|-----|------|\n| `@modelcontextprotocol/sdk` | 1.24.3 |\n| `playwright` | 1.57.0 |\n| `@playwright/browser-chromium` | 1.57.0 |\n\n资料来源：[package.json:1-30]()\n\n---\n\n\n\n## 日志与监控\n\n### 相关页面\n\n相关主题：[系统架构](#architecture), [故障排除指南](#troubleshooting)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/logging/index.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/index.ts)\n- [src/logging/logger.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/logger.ts)\n- [src/logging/middleware.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/middleware.ts)\n- [src/logging/types.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/types.ts)\n- [src/monitoring/index.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/monitoring/index.ts)\n- [src/monitoring/system.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/monitoring/system.ts)\n- [src/rate-limiting/index.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/rate-limiting/index.ts)\n- [src/rate-limiting/limiter.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/rate-limiting/limiter.ts)\n \n\n# 日志与监控\n\n## 概述\n\nmcp-playwright 的日志与监控系统为 MCP 服务器提供了一套完整的请求追踪、错误分类和系统健康监测能力。该系统通过统一的日志记录层捕获所有工具调用请求、响应状态和错误信息，同时结合健康检查机制确保服务稳定运行。\n\n核心功能包括：\n\n- **请求日志记录**：追踪所有工具调用的生命周期\n- **错误分类与增强上下文**：自动识别错误类型并收集诊断信息\n- **敏感数据脱敏**：防止日志中泄露密码、Token 等敏感信息\n- **系统健康监控**：实时监测 CPU、内存、错误率等关键指标\n- **日志轮转**：自动管理日志文件大小和数量\n\n## 架构设计\n\n### 系统组件关系\n\n```mermaid\ngraph TD\n A[MCP 客户端请求] --> B[LoggingMiddleware]\n B --> C[Logger]\n B --> D[MonitoringSystem]\n B --> E[工具处理器]\n C --> F[文件日志]\n D --> G[健康检查端点]\n E --> H[Response]\n B --> I[错误处理]\n I --> C\n D --> J[Rate Limiter]\n```\n\n### 日志层级\n\n| 级别 | 用途 | 日志方法 |\n|------|------|----------|\n| debug | 调试信息，仅开发环境使用 | `logger.debug()` |\n| info | 常规操作记录 | `logger.info()` |\n| warn | 警告信息，需要关注但非致命 | `logger.warn()` |\n| error | 错误信息，记录异常和堆栈 | `logger.error()` |\n\n日志级别通过配置控制，低于配置级别的日志不会输出。 资料来源：[src/logging/logger.ts:156-162]()\n\n## 日志系统\n\n### Logger 核心功能\n\nLogger 是日志系统的核心组件，支持以下功能：\n\n| 功能 | 描述 | 配置项 |\n|------|------|--------|\n| 文件输出 | 写入本地日志文件 | `filePath`, `maxFileSize` |\n| 日志轮转 | 自动管理日志文件数量 | `maxFiles` |\n| 级别控制 | 按级别过滤日志 | `level` |\n| 请求上下文 | 记录请求相关详细信息 | `RequestLogContext` |\n| 错误增强 | 附带错误对象信息 | `ErrorLogContext` |\n\n资料来源：[src/logging/logger.ts:1-60]()\n\n### 日志格式化\n\n每条日志条目包含以下结构化数据：\n\n```typescript\ninterface LogEntry {\n timestamp: string; // ISO 8601 格式时间戳\n level: 'debug' | 'info' | 'warn' | 'error';\n message: string; // 日志消息\n requestId?: string; // 请求唯一标识\n context?: Record; // 附加上下文\n}\n```\n\n### 请求日志上下文\n\n```typescript\ninterface RequestLogContext {\n method: string; // HTTP 方法或工具调用类型\n url?: string; // 请求路径或工具名称\n body?: any; // 请求体（已脱敏）\n statusCode?: number; // 响应状态码\n duration?: number; // 处理时长（毫秒）\n userAgent?: string; // 客户端标识\n clientIp?: string; // 客户端 IP\n}\n```\n\n资料来源：[src/logging/middleware.ts:1-40]()\n\n## 中间件层\n\n### LoggingMiddleware 工作流程\n\nLoggingMiddleware 拦截所有 MCP 请求，提供统一的日志记录和错误处理能力：\n\n```mermaid\nsequenceDiagram\n participant Client as MCP 客户端\n participant Middleware as LoggingMiddleware\n participant Logger as Logger\n participant Handler as 工具处理器\n participant Monitoring as MonitoringSystem\n\n Client->>Middleware: 工具调用请求\n Middleware->>Logger: logRequest() - 请求开始\n Middleware->>Handler: 执行工具处理\n Handler-->>Middleware: 处理结果\n alt 成功响应\n Middleware->>Logger: logRequest() - 请求成功\n else 错误响应\n Middleware->>Middleware: captureErrorContext()\n Middleware->>Logger: warn() - 请求错误\n end\n Middleware->>Monitoring: recordRequest()\n Middleware-->>Client: 返回响应\n```\n\n### 错误分类\n\n中间件能够自动识别并分类错误类型：\n\n| 错误类别 | 触发条件 | 示例 |\n|----------|----------|------|\n| validation | 包含 invalid、validation、required 等关键词 | 参数校验失败 |\n| resource | 浏览器断开、页面关闭、协议错误 | 浏览器未启动 |\n| authentication | 未授权、禁止访问、权限问题 | Token 无效 |\n| rate_limit | 速率限制、请求过多 | 请求频率超限 |\n| system | 超时、元素未找到、导航失败 | 元素等待超时 |\n| unknown | 无法归类的其他错误 | 未知异常 |\n\n资料来源：[src/logging/middleware.ts:80-110]()\n\n### 错误上下文捕获\n\n```typescript\ninterface ErrorContext {\n errorName: string; // 错误类型名称\n errorMessage: string; // 错误消息\n stack?: string; // 堆栈跟踪\n timestamp: string; // 错误发生时间\n nodeVersion: string; // Node.js 版本\n platform: string; // 操作系统平台\n arch: string; // CPU 架构\n memoryUsage: object; // 内存使用情况\n uptime: number; // 进程运行时间\n toolName?: string; // 调用的工具名称\n toolCategory?: string; // 工具分类\n}\n```\n\n资料来源：[src/logging/middleware.ts:120-145]()\n\n## 敏感数据保护\n\n### 脱敏策略\n\n日志中间件包含智能数据脱敏功能，防止敏感信息泄露：\n\n| 数据类型 | 脱敏规则 | 示例 |\n|----------|----------|------|\n| 密码字段 | 替换为 `[REDACTED]` | `password: \"***\"` |\n| Token 字段 | 替换为 `[REDACTED]` | `token: \"***\"` |\n| Secret 字段 | 替换为 `[REDACTED]` | `secret: \"***\"` |\n| Key 字段 | 替换为 `[REDACTED]` | `apiKey: \"***\"` |\n| Auth 字段 | 替换为 `[REDACTED]` | `auth: \"***\"` |\n| 长请求体 | 截断并标注长度 | `[TRUNCATED:5000chars]` |\n\n资料来源：[src/logging/middleware.ts:160-180]()\n\n### 工具参数过滤\n\n```typescript\nprivate sanitizeToolArgs(toolName: string, args: any): any {\n // 检测包含敏感关键词的参数\n const sensitiveFields = ['password', 'token', 'secret', 'key', 'auth'];\n // 将敏感字段值替换为 [REDACTED]\n}\n```\n\n## 监控系统\n\n### HealthStatus 系统状态\n\n系统健康状态包含多个检查项：\n\n| 检查项 | 指标 | 阈值 | 状态 |\n|--------|------|------|------|\n| CPU | 使用率 | >80% 警告, >90% 失败 | pass/warn/fail |\n| Memory | 使用率 | >80% 警告, >90% 失败 | pass/warn/fail |\n| Error Rate | 错误率 | >1% 警告, >5% 失败 | pass/warn/fail |\n\n资料来源：[src/monitoring/system.ts:80-120]()\n\n### 健康状态响应格式\n\n```typescript\ninterface HealthStatus {\n status: 'healthy' | 'degraded' | 'unhealthy';\n checks: {\n [key: string]: {\n status: 'pass' | 'warn' | 'fail';\n description: string;\n data: Record;\n };\n };\n timestamp: number;\n version: string;\n}\n```\n\n### 指标收集\n\n监控系统持续收集以下指标：\n\n- **请求计数**：总请求数、成功/失败数\n- **响应时长**：平均、最小、最大响应时间\n- **错误分类统计**：按错误类型分类的错误计数\n- **系统资源**：CPU、内存使用率\n- **分类指标**：按工具分类的请求统计\n\n资料来源：[src/monitoring/system.ts:1-50]()\n\n### HTTP 健康检查服务器\n\n监控系统可启动独立的 HTTP 服务器提供健康检查端点：\n\n```typescript\nasync startMetricsCollection(port: number = 3001): Promise {\n // 启动 HTTP 服务器用于健康检查\n await this.startHttpServer(port);\n}\n```\n\n## 日志输出模式\n\n### STDIO 模式\n\n在标准 MCP stdio 通信模式下，日志自动写入文件而非控制台：\n\n> 日志会自动定向到文件（而非控制台），以保持 JSON-RPC 通信的清洁性。\n\n日志文件位置：`~/playwright-mcp-server.log`\n\n资料来源：[README.md:1-30]()\n\n### HTTP 模式\n\n在 HTTP 服务模式下，可通过以下端点访问：\n\n```\nGET /health - 健康检查端点\nGET /sse - SSE 流式端点\nPOST /messages - 消息处理端点\nGET /mcp - MCP 统一端点\n```\n\n资料来源：[examples/http-mode-example.md:1-30]()\n\n## 日志文件管理\n\n### 日志轮转机制\n\nLogger 实现自动日志轮转功能：\n\n1. **大小检查**：每次写入前检查当前文件大小\n2. **阈值触发**：超过 `maxFileSize` 触发轮转\n3. **文件重命名**：当前日志文件重命名为 `.1` 后缀\n4. **序号递进**：现有轮转文件序号递增（`.1` → `.2` → ...）\n5. **旧文件清理**：超过 `maxFiles` 数量的最旧文件被删除\n\n```mermaid\ngraph LR\n A[app.log] -->|超过 10MB| B[app.log.1]\n B -->|再次轮转| C[app.log.2]\n C -->|再次轮转| D[app.log.3]\n D -->|超过最大数量| X[删除]\n```\n\n资料来源：[src/logging/logger.ts:100-140]()\n\n## 集成使用\n\n### 请求处理中的集成\n\n日志和监控系统通过 `wrapWithMonitoring` 包装器集成到请求处理流程中：\n\n```typescript\nconst wrapWithMonitoring = (\n fn: T,\n category: string\n): T => {\n return (async (...args: any[]) => {\n const startTime = Date.now();\n let success = true;\n \n try {\n const result = await fn(...args);\n // 记录成功指标\n monitoringSystem.recordRequest(duration, true, category);\n return result;\n } catch (error) {\n // 记录失败指标\n monitoringSystem.recordRequest(duration, false, category);\n throw error;\n }\n }) as T;\n};\n```\n\n资料来源：[src/requestHandler.ts:1-50]()\n\n### 资源暴露\n\n日志系统通过 MCP 资源机制暴露以下信息：\n\n| 资源 URI | 类型 | 内容 |\n|----------|------|------|\n| `console://logs` | text/plain | 浏览器控制台日志 |\n| `screenshot://{name}` | image/png | 已存储的截图 |\n\n```typescript\nconst resources = [\n {\n uri: \"console://logs\",\n mimeType: \"text/plain\",\n name: \"Browser console logs\",\n },\n ...Array.from(getScreenshots().keys()).map(name => ({\n uri: `screenshot://${name}`,\n mimeType: \"image/png\",\n name: `Screenshot: ${name}`,\n })),\n];\n```\n\n资料来源：[src/requestHandler.ts:60-80]()\n\n## 配置参考\n\n### 日志配置\n\n```typescript\ninterface LoggerConfig {\n level: 'debug' | 'info' | 'warn' | 'error'; // 日志级别\n filePath: string; // 日志文件路径\n maxFileSize: number; // 单文件最大大小（字节）\n maxFiles: number; // 保留的最大文件数\n console?: boolean; // 是否输出到控制台\n}\n```\n\n### 监控配置\n\n```typescript\ninterface MonitoringConfig {\n enabled: boolean; // 是否启用监控\n metricsInterval: number; // 指标收集间隔（毫秒）\n healthCheckInterval: number; // 健康检查间隔（毫秒）\n}\n```\n\n## 总结\n\nmcp-playwright 的日志与监控系统提供了企业级的可观测性能力：\n\n- **统一日志层**：通过 LoggingMiddleware 拦截所有请求，提供一致的日志格式和错误处理\n- **智能错误分类**：自动识别错误类型并收集丰富的诊断上下文\n- **敏感数据保护**：内置敏感字段脱敏，防止日志泄露\n- **健康监测**：实时监控系统资源和错误率，及时发现服务异常\n- **日志轮转**：自动管理日志文件，避免磁盘空间问题\n\n这套系统确保了 MCP 服务器在生产环境中的可维护性和问题可追溯性。\n\n---\n\n\n\n## 故障排除指南\n\n### 相关页面\n\n相关主题：[Docker 容器化部署](#docker-deployment), [日志与监控](#logging-monitoring), [客户端配置指南](#client-configuration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [DOCKER.md](https://github.com/executeautomation/mcp-playwright/blob/main/DOCKER.md)\n- [README.md](https://github.com/executeautomation/mcp-playwright/blob/main/README.md)\n- [src/logging/middleware.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/middleware.ts)\n- [src/logging/logger.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/logger.ts)\n- [src/http-server.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/http-server.ts)\n- [src/tools/browser/screenshot.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/screenshot.ts)\n- [package.json](https://github.com/executeautomation/mcp-playwright/blob/main/package.json)\n \n\n# 故障排除指南\n\n本文档提供 mcp-playwright 项目的完整故障排除指南，帮助开发者诊断和解决常见问题。\n\n## 概述\n\nmcp-playwright 是一个基于 Playwright 的 MCP（Model Context Protocol）服务器，为 AI 助手提供浏览器自动化能力。故障排除系统采用多层次错误分类机制，能够自动识别和归类不同类型的错误。 资料来源：[src/logging/middleware.ts:1-50]()\n\n### 错误分类体系\n\n系统支持以下错误类别分类：\n\n| 错误类别 | 触发条件 | 处理建议 |\n|---------|---------|---------|\n| validation | 包含 invalid、validation、required、missing parameter | 检查参数格式和必填项 |\n| resource | 浏览器关闭、连接断开、协议错误 | 重启浏览器会话 |\n| system | 超时、元素未找到、导航失败 | 等待元素加载或重试操作 |\n| authentication | 未经授权、权限拒绝 | 检查认证信息 |\n| rate_limit | 请求过多、限流 | 降低请求频率 |\n\n 资料来源：[src/logging/middleware.ts:100-150]()\n\n## 常见问题与解决方案\n\n### 1. 服务器启动问题\n\n#### 1.1 服务无法启动\n\n**症状表现**：\n\n- 终端无响应或报错退出\n- 端口 8931 被占用\n- 连接被拒绝\n\n**诊断步骤**：\n\n```bash\n# 检查端口占用情况\nnetstat -an | grep 8931\n\n# Windows\nnetstat -ano | findstr 8931\n```\n\n**解决方案**：\n\n1. 确认端口 8931 未被其他进程占用\n2. 使用 `--port` 参数指定其他端口\n3. 检查配置文件中的 URL 配置是否正确\n\n 资料来源：[src/http-server.ts:1-30]()\n\n#### 1.2 HTTP 模式安全限制\n\n**重要说明**：HTTP 服务器默认绑定到 `127.0.0.1`（localhost）以确保安全，外部网络无法直接访问。\n\n```typescript\n// 安全绑定配置\nconst host = '127.0.0.1';\nconst httpServer = app.listen(port, host, () => {\n // 服务器仅接受本地连接\n});\n```\n\n**远程访问方案**：使用 SSH 隧道连接远程服务器\n\n```bash\nssh -L 8931:localhost:8931 user@remote-server\n```\n\n 资料来源：[src/http-server.ts:50-70]()\n\n### 2. Docker 相关问题\n\n#### 2.1 容器立即退出\n\n**症状**：容器启动后立即退出\n\n**原因**：MCP 服务器需要通过 stdin/stdout 进行通信，缺少必要的交互参数\n\n**解决方案**：使用 `-i` 参数保持标准输入打开\n\n```bash\ndocker run -i --rm mcp-playwright:latest\n```\n\n| 参数 | 作用 |\n|-----|------|\n| `-i` | 保持 STDIN 打开以支持交互通信 |\n| `--rm` | 容器退出时自动删除 |\n| `-v` | 挂载卷以持久化数据 |\n\n 资料来源：[DOCKER.md:1-50]()\n\n#### 2.2 浏览器未找到\n\n**症状**：`Browser not found` 或浏览器下载失败\n\n**原因**：Docker 镜像默认跳过浏览器下载以减小体积\n\n**解决方案**：创建自定义 Dockerfile 预安装浏览器\n\n```dockerfile\nFROM mcp-playwright:latest\n\n# 安装 Playwright 浏览器\nRUN npx playwright install chromium --with-deps\n```\n\n或者设置环境变量跳过浏览器下载检查：\n\n```bash\ndocker run -i --rm \\\n -e PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 \\\n mcp-playwright:latest\n```\n\n 资料来源：[DOCKER.md:60-80]()\n\n#### 2.3 挂载卷权限问题\n\n**症状**：容器内无法读写挂载的目录\n\n**解决方案**：使用 `--user` 参数指定用户身份\n\n```bash\ndocker run -i --rm \\\n -v $(pwd)/data:/app/data \\\n --user $(id -u):$(id -g) \\\n mcp-playwright:latest\n```\n\n 资料来源：[DOCKER.md:85-95]()\n\n### 3. 浏览器相关问题\n\n#### 3.1 浏览器自动安装\n\n系统支持浏览器自动安装，首次使用时自动检测并下载缺失的浏览器二进制文件：\n\n```mermaid\ngraph TD\n A[启动服务器] --> B{检测浏览器}\n B -->|浏览器缺失| C[自动下载安装]\n B -->|浏览器存在| D[继续执行]\n C --> E[显示安装进度]\n E --> D\n```\n\n**手动安装命令**：\n\n```bash\n# 安装所有浏览器\nnpx playwright install\n\n# 安装特定浏览器\nnpx playwright install chromium\nnpx playwright install firefox\nnpx playwright install webkit\n```\n\n**浏览器存储位置**：\n\n| 操作系统 | 存储路径 |\n|---------|---------|\n| Windows | `%USERPROFILE%\\AppData\\Local\\ms-playwright` |\n| macOS | `~/Library/Caches/ms-playwright` |\n| Linux | `~/.cache/ms-playwright` |\n\n 资料来源：[README.md:100-130]()\n\n#### 3.2 浏览器连接断开\n\n**症状**：`Target page, context or browser has been closed`\n\n**错误分类**：`resource` 类型错误\n\n**解决方案**：\n\n1. 检查浏览器实例是否正常启动\n2. 避免在页面加载完成前执行操作\n3. 使用适当的等待策略\n\n```typescript\n// 浏览器上下文捕获示例\nprivate captureBrowserContext(error: Error): Record {\n const context: Record = {};\n const message = error.message.toLowerCase();\n\n if (message.includes('closed') || message.includes('disconnected')) {\n context.browserState = 'disconnected';\n } else if (message.includes('timeout')) {\n context.browserState = 'timeout';\n } else if (message.includes('navigation')) {\n context.browserState = 'navigation_error';\n }\n\n return context;\n}\n```\n\n 资料来源：[src/logging/middleware.ts:150-200]()\n\n### 4. 工具执行问题\n\n#### 4.1 日志输出配置\n\n在 stdio 模式下，日志自动写入文件而非控制台，以保持 JSON-RPC 通信的清洁性。\n\n**日志文件位置**：`~/playwright-mcp-server.log`\n\n```mermaid\ngraph LR\n A[stdio 模式] --> B[日志写入文件]\n C[HTTP 模式] --> D[日志输出控制台]\n B --> E[~/playwright-mcp-server.log]\n```\n\n 资料来源：[README.md:50-60]()\n\n#### 4.2 工具执行流程监控\n\n系统提供完整的工具执行日志记录：\n\n```mermaid\nsequenceDiagram\n participant C as 客户端\n participant M as 日志中间件\n participant H as 处理器\n participant L as 日志记录器\n\n C->>M: 工具调用请求\n M->>L: 记录开始状态\n M->>H: 执行处理器\n H-->>M: 返回结果\n M->>L: 记录完成状态\n M-->>C: 返回响应\n```\n\n**请求日志上下文**：\n\n```typescript\ninterface RequestLogContext {\n method: 'TOOL_CALL' | 'HTTP_REQUEST';\n url: string;\n body?: any;\n statusCode?: number;\n duration?: number;\n}\n```\n\n 资料来源：[src/logging/middleware.ts:10-40]()\n\n#### 4.3 工具名称长度限制\n\n**重要提示**：部分客户端（如 Cursor）对工具名称有 60 字符限制。\n\n服务器名称：`playwright-mcp`\n\n确保工具名称足够简短，避免组合后超过限制。\n\n 资料来源：[README.md:140-150]()\n\n### 5. 截图功能问题\n\n#### 5.1 截图存储机制\n\n截图工具支持内存存储和文件存储两种模式：\n\n```mermaid\ngraph TD\n A[截图请求] --> B{storeBase64 参数}\n B -->|true| C[存入内存 Map]\n B -->|false| D[仅保存文件]\n C --> E[触发资源变更通知]\n D --> F[返回文件路径]\n E --> G[通知 MCP 客户端]\n```\n\n**存储配置**：\n\n```typescript\n// 截图参数配置\ninterface ScreenshotArgs {\n name?: string; // 截图标识名称\n downloadsDir?: string; // 下载目录路径\n storeBase64?: boolean; // 是否存入内存，默认为 true\n}\n```\n\n 资料来源：[src/tools/browser/screenshot.ts:20-50]()\n\n#### 5.2 获取已存储截图\n\n```typescript\n// 获取所有已存储的截图\ngetScreenshots(): Map {\n return this.screenshots;\n}\n```\n\n返回内存中所有 Base64 编码的截图数据。\n\n 资料来源：[src/tools/browser/screenshot.ts:80-90]()\n\n### 6. 连接问题诊断\n\n#### 6.1 连接问题排查清单\n\n| 检查项 | 验证方法 | 解决方案 |\n|-------|---------|---------|\n| 端口可用性 | `netstat -an \\| grep 8931` | 更换端口或终止占用进程 |\n| 本地访问 | `curl http://localhost:8931/health` | 检查服务器状态 |\n| 防火墙 | 检查入站规则 | 开放相应端口 |\n| 外部访问 | 远程主机测试 | 使用 SSH 隧道 |\n\n 资料来源：[README.md:80-100]()\n\n#### 6.2 健康检查端点\n\n```bash\n# HTTP 模式健康检查\ncurl http://localhost:8931/health\n```\n\n**响应示例**：\n\n```json\n{\n \"status\": \"ok\",\n \"version\": \"1.x.x\",\n \"activeSessions\": 0\n}\n```\n\n 资料来源：[src/http-server.ts:30-45]()\n\n### 7. 日志系统调试\n\n#### 7.1 日志级别\n\n```typescript\n// 日志方法\ninfo(message: string, context?: Record): void\nwarn(message: string, context?: Record): void\nerror(message: string, error?: Error, context?: Record): void\nlogRequest(message: string, requestContext: RequestLogContext): void\nlogError(message: string, error: Error, errorContext?: ErrorLogContext): void\n```\n\n#### 7.2 错误上下文捕获\n\n系统自动捕获丰富的错误上下文信息：\n\n```typescript\ncaptureErrorContext(error: Error, toolName?: string, args?: any): Record {\n return {\n errorName: error.name,\n errorMessage: error.message,\n stack: error.stack,\n timestamp: new Date().toISOString(),\n nodeVersion: process.version,\n platform: process.platform,\n arch: process.arch,\n memoryUsage: process.memoryUsage(),\n uptime: process.uptime(),\n toolName,\n toolCategory: toolName?.split('_')[0]\n };\n}\n```\n\n 资料来源：[src/logging/middleware.ts:180-220]()\n\n### 8. 性能与资源限制\n\n#### 8.1 Docker 资源限制\n\n```yaml\nservices:\n playwright-mcp:\n deploy:\n resources:\n limits:\n cpus: '2.0'\n memory: 2G\n```\n\n#### 8.2 健康检查配置\n\n```yaml\nservices:\n playwright-mcp:\n healthcheck:\n test: [\"CMD\", \"node\", \"-e\", \"process.exit(0)\"]\n interval: 30s\n timeout: 10s\n retries: 3\n```\n\n 资料来源：[DOCKER.md:100-130]()\n\n## 获取帮助\n\n如果问题仍未解决：\n\n1. 查看完整的 [README.md](README.md) 获取一般信息\n2. 在 [GitHub Issues](https://github.com/executeautomation/mcp-playwright/issues) 报告问题\n3. 为 Docker 相关问题添加 `docker` 标签\n4. 使用 `docker scan` 检查镜像安全漏洞\n\n## 依赖版本参考\n\n| 依赖包 | 版本 | 用途 |\n|-------|------|------|\n| @modelcontextprotocol/sdk | 1.24.3 | MCP 协议实现 |\n| playwright | 1.57.0 | 浏览器自动化核心 |\n| @playwright/browser-chromium | 1.57.0 | Chromium 浏览器 |\n| @playwright/browser-firefox | 1.57.0 | Firefox 浏览器 |\n| @playwright/browser-webkit | 1.57.0 | WebKit 浏览器 |\n\n 资料来源：[package.json:1-30]()\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：executeautomation/mcp-playwright\n\n摘要：发现 16 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Playwright is asking for an specific browser version.。\n\n## 1. 安装坑 · 来源证据：Playwright is asking for an specific browser version.\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Playwright is asking for an specific browser version.\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_38465ac94a9d4fb0bd352ba5209096ac | https://github.com/executeautomation/mcp-playwright/issues/117 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 2. 安全/权限坑 · 来源证据：How to configure proxy and storageState when launching browser in Playwright MCP?\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：How to configure proxy and storageState when launching browser in Playwright MCP?\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a2f7e4a410994d4195a9af9f139e0caa | https://github.com/executeautomation/mcp-playwright/issues/203 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | host_targets=mcp_host, claude, cursor\n\n## 4. 配置坑 · 来源证据：Add Clarvia AEO score badge to README (AEO 32/100)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Add Clarvia AEO score badge to README (AEO 32/100)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_74959d07d5f74165bcd9cae829d384ce | https://github.com/executeautomation/mcp-playwright/issues/212 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 配置坑 · 来源证据：Add policy enforcement for browser automation and HTTP request tools\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Add policy enforcement for browser automation and HTTP request tools\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_23a30d245f794b8db40c1d031b8be565 | https://github.com/executeautomation/mcp-playwright/issues/216 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | README/documentation is current enough for a first validation pass.\n\n## 7. 运行坑 · 来源证据：How to pass in the `--ignore-https-errors` parameter?\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：How to pass in the `--ignore-https-errors` parameter?\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_47d5e333819d49b4b8ce2abb9484b23d | https://github.com/executeautomation/mcp-playwright/issues/202 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 8. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | last_activity_observed missing\n\n## 9. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 11. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 来源证据：Feature Request: Add browser context persistence for login state (userDataDir/storageState)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature Request: Add browser context persistence for login state (userDataDir/storageState)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3632e6a11e044dda870b3267ccfa3040 | https://github.com/executeautomation/mcp-playwright/issues/201 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 13. 安全/权限坑 · 来源证据：Free MCP security scan report for @executeautomation/playwright-mcp-server\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Free MCP security scan report for @executeautomation/playwright-mcp-server\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9720dc9967444ed08710cdb0660a212a | https://github.com/executeautomation/mcp-playwright/issues/211 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 14. 安全/权限坑 · 来源证据：Security Advisory: SSRF, Prompt Injection, and Arbitrary JavaScript Execution via Browser Automation Tools\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security Advisory: SSRF, Prompt Injection, and Arbitrary JavaScript Execution via Browser Automation Tools\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ced642164084421f84bbb63681653057 | https://github.com/executeautomation/mcp-playwright/issues/209 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 15. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | issue_or_pr_quality=unknown\n\n## 16. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | release_recency=unknown\n\n\n",
"markdown_key": "mcp-playwright",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:898077246",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/executeautomation/mcp-playwright"
},
{
"evidence_id": "art_904b3d0637f0432db08e131df9c7b98d",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/executeautomation/mcp-playwright#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "mcp-playwright 说明书",
"toc": [
"https://github.com/executeautomation/mcp-playwright 项目说明书",
"目录",
"快速入门指南",
"项目概述",
"环境要求",
"安装方式",
"配置 AI 客户端",
"运行模式",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "2349c2891e7c499c8c07b7d78c7f3fb4c797a1da",
"repo_inspection_error": null,
"repo_inspection_files": [
"Dockerfile",
"package.json",
"README.md",
"docker-compose.yml",
"docs/package-lock.json",
"docs/package.json",
"docs/tsconfig.json",
"docs/sidebars.ts",
"docs/docusaurus.config.ts",
"docs/docs/intro.mdx",
"docs/docs/release.mdx",
"docs/src/pages/markdown-page.md",
"docs/docs/ai-courses/MachineLearning.mdx",
"docs/docs/ai-courses/_category_.json",
"docs/docs/ai-courses/GenAICourse.mdx",
"docs/docs/ai-courses/AIAgents.mdx",
"docs/docs/testing-videos/_category_.json",
"docs/docs/testing-videos/Bdd.mdx",
"docs/docs/testing-videos/AIAgents.mdx",
"docs/docs/local-setup/_category_.json",
"docs/docs/local-setup/Installation.mdx",
"docs/docs/local-setup/Debugging.mdx",
"docs/docs/playwright-web/Supported-Tools.mdx",
"docs/docs/playwright-web/_category_.json",
"docs/docs/playwright-web/Device-Quick-Reference.md",
"docs/docs/playwright-web/Examples.md",
"docs/docs/playwright-web/Recording-Actions.mdx",
"docs/docs/playwright-web/Support-of-Cline-Cursor.mdx",
"docs/docs/playwright-web/Resize-Prompts-Guide.md",
"docs/docs/playwright-web/Console-Logging.mdx",
"docs/docs/playwright-web/HTTP-SSE-Transport.mdx",
"docs/docs/playwright-api/Supported-Tools.mdx",
"docs/docs/playwright-api/_category_.json",
"docs/docs/playwright-api/Examples.md",
"examples/http-mode-example.md",
"src/requestHandler.ts",
"src/tools.ts",
"src/toolHandler.ts",
"src/index.ts",
"src/types.ts"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# @executeautomation/playwright-mcp-server - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 @executeautomation/playwright-mcp-server 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `npm install -g @executeautomation/playwright-mcp-server` 证据：`README.md` Claim：`clm_0003` supported 0.86\n- `npx @michaellatman/mcp-get@latest install @executeautomation/playwright-mcp-server` 证据：`README.md` Claim：`clm_0004` supported 0.86\n- `npx @smithery/cli install @executeautomation/playwright-mcp-server --client claude` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `claude mcp add --transport stdio playwright npx @executeautomation/playwright-mcp-server` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `npx playwright install` 证据：`README.md` Claim：`clm_0007` supported 0.86, `clm_0008` supported 0.86, `clm_0009` supported 0.86, `clm_0010` supported 0.86\n- `npx playwright install chromium` 证据：`README.md` Claim：`clm_0008` supported 0.86\n- `npx playwright install firefox` 证据：`README.md` Claim：`clm_0009` supported 0.86\n- `npx playwright install webkit` 证据：`README.md` Claim：`clm_0010` supported 0.86\n- `npx @executeautomation/playwright-mcp-server --port 8931` 证据：`README.md` Claim：`clm_0011` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、本地环境或项目文件、环境变量 / API Key\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0012` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0013` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：122\n- 重要文件覆盖：40/122\n- 证据索引条目：40\n- 角色 / Skill 条目：9\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 @executeautomation/playwright-mcp-server 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 @executeautomation/playwright-mcp-server 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 @executeautomation/playwright-mcp-server 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 9 个角色 / Skill / 项目文档条目。\n\n- **Playwright MCP Server 🎭**（project_doc）：! Trust Score https://archestra.ai/mcp-catalog/api/badge/quality/executeautomation/mcp-playwright https://archestra.ai/mcp-catalog/executeautomation mcp-playwright ! smithery badge https://smithery.ai/badge/@executeautomation/playwright-mcp-server https://smithery.ai/server/@executeautomation/playwright-mcp-server 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **⚙️Examples of API automation**（project_doc）：Lets see how we can use the power of Playwright MCP Server to automate API of our application 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/playwright-api/Examples.md`\n- **Device Testing Quick Reference**（project_doc）：What You Want Natural Language Prompt --------------- ------------------------ 📱 iPhone \"Test on iPhone 13\" 📱 iPhone Landscape \"Switch to iPhone 13 landscape\" 📱 Android \"Test on Pixel 7\" 📱 Samsung \"Switch to Galaxy S24\" 📱 Tablet \"Test on iPad Pro 11\" 💻 Desktop \"Show desktop view\" or \"Desktop Chrome\" 🔄 Rotate \"Rotate to landscape\" 📏 Custom \"Resize to 1024x768\" 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/playwright-web/Device-Quick-Reference.md`\n- **🌐 Examples of browser automation**（project_doc）：🌐 Examples of browser automation Lets see how we can use the power of Playwright MCP Server to automate our browser and do webscrapping 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/playwright-web/Examples.md`\n- **Prompt Guide: Using playwright resize**（project_doc）：Prompt Guide: Using playwright resize 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/playwright-web/Resize-Prompts-Guide.md`\n- **Markdown page example**（project_doc）：You don't need React to write simple standalone pages. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/src/pages/markdown-page.md`\n- **Changelog**（project_doc）：All notable changes to the Playwright MCP Server will be documented in this file. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CHANGELOG.md`\n- **Docker Support for Playwright MCP Server**（project_doc）：Docker Support for Playwright MCP Server 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`DOCKER.md`\n- **HTTP Mode Example**（project_doc）：This example demonstrates how to use the Playwright MCP Server in HTTP mode. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/http-mode-example.md`\n\n## 证据索引\n\n- 共索引 40 条证据。\n\n- **Playwright MCP Server 🎭**（documentation）：! Trust Score https://archestra.ai/mcp-catalog/api/badge/quality/executeautomation/mcp-playwright https://archestra.ai/mcp-catalog/executeautomation mcp-playwright ! smithery badge https://smithery.ai/badge/@executeautomation/playwright-mcp-server https://smithery.ai/server/@executeautomation/playwright-mcp-server 证据：`README.md`\n- **Package**（package_manifest）：{ \"name\": \"playwright-mcp-server\", \"version\": \"0.0.0\", \"private\": true, \"scripts\": { \"docusaurus\": \"docusaurus\", \"start\": \"docusaurus start\", \"build\": \"docusaurus build\", \"swizzle\": \"docusaurus swizzle\", \"deploy\": \"docusaurus deploy\", \"clear\": \"docusaurus clear\", \"serve\": \"docusaurus serve\", \"write-translations\": \"docusaurus write-translations\", \"write-heading-ids\": \"docusaurus write-heading-ids\", \"typecheck\": \"tsc\" }, \"dependencies\": { \"@docusaurus/core\": \"3.6.3\", \"@docusaurus/preset-classic\": \"3.6.3\", \"@mdx-js/react\": \"^3.0.0\", \"clsx\": \"^2.0.0\", \"gh-pages\": \"^6.2.0\", \"prism-react-renderer\": \"^2.3.0\", \"react\": \"^18.0.0\", \"react-dom\": \"^18.0.0\" }, \"devDependencies\": { \"@docusaurus/module-ty… 证据：`docs/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@executeautomation/playwright-mcp-server\", \"version\": \"1.0.12\", \"description\": \"Model Context Protocol servers for Playwright\", \"license\": \"MIT\", \"author\": \"ExecuteAutomation, Ltd https://executeautomation.com \", \"homepage\": \"https://executeautomation.github.io/mcp-playwright/\", \"bugs\": \"https://github.com/executeautomation/mcp-playwright/issues\", \"types\": \"dist/index.d.ts\", \"type\": \"module\", \"bin\": { \"playwright-mcp-server\": \"dist/index.js\" }, \"files\": \"dist\" , \"scripts\": { \"build\": \"tsc && shx chmod +x dist/ .js\", \"prepare\": \"npm run build\", \"watch\": \"tsc --watch\", \"test\": \"jest --testMatch=\\\" /src/ tests / / .test.ts\\\"\", \"test:coverage\": \"jest --coverage --testMatch=\\\" /src/ t… 证据：`package.json`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`LICENSE`\n- **⚙️Examples of API automation**（documentation）：Lets see how we can use the power of Playwright MCP Server to automate API of our application 证据：`docs/docs/playwright-api/Examples.md`\n- **Device Testing Quick Reference**（documentation）：What You Want Natural Language Prompt --------------- ------------------------ 📱 iPhone \"Test on iPhone 13\" 📱 iPhone Landscape \"Switch to iPhone 13 landscape\" 📱 Android \"Test on Pixel 7\" 📱 Samsung \"Switch to Galaxy S24\" 📱 Tablet \"Test on iPad Pro 11\" 💻 Desktop \"Show desktop view\" or \"Desktop Chrome\" 🔄 Rotate \"Rotate to landscape\" 📏 Custom \"Resize to 1024x768\" 证据：`docs/docs/playwright-web/Device-Quick-Reference.md`\n- **🌐 Examples of browser automation**（documentation）：🌐 Examples of browser automation Lets see how we can use the power of Playwright MCP Server to automate our browser and do webscrapping 证据：`docs/docs/playwright-web/Examples.md`\n- **Prompt Guide: Using playwright resize**（documentation）：Prompt Guide: Using playwright resize 证据：`docs/docs/playwright-web/Resize-Prompts-Guide.md`\n- **Markdown page example**（documentation）：You don't need React to write simple standalone pages. 证据：`docs/src/pages/markdown-page.md`\n- **Changelog**（documentation）：All notable changes to the Playwright MCP Server will be documented in this file. 证据：`CHANGELOG.md`\n- **Docker Support for Playwright MCP Server**（documentation）：Docker Support for Playwright MCP Server 证据：`DOCKER.md`\n- **HTTP Mode Example**（documentation）：This example demonstrates how to use the Playwright MCP Server in HTTP mode. 证据：`examples/http-mode-example.md`\n- **Tsconfig**（structured_config）：{ // This file is not used in compilation. It is here just for a nice editor experience. \"extends\": \"@docusaurus/tsconfig\", \"compilerOptions\": { \"baseUrl\": \".\" }, \"exclude\": \".docusaurus\", \"build\" } 证据：`docs/tsconfig.json`\n- **Mcp Config**（structured_config）：{ \"mcpServers\": { \"playwright\": { \"command\": \"npx\", \"args\": \"-y\", \"@executeautomation/playwright-mcp-server\" } } } 证据：`mcp-config.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2020\", \"module\": \"ES2022\", \"moduleResolution\": \"bundler\", \"outDir\": \"./dist\", \"strict\": true, \"esModuleInterop\": true, \"skipLibCheck\": true, \"declaration\": true, \"noImplicitAny\": false, \"strictNullChecks\": false, \"allowJs\": true, \"resolveJsonModule\": true }, \"include\": \"src/ / \" , \"exclude\": \"node modules\", \"dist\", \"src/ tests \" } 证据：`tsconfig.json`\n- **Tsconfig.Test**（structured_config）：{ \"extends\": \"./tsconfig.json\", \"compilerOptions\": { \"noImplicitAny\": false, \"strictNullChecks\": false, \"types\": \"jest\", \"node\" }, \"include\": \"src/ / \", \"test/ / \", \"src/ tests / / \" } 证据：`tsconfig.test.json`\n- **Category**（structured_config）：{ \"label\": \"AI Courses to Learn\", \"position\": 6, \"collapsed\": false, \"link\": { \"type\": \"generated-index\", \"description\": \"AI Courses which helps you learn more on Using it for Testing and Development\" } } 证据：`docs/docs/ai-courses/_category_.json`\n- **Category**（structured_config）：{ \"label\": \"Local Development\", \"position\": 3, \"collapsed\": false, \"link\": { \"type\": \"generated-index\", \"description\": \"Understand how to setup Playwright MCP Server to run in your local machine.\" } } 证据：`docs/docs/local-setup/_category_.json`\n- **Category**（structured_config）：{ \"label\": \"Playwright API Features\", \"position\": 5, \"collapsed\": false, \"link\": { \"type\": \"generated-index\", \"description\": \"Supported features in Playwright API Testing.\" } } 证据：`docs/docs/playwright-api/_category_.json`\n- **Category**（structured_config）：{ \"label\": \"Playwright Web Features\", \"position\": 4, \"collapsed\": false, \"link\": { \"type\": \"generated-index\", \"description\": \"Supported features in Playwright Web browser automation.\" } } 证据：`docs/docs/playwright-web/_category_.json`\n- **Node modules - commented out to allow copying from host**（source_file）：Node modules - commented out to allow copying from host node modules npm-debug.log 证据：`.dockerignore`\n- **.gitattributes**（source_file）：package-lock.json linguist-generated=true 证据：`.gitattributes`\n- **Logs**（source_file）：Logs logs .log npm-debug.log yarn-debug.log yarn-error.log lerna-debug.log .pnpm-debug.log 证据：`.gitignore`\n- **Multi-stage Dockerfile for MCP Playwright Server**（source_file）：Multi-stage Dockerfile for MCP Playwright Server This Dockerfile expects the project to be built before running docker build Run npm install --omit=dev && npm run build before building the image 证据：`Dockerfile`\n- **!/bin/bash**（source_file）：!/bin/bash Build script for Docker image This ensures the project and dependencies are properly prepared 证据：`docker-build.sh`\n- **MCP servers communicate via stdio**（source_file）：services: playwright-mcp: build: context: . dockerfile: Dockerfile image: mcp-playwright:latest container name: playwright-mcp-server stdin open: true tty: true MCP servers communicate via stdio You can interact with this container using: docker compose run --rm playwright-mcp environment: Skip browser download in container - PLAYWRIGHT SKIP BROWSER DOWNLOAD=1 Optionally mount a volume for persistent data volumes: - ./data:/app/data 证据：`docker-compose.yml`\n- **Docusaurus.Config**（source_file）：import {themes as prismThemes} from 'prism-react-renderer'; import type {Config} from '@docusaurus/types'; import type as Preset from '@docusaurus/preset-classic'; 证据：`docs/docusaurus.config.ts`\n- **Sidebars**（source_file）：import type {SidebarsConfig} from '@docusaurus/plugin-content-docs'; 证据：`docs/sidebars.ts`\n- **Jest.Config**（source_file）：module.exports = { preset: 'ts-jest', testEnvironment: 'node', collectCoverage: true, coverageDirectory: 'coverage', coverageReporters: 'text', 'lcov' , collectCoverageFrom: 'src/ / .ts', '!src/index.ts', // exclude index.ts , testMatch: ' /src/ tests / / .test.ts' , modulePathIgnorePatterns: \" /docs/\", \" /dist/\" , moduleNameMapper: { \"^ . \\\\.js$\": \"$1\" }, transform: { '^.+\\\\.tsx?$': 'ts-jest', { useESM: true, tsconfig: 'tsconfig.test.json' } , }, extensionsToTreatAsEsm: '.ts' , moduleFileExtensions: 'ts', 'tsx', 'js', 'jsx', 'json', 'node' , }; 证据：`jest.config.cjs`\n- **Run Tests**（source_file）：const { execSync } = require 'child process' ; 证据：`run-tests.cjs`\n- **Run Tests**（source_file）：const { execSync } = require 'child process' ; 证据：`run-tests.js`\n- **!/usr/bin/env node**（source_file）：/ Script to list all available Playwright device descriptors Usage: node scripts/list-devices.js filter / 证据：`scripts/list-devices.cjs`\n- **Smithery configuration file: https://smithery.ai/docs/config smitheryyaml**（source_file）：Smithery configuration file: https://smithery.ai/docs/config smitheryyaml 证据：`smithery.yaml`\n- **!/usr/bin/env node**（source_file）：import express from 'express'; import { randomUUID } from 'node:crypto'; import { Server } from \"@modelcontextprotocol/sdk/server/index.js\"; import { SSEServerTransport } from \"@modelcontextprotocol/sdk/server/sse.js\"; import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js'; import { createToolDefinitions } from \"./tools.js\"; import { setupRequestHandlers } from \"./requestHandler.js\"; import { Logger, RequestLoggingMiddleware } from \"./logging/index.js\"; import { MonitoringSystem } from \"./monitoring/index.js\"; 证据：`src/http-server.ts`\n- **!/usr/bin/env node**（source_file）：import { Server } from \"@modelcontextprotocol/sdk/server/index.js\"; import { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\"; import { createToolDefinitions } from \"./tools.js\"; import { setupRequestHandlers } from \"./requestHandler.js\"; import { Logger, RequestLoggingMiddleware } from \"./logging/index.js\"; import { MonitoringSystem } from \"./monitoring/index.js\"; import { startHttpServer } from \"./http-server.js\"; 证据：`src/index.ts`\n- **Requesthandler**（source_file）：import { Server } from \"@modelcontextprotocol/sdk/server/index.js\"; import { ListResourcesRequestSchema, ReadResourceRequestSchema, ListToolsRequestSchema, CallToolRequestSchema, Tool, McpError } from \"@modelcontextprotocol/sdk/types.js\"; import { handleToolCall, getConsoleLogs, getScreenshots } from \"./toolHandler.js\"; import { Logger, RequestLoggingMiddleware } from \"./logging/index.js\"; import { MonitoringSystem } from \"./monitoring/index.js\"; 证据：`src/requestHandler.ts`\n- **Toolhandler**（source_file）：import type { Browser, Page } from 'playwright'; import { chromium, firefox, webkit, request } from 'playwright'; import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js'; import { BROWSER TOOLS, API TOOLS } from './tools.js'; import type { ToolContext } from './tools/common/types.js'; import { ActionRecorder } from './tools/codegen/recorder.js'; import { spawn } from 'child process'; import { startCodegenSession, endCodegenSession, getCodegenSession, clearCodegenSession } from './tools/codegen/index.js'; import { ScreenshotTool, NavigationTool, CloseBrowserTool, ConsoleLogsTool, ExpectResponseTool, AssertResponseTool, CustomUserAgentTool, ResizeTool } from './tools/browser/… 证据：`src/toolHandler.ts`\n- **Tools**（source_file）：import type { Tool } from \"@modelcontextprotocol/sdk/types.js\"; import { codegenTools } from './tools/codegen'; 证据：`src/tools.ts`\n- **Types**（source_file）：import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js'; 证据：`src/types.ts`\n- **Test Import**（source_file）：// test-import.js import { setupRequestHandlers } from './dist/requestHandler.js'; import { handleToolCall } from './dist/toolHandler.js'; 证据：`test-import.js`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `docs/package.json`, `package.json`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `docs/package.json`, `package.json`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **快速入门指南**：importance `high`\n - source_paths: README.md, package.json, mcp-config.json\n- **系统架构**：importance `high`\n - source_paths: src/index.ts, src/http-server.ts, src/requestHandler.ts, src/toolHandler.ts, src/sse/server.ts\n- **工具参考手册**：importance `high`\n - source_paths: src/tools.ts, src/tools/index.ts, src/tools/browser/index.ts, src/tools/api/index.ts, src/tools/codegen/index.ts\n- **设备模拟功能**：importance `medium`\n - source_paths: src/tools/browser/resize.ts, src/tools/browser/useragent.ts, scripts/list-devices.cjs, docs/docs/playwright-web/Device-Quick-Reference.md\n- **测试代码生成**：importance `medium`\n - source_paths: src/tools/codegen/recorder.ts, src/tools/codegen/generator.ts, src/tools/codegen/types.ts, src/tools/codegen/index.ts\n- **HTTP/SSE 传输模式**：importance `high`\n - source_paths: src/http-server.ts, src/sse/server.ts, src/sse/types.ts, src/sse/index.ts, docs/docs/playwright-web/HTTP-SSE-Transport.mdx\n- **Docker 容器化部署**：importance `medium`\n - source_paths: Dockerfile, docker-compose.yml, docker-build.sh, DOCKER.md\n- **客户端配置指南**：importance `high`\n - source_paths: mcp-config.json, smithery.yaml, docs/docs/playwright-web/Support-of-Cline-Cursor.mdx\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `2349c2891e7c499c8c07b7d78c7f3fb4c797a1da`\n- inspected_files: `Dockerfile`, `package.json`, `README.md`, `docker-compose.yml`, `docs/package-lock.json`, `docs/package.json`, `docs/tsconfig.json`, `docs/sidebars.ts`, `docs/docusaurus.config.ts`, `docs/docs/intro.mdx`, `docs/docs/release.mdx`, `docs/src/pages/markdown-page.md`, `docs/docs/ai-courses/MachineLearning.mdx`, `docs/docs/ai-courses/_category_.json`, `docs/docs/ai-courses/GenAICourse.mdx`, `docs/docs/ai-courses/AIAgents.mdx`, `docs/docs/testing-videos/_category_.json`, `docs/docs/testing-videos/Bdd.mdx`, `docs/docs/testing-videos/AIAgents.mdx`, `docs/docs/local-setup/_category_.json`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：Playwright is asking for an specific browser version.\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Playwright is asking for an specific browser version.\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_38465ac94a9d4fb0bd352ba5209096ac | https://github.com/executeautomation/mcp-playwright/issues/117 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：How to configure proxy and storageState when launching browser in Playwright MCP?\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：How to configure proxy and storageState when launching browser in Playwright MCP?\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_a2f7e4a410994d4195a9af9f139e0caa | https://github.com/executeautomation/mcp-playwright/issues/203 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 可能修改宿主 AI 配置\n\n- Trigger: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- Host AI rule: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Why it matters: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Evidence: capability.host_targets | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | host_targets=mcp_host, claude, cursor\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：Add Clarvia AEO score badge to README (AEO 32/100)\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Add Clarvia AEO score badge to README (AEO 32/100)\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_74959d07d5f74165bcd9cae829d384ce | https://github.com/executeautomation/mcp-playwright/issues/212 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：Add policy enforcement for browser automation and HTTP request tools\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Add policy enforcement for browser automation and HTTP request tools\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_23a30d245f794b8db40c1d031b8be565 | https://github.com/executeautomation/mcp-playwright/issues/216 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：How to pass in the `--ignore-https-errors` parameter?\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：How to pass in the `--ignore-https-errors` parameter?\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_47d5e333819d49b4b8ce2abb9484b23d | https://github.com/executeautomation/mcp-playwright/issues/202 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 存在安全注意事项\n\n- Trigger: No sandbox install has been executed yet; downstream must verify before user use.\n- Host AI rule: 转成明确权限清单和安全审查提示。\n- Why it matters: 用户安装前需要知道权限边界和敏感操作。\n- Evidence: risks.safety_notes | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | No sandbox install has been executed yet; downstream must verify before user use.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：executeautomation/mcp-playwright\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host, claude, cursor\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：Playwright is asking for an specific browser version.（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：How to configure proxy and storageState when launching browser in Playwright MCP?（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 可能修改宿主 AI 配置（medium）：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 来源证据：Add Clarvia AEO score badge to README (AEO 32/100)（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Add policy enforcement for browser automation and HTTP request tools（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/executeautomation/mcp-playwright 项目说明书\n\n生成时间：2026-05-13 07:26:04 UTC\n\n## 目录\n\n- [快速入门指南](#getting-started)\n- [系统架构](#architecture)\n- [工具参考手册](#tool-reference)\n- [设备模拟功能](#device-emulation)\n- [测试代码生成](#code-generation)\n- [HTTP/SSE 传输模式](#http-transport)\n- [Docker 容器化部署](#docker-deployment)\n- [客户端配置指南](#client-configuration)\n- [日志与监控](#logging-monitoring)\n- [故障排除指南](#troubleshooting)\n\n\n\n## 快速入门指南\n\n### 相关页面\n\n相关主题：[系统架构](#architecture), [工具参考手册](#tool-reference), [客户端配置指南](#client-configuration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/executeautomation/mcp-playwright/blob/main/README.md)\n- [package.json](https://github.com/executeautomation/mcp-playwright/blob/main/package.json)\n- [DOCKER.md](https://github.com/executeautomation/mcp-playwright/blob/main/DOCKER.md)\n- [examples/http-mode-example.md](https://github.com/executeautomation/mcp-playwright/blob/main/examples/http-mode-example.md)\n- [CLAUDE_DESKTOP_CONFIG.md](https://github.com/executeautomation/mcp-playwright/blob/main/CLAUDE_DESKTOP_CONFIG.md)\n \n\n# 快速入门指南\n\n本指南将帮助您快速上手 **mcp-playwright** 项目，这是一个基于 Model Context Protocol (MCP) 的 Playwright 自动化服务器。通过本指南，您将了解如何安装、配置并开始使用该服务器进行浏览器自动化操作。\n\n## 项目概述\n\nmcp-playwright 是一个开源的 MCP 服务器实现，它将 Playwright 浏览器自动化能力通过 MCP 协议暴露给 AI 助手和开发工具。该项目由 ExecuteAutomation 维护，支持多浏览器引擎（Chromium、Firefox、WebKit），并提供 stdio 和 HTTP 两种通信模式。\n\n**核心特性：**\n\n| 特性 | 说明 |\n|------|------|\n| 协议支持 | Model Context Protocol (MCP) |\n| 浏览器支持 | Chromium、Firefox、WebKit |\n| 通信模式 | stdio（标准输入输出）、HTTP Server |\n| 安装方式 | npm、mcp-get、Smithery、Docker |\n| 日志管理 | 自动写入文件（stdio 模式） |\n\n## 环境要求\n\n在开始之前，请确保您的系统满足以下要求：\n\n- **Node.js**: 20.x 或更高版本\n- **操作系统**: Windows、macOS、Linux\n- **网络**: 能够访问 npm registry 下载依赖包\n\n您可以通过以下命令检查 Node.js 版本：\n\n```bash\nnode --version\n```\n\n## 安装方式\n\nmcp-playwright 提供多种安装方式，您可以根据使用场景选择最合适的一种。\n\n### 方式一：使用 npm 全局安装\n\n这是最直接的安装方式：\n\n```bash\nnpm install -g @executeautomation/playwright-mcp-server\n```\n\n安装完成后，可执行文件 `playwright-mcp-server` 将全局可用。资料来源：[README.md:54]()\n\n### 方式二：使用 npx 免安装运行\n\n如果您不想全局安装，可以使用 npx 直接运行：\n\n```bash\nnpx -y @executeautomation/playwright-mcp-server\n```\n\n这种方式每次都会下载最新版本，适合临时使用或测试场景。资料来源：[README.md:42]()\n\n### 方式三：使用 mcp-get 安装\n\nmcp-get 是专门为 MCP 服务器设计的包管理工具：\n\n```bash\nnpx @michaellatman/mcp-get@latest install @executeautomation/playwright-mcp-server\n```\n\n### 方式四：使用 Smithery 自动安装\n\nSmithery 提供了针对 Claude Desktop 的自动化安装：\n\n```bash\nnpx @smithery/cli install @executeautomation/playwright-mcp-server --client claude\n```\n\n### 方式五：Docker 部署\n\n对于容器化环境，可以使用 Docker 运行：\n\n```bash\ndocker run -i --rm mcp-playwright:latest\n```\n\nDocker 部署的详细配置请参考 [DOCKER.md](DOCKER.md)。资料来源：[DOCKER.md:1]()\n\n## 配置 AI 客户端\n\n安装完成后，您需要在 AI 客户端中配置 MCP 服务器连接。以下是常见客户端的配置方法。\n\n### Claude Desktop 配置\n\n**配置文件位置：**\n\n| 操作系统 | 配置文件路径 |\n|----------|--------------|\n| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Windows | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| Linux | `~/.config/Claude/claude_desktop_config.json` |\n\n**stdio 模式配置（推荐）：**\n\n```json\n{\n \"mcpServers\": {\n \"playwright\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@executeautomation/playwright-mcp-server\"]\n }\n }\n}\n```\n\n**HTTP 模式配置：**\n\n如果您使用 HTTP 模式运行服务器，可以配置如下：\n\n```json\n{\n \"mcpServers\": {\n \"playwright\": {\n \"url\": \"http://localhost:8931/mcp\"\n }\n }\n}\n```\n\n> **注意**：Claude Desktop 目前需要 stdio 模式。如果您需要 HTTP 模式，建议使用 VS Code 或其他自定义客户端。资料来源：[README.md:25-35]()\n\n### Claude Code 配置\n\n使用 Claude Code 时，可以通过命令行添加 MCP 服务器：\n\n```bash\nclaude mcp add --transport stdio playwright npx @executeautomation/playwright-mcp-server\n```\n\n### VS Code MCP 扩展配置\n\n对于 VS Code 用户，可以使用以下配置：\n\n```json\n{\n \"name\": \"playwright\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@executeautomation/playwright-mcp-server\"]\n}\n```\n\n## 运行模式\n\nmcp-playwright 支持两种运行模式，您可以根据需求选择。\n\n### stdio 模式（标准输入输出）\n\nstdio 模式是 Claude Desktop 的推荐模式。在此模式下，MCP 服务器通过标准输入和标准输出与客户端通信。\n\n**启动方式：**\n\n```bash\nnpx -y @executeautomation/playwright-mcp-server\n```\n\n**配置说明：**\n\n| 参数 | 说明 |\n|------|------|\n| `-i` | 保持 STDIN 打开以接收输入 |\n| `--rm` | 容器退出时自动删除 |\n\n在 stdio 模式下，日志会自动写入文件而非控制台，以确保 JSON-RPC 通信的清洁性。日志文件位置为 `~/playwright-mcp-server.log`。资料来源：[README.md:30]()\n\n### HTTP 模式（独立服务器）\n\nHTTP 模式适合以下场景：\n\n- 在无显示环境的系统中运行有头浏览器\n- 从 IDE 工作进程调用\n- 需要远程部署\n- VS Code 用户\n\n**启动 HTTP 服务器：**\n\n```bash\n# 使用 npx\nnpx @executeautomation/playwright-mcp-server --port 8931\n\n# 或使用全局安装后\nplaywright-mcp-server --port 8931\n```\n\n服务器启动后将显示可用端点：\n\n```\n==============================================\nPlaywright MCP Server (HTTP Mode)\n==============================================\nPort: 8931\n\nENDPOINTS:\n- SSE Stream: GET http://localhost:8931/sse\n- Messages: POST http://localhost:8931/messages?sessionId=\n- MCP (unified): GET http://localhost:8931/mcp\n- MCP (unified): POST http://localhost:8931/mcp?sessionId=\n- Health Check: GET http://localhost:8931/health\n```\n\n资料来源：[README.md:38-52]()\n\n**健康检查：**\n\n```bash\ncurl http://localhost:8931/health\n```\n\n## 浏览器安装\n\n### 自动安装（推荐）\n\nmcp-playwright **会在首次使用时自动安装浏览器**。当服务器检测到缺少浏览器时，会自动：\n\n1. 下载并安装所需浏览器（Chromium、Firefox 或 WebKit）\n2. 在控制台显示安装进度\n3. 安装完成后自动重试您的请求\n\n无需手动操作！\n\n### 手动安装\n\n如果您偏好手动安装或遇到自动安装问题：\n\n```bash\n# 安装所有浏览器\nnpx playwright install\n\n# 或安装特定浏览器\nnpx playwright install chromium\nnpx playwright install firefox\nnpx playwright install webkit\n```\n\n**浏览器存储位置：**\n\n| 操作系统 | 路径 |\n|----------|------|\n| Windows | `%USERPROFILE%\\AppData\\Local\\ms-playwright` |\n| macOS | `~/Library/Caches/ms-playwright` |\n| Linux | `~/.cache/ms-playwright` |\n\n资料来源：[README.md:57-72]()\n\n## 项目架构\n\n下面通过 Mermaid 图展示 mcp-playwright 的整体架构：\n\n```mermaid\ngraph TD\n A[AI 客户端
Claude Desktop/VS Code] -->|stdio 或 HTTP| B[MCP 协议层]\n B --> C[Playwright MCP Server]\n C --> D[Playwright 核心]\n D --> E[Chromium]\n D --> F[Firefox]\n D --> G[WebKit]\n \n H[日志系统] --> C\n \n style A fill:#e1f5fe\n style C fill:#fff3e0\n style D fill:#e8f5e9\n```\n\n### 组件说明\n\n| 组件 | 说明 | 源码位置 |\n|------|------|----------|\n| MCP 协议层 | 处理 JSON-RPC 通信协议 | `@modelcontextprotocol/sdk` |\n| 工具处理器 | 执行浏览器自动化操作 | `src/tools/` |\n| 日志中间件 | 请求日志和错误追踪 | `src/logging/middleware.ts` |\n| Playwright 核心 | 跨浏览器自动化引擎 | `playwright@1.57.0` |\n\n## 常用工作流程\n\n### 基本导航流程\n\n```mermaid\ngraph LR\n A[启动服务器] --> B[配置客户端]\n B --> C[打开浏览器]\n C --> D[导航到 URL]\n D --> E[执行交互]\n E --> F[获取结果]\n```\n\n### Docker 部署流程\n\n如果您选择 Docker 部署，典型的工作流程如下：\n\n```mermaid\ngraph TD\n A[编写 docker-compose.yml] --> B[配置环境变量]\n B --> C[配置卷挂载]\n C --> D[启动容器]\n D --> E[配置 AI 客户端连接]\n E --> F[开始使用]\n```\n\n**示例 docker-compose.yml：**\n\n```yaml\nservices:\n playwright-mcp:\n image: mcp-playwright:latest\n environment:\n - PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1\n - NODE_ENV=production\n volumes:\n - ./data:/app/data\n - ./screenshots:/app/screenshots\n```\n\n资料来源：[DOCKER.md:38-48]()\n\n## 环境变量\n\n您可以通过环境变量配置服务器行为：\n\n| 变量名 | 说明 | 默认值 |\n|--------|------|--------|\n| `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD` | 跳过浏览器自动下载 | `1`（Docker 中默认） |\n| `NODE_ENV` | 运行环境 | `production` |\n\n**Docker 中设置环境变量：**\n\n```bash\ndocker run -i --rm \\\n -e PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 \\\n mcp-playwright:latest\n```\n\n资料来源：[DOCKER.md:26-31]()\n\n## 故障排除\n\n### 容器立即退出\n\nMCP 服务器需要通过 stdin 接收输入，确保使用 `-i` 标志：\n\n```bash\ndocker run -i --rm mcp-playwright:latest\n```\n\n### 浏览器未找到\n\nDocker 镜像默认跳过浏览器下载以减小体积。如需预安装浏览器，创建自定义 Dockerfile：\n\n```dockerfile\nFROM mcp-playwright:latest\nRUN npx playwright install chromium --with-deps\n```\n\n### 权限问题\n\n如果遇到挂载卷权限问题：\n\n```bash\ndocker run -i --rm \\\n -v $(pwd)/data:/app/data \\\n --user $(id -u):$(id -g) \\\n mcp-playwright:latest\n```\n\n### 日志位置\n\nstdio 模式下，日志文件位置为：`~/playwright-mcp-server.log`\n\n## 下一步\n\n完成快速入门后，您可以：\n\n- 阅读完整的 [API 文档](https://executeautomation.github.io/mcp-playwright/docs/playwright-web/Supported-Tools)\n- 了解支持的 [设备配置](https://executeautomation.github.io/mcp-playwright/docs/playwright-web/Device-Quick-Reference)\n- 参考 [调整提示指南](https://executeautomation.github.io/mcp-playwright/docs/playwright-web/Resize-Prompts-Guide)\n- 查看 [GitHub Issues](https://github.com/executeautomation/mcp-playwright/issues) 获取帮助\n\n## 资源链接\n\n| 资源 | 链接 |\n|------|------|\n| 官方文档 | https://executeautomation.github.io/mcp-playwright/ |\n| API 参考 | https://executeautomation.github.io/mcp-playwright/docs/playwright-web/Supported-Tools |\n| GitHub 仓库 | https://github.com/executeautomation/mcp-playwright |\n| 问题反馈 | https://github.com/executeautomation/mcp-playwright/issues |\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[快速入门指南](#getting-started), [HTTP/SSE 传输模式](#http-transport), [日志与监控](#logging-monitoring)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/index.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/index.ts)\n- [src/http-server.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/http-server.ts)\n- [src/requestHandler.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/requestHandler.ts)\n- [src/toolHandler.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/toolHandler.ts)\n- [src/sse/server.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/sse/server.ts)\n- [src/logging/middleware.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/middleware.ts)\n- [src/logging/logger.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/logger.ts)\n- [src/tools.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools.ts)\n \n\n# 系统架构\n\n## 概述\n\nmcp-playwright 是一个基于 Model Context Protocol (MCP) 的 Playwright 自动化服务器，为 AI 助手提供浏览器自动化能力。该项目采用模块化架构设计，支持两种运行模式：stdio（标准输入输出）和 HTTP 模式。 资料来源：[package.json](https://github.com/executeautomation/mcp-playwright/blob/main/package.json)\n\n## 核心架构组件\n\n### 组件架构图\n\n```mermaid\ngraph TB\n subgraph \"传输层\"\n STDIO[STDIO 传输]\n HTTP[HTTP 服务器]\n SSE[SSE 流]\n end\n \n subgraph \"核心层\"\n MCP_SDK[MCP SDK
1.24.3]\n RequestHandler[请求处理器]\n ToolHandler[工具处理器]\n end\n \n subgraph \"工具层\"\n BrowserTools[浏览器工具]\n InteractionTools[交互工具]\n OutputTools[输出工具]\n ContentTools[内容提取工具]\n end\n \n subgraph \"浏览器层\"\n Chromium[@playwright/browser-chromium]\n Firefox[@playwright/browser-firefox]\n WebKit[@playwright/browser-webkit]\n end\n \n subgraph \"日志层\"\n Logger[日志记录器]\n Middleware[日志中间件]\n end\n \n STDIO --> MCP_SDK\n HTTP --> SSE\n HTTP --> RequestHandler\n MCP_SDK --> RequestHandler\n RequestHandler --> ToolHandler\n ToolHandler --> BrowserTools\n ToolHandler --> InteractionTools\n ToolHandler --> OutputTools\n ToolHandler --> ContentTools\n \n BrowserTools --> Chromium\n BrowserTools --> Firefox\n BrowserTools --> WebKit\n \n RequestHandler --> Middleware\n Middleware --> Logger\n```\n\n## 传输层架构\n\n### STDIO 模式\n\nSTDIO 模式是 MCP 协议的默认传输方式，适用于 Claude Desktop 等本地客户端。服务器通过标准输入输出进行 JSON-RPC 通信，日志自动写入 `~/playwright-mcp-server.log` 文件。 资料来源：[README.md](https://github.com/executeautomation/mcp-playwright/blob/main/README.md)\n\n```mermaid\ngraph LR\n Client[Claude Desktop
或其他 MCP 客户端] <--> STDIO\n STDIO --> Server[主服务器进程]\n Server --> Logger[文件日志
playwright-mcp-server.log]\n```\n\n### HTTP 模式\n\nHTTP 模式提供独立的 HTTP 服务器，支持远程访问和 VS Code 等 IDE 集成。服务器绑定到 `127.0.0.1`（仅本地），提供 SSE 流式传输和消息接口。 资料来源：[src/http-server.ts:1-50](https://github.com/executeautomation/mcp-playwright/blob/main/src/http-server.ts)\n\n```mermaid\ngraph LR\n subgraph \"HTTP 端点\"\n SSE[SSE Stream
GET /sse]\n Messages[Messages
POST /messages]\n MCP[MCP 统一接口
GET/POST /mcp]\n Health[Health Check
GET /health]\n end\n \n Client[外部客户端] --> HTTP_Server[HTTP 服务器
127.0.0.1:8931]\n HTTP_Server --> SSE\n HTTP_Server --> Messages\n HTTP_Server --> MCP\n HTTP_Server --> Health\n```\n\n### HTTP 端点配置\n\n| 端点 | 方法 | 路径 | 说明 |\n|------|------|------|------|\n| SSE Stream | GET | `/sse` | 服务器发送事件流 |\n| Messages | POST | `/messages?sessionId=` | 发送消息接口 |\n| MCP 统一 | GET/POST | `/mcp` | MCP 协议统一接口 |\n| Health Check | GET | `/health` | 健康检查端点 |\n\n## 请求处理流程\n\n### 请求生命周期\n\n```mermaid\nsequenceDiagram\n participant Client as MCP 客户端\n participant Middleware as 日志中间件\n participant RequestHandler as 请求处理器\n participant ToolHandler as 工具处理器\n participant Tools as 工具实现\n participant Logger as 日志记录器\n\n Client->>Middleware: JSON-RPC 请求\n Middleware->>Logger: 记录请求开始\n Middleware->>RequestHandler: 转发请求\n RequestHandler->>ToolHandler: 分发工具调用\n ToolHandler->>Tools: 执行具体工具\n Tools-->>ToolHandler: 返回结果\n ToolHandler-->>RequestHandler: 返回响应\n RequestHandler-->>Middleware: 返回结果\n Middleware->>Logger: 记录请求完成\n Middleware-->>Client: JSON-RPC 响应\n```\n\n### 请求处理器\n\n请求处理器（RequestHandler）负责接收 MCP 协议的 JSON-RPC 请求，进行参数验证和错误处理，然后分发到相应的工具处理器。 资料来源：[src/requestHandler.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/requestHandler.ts)\n\n核心职责包括：\n\n- 解析 MCP 协议消息格式\n- 验证请求参数\n- 路由工具调用到对应的处理器\n- 处理错误和异常情况\n\n## 工具系统架构\n\n### 工具分类\n\n所有工具定义统一在 `src/tools.ts` 中声明，分为以下几类： 资料来源：[src/tools.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools.ts)\n\n| 类别 | 工具名称 | 说明 |\n|------|----------|------|\n| **浏览器操作** | `playwright_navigate` | 页面导航 |\n| | `playwright_screenshot` | 页面截图 |\n| | `playwright_close` | 关闭浏览器 |\n| **元素交互** | `playwright_click` | 点击元素 |\n| | `playwright_fill` | 填写表单 |\n| | `playwright_select` | 选择下拉选项 |\n| | `playwright_hover` | 悬停元素 |\n| | `playwright_press_key` | 按键操作 |\n| | `playwright_drag` | 拖拽操作 |\n| **内容提取** | `playwright_get_visible_text` | 获取可见文本 |\n| | `playwright_get_visible_html` | 获取 HTML 内容 |\n| **输出工具** | `playwright_save_as_pdf` | 保存为 PDF |\n| **API 测试** | `playwright_expect_response` | 期望响应验证 |\n| | `playwright_assert_response` | 断言响应 |\n| **IFrame** | `playwright_iframe_click` | IFrame 点击 |\n| | `playwright_iframe_fill` | IFrame 填写 |\n\n### 浏览器启动条件\n\n工具系统使用条件启动机制，仅在需要时启动浏览器： 资料来源：[src/tools.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools.ts)\n\n```typescript\nexport const BROWSER_TOOLS = [\n \"playwright_navigate\",\n \"playwright_screenshot\",\n \"playwright_click\",\n \"playwright_iframe_click\",\n \"playwright_iframe_fill\",\n \"playwright_fill\",\n \"playwright_select\",\n \"playwright_hover\",\n \"playwright_upload_file\",\n \"playwright_evaluate\",\n \"playwright_resize\",\n \"playwright_close\",\n \"playwright_expect_response\",\n \"playwright_assert_response\",\n \"playwright_custom_user_agent\",\n \"playwright_get_visible_text\",\n ...\n];\n```\n\n### 工具处理器\n\n工具处理器（ToolHandler）负责管理浏览器实例的生命周期和执行具体工具调用。 资料来源：[src/toolHandler.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/toolHandler.ts)\n\n```mermaid\ngraph TB\n subgraph \"ToolHandler\"\n BrowserManager[浏览器管理器]\n ToolRegistry[工具注册表]\n SessionManager[会话管理器]\n end\n \n ToolRegistry -->|执行| BrowserManager\n SessionManager -->|状态| BrowserManager\n```\n\n## 日志系统架构\n\n### 日志中间件\n\n日志中间件（LoggingMiddleware）拦截所有工具调用请求，记录详细的执行上下文和错误信息。 资料来源：[src/logging/middleware.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/middleware.ts)\n\n```mermaid\ngraph LR\n Request[请求] --> Middleware[日志中间件]\n Middleware --> Sanitize[参数脱敏]\n Middleware --> LogStart[记录开始]\n Request -->|执行| Handler[工具处理器]\n Handler -->|结果| Middleware\n Middleware --> LogComplete[记录完成]\n Middleware --> LogError[记录错误]\n Middleware --> Response[响应]\n```\n\n### 日志级别和上下文\n\n| 方法 | 用途 |\n|------|------|\n| `info()` | 一般信息日志 |\n| `warn()` | 警告信息日志 |\n| `error()` | 错误信息日志 |\n| `logRequest()` | 请求详情日志 |\n| `logError()` | 错误详情日志 |\n\n日志上下文包含丰富的系统信息： 资料来源：[src/logging/logger.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/logger.ts)\n\n- 错误名称和消息\n- 堆栈跟踪\n- 时间戳\n- Node.js 版本\n- 平台和架构信息\n- 内存使用情况\n- 运行时间\n\n### 错误分类\n\n日志中间件实现了智能错误分类功能： 资料来源：[src/logging/middleware.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/middleware.ts)\n\n| 错误类型 | 触发条件 |\n|----------|----------|\n| `validation` | 参数验证失败、缺少必填字段 |\n| `resource` | 浏览器/页面连接断开、协议错误 |\n| `authentication` | 未授权访问、权限不足 |\n| `rate_limit` | 请求频率限制 |\n| `system` | 超时、元素未找到、导航失败 |\n\n## 多浏览器支持\n\n### 浏览器类型\n\n项目支持三种浏览器引擎，通过 `browserType` 参数指定： 资料来源：[CHANGELOG.md](https://github.com/executeautomation/mcp-playwright/blob/main/CHANGELOG.md)\n\n| 浏览器 | 参数值 | 包依赖 |\n|--------|--------|--------|\n| Chromium | `chromium` | `@playwright/browser-chromium` |\n| Firefox | `firefox` | `@playwright/browser-firefox` |\n| WebKit | `webkit` | `@playwright/browser-webkit` |\n\n### 浏览器依赖版本\n\n所有浏览器包版本统一为 `1.57.0`，核心 Playwright 版本也保持一致。 资料来源：[package.json](https://github.com/executeautomation/mcp-playwright/blob/main/package.json)\n\n```json\n{\n \"@playwright/browser-chromium\": \"1.57.0\",\n \"@playwright/browser-firefox\": \"1.57.0\",\n \"@playwright/browser-webkit\": \"1.57.0\",\n \"playwright\": \"1.57.0\"\n}\n```\n\n## 服务器启动流程\n\n```mermaid\ngraph TB\n Start[启动] --> Args[解析命令行参数]\n Args --> Mode{运行模式}\n Mode -->|stdio| STDIO_Init[STDIO 模式初始化]\n Mode -->|http| HTTP_Init[HTTP 模式初始化]\n \n STDIO_Init --> SDK_Init[MCP SDK 初始化]\n HTTP_Init --> Express[Express 服务器]\n Express --> Routes[注册路由]\n Routes --> SSE_Init[SSE 服务初始化]\n SSE_Init --> SSE_Ready[SSE 就绪]\n \n SDK_Init --> RegisterTools[注册工具]\n RegisterTools --> Loop[事件循环]\n Loop -->|请求| Handle[处理请求]\n Handle -->|调用| Execute[执行工具]\n Execute --> Response[返回结果]\n Response --> Loop\n```\n\n## 入口点架构\n\n### src/index.ts 主入口\n\n主入口文件负责根据命令行参数选择运行模式： 资料来源：[src/index.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/index.ts)\n\n```mermaid\ngraph LR\n Node[Node.js] --> Index[index.ts]\n Index --> ParseArgs[解析 --port 参数]\n ParseArgs -->|有端口参数| HTTP[HTTP 模式]\n ParseArgs -->|无端口参数| STDIO[STDIO 模式]\n```\n\n### HTTP 服务器初始化\n\nHTTP 服务器使用 Express 框架，绑定到本地主机（安全考虑）： 资料来源：[src/http-server.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/http-server.ts)\n\n```typescript\n// 安全配置：仅绑定本地主机\nconst host = '127.0.0.1';\nconst httpServer = app.listen(port, host, () => {\n logger.info(`Playwright MCP HTTP server listening on ${host}:${port}`);\n});\n```\n\n## SSE 服务器架构\n\n### SSE 服务端点\n\nSSE（Server-Sent Events）服务器负责将服务器端事件推送到客户端。 资料来源：[src/sse/server.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/sse/server.ts)\n\n```mermaid\ngraph LR\n Client[客户端] -->|建立连接| SSE[SSE 服务器]\n SSE -->|事件流| Client\n HTTP_Server[HTTP 服务器] -->|管理| SSE\n```\n\n### 会话管理\n\nSSE 服务器支持多会话管理，每个会话通过 `sessionId` 标识：\n\n- `/sse` - 建立 SSE 连接\n- `/messages?sessionId=` - 发送消息到指定会话\n- `/mcp` - MCP 统一接口（支持 sessionId 参数）\n\n## 安全特性\n\n### 安全设计原则\n\n| 特性 | 说明 |\n|------|------|\n| 本地绑定 | HTTP 服务器仅绑定 `127.0.0.1`，防止外部访问 |\n| 日志脱敏 | 工具参数自动脱敏，移除敏感字段 |\n| STDIO 隔离 | stdio 模式下日志仅写入文件 |\n\n### 参数脱敏规则\n\n日志中间件自动识别并脱敏以下敏感字段： 资料来源：[src/logging/middleware.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/middleware.ts)\n\n```typescript\nconst sensitiveFields = ['password', 'token', 'secret', 'key', 'auth'];\n```\n\n## 依赖关系图\n\n### 核心依赖\n\n| 包名 | 版本 | 用途 |\n|------|------|------|\n| `@modelcontextprotocol/sdk` | 1.24.3 | MCP 协议实现 |\n| `express` | ^4.21.1 | HTTP 服务器框架 |\n| `cors` | ^2.8.5 | 跨域资源共享 |\n| `playwright` | 1.57.0 | 浏览器自动化核心 |\n| `uuid` | 11.1.0 | 会话 ID 生成 |\n\n## 测试架构\n\n### 测试框架\n\n项目使用 Jest 作为测试框架，测试文件位于 `src/__tests__` 目录： 资料来源：[README.md](https://github.com/executeautomation/mcp-playwright/blob/main/README.md)\n\n```bash\n# 运行测试\nnpm test\n\n# 带覆盖率\nnpm run test:coverage\n\n# 自定义测试脚本\nnode run-tests.cjs\n```\n\n### 评估测试\n\n使用 `mcp-eval` 包进行 AI 能力评估：\n\n```bash\nOPENAI_API_KEY=your-key npx mcp-eval src/evals/evals.ts src/tools/codegen/index.ts\n```\n\n## 总结\n\nmcp-playwright 采用清晰的层次化架构设计：\n\n1. **传输层**：支持 STDIO 和 HTTP 两种模式，适配不同客户端需求\n2. **协议层**：基于 MCP SDK 实现标准化的工具调用协议\n3. **处理层**：请求处理器和工具处理器分离，职责明确\n4. **工具层**：模块化的浏览器自动化工具集，支持多浏览器\n5. **日志层**：完善的日志记录和错误追踪机制\n\n该架构确保了系统的可扩展性、可维护性和安全性，同时提供了灵活的部署选项。\n\n---\n\n\n\n## 工具参考手册\n\n### 相关页面\n\n相关主题：[快速入门指南](#getting-started), [设备模拟功能](#device-emulation), [测试代码生成](#code-generation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tools.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools.ts)\n- [src/tools/index.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/index.ts)\n- [src/tools/browser/index.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/index.ts)\n- [src/tools/browser/screenshot.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/screenshot.ts)\n- [src/tools/browser/visiblePage.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/visiblePage.ts)\n- [src/logging/middleware.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/middleware.ts)\n- [package.json](https://github.com/executeautomation/mcp-playwright/blob/main/package.json)\n \n\n# 工具参考手册\n\nPlaywright MCP Server 提供了一套完整的浏览器自动化工具集，通过 MCP（Model Context Protocol）协议暴露给 AI 助手使用。本工具手册详细介绍了所有可用工具的功能、参数配置及使用方法。\n\n## 1. 工具系统概述\n\n### 1.1 架构设计\n\nMCP Playwright 的工具系统采用模块化分层架构，将不同类型的工具按功能域划分为独立的模块。\n\n```mermaid\ngraph TD\n A[MCP Client
Claude/Copilot] --> B[Tool Handler
handleToolCall]\n B --> C[Browser Tools
浏览器操作]\n B --> D[API Tools
API 测试]\n B --> E[Codegen Tools
代码生成]\n \n C --> C1[navigate/click/fill]\n C --> C2[screenshot/evaluate]\n C --> C3[resize/hover]\n C --> C4[drag/press_key]\n \n D --> D1[api_request]\n D --> D2[expect_response]\n D --> D3[assert_response]\n \n E --> E1[代码生成工具]\n```\n\n资料来源：[src/tools.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools.ts)\n\n### 1.2 工具分类\n\n| 工具类别 | 前缀命名 | 功能说明 |\n|---------|---------|---------|\n| 浏览器工具 | `playwright_*` | 网页导航、元素交互、内容提取 |\n| API 工具 | `api_*` | HTTP 请求测试、响应验证 |\n| 代码生成工具 | `codegen_*` | 测试代码自动生成 |\n\n### 1.3 工具依赖关系\n\n浏览器操作类工具需要启动浏览器实例，系统通过 `BROWSER_TOOLS` 数组标识这些工具：\n\n```typescript\nexport const BROWSER_TOOLS = [\n \"playwright_navigate\",\n \"playwright_screenshot\",\n \"playwright_click\",\n \"playwright_iframe_click\",\n \"playwright_iframe_fill\",\n \"playwright_fill\",\n \"playwright_select\",\n \"playwright_hover\",\n \"playwright_upload_file\",\n \"playwright_evaluate\",\n \"playwright_resize\",\n \"playwright_close\",\n \"playwright_expect_response\",\n \"playwright_assert_response\",\n \"playwright_custom_user_agent\",\n \"playwright_get_visible_text\",\n];\n```\n\n资料来源：[src/tools.ts:1-16](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools.ts)\n\n---\n\n## 2. 浏览器工具详解\n\n### 2.1 导航与浏览器控制\n\n#### playwright_navigate\n\n打开指定 URL 并启动浏览器会话。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| url | string | 是 | 目标网页 URL |\n| browserType | string | 否 | 浏览器类型：chromium/firefox/webkit，默认 chromium |\n\n```javascript\n// 示例：使用 Firefox 打开网页\nawait playwright_navigate({ \n url: \"https://example.com\",\n browserType: \"firefox\"\n});\n```\n\n#### playwright_close\n\n关闭当前浏览器实例并清理资源。\n\n```javascript\nawait playwright_close();\n```\n\n资料来源：[src/tools/browser/index.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/index.ts)\n\n### 2.2 元素交互工具\n\n#### playwright_click\n\n点击页面上的指定元素。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| selector | string | 是 | CSS 选择器 |\n| button | string | 否 | 鼠标按钮：left/right/middle，默认 left |\n| clickCount | number | 否 | 点击次数：1/2/3 |\n| modifiers | string | 否 | 按住的修饰键：Alt/Control/Meta/Shift |\n\n#### playwright_fill\n\n向输入框填充文本内容。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| selector | string | 是 | CSS 选择器 |\n| value | string | 是 | 要填充的文本值 |\n\n#### playwright_select\n\n从下拉菜单中选择选项。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| selector | string | 是 | select 元素选择器 |\n| value | string | 是 | 选项值或标签 |\n| selectType | string | 否 | 选择类型：value/label/index |\n\n#### playwright_hover\n\n鼠标悬停在指定元素上。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| selector | string | 是 | CSS 选择器 |\n\n#### playwright_drag\n\n将元素从一位置拖拽到另一位置。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| sourceSelector | string | 是 | 源元素选择器 |\n| targetSelector | string | 是 | 目标元素选择器 |\n\n#### playwright_press_key\n\n模拟键盘按键操作。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| key | string | 是 | 按键名称 |\n| selector | string | 否 | 聚焦元素选择器 |\n| modifiers | string | 否 | 组合修饰键 |\n\n#### playwright_click_and_switch_tab\n\n点击链接并切换到新打开的标签页。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| selector | string | 是 | 链接选择器 |\n\n资料来源：[src/tools.ts:20-80](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools.ts)\n\n### 2.3 截图与内容提取\n\n#### playwright_screenshot\n\n对当前页面或指定元素进行截图。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| name | string | 否 | 截图名称标识（默认 screenshot） |\n| selector | string | 否 | 元素选择器，指定则截取元素而非全页 |\n| fullPage | boolean | 否 | 是否截取整个可滚动页面 |\n| storeBase64 | boolean | 否 | 是否存储 base64 副本到内存 |\n| downloadsDir | string | 否 | 保存目录路径 |\n\n```javascript\n// 全页面截图\nawait playwright_screenshot({ \n name: \"homepage\",\n fullPage: true \n});\n\n// 元素截图\nawait playwright_screenshot({ \n selector: \"#banner\",\n name: \"banner-element\"\n});\n```\n\n截图后，系统自动将 base64 数据存储到内存中供后续访问：\n\n```typescript\nif (args.storeBase64 !== false) {\n this.screenshots.set(args.name || 'screenshot', base64Screenshot);\n this.server.notification({\n method: \"notifications/resources/list_changed\",\n });\n}\n```\n\n资料来源：[src/tools/browser/screenshot.ts:40-50](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/screenshot.ts)\n\n#### playwright_get_visible_text\n\n提取页面或元素的可见文本内容。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| selector | string | 否 | 元素选择器，不指定则获取整个页面 |\n\n#### playwright_get_visible_html\n\n获取页面或元素的完整 HTML 内容。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| selector | string | 否 | 元素选择器 |\n| removeScripts | boolean | 否 | 移除 script 标签 |\n| removeComments | boolean | 否 | 移除 HTML 注释 |\n| removeStyles | boolean | 否 | 移除 style 标签 |\n| removeMeta | boolean | 否 | 移除 meta 标签 |\n| cleanHtml | boolean | 否 | 应用所有清理选项 |\n| minify | boolean | 否 | 压缩 HTML |\n\n```javascript\n// 获取清理后的 HTML\nawait playwright_get_visible_html({\n selector: \"#content\",\n cleanHtml: true,\n minify: true\n});\n```\n\n资料来源：[src/tools/browser/visiblePage.ts:1-50](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/visiblePage.ts)\n\n### 2.4 设备模拟与视口控制\n\n#### playwright_resize\n\n调整浏览器视口大小或模拟设备。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| width | number | 否 | 视口宽度（像素） |\n| height | number | 否 | 视口高度（像素） |\n| device | string | 否 | 预设设备名称（自动设置 viewport、userAgent） |\n| orientation | string | 否 | 设备方向：portrait/landscape |\n\n支持 143 种预设设备，包括：\n\n- iPhone 系列（iPhone 13, iPhone 15 Pro Max 等）\n- iPad 系列（iPad Pro 11, iPad Mini 等）\n- Pixel 系列（Pixel 7, Pixel 8 等）\n- Samsung Galaxy 系列\n- 桌面浏览器（Desktop Chrome, Firefox, Safari）\n\n```javascript\n// 模拟 iPhone 13\nawait playwright_resize({ device: \"iPhone 13\" });\n\n// 模拟 iPad 横屏\nawait playwright_resize({ \n device: \"iPad Pro 11\", \n orientation: \"landscape\" \n});\n\n// 自定义视口\nawait playwright_resize({ \n width: 1920, \n height: 1080 \n});\n```\n\n资料来源：[README.md:1-30](https://github.com/executeautomation/mcp-playwright/blob/main/README.md)\n\n### 2.5 JavaScript 执行\n\n#### playwright_evaluate\n\n在浏览器上下文中执行任意 JavaScript 代码。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| script | string | 是 | 要执行的 JavaScript 代码 |\n| params | object | 否 | 传递给脚本的参数 |\n\n```javascript\n// 获取页面标题\nconst title = await playwright_evaluate({\n script: \"() => document.title\"\n});\n\n// 带参数执行\nconst links = await playwright_evaluate({\n script: \"(count) => Array.from(document.links).slice(0, count)\",\n params: { count: 10 }\n});\n```\n\n### 2.6 文件操作\n\n#### playwright_upload_file\n\n上传文件到页面中的文件上传控件。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| selector | string | 是 | 文件输入框选择器 |\n| filePaths | string[] | 是 | 文件路径数组 |\n\n```javascript\nawait playwright_upload_file({\n selector: \"input[type='file']\",\n filePaths: [\"/path/to/file.pdf\", \"/path/to/image.png\"]\n});\n```\n\n#### playwright_save_as_pdf\n\n将当前页面保存为 PDF 文件。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| outputPath | string | 是 | 输出文件路径 |\n| format | string | 否 | 页面格式：A4/Letter |\n| printBackground | boolean | 否 | 是否打印背景图形 |\n| margin | object | 否 | 页边距配置 |\n\n```javascript\nawait playwright_save_as_pdf({\n outputPath: \"/tmp/report.pdf\",\n format: \"A4\",\n printBackground: true,\n margin: {\n top: \"1cm\",\n right: \"1cm\",\n bottom: \"1cm\",\n left: \"1cm\"\n }\n});\n```\n\n---\n\n## 3. API 测试工具\n\n### 3.1 API 请求工具\n\n#### api_request\n\n发送 HTTP 请求并进行测试验证。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| url | string | 是 | 请求 URL |\n| method | string | 否 | HTTP 方法：GET/POST/PUT/DELETE/PATCH |\n| headers | object | 否 | 请求头 |\n| body | object | 否 | 请求体 |\n| timeout | number | 否 | 超时时间（毫秒） |\n| authorization | string | 否 | Bearer 认证令牌 |\n\n```javascript\n// 发送 POST 请求\nconst response = await api_request({\n url: \"https://api.example.com/users\",\n method: \"POST\",\n headers: {\n \"Content-Type\": \"application/json\"\n },\n body: {\n name: \"张三\",\n email: \"zhangsan@example.com\"\n },\n authorization: \"Bearer your-token-here\"\n});\n```\n\n### 3.2 响应验证工具\n\n#### playwright_expect_response\n\n设置预期响应模式，验证后续请求的响应。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| urlPattern | string | 是 | URL 匹配模式（正则表达式） |\n| statusCode | number | 否 | 预期状态码 |\n| headers | object | 否 | 预期响应头 |\n| bodyPattern | string | 否 | 预期响应体模式 |\n\n#### playwright_assert_response\n\n对已发生的响应进行断言验证。\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| urlPattern | string | 是 | URL 匹配模式 |\n| assertType | string | 是 | 断言类型：status/header/body |\n| expectedValue | any | 是 | 预期值 |\n\n---\n\n## 4. 工具执行流程\n\n### 4.1 请求处理流程\n\n```mermaid\nsequenceDiagram\n participant Client as MCP 客户端\n participant Handler as Tool Handler\n participant Logger as 日志中间件\n participant Browser as Playwright 浏览器\n participant Tools as 工具实现\n \n Client->>Handler: 工具调用请求\n Handler->>Logger: 记录请求开始\n Logger->>Browser: 检查/启动浏览器\n Browser->>Tools: 传递参数\n Tools->>Browser: 执行浏览器操作\n Browser-->>Tools: 返回结果\n Tools-->>Logger: 返回响应\n Logger-->>Client: 返回结果+日志\n```\n\n资料来源：[src/logging/middleware.ts:1-30](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/middleware.ts)\n\n### 4.2 日志记录机制\n\n工具执行中间件提供完整的请求追踪功能：\n\n| 日志阶段 | 记录内容 |\n|---------|---------|\n| 请求开始 | 工具名称、参数、请求 ID |\n| 执行中 | 操作类型、浏览器状态 |\n| 完成 | 状态码、耗时、响应内容 |\n| 错误 | 错误分类、堆栈跟踪、系统上下文 |\n\n错误分类系统：\n\n```typescript\nprivate categorizeToolError(toolName: string, error: Error): ErrorCategory {\n const message = error.message.toLowerCase();\n \n // 资源错误\n if (message.includes('browser') || message.includes('page') || \n message.includes('closed') || message.includes('disconnected')) {\n return 'resource';\n }\n \n // 验证错误\n if (message.includes('invalid') || message.includes('validation')) {\n return 'validation';\n }\n \n // 认证错误\n if (message.includes('unauthorized') || message.includes('forbidden')) {\n return 'authentication';\n }\n \n // 超时错误\n if (message.includes('timeout')) {\n return 'system';\n }\n}\n```\n\n资料来源：[src/logging/middleware.ts:50-100](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/middleware.ts)\n\n---\n\n## 5. 工具命名规范\n\n### 5.1 命名限制\n\n工具名称必须遵循以下约束：\n\n| 限制项 | 最大值 | 原因 |\n|-------|-------|------|\n| 工具名称长度 | 60 字符 | Cursor 等客户端限制 |\n| 服务器前缀 | playwright_ | 区分不同 MCP 服务器 |\n\n完整工具标识符格式：`playwright-mcp:playwright_xxx`\n\n### 5.2 推荐的短命名\n\n| 完整名称 | 用途场景 |\n|---------|---------|\n| playwright_navigate | 导航 |\n| playwright_click | 点击 |\n| playwright_fill | 填充表单 |\n| playwright_screenshot | 截图 |\n| playwright_close | 关闭 |\n\n---\n\n## 6. 错误处理\n\n### 6.1 错误分类\n\n| 错误类型 | 触发条件 | 示例消息 |\n|---------|---------|---------|\n| validation | 参数验证失败 | \"invalid selector\"、\"required parameter missing\" |\n| resource | 浏览器资源问题 | \"browser closed\"、\"target page closed\" |\n| authentication | 认证授权失败 | \"unauthorized\"、\"access denied\" |\n| rate_limit | 请求频率限制 | \"rate limit exceeded\" |\n| system | 超时/系统错误 | \"timeout waiting for element\" |\n\n### 6.2 错误上下文捕获\n\n系统自动捕获并记录以下错误上下文信息：\n\n```typescript\n{\n errorName: string, // 错误类型名称\n errorMessage: string, // 错误消息\n stack: string, // 堆栈跟踪\n timestamp: string, // ISO 时间戳\n nodeVersion: string, // Node.js 版本\n platform: string, // 操作系统平台\n memoryUsage: object, // 内存使用情况\n uptime: number, // 进程运行时间\n toolName: string, // 工具名称\n toolCategory: string, // 工具类别\n browserContext: object // 浏览器上下文\n}\n```\n\n---\n\n## 7. 配置与运行模式\n\n### 7.1 标准模式（stdio）\n\n适合 Claude Desktop 等标准 MCP 客户端：\n\n```json\n{\n \"mcpServers\": {\n \"playwright\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@executeautomation/playwright-mcp-server\"]\n }\n }\n}\n```\n\n### 7.2 HTTP 模式\n\n适合 VS Code、自定义客户端和远程部署：\n\n```bash\nnpx @executeautomation/playwright-mcp-server --port 8931\n```\n\n可用端点：\n\n| 端点 | 方法 | 用途 |\n|-----|------|------|\n| /sse | GET | SSE 流推送 |\n| /messages | POST | 消息接收 |\n| /mcp | GET/POST | MCP 统一接口 |\n| /health | GET | 健康检查 |\n\n### 7.3 Docker 部署\n\n```bash\ndocker run -i --rm mcp-playwright:latest\n```\n\n环境变量配置：\n\n| 变量名 | 说明 | 默认值 |\n|-------|------|-------|\n| PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD | 跳过浏览器自动安装 | false |\n| NODE_ENV | 运行环境 | development |\n\n---\n\n## 8. 快速参考表\n\n### 8.1 常用工具速查\n\n| 功能需求 | 推荐工具 | 必需参数 |\n|---------|---------|---------|\n| 打开网页 | playwright_navigate | url |\n| 点击元素 | playwright_click | selector |\n| 填写表单 | playwright_fill | selector, value |\n| 页面截图 | playwright_screenshot | - |\n| 获取文本 | playwright_get_visible_text | selector |\n| 调整窗口 | playwright_resize | width, height |\n| 模拟设备 | playwright_resize | device |\n| 发送请求 | api_request | url |\n\n### 8.2 参数类型速查\n\n| 类型标识 | 说明 | 示例 |\n|---------|------|------|\n| string | 字符串 | \"hello\" |\n| number | 数字 | 123 |\n| boolean | 布尔值 | true/false |\n| object | 对象 | {key: \"value\"} |\n| string[] | 字符串数组 | [\"a\", \"b\", \"c\"] |\n\n---\n\n## 9. 依赖版本\n\n| 依赖包 | 版本 | 用途 |\n|-------|------|------|\n| playwright | 1.57.0 | 浏览器自动化核心 |\n| @modelcontextprotocol/sdk | 1.24.3 | MCP 协议实现 |\n| @playwright/test | ^1.57.0 | 测试框架 |\n| express | ^4.21.1 | HTTP 服务器（HTTP 模式） |\n\n资料来源：[package.json:1-30](https://github.com/executeautomation/mcp-playwright/blob/main/package.json)\n\n---\n\n\n\n## 设备模拟功能\n\n### 相关页面\n\n相关主题：[工具参考手册](#tool-reference), [快速入门指南](#getting-started)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/browser/resize.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/resize.ts)\n- [src/tools/browser/useragent.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/useragent.ts)\n- [scripts/list-devices.cjs](https://github.com/executeautomation/mcp-playwright/blob/main/scripts/list-devices.cjs)\n- [docs/docs/playwright-web/Device-Quick-Reference.md](https://github.com/executeautomation/mcp-playwright/blob/main/docs/docs/playwright-web/Device-Quick-Reference.md)\n \n\n# 设备模拟功能\n\n## 概述\n\n设备模拟功能是 MCP Playwright 服务器的核心特性之一，允许 AI 助手和自动化测试工具在真实的设备配置下测试 Web 应用程序。该功能通过 `playwright_resize` 工具实现，支持 **143 种真实设备预设**，涵盖 iPhone、iPad、Pixel、Galaxy 以及主流桌面浏览器。\n\n设备模拟功能的核心价值在于：\n\n- 无需物理设备即可在真实设备配置下进行测试\n- 自动模拟设备的视口尺寸、用户代理字符串、触摸事件和设备像素比\n- 支持横竖屏切换\n- 与 AI 助手自然语言交互\n\n资料来源：[README.md](https://github.com/executeautomation/mcp-playwright/blob/main/README.md)\n\n## 架构设计\n\n### 组件关系\n\n```mermaid\ngraph TD\n A[playwright_resize 工具] --> B[ResizeTool 类]\n B --> C[BrowserToolBase 基类]\n B --> D[Playwright devices 模块]\n C --> E[BrowserContext]\n D --> F[设备配置数据]\n \n F --> F1[viewport 视口尺寸]\n F --> F2[userAgent 用户代理]\n F --> F3[deviceScaleFactor 像素比]\n F --> F4[isMobile 移动标识]\n F --> F5[hasTouch 触摸支持]\n```\n\n### 执行流程\n\n```mermaid\nsequenceDiagram\n participant AI as AI 助手\n participant MCP as MCP 服务器\n participant PT as Playwright ResizeTool\n participant PW as Playwright Core\n\n AI->>MCP: playwright_resize({ device: \"iPhone 13\" })\n MCP->>PT: execute(args, context)\n \n alt 使用设备预设\n PT->>PT: 查询 devices['iPhone 13']\n PT->>PT: 提取设备属性\n PT->>PT: 验证设备存在性\n PT->>PW: page.setViewportSize({width, height})\n PT->>PW: page.setExtraHTTPHeaders({User-Agent})\n else 自定义尺寸\n PT->>PT: 验证 width, height 参数\n PT->>PT: 检查分辨率限制 (≤7680x4320)\n PT->>PW: page.setViewportSize({width, height})\n end\n \n alt 设备预设 + 横竖屏\n PT->>PT: 根据 orientation 交换宽高\n end\n \n PT-->>MCP: ToolResponse\n MCP-->>AI: 成功响应\n```\n\n## 核心实现\n\n### ResizeTool 类\n\n`ResizeTool` 继承自 `BrowserToolBase`，负责处理设备模拟的核心逻辑。\n\n资料来源：[src/tools/browser/resize.ts:6-12](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/resize.ts)\n\n```typescript\nexport class ResizeTool extends BrowserToolBase {\n async execute(args: any, context: ToolContext): Promise {\n return this.safeExecute(context, async (page) => {\n let width: number;\n let height: number;\n let deviceName: string | undefined;\n let shouldSetUserAgent = false;\n let userAgent: string | undefined;\n let isMobile = false;\n let hasTouch = false;\n let deviceScaleFactor = 1;\n \n // 设备预设解析逻辑\n // ...\n });\n }\n}\n```\n\n### 设备预设处理逻辑\n\n```mermaid\ngraph TD\n S[开始] --> A{args.device 存在?}\n A -->|是| B[查找设备预设]\n A -->|否| C[使用 width/height 参数]\n \n B --> D{设备存在?}\n D -->|否| E[返回错误 + 热门设备列表]\n D -->|是| F[提取设备属性]\n \n F --> F1[提取 viewport 尺寸]\n F --> F2[提取 userAgent]\n F --> F3[提取 isMobile]\n F --> F4[提取 hasTouch]\n F --> F5[提取 deviceScaleFactor]\n \n F1 --> G{orientation 参数?}\n C --> G\n E --> END[返回]\n \n G -->|landscape| H[交换宽高]\n G -->|portrait| I[保持原尺寸]\n \n H --> J[应用视口配置]\n I --> J\n J --> K[返回成功响应]\n K --> END\n```\n\n资料来源：[src/tools/browser/resize.ts:21-85](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/resize.ts)\n\n## API 参考\n\n### 工具名称\n\n`playwright_resize`\n\n### 输入参数\n\n| 参数名 | 类型 | 必填 | 描述 |\n|--------|------|------|------|\n| `device` | `string` | 否 | 设备预设名称，如 \"iPhone 13\"、\"Desktop Chrome\" |\n| `width` | `number` | 否 | 视口宽度（像素），与 device 二选一 |\n| `height` | `number` | 否 | 视口高度（像素），与 device 二选一 |\n| `orientation` | `string` | 否 | 设备方向：`portrait`（竖屏）或 `landscape`（横屏） |\n\n### 参数优先级\n\n1. 若指定 `device`，优先使用设备预设配置\n2. 若未指定 `device`，使用自定义 `width` 和 `height`\n3. `orientation` 参数仅在 `device` 模式下生效，用于切换横竖屏\n\n### 设备预设 vs 自定义尺寸\n\n| 特性 | 设备预设模式 | 自定义尺寸模式 |\n|------|-------------|---------------|\n| 视口尺寸 | 自动从预设提取 | 手动指定 |\n| 用户代理 | 自动设置为设备 UA | 不修改 |\n| 触摸支持 | 自动启用 | 不启用 |\n| 设备像素比 | 自动设置 | 默认为 1 |\n| 移动端模拟 | 自动标识 | 不标识 |\n| 横竖屏切换 | 支持 | 不支持 |\n\n## 使用示例\n\n### 基础设备模拟\n\n```javascript\n// 测试 iPhone 13\nawait playwright_resize({ device: \"iPhone 13\" });\n```\n\n### 横竖屏切换\n\n```javascript\n// iPad Pro 横屏模式\nawait playwright_resize({ device: \"iPad Pro 11\", orientation: \"landscape\" });\n\n// iPhone 14 竖屏模式（默认）\nawait playwright_resize({ device: \"iPhone 14\", orientation: \"portrait\" });\n```\n\n### 桌面浏览器\n\n```javascript\n// Chrome 桌面视图\nawait playwright_resize({ device: \"Desktop Chrome\" });\n\n// Firefox 桌面视图\nawait playwright_resize({ device: \"Desktop Firefox\" });\n```\n\n### 自定义视口尺寸\n\n```javascript\n// 自定义 1920x1080 分辨率\nawait playwright_resize({ width: 1920, height: 1080 });\n```\n\n## 支持的设备列表\n\n设备模拟功能支持 Playwright 内置的完整设备库，包含 **143 种设备预设**。\n\n### 设备分类\n\n| 类别 | 示例设备 | 数量 |\n|------|----------|------|\n| iPhone 系列 | iPhone 13, iPhone 13 Pro, iPhone 14, iPhone 15 | ~15+ |\n| iPad 系列 | iPad Pro 11, iPad Pro 12.9, iPad Mini | ~10+ |\n| Pixel 系列 | Pixel 5, Pixel 7, Pixel 8 | ~10+ |\n| Galaxy 系列 | Galaxy S9+, Galaxy S21, Galaxy S24 | ~15+ |\n| Kindle 系列 | Kindle Paperwhite, Kindle Fire | ~5+ |\n| 桌面浏览器 | Desktop Chrome, Desktop Firefox, Desktop Safari | 3 |\n\n### 热门设备建议\n\n当用户输入不存在的设备名时，系统会返回热门设备建议列表：\n\n```\nDevice \"xxx\" not found. Popular devices: iPhone 13, iPhone 13 Pro, iPhone 14, \niPhone 15, iPad Pro 11, iPad Pro 12.9, Pixel 5, Pixel 7, Galaxy S9+, Galaxy S24, \nDesktop Chrome, Desktop Firefox, Desktop Safari. \nUse playwright.devices to see all 143 available devices.\n```\n\n资料来源：[src/tools/browser/resize.ts:43-53](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/resize.ts)\n\n## 设备配置属性\n\n每个设备预设包含以下属性：\n\n| 属性 | 类型 | 描述 |\n|------|------|------|\n| `viewport.width` | `number` | 视口宽度（像素） |\n| `viewport.height` | `number` | 视口高度（像素） |\n| `viewport.deviceScaleFactor` | `number` | 设备像素比（通常为 1-3） |\n| `viewport.isMobile` | `boolean` | 是否为移动设备 |\n| `viewport.hasTouch` | `boolean` | 是否支持触摸 |\n| `userAgent` | `string` | HTTP User-Agent 字符串 |\n\n### 示例：iPhone 13 配置\n\n```javascript\n{\n viewport: {\n width: 390,\n height: 844,\n deviceScaleFactor: 3,\n isMobile: true,\n hasTouch: true,\n isLandscape: false\n },\n userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 15_0 like Mac OS X) AppleWebKit/605.1.15'\n}\n```\n\n## 参数验证规则\n\n### 设备预设模式\n\n- 设备名称必须在 Playwright devices 库中存在\n- `orientation` 必须是 `portrait` 或 `landscape`\n\n### 自定义尺寸模式\n\n| 验证项 | 规则 | 错误消息 |\n|--------|------|----------|\n| 参数必填 | `width` 和 `height` 至少提供一个 | \"Width or height parameter is required\" |\n| 正整数验证 | 值必须大于 0 | \"Width and height must be positive integers\" |\n| 分辨率上限 | 不超过 7680x4320 (8K) | \"Width and height must not exceed 7680x4320 (8K resolution)\" |\n\n资料来源：[src/tools/browser/resize.ts:103-112](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/resize.ts)\n\n## AI 助手自然语言集成\n\n设备模拟功能设计为与 AI 助手无缝集成，支持自然语言命令：\n\n### 支持的命令模式\n\n| 自然语言 | 转换为工具调用 |\n|----------|---------------|\n| \"Test on iPhone 13\" | `playwright_resize({ device: \"iPhone 13\" })` |\n| \"Switch to iPad view\" | `playwright_resize({ device: \"iPad Pro 11\" })` |\n| \"Rotate to landscape\" | `playwright_resize({ device: \"iPhone 14\", orientation: \"landscape\" })` |\n| \"Show desktop view\" | `playwright_resize({ device: \"Desktop Chrome\" })` |\n\n资料来源：[README.md](https://github.com/executeautomation/mcp-playwright/blob/main/README.md)\n\n## 错误处理\n\n### 常见错误及解决方案\n\n| 错误类型 | 错误消息 | 解决方案 |\n|----------|----------|----------|\n| 设备不存在 | `Device \"xxx\" not found` | 使用热门设备列表中的设备名 |\n| 尺寸无效 | `Width and height must be positive integers` | 提供正整数值 |\n| 分辨率超限 | `Width and height must not exceed 7680x4320` | 使用合理的分辨率 |\n| 浏览器未启动 | `Browser not launched` | 先调用 `playwright_navigate` 启动浏览器 |\n\n### 错误响应格式\n\n```json\n{\n \"isError\": true,\n \"content\": [\n {\n \"type\": \"text\",\n \"text\": \"Device \\\"iPhone 99\\\" not found. Popular devices: iPhone 13, iPhone 13 Pro...\"\n }\n ]\n}\n```\n\n## 与其他工具的配合\n\n### 推荐的工具调用顺序\n\n```mermaid\ngraph LR\n A[playwright_navigate] --> B[playwright_resize]\n B --> C[playwright_screenshot]\n C --> D[playwright_click]\n D --> E[playwright_fill]\n```\n\n1. **启动浏览器**：`playwright_navigate` - 初始化浏览器上下文\n2. **设置设备**：`playwright_resize` - 应用设备模拟配置\n3. **截图验证**：`playwright_screenshot` - 验证设备视图\n4. **交互操作**：`playwright_click` / `playwright_fill` - 执行测试操作\n\n## 性能注意事项\n\n| 项目 | 建议 |\n|------|------|\n| 设备切换频率 | 避免频繁切换设备，每次切换都有性能开销 |\n| 高分辨率设备 | 8K 以上分辨率可能导致内存问题 |\n| 触摸事件 | `hasTouch: true` 会影响事件分发逻辑 |\n| 设备像素比 | 高像素比（如 3x）会增加截图和渲染开销 |\n\n## 相关工具\n\n| 工具名称 | 功能描述 | 关系 |\n|----------|----------|------|\n| `playwright_navigate` | 启动浏览器并导航到 URL | 前置依赖 |\n| `playwright_screenshot` | 截取页面截图 | 配合使用 |\n| `playwright_custom_user_agent` | 自定义用户代理字符串 | 独立功能 |\n| `playwright_get_visible_text` | 获取页面可见文本 | 配合使用 |\n\n资料来源：[src/tools.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools.ts)\n\n---\n\n\n\n## 测试代码生成\n\n### 相关页面\n\n相关主题：[工具参考手册](#tool-reference)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/codegen/recorder.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/codegen/recorder.ts)\n- [src/tools/codegen/generator.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/codegen/generator.ts)\n- [src/tools/codegen/types.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/codegen/types.ts)\n- [src/tools/codegen/index.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/codegen/index.ts)\n \n\n# 测试代码生成\n\n## 概述\n\n测试代码生成（Code Generation）是 MCP Playwright 提供的一项高级功能，允许开发者通过 MCP 工具执行自动化操作，并自动记录这些操作，最终生成可重用的 Playwright 测试脚本。\n\n该功能的核心价值在于：\n\n- 将手动录制的用户操作自动转化为可执行的测试代码\n- 支持从记录的会话中生成结构化的 Playwright 测试用例\n- 提供灵活的配置选项以满足不同项目的测试需求\n\n资料来源：[src/tools/codegen/index.ts:1-20]()\n\n## 架构设计\n\n### 核心组件\n\n测试代码生成模块由三个主要组件构成：\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| ActionRecorder | `recorder.ts` | 记录 MCP 工具调用操作 |\n| PlaywrightGenerator | `generator.ts` | 根据记录的操作生成测试代码 |\n| 工具接口 | `index.ts` | 提供对外的 MCP 工具入口 |\n\n```mermaid\ngraph TD\n A[MCP 客户端] --> B[start_codegen_session]\n B --> C[ActionRecorder]\n C --> D[CodegenSession]\n D --> E[PlaywrightGenerator]\n E --> F[PlaywrightTestCase]\n F --> G[测试代码文件]\n \n H[record_action] --> C\n C --> I[get_session]\n```\n\n资料来源：[src/tools/codegen/generator.ts:1-10]()\n\n### 类型定义\n\ntypes.ts 文件定义了核心数据结构：\n\n| 类型 | 用途 |\n|------|------|\n| `CodegenAction` | 单个工具调用操作的表示 |\n| `CodegenSession` | 包含多个操作的会话容器 |\n| `CodegenOptions` | 代码生成的配置选项 |\n| `CodegenResult` | 生成的测试代码结果 |\n| `PlaywrightTestCase` | 生成的测试用例结构 |\n\n资料来源：[src/tools/codegen/types.ts]()\n\n## 工作流程\n\n### 整体流程\n\n```mermaid\ngraph LR\n A[开始会话] --> B[执行 MCP 工具]\n B --> C[record_action]\n C --> D{是否结束会话?}\n D -->|否| B\n D -->|是| E[generate_test]\n E --> F[输出测试代码]\n F --> G[保存到文件]\n```\n\n### 会话管理\n\n1. **启动会话**：调用 `start_codegen_session` 初始化新的代码生成会话\n2. **记录操作**：每个 MCP 工具调用通过 `record_action` 自动记录\n3. **生成代码**：调用 `generate_playwright_test` 将会话转化为测试代码\n4. **保存结果**：生成的代码保存到指定的输出目录\n\n资料来源：[src/tools/codegen/index.ts:35-80]()\n\n## 配置选项\n\n`CodegenOptions` 接口提供以下可配置项：\n\n| 选项 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `outputPath` | `string` | `'tests'` | 测试文件输出目录 |\n| `testNamePrefix` | `string` | `'MCP'` | 测试名称前缀 |\n| `includeComments` | `boolean` | `true` | 是否在生成的代码中包含注释 |\n\n```typescript\nconst DEFAULT_OPTIONS: Required = {\n outputPath: 'tests',\n testNamePrefix: 'MCP',\n includeComments: true,\n};\n```\n\n资料来源：[src/tools/codegen/generator.ts:10-15]()\n\n### 自定义配置示例\n\n```json\n{\n \"options\": {\n \"outputPath\": \"/path/to/e2e\",\n \"testNamePrefix\": \"E2E\",\n \"includeComments\": true\n }\n}\n```\n\n## MCP 工具接口\n\n### start_codegen_session\n\n启动一个新的代码生成会话。\n\n**参数**：\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| `options` | `CodegenOptions` | 否 | 代码生成配置选项 |\n\n**返回值**：包含会话 ID 和状态的对象\n\n资料来源：[src/tools/codegen/index.ts:35-50]()\n\n### record_action\n\n记录单个工具调用操作到当前会话。\n\n**参数**：\n\n| 参数名 | 类型 | 说明 |\n|--------|------|------|\n| `toolName` | `string` | 工具名称 |\n| `args` | `object` | 工具参数 |\n| `result` | `object` | 工具执行结果 |\n\n### generate_playwright_test\n\n根据记录的会话生成 Playwright 测试代码。\n\n**参数**：\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| `sessionId` | `string` | 是 | 会话 ID |\n\n**返回值**：`CodegenResult`，包含生成的代码和文件路径\n\n资料来源：[src/tools/codegen/generator.ts:30-45]()\n\n### get_codegen_session\n\n获取指定会话的信息和已记录的操作。\n\n**参数**：\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| `sessionId` | `string` | 是 | 会话 ID |\n\n### cleanup_codegen_session\n\n清理指定会话，释放相关资源。\n\n**参数**：\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| `sessionId` | `string` | 是 | 会话 ID |\n\n## PlaywrightGenerator 类\n\n`PlaywrightGenerator` 是核心的测试代码生成器类，负责将操作记录转化为 Playwright 测试代码。\n\n```typescript\nexport class PlaywrightGenerator {\n private static readonly DEFAULT_OPTIONS: Required = {\n outputPath: 'tests',\n testNamePrefix: 'MCP',\n includeComments: true,\n };\n\n private options: Required;\n}\n```\n\n### 公共方法\n\n| 方法 | 返回类型 | 说明 |\n|------|----------|------|\n| `generateTest(session)` | `Promise` | 生成测试代码 |\n| `createTestCase(session)` | `PlaywrightTestCase` | 创建测试用例对象 |\n| `generateTestCode(testCase)` | `string` | 生成测试代码字符串 |\n| `getOutputFilePath(session)` | `string` | 获取输出文件路径 |\n\n### 生成流程\n\n```mermaid\ngraph TD\n A[generateTest] --> B[验证 session 数据]\n B --> C[createTestCase]\n C --> D[生成测试用例对象]\n D --> E[generateTestCode]\n E --> F[获取输出文件路径]\n F --> G[返回 CodegenResult]\n```\n\n资料来源：[src/tools/codegen/generator.ts:35-55]()\n\n### 选项验证\n\n`validateOptions` 方法确保配置选项的类型正确：\n\n| 验证规则 | 选项 | 类型要求 |\n|----------|------|----------|\n| 1 | `outputPath` | 必须为字符串 |\n| 2 | `testNamePrefix` | 必须为字符串 |\n| 3 | `includeComments` | 必须为布尔值 |\n\n如果选项类型不匹配，将抛出相应的验证错误。\n\n资料来源：[src/tools/codegen/generator.ts:20-30]()\n\n## 错误处理\n\n### 会话验证\n\n- 无效的会话数据将抛出 `Invalid session data` 错误\n- 会话必须包含有效的 `actions` 数组\n\n### 选项验证\n\n- `outputPath` 类型错误抛出 `outputPath must be a string`\n- `testNamePrefix` 类型错误抛出 `testNamePrefix must be a string`\n- `includeComments` 类型错误抛出 `includeComments must be a boolean`\n\n### 常见错误场景\n\n| 错误场景 | 错误信息 |\n|----------|----------|\n| 空 session | `Invalid session data` |\n| actions 非数组 | `Invalid session data` |\n| 选项类型错误 | `{optionName} must be a {type}` |\n\n资料来源：[src/tools/codegen/generator.ts:25-40]()\n\n## 使用示例\n\n### 基本使用流程\n\n```mermaid\nsequenceDiagram\n participant User\n participant MCP as MCP Server\n participant Recorder as ActionRecorder\n participant Generator as PlaywrightGenerator\n\n User->>MCP: start_codegen_session()\n MCP->>Recorder: 创建新会话\n User->>MCP: 导航到页面\n User->>MCP: record_action(\"navigate\", args)\n MCP->>Recorder: 记录操作\n User->>MCP: 执行其他操作\n User->>MCP: generate_playwright_test(sessionId)\n MCP->>Generator: 生成测试代码\n Generator-->>User: 返回测试代码\n```\n\n### 完整配置示例\n\n```json\n{\n \"name\": \"start_codegen_session\",\n \"description\": \"Start a new code generation session to record MCP tool actions\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"options\": {\n \"type\": \"object\",\n \"description\": \"Code generation options\",\n \"properties\": {\n \"outputPath\": { \"type\": \"string\" },\n \"testNamePrefix\": { \"type\": \"string\" },\n \"includeComments\": { \"type\": \"boolean\" }\n }\n }\n }\n }\n}\n```\n\n资料来源：[src/tools/codegen/index.ts:35-60]()\n\n## 全局状态管理\n\n代码生成模块使用全局变量存储浏览器和页面实例：\n\n```typescript\ndeclare global {\n var browser: Browser | undefined;\n var page: Page | undefined;\n}\n```\n\n这允许在工具调用之间共享 Playwright 浏览器和页面上下文。\n\n资料来源：[src/tools/codegen/index.ts:14-20]()\n\n## 与其他模块的关系\n\n```mermaid\ngraph TD\n A[codegen 模块] --> B[logging 模块]\n A --> C[browser 工具]\n A --> D[MCP SDK]\n \n B --> B1[middleware.ts]\n B --> B2[logger.ts]\n \n C --> C1[navigate.ts]\n C --> C2[screenshot.ts]\n C --> C3[click.ts]\n```\n\ncodegen 模块依赖于 logging 模块进行操作记录，并使用 browser 工具执行实际的浏览器操作。\n\n## 最佳实践\n\n1. **会话管理**：在完成操作录制后及时清理会话，避免内存泄漏\n2. **路径配置**：使用绝对路径或确保相对路径相对于工作区根目录\n3. **命名规范**：使用有意义的 `testNamePrefix` 以便识别生成的测试\n4. **注释保留**：在开发阶段保持 `includeComments: true` 以便理解生成的代码\n5. **工具命名**：注意 Cursor 等客户端对工具名称有 60 字符限制\n\n资料来源：[README.md:1-10]()\n\n## 相关文档\n\n- [HTTP 模式示例](../examples/http-mode-example.md)\n- [Docker 部署指南](./DOCKER.md)\n- [主要工具文档](./tools/README.md)\n\n---\n\n\n\n## HTTP/SSE 传输模式\n\n### 相关页面\n\n相关主题：[系统架构](#architecture), [客户端配置指南](#client-configuration), [Docker 容器化部署](#docker-deployment)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/http-server.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/http-server.ts)\n- [src/sse/server.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/sse/server.ts)\n- [src/sse/types.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/sse/types.ts)\n- [src/sse/index.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/sse/index.ts)\n- [examples/http-mode-example.md](https://github.com/executeautomation/mcp-playwright/blob/main/examples/http-mode-example.md)\n \n\n# HTTP/SSE 传输模式\n\n## 概述\n\nHTTP/SSE 传输模式是 Playwright MCP Server 在 1.0.7 版本中引入的一种独立 HTTP 服务器部署方式。该模式允许将传统的 stdio 通信方式替换为基于 HTTP 和 Server-Sent Events (SSE) 的网络传输架构，适用于在无显示环境的系统中运行有头浏览器、从 IDE 工作进程发起连接，或需要支持多个并发客户端的场景。\n\n此传输模式的核心价值在于将 MCP 协议适配到标准的 HTTP 协议栈上，使得客户端可以通过 RESTful API 与 MCP 服务器进行交互，同时利用 SSE 机制实现服务端向客户端的实时事件推送。\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TB\n subgraph \"MCP 客户端\"\n A[Claude Desktop / VS Code]\n B[自定义 HTTP 客户端]\n C[curl / Postman]\n end\n \n subgraph \"HTTP/SSE 服务器\"\n D[Express Server
端口: 8931]\n E[SSE 连接管理器]\n F[Session 管理器]\n G[请求日志中间件]\n end\n \n subgraph \"MCP Server Core\"\n H[工具处理器]\n I[浏览器工具集]\n J[Playwright 引擎]\n end\n \n A -->|\"HTTP POST /mcp\"| D\n B -->|\"HTTP POST /mcp\"| D\n C -->|\"HTTP GET /health\"| D\n D --> G\n G --> F\n F --> E\n E -.->|\"SSE Stream\"| A\n D --> H\n H --> I\n I --> J\n \n style D fill:#e1f5fe\n style E fill:#fff3e0\n style F fill:#e8f5e9\n```\n\n### 核心组件\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| HTTP Server | `src/http-server.ts` | 启动 Express 服务器，路由配置，端点暴露 |\n| SSE Server | `src/sse/server.ts` | 管理 SSE 连接，处理事件流推送 |\n| SSE Types | `src/sse/types.ts` | 定义 SSE 相关的数据类型和接口 |\n| Session Manager | 内置于 `http-server.ts` | 管理多会话生命周期，跟踪连接状态 |\n| 日志中间件 | `src/logging/middleware.ts` | 请求日志记录，错误分类，性能监控 |\n\n## 启动服务器\n\n### 基本启动命令\n\n```bash\n# 使用 npx 启动\nnpx @executeautomation/playwright-mcp-server --port 8931\n\n# 全局安装后启动\nnpm install -g @executeautomation/playwright-mcp-server\nplaywright-mcp-server --port 8931\n```\n\n服务器启动后会显示以下端点信息：\n\n```\n==============================================\nPlaywright MCP Server (HTTP Mode)\n==============================================\nPort: 8931\n\nENDPOINTS:\n- SSE Stream: GET http://localhost:8931/sse\n- Messages: POST http://localhost:8931/messages?sessionId=\n- MCP (unified): GET http://localhost:8931/mcp\n- MCP (unified): POST http://localhost:8931/mcp?sessionId=\n- Health Check: GET http://localhost:8931/health\n```\n\n资料来源：[examples/http-mode-example.md:1-20]()\n\n### 环境变量配置\n\n| 变量名 | 说明 | 默认值 |\n|--------|------|--------|\n| `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD` | 跳过浏览器下载 | `1` |\n| `OPENAI_API_KEY` | API 密钥（用于评估） | - |\n\n## API 端点详解\n\n### 健康检查端点\n\n```\nGET http://localhost:8931/health\n```\n\n用于验证服务器运行状态，返回服务器健康状态信息。\n\n```bash\ncurl http://localhost:8931/health\n```\n\n资料来源：[examples/http-mode-example.md:30]()\n\n### SSE 流端点\n\n```\nGET http://localhost:8931/sse\n```\n\n建立与服务端的 SSE 连接，接收服务端推送的事件流。适用于需要实时接收 MCP 工具执行结果或通知的场景。\n\n### 消息发送端点\n\n```\nPOST http://localhost:8931/messages?sessionId=\nContent-Type: application/json\n\n{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"playwright_navigate\",\n \"arguments\": { \"url\": \"https://example.com\" }\n }\n}\n```\n\n### 统一 MCP 端点\n\n```\nGET http://localhost:8931/mcp # 获取 MCP 连接配置\nPOST http://localhost:8931/mcp # 发送 MCP 请求\nPOST http://localhost:8931/mcp?sessionId= # 指定会话的 MCP 请求\n```\n\n统一端点将 SSE 流和消息发送合并为一个简洁的接口，是推荐使用的端点。\n\n## 客户端配置\n\n### Claude Desktop 配置\n\nClaude Desktop 目前需要使用 stdio 模式，不支持 HTTP 模式。如需远程访问，推荐通过 SSH 隧道方式连接。\n\n### 自定义客户端配置\n\n```json\n{\n \"mcpServers\": {\n \"playwright\": {\n \"url\": \"http://localhost:8931/mcp\"\n }\n }\n}\n```\n\n资料来源：[examples/http-mode-example.md:18-24]()\n\n## 会话管理\n\n### 会话生命周期\n\n```mermaid\nstateDiagram-v2\n [*] --> 创建会话: 首次连接\n 创建会话 --> 活跃: 开始通信\n 活跃 --> 活跃: 发送请求\n 活跃 --> 心跳: 空闲超时\n 心跳 --> 活跃: 收到消息\n 心跳 --> 关闭: 超时\n 活跃 --> 关闭: 客户端断开\n 关闭 --> [*]: 清理资源\n```\n\n### 会话标识\n\n每个客户端连接通过 `sessionId` 参数进行标识，支持多个客户端并发连接。服务器自动管理会话的创建、维护和销毁。\n\n## 安全特性\n\n### 本地绑定\n\n服务器默认绑定到 `127.0.0.1`（localhost），防止外部网络访问：\n\n> **安全说明**：服务器默认仅监听本地回环地址，这可以防止意外的网络暴露和未授权访问。\n\n资料来源：[README.md:40-45]()\n\n### SSH 隧道远程访问\n\n如需从远程机器访问，建议使用 SSH 隧道：\n\n```bash\nssh -L 8931:localhost:8931 user@server-host\n```\n\n这种方式可以在保持服务器本地绑定的同时，实现安全的远程访问。\n\n## 日志与监控\n\n### 请求日志中间件\n\n`src/logging/middleware.ts` 实现了完整的请求日志系统：\n\n| 功能 | 说明 |\n|------|------|\n| 请求 ID 生成 | 为每个请求分配唯一标识符 |\n| 执行时间记录 | 记录工具执行的开始和结束时间 |\n| 参数脱敏 | 自动移除敏感字段（password、token、secret、key、auth） |\n| 错误分类 | 将错误分为 validation、system、resource 等类别 |\n\n### 日志级别\n\n系统支持以下日志级别，按优先级从低到高：\n\n1. `debug` - 调试信息\n2. `info` - 一般信息\n3. `warn` - 警告信息\n4. `error` - 错误信息\n\n### 文件日志\n\n日志默认写入文件而非控制台，以保证 stdio 模式下的 JSON-RPC 通信不被干扰。日志文件位置：`~/playwright-mcp-server.log`\n\n## 错误处理\n\n### 错误分类系统\n\n| 类别 | 触发条件 | 示例消息 |\n|------|----------|----------|\n| `validation` | 参数验证失败 | invalid、validation、required |\n| `resource` | 资源不可用 | browser、page、connection、closed |\n| `authentication` | 认证授权问题 | unauthorized、forbidden、permission |\n| `rate_limit` | 速率限制 | rate limit、too many requests |\n| `system` | 系统级错误 | timeout、element、navigation |\n\n### 错误上下文捕获\n\n错误对象包含丰富的上下文信息：\n\n```typescript\n{\n errorName: string,\n errorMessage: string,\n stack: string,\n timestamp: ISO8601,\n nodeVersion: string,\n platform: string,\n arch: string,\n memoryUsage: object,\n uptime: number,\n toolName?: string,\n toolCategory?: string\n}\n```\n\n资料来源：[src/logging/middleware.ts:100-115]()\n\n## 部署场景\n\n### Docker 部署\n\n在 Docker 容器中运行时，HTTP 模式特别有用：\n\n```bash\ndocker run -i --rm \\\n -p 8931:8931 \\\n mcp-playwright:latest\n```\n\n容器内运行需要使用 `-i` 标志保持 STDIN 开放，以便 MCP 服务器正常工作。\n\n### Docker Compose 配置\n\n```yaml\nservices:\n playwright-mcp:\n image: mcp-playwright:latest\n ports:\n - \"8931:8931\"\n environment:\n - NODE_ENV=production\n healthcheck:\n test: [\"CMD\", \"curl\", \"-f\", \"http://localhost:8931/health\"]\n interval: 30s\n timeout: 10s\n retries: 3\n```\n\n### 资源限制\n\n```bash\ndocker run -i --rm \\\n --cpus=\"2.0\" \\\n --memory=\"2g\" \\\n -p 8931:8931 \\\n mcp-playwright:latest\n```\n\n## 与 Stdio 模式对比\n\n| 特性 | Stdio 模式 | HTTP/SSE 模式 |\n|------|------------|----------------|\n| 通信方式 | 标准输入/输出 | HTTP + SSE |\n| 多客户端 | 不支持 | 支持 |\n| 远程访问 | 不直接支持 | 支持（需 SSH 隧道） |\n| 健康检查 | 无 | 有（`/health`） |\n| Claude Desktop | 支持 | 不支持 |\n| VS Code | 支持 | 支持 |\n| 日志输出 | 文件 | 文件 + 可配置 |\n\n## 故障排除\n\n### 容器立即退出\n\nMCP 服务器需要通过 STDIN 接收输入。确保使用 `-i` 标志：\n\n```bash\ndocker run -i --rm mcp-playwright:latest\n```\n\n### 浏览器未找到\n\nDocker 镜像默认跳过浏览器下载以减小体积。如需预装浏览器，创建自定义 Dockerfile：\n\n```dockerfile\nFROM mcp-playwright:latest\nRUN npx playwright install chromium --with-deps\n```\n\n### 端口占用\n\n如果 8931 端口被占用，使用其他端口：\n\n```bash\nnpx @executeautomation/playwright-mcp-server --port 8932\n```\n\n## 版本历史\n\n| 版本 | 发布日期 | 主要变更 |\n|------|----------|----------|\n| 1.0.9 | 2025-12-09 | 修复 console 输出缓冲问题，使用 `process.stdout.write()` |\n| 1.0.8 | 2025-12-08 | 改善 HTTP 模式下控制台输出可见性 |\n| 1.0.7 | 2025-12-07 | 初始引入 HTTP/SSE 传输模式，多会话支持，健康检查 |\n\n资料来源：[CHANGELOG.md:1-25]()\n\n---\n\n\n\n## Docker 容器化部署\n\n### 相关页面\n\n相关主题：[HTTP/SSE 传输模式](#http-transport), [客户端配置指南](#client-configuration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [Dockerfile](https://github.com/executeautomation/mcp-playwright/blob/main/Dockerfile)\n- [docker-compose.yml](https://github.com/executeautomation/mcp-playwright/blob/main/docker-compose.yml)\n- [docker-build.sh](https://github.com/executeautomation/mcp-playwright/blob/main/docker-build.sh)\n- [DOCKER.md](https://github.com/executeautomation/mcp-playwright/blob/main/DOCKER.md)\n \n\n# Docker 容器化部署\n\n## 概述\n\nMCP Playwright 项目提供了完整的 Docker 容器化解决方案，使 Playwright MCP 服务器能够在隔离的容器环境中运行。该部署方案具有以下核心特性：\n\n- **隔离执行环境**：通过 Docker 容器提供一致的运行时环境\n- **简化依赖管理**：所有依赖在镜像构建时预装\n- **易于部署分发**：支持 Docker Compose 一键启动\n- **MCP 协议支持**：通过 stdio 或 HTTP 模式与 MCP 客户端通信\n\n资料来源：[DOCKER.md]()\n\n## 架构概览\n\n```mermaid\ngraph TD\n subgraph \"宿主机 (Host)\"\n A[MCP 客户端
Claude Desktop / VS Code]\n B[Docker 守护进程]\n end\n \n subgraph \"Docker 容器\"\n C[Node.js 运行环境]\n D[Playwright MCP Server
dist/index.js]\n E[Playwright 浏览器
Chromium/Firefox/WebKit]\n end\n \n A -->|JSON-RPC / HTTP| B\n B -->|docker run -i| C\n C --> D\n D -->|自动化控制| E\n \n F[本地文件系统] -.->|volume mount| C\n G[screenshots] -.->|volume mount| C\n```\n\n## 镜像构建\n\n### 前置条件\n\n在构建 Docker 镜像前，需要确保：\n\n1. 本地已安装 Docker ([Install Docker](https://docs.docker.com/get-docker/))\n2. 项目已通过 TypeScript 编译\n3. 已安装生产环境依赖\n\n### 构建流程\n\n```mermaid\ngraph LR\n A[npm install --omit=dev] --> B[npm run build]\n B --> C[生成 dist/ 和 node_modules/]\n C --> D[docker build -t mcp-playwright:latest .]\n D --> E[Docker 镜像创建完成]\n```\n\n### 使用构建脚本\n\n项目提供了便捷的构建脚本 `docker-build.sh`：\n\n```bash\nchmod +x docker-build.sh\n./docker-build.sh\n```\n\n该脚本会自动执行以下操作：\n\n1. 安装生产依赖 (`npm install --omit=dev`)\n2. 编译 TypeScript 代码 (`npm run build`)\n3. 构建 Docker 镜像\n\n### 手动构建\n\n手动构建需要分步执行：\n\n```bash\n# 1. 安装生产依赖并构建\nnpm install --omit=dev\nnpm run build\n\n# 2. 构建 Docker 镜像\ndocker build -t mcp-playwright:latest .\n\n# 3. 或指定版本标签\ndocker build -t mcp-playwright:1.0.6 .\n```\n\n**重要提示**：Dockerfile 会从本地构建目录复制 `node_modules` 和 `dist`，因此必须先安装 `--omit=dev` 标志的生产依赖，以保持镜像体积最小化。\n\n资料来源：[DOCKER.md:1-50]()\n\n## 容器运行模式\n\n### 标准模式 (stdio)\n\nstdio 模式是 **Claude Desktop 推荐的运行方式**。MCP 服务器通过标准输入输出与客户端通信：\n\n```bash\ndocker run -i --rm mcp-playwright:latest\n```\n\n| 参数 | 说明 |\n|------|------|\n| `-i` | 保持 STDIN 打开，支持交互式通信 |\n| `--rm` | 容器退出时自动删除 |\n| `mcp-playwright:latest` | 镜像名称和标签 |\n\n### Docker Compose 模式\n\n项目提供了 `docker-compose.yml` 配置文件：\n\n```bash\n# 启动服务\ndocker compose run --rm playwright-mcp\n\n# 或先构建后运行\ndocker compose build\ndocker compose run --rm playwright-mcp\n```\n\n`docker-compose.yml` 核心配置：\n\n| 配置项 | 值 | 说明 |\n|--------|-----|------|\n| `stdin_open` | true | 打开标准输入 |\n| `tty` | true | 分配伪终端 |\n| `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD` | 1 | 跳过浏览器下载 |\n\n资料来源：[docker-compose.yml]()\n\n## MCP 客户端集成\n\n### Claude Desktop 配置\n\n对于 Claude Desktop 用户，需要修改配置文件：\n\n**配置文件位置**：\n\n| 操作系统 | 路径 |\n|----------|------|\n| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Windows | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| Linux | `~/.config/Claude/claude_desktop_config.json` |\n\n**配置示例**：\n\n```json\n{\n \"mcpServers\": {\n \"playwright-docker\": {\n \"command\": \"docker\",\n \"args\": [\"run\", \"-i\", \"--rm\", \"mcp-playwright:latest\"]\n }\n }\n}\n```\n\n### VS Code MCP 扩展配置\n\n对于 VS Code MCP 扩展：\n\n```json\n{\n \"name\": \"playwright-docker\",\n \"command\": \"docker\",\n \"args\": [\"run\", \"-i\", \"--rm\", \"mcp-playwright:latest\"]\n}\n```\n\n## 环境变量配置\n\n| 变量名 | 说明 | 默认值 |\n|--------|------|--------|\n| `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD` | 跳过浏览器下载 | 未设置 |\n| `NODE_ENV` | Node.js 运行环境 | `production` |\n\n### 命令行设置环境变量\n\n```bash\ndocker run -i --rm \\\n -e PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 \\\n -e NODE_ENV=production \\\n mcp-playwright:latest\n```\n\n### docker-compose.yml 设置环境变量\n\n```yaml\nservices:\n playwright-mcp:\n environment:\n - PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1\n - NODE_ENV=production\n```\n\n资料来源：[DOCKER.md:50-80]()\n\n## 数据持久化\n\n### 卷挂载配置\n\n如需与容器共享文件或持久化数据，可使用 volume 挂载：\n\n```bash\ndocker run -i --rm \\\n -v $(pwd)/data:/app/data \\\n -v $(pwd)/screenshots:/app/screenshots \\\n mcp-playwright:latest\n```\n\n### docker-compose.yml 卷配置\n\n```yaml\nservices:\n playwright-mcp:\n volumes:\n - ./data:/app/data\n - ./screenshots:/app/screenshots\n```\n\n**注意**：挂载的目录路径必须是绝对路径或使用 `$(pwd)` 获取当前目录。\n\n## 故障排除\n\n### 容器立即退出\n\n**问题**：容器启动后立即退出\n\n**原因**：MCP 服务器需要通过 stdin 接收输入，未使用 `-i` 标志\n\n**解决方案**：\n\n```bash\n# 错误\ndocker run --rm mcp-playwright:latest\n\n# 正确\ndocker run -i --rm mcp-playwright:latest\n```\n\n### 浏览器未找到\n\n**问题**：运行时报错找不到浏览器\n\n**原因**：Docker 镜像默认跳过浏览器下载以减小体积\n\n**解决方案**：创建自定义 Dockerfile 预装浏览器\n\n```dockerfile\nFROM mcp-playwright:latest\n\n# 安装 Playwright 浏览器\nRUN npx playwright install chromium --with-deps\n```\n\n### 权限问题\n\n**问题**：挂载卷出现权限拒绝\n\n**解决方案**：以指定用户身份运行\n\n```bash\ndocker run -i --rm \\\n -v $(pwd)/data:/app/data \\\n --user $(id -u):$(id -g) \\\n mcp-playwright:latest\n```\n\n资料来源：[DOCKER.md:100-130]()\n\n## 高级配置\n\n### 资源限制\n\n```bash\ndocker run -i --rm \\\n --cpus=\"2.0\" \\\n --memory=\"2g\" \\\n mcp-playwright:latest\n```\n\n### docker-compose.yml 资源限制配置\n\n```yaml\nservices:\n playwright-mcp:\n deploy:\n resources:\n limits:\n cpus: '2.0'\n memory: 2G\n```\n\n### 健康检查配置\n\n```yaml\nservices:\n playwright-mcp:\n healthcheck:\n test: [\"CMD\", \"node\", \"-e\", \"process.exit(0)\"]\n interval: 30s\n timeout: 10s\n retries: 3\n```\n\n### 自定义网络配置\n\n```bash\n# 创建网络\ndocker network create mcp-network\n\n# 在指定网络中运行\ndocker run -i --rm --network mcp-network mcp-playwright:latest\n```\n\n## 从源码构建 Docker 镜像\n\n如果希望完全在 Docker 内构建（不使用本地预编译的 dist）：\n\n```dockerfile\nFROM node:20-alpine AS builder\n\nWORKDIR /app\nCOPY package*.json ./\nENV PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1\nRUN npm ci\n\nCOPY src ./src\nCOPY tsconfig.json ./\nRUN npm run build\n\nFROM node:20-alpine\nWORKDIR /app\nCOPY --from=builder /app/dist ./dist\nCOPY --from=builder /app/package*.json ./\nRUN npm ci --only=production\nCMD [\"node\", \"dist/index.js\"]\n```\n\n此多阶段构建方式：\n\n1. **Builder 阶段**：安装依赖并编译 TypeScript\n2. **Runtime 阶段**：仅复制生产文件，减小镜像体积\n\n## 安全最佳实践\n\n### 以非 root 用户运行\n\n```dockerfile\nFROM mcp-playwright:latest\nUSER node\n```\n\n### 只读根文件系统\n\n```bash\ndocker run -i --rm --read-only mcp-playwright:latest\n```\n\n### 安全扫描\n\n```bash\ndocker scan mcp-playwright:latest\n```\n\n## 镜像优化\n\n当前 Dockerfile 优化策略：\n\n| 优化项 | 说明 |\n|--------|------|\n| 基础镜像 | Debian-based slim Node.js (~200MB) |\n| 复制策略 | 复制预编译的 dist 目录 |\n| 依赖策略 | 仅安装生产依赖 |\n| 浏览器 | 默认跳过下载 |\n\n**当前镜像大小**：约 200MB（不含浏览器）\n\n资料来源：[DOCKER.md:180-200]()\n\n## 快速入门命令汇总\n\n```bash\n# 1. 克隆项目\ngit clone https://github.com/executeautomation/mcp-playwright.git\ncd mcp-playwright\n\n# 2. 构建镜像\n./docker-build.sh\n\n# 3. 测试运行\ndocker run -i --rm mcp-playwright:latest\n\n# 4. 配置 Claude Desktop\n# 编辑 ~/.config/Claude/claude_desktop_config.json\n\n# 5. 重启客户端服务\n# 重启 Claude Desktop 使配置生效\n```\n\n## 相关信息\n\n- **项目地址**：[executeautomation/mcp-playwright](https://github.com/executeautomation/mcp-playwright)\n- **问题反馈**：[GitHub Issues](https://github.com/executeautomation/mcp-playwright/issues)（请添加 `docker` 标签）\n- **标准模式部署**：请参阅 [README.md](./README.md) 了解 stdio 模式配置\n- **HTTP 模式部署**：请参阅 [examples/http-mode-example.md](./examples/http-mode-example.md) 了解独立服务器部署\n\n---\n\n\n\n## 客户端配置指南\n\n### 相关页面\n\n相关主题：[快速入门指南](#getting-started), [HTTP/SSE 传输模式](#http-transport), [Docker 容器化部署](#docker-deployment)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/executeautomation/mcp-playwright/blob/main/README.md)\n- [DOCKER.md](https://github.com/executeautomation/mcp-playwright/blob/main/DOCKER.md)\n- [examples/http-mode-example.md](https://github.com/executeautomation/mcp-playwright/blob/main/examples/http-mode-example.md)\n- [src/http-server.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/http-server.ts)\n- [package.json](https://github.com/executeautomation/mcp-playwright/blob/main/package.json)\n \n\n# 客户端配置指南\n\n## 概述\n\nPlaywright MCP Server 支持多种客户端配置方式，以满足不同开发环境和部署场景的需求。本指南涵盖 **stdio 模式**（Claude Desktop 等）、**HTTP 模式**（VS Code、自定义客户端等）以及 **Docker 部署**的完整配置说明。\n\n## 架构概览\n\n```mermaid\ngraph TD\n A[MCP 客户端] --> B{通信模式}\n B -->|stdio| C[标准输入输出]\n B -->|HTTP| D[SSE/Messages 端点]\n \n C --> E[playwright-mcp-server]\n D --> E\n \n E --> F[Playwright 浏览器]\n F --> G[自动化操作]\n \n H[日志文件] -.->|~/playwright-mcp-server.log| E\n```\n\n## Stdio 模式配置\n\nStdio 模式是 MCP 协议的默认通信方式，适用于 Claude Desktop 等支持标准输入输出的客户端。\n\n### Claude Desktop 配置\n\n**配置文件位置：**\n\n| 操作系统 | 配置文件路径 |\n|---------|------------|\n| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Windows | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| Linux | `~/.config/Claude/claude_desktop_config.json` |\n\n**配置示例：**\n\n```json\n{\n \"mcpServers\": {\n \"playwright\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@executeautomation/playwright-mcp-server\"]\n }\n }\n}\n```\n\n资料来源：[README.md:1-15]()\n\n**注意事项：**\n\n- stdio 模式下，日志自动重定向到文件而非控制台，以保持 JSON-RPC 通信的纯净性\n- 日志文件位置：`~/playwright-mcp-server.log` 资料来源：[README.md:18]()\n\n### Cline 与 Cursor 配置\n\n对于 Cline 和 Cursor 等编辑器插件，工具名称长度限制为 60 字符（`server_name:tool_name`）。由于服务器名称为 `playwright-mcp`，请确保自定义工具名称不超过 40 字符。 资料来源：[README.md:5-10]()\n\n## HTTP 模式配置\n\nHTTP 模式适用于无显示环境（如 headless 系统）或 IDE 工作进程中的有头浏览器运行场景。\n\n### 服务器启动\n\n```bash\n# 使用 npx 启动\nnpx @executeautomation/playwright-mcp-server --port 8931\n\n# 全局安装后启动\nnpm install -g @executeautomation/playwright-mcp-server\nplaywright-mcp-server --port 8931\n```\n\n资料来源：[README.md:22-27]()\n\n### 端点说明\n\n| 端点类型 | 方法 | URL 格式 | 用途 |\n|---------|------|---------|------|\n| SSE 流 | GET | `http://localhost:8931/sse` | 服务器发送事件流 |\n| 消息 | POST | `http://localhost:8931/messages?sessionId=` | 发送消息 |\n| MCP 统一 | GET/POST | `http://localhost:8931/mcp` | 统一 MCP 接口 |\n| 健康检查 | GET | `http://localhost:8931/health` | 服务状态检查 |\n\n资料来源：[src/http-server.ts:1-50]()\n\n### HTTP 服务器安全配置\n\n服务器默认绑定到 `127.0.0.1`（localhost），防止外部网络访问：\n\n```mermaid\ngraph LR\n A[客户端] -->|localhost| B[127.0.0.1:8931]\n C[外部请求] -.->|✗ 已阻止| B\n```\n\n资料来源：[src/http-server.ts:35-36]()\n\n### Claude Desktop HTTP 配置\n\n```json\n{\n \"mcpServers\": {\n \"playwright\": {\n \"url\": \"http://localhost:8931/mcp\"\n }\n }\n}\n```\n\n资料来源：[examples/http-mode-example.md:1-15]()\n\n### 健康检查\n\n```bash\ncurl http://localhost:8931/health\n```\n\n响应示例：\n\n```json\n{\n \"status\": \"ok\",\n \"version\": \"1.x.x\",\n \"activeSessions\": 0\n}\n```\n\n## Docker 部署配置\n\n### Docker 运行\n\n**基本命令：**\n\n```bash\ndocker run -i --rm mcp-playwright:latest\n```\n\n参数说明：\n\n| 参数 | 作用 |\n|-----|------|\n| `-i` | 保持 STDIN 打开，支持交互式通信 |\n| `--rm` | 容器退出时自动删除 |\n| `mcp-playwright:latest` | 镜像名称和标签 |\n\n资料来源：[DOCKER.md:40-50]()\n\n**Docker Compose 配置：**\n\n```yaml\nservices:\n playwright-mcp:\n image: mcp-playwright:latest\n```\n\n启动命令：\n\n```bash\n# 启动服务\ndocker compose run --rm playwright-mcp\n\n# 构建并运行\ndocker compose build\ndocker compose run --rm playwright-mcp\n```\n\n### Docker 客户端配置\n\n**Claude Desktop Docker 配置：**\n\n```json\n{\n \"mcpServers\": {\n \"playwright-docker\": {\n \"command\": \"docker\",\n \"args\": [\"run\", \"-i\", \"--rm\", \"mcp-playwright:latest\"]\n }\n }\n}\n```\n\n资料来源：[DOCKER.md:10-20]()\n\n**VS Code MCP Extension 配置：**\n\n```json\n{\n \"name\": \"playwright-docker\",\n \"command\": \"docker\",\n \"args\": [\"run\", \"-i\", \"--rm\", \"mcp-playwright:latest\"]\n}\n```\n\n资料来源：[DOCKER.md:22-28]()\n\n## 环境变量配置\n\n### Docker 环境变量\n\n通过 `-e` 参数传递环境变量：\n\n```bash\ndocker run -i --rm \\\n -e PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 \\\n -e NODE_ENV=production \\\n mcp-playwright:latest\n```\n\n**常用环境变量：**\n\n| 变量名 | 默认值 | 说明 |\n|-------|-------|------|\n| `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD` | 未设置 | 设为 `1` 跳过浏览器下载 |\n| `NODE_ENV` | `production` | Node.js 运行环境 |\n\n资料来源：[DOCKER.md:30-45]()\n\n### Docker Compose 环境变量\n\n```yaml\nservices:\n playwright-mcp:\n environment:\n - PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1\n - NODE_ENV=production\n```\n\n## 存储卷挂载\n\n### 数据持久化\n\n```bash\ndocker run -i --rm \\\n -v $(pwd)/data:/app/data \\\n -v $(pwd)/screenshots:/app/screenshots \\\n mcp-playwright:latest\n```\n\n### Docker Compose 卷配置\n\n```yaml\nservices:\n playwright-mcp:\n volumes:\n - ./data:/app/data\n - ./screenshots:/app/screenshots\n```\n\n资料来源：[DOCKER.md:48-55]()\n\n## 高级配置\n\n### 资源限制\n\n```bash\ndocker run -i --rm \\\n --cpus=\"2.0\" \\\n --memory=\"2g\" \\\n mcp-playwright:latest\n```\n\nDocker Compose 配置：\n\n```yaml\nservices:\n playwright-mcp:\n deploy:\n resources:\n limits:\n cpus: '2.0'\n memory: 2G\n```\n\n资料来源：[DOCKER.md:130-140]()\n\n### 自定义网络\n\n```bash\ndocker network create mcp-network\ndocker run -i --rm --network mcp-network mcp-playwright:latest\n```\n\n### 用户权限配置\n\n解决挂载卷权限问题：\n\n```bash\ndocker run -i --rm \\\n -v $(pwd)/data:/app/data \\\n --user $(id -u):$(id -g) \\\n mcp-playwright:latest\n```\n\n### 健康检查配置\n\n```yaml\nservices:\n playwright-mcp:\n healthcheck:\n test: [\"CMD\", \"node\", \"-e\", \"process.exit(0)\"]\n interval: 30s\n timeout: 10s\n retries: 3\n```\n\n## 故障排查\n\n### 容器立即退出\n\n**问题原因：** MCP 服务器需要通过 stdin 接收输入。\n\n**解决方案：** 确保使用 `-i` 参数：\n\n```bash\ndocker run -i --rm mcp-playwright:latest\n```\n\n资料来源：[DOCKER.md:60-65]()\n\n### 浏览器未找到\n\nDocker 镜像默认跳过浏览器下载以减小体积。首次使用时 Playwright 会自动下载浏览器。\n\n**预安装浏览器（自定义 Dockerfile）：**\n\n```dockerfile\nFROM mcp-playwright:latest\n\n# 安装 Playwright 浏览器\nRUN npx playwright install chromium --with-deps\n```\n\n资料来源：[DOCKER.md:70-75]()\n\n## 完整配置示例\n\n### 最小化配置（Stdio 模式）\n\n```json\n{\n \"mcpServers\": {\n \"playwright\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@executeautomation/playwright-mcp-server\"]\n }\n }\n}\n```\n\n### 生产环境配置（HTTP 模式）\n\n```json\n{\n \"mcpServers\": {\n \"playwright\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"-i\",\n \"--rm\",\n \"--cpus=2.0\",\n \"--memory=2g\",\n \"-e\", \"NODE_ENV=production\",\n \"mcp-playwright:latest\"\n ]\n }\n }\n}\n```\n\n### Docker Compose 完整配置\n\n```yaml\nservices:\n playwright-mcp:\n image: mcp-playwright:latest\n environment:\n - PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1\n - NODE_ENV=production\n volumes:\n - ./data:/app/data\n - ./screenshots:/app/screenshots\n deploy:\n resources:\n limits:\n cpus: '2.0'\n memory: 2G\n healthcheck:\n test: [\"CMD\", \"node\", \"-e\", \"process.exit(0)\"]\n interval: 30s\n timeout: 10s\n retries: 3\n```\n\n## 版本信息\n\n当前稳定版本参考 [CHANGELOG.md](https://github.com/executeautomation/mcp-playwright/blob/main/CHANGELOG.md)：\n\n| 版本 | 发布日期 | 主要特性 |\n|-----|---------|---------|\n| 1.0.2 | 2024-11-10 | 多浏览器支持（Chromium、Firefox、WebKit） |\n| 1.0.0 | 2024-11-01 | 首个主要版本，重构工具结构 |\n\n**依赖版本：**\n\n| 包名 | 版本 |\n|-----|------|\n| `@modelcontextprotocol/sdk` | 1.24.3 |\n| `playwright` | 1.57.0 |\n| `@playwright/browser-chromium` | 1.57.0 |\n\n资料来源：[package.json:1-30]()\n\n---\n\n\n\n## 日志与监控\n\n### 相关页面\n\n相关主题：[系统架构](#architecture), [故障排除指南](#troubleshooting)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/logging/index.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/index.ts)\n- [src/logging/logger.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/logger.ts)\n- [src/logging/middleware.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/middleware.ts)\n- [src/logging/types.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/types.ts)\n- [src/monitoring/index.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/monitoring/index.ts)\n- [src/monitoring/system.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/monitoring/system.ts)\n- [src/rate-limiting/index.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/rate-limiting/index.ts)\n- [src/rate-limiting/limiter.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/rate-limiting/limiter.ts)\n \n\n# 日志与监控\n\n## 概述\n\nmcp-playwright 的日志与监控系统为 MCP 服务器提供了一套完整的请求追踪、错误分类和系统健康监测能力。该系统通过统一的日志记录层捕获所有工具调用请求、响应状态和错误信息，同时结合健康检查机制确保服务稳定运行。\n\n核心功能包括：\n\n- **请求日志记录**：追踪所有工具调用的生命周期\n- **错误分类与增强上下文**：自动识别错误类型并收集诊断信息\n- **敏感数据脱敏**：防止日志中泄露密码、Token 等敏感信息\n- **系统健康监控**：实时监测 CPU、内存、错误率等关键指标\n- **日志轮转**：自动管理日志文件大小和数量\n\n## 架构设计\n\n### 系统组件关系\n\n```mermaid\ngraph TD\n A[MCP 客户端请求] --> B[LoggingMiddleware]\n B --> C[Logger]\n B --> D[MonitoringSystem]\n B --> E[工具处理器]\n C --> F[文件日志]\n D --> G[健康检查端点]\n E --> H[Response]\n B --> I[错误处理]\n I --> C\n D --> J[Rate Limiter]\n```\n\n### 日志层级\n\n| 级别 | 用途 | 日志方法 |\n|------|------|----------|\n| debug | 调试信息，仅开发环境使用 | `logger.debug()` |\n| info | 常规操作记录 | `logger.info()` |\n| warn | 警告信息，需要关注但非致命 | `logger.warn()` |\n| error | 错误信息，记录异常和堆栈 | `logger.error()` |\n\n日志级别通过配置控制，低于配置级别的日志不会输出。 资料来源：[src/logging/logger.ts:156-162]()\n\n## 日志系统\n\n### Logger 核心功能\n\nLogger 是日志系统的核心组件，支持以下功能：\n\n| 功能 | 描述 | 配置项 |\n|------|------|--------|\n| 文件输出 | 写入本地日志文件 | `filePath`, `maxFileSize` |\n| 日志轮转 | 自动管理日志文件数量 | `maxFiles` |\n| 级别控制 | 按级别过滤日志 | `level` |\n| 请求上下文 | 记录请求相关详细信息 | `RequestLogContext` |\n| 错误增强 | 附带错误对象信息 | `ErrorLogContext` |\n\n资料来源：[src/logging/logger.ts:1-60]()\n\n### 日志格式化\n\n每条日志条目包含以下结构化数据：\n\n```typescript\ninterface LogEntry {\n timestamp: string; // ISO 8601 格式时间戳\n level: 'debug' | 'info' | 'warn' | 'error';\n message: string; // 日志消息\n requestId?: string; // 请求唯一标识\n context?: Record; // 附加上下文\n}\n```\n\n### 请求日志上下文\n\n```typescript\ninterface RequestLogContext {\n method: string; // HTTP 方法或工具调用类型\n url?: string; // 请求路径或工具名称\n body?: any; // 请求体（已脱敏）\n statusCode?: number; // 响应状态码\n duration?: number; // 处理时长（毫秒）\n userAgent?: string; // 客户端标识\n clientIp?: string; // 客户端 IP\n}\n```\n\n资料来源：[src/logging/middleware.ts:1-40]()\n\n## 中间件层\n\n### LoggingMiddleware 工作流程\n\nLoggingMiddleware 拦截所有 MCP 请求，提供统一的日志记录和错误处理能力：\n\n```mermaid\nsequenceDiagram\n participant Client as MCP 客户端\n participant Middleware as LoggingMiddleware\n participant Logger as Logger\n participant Handler as 工具处理器\n participant Monitoring as MonitoringSystem\n\n Client->>Middleware: 工具调用请求\n Middleware->>Logger: logRequest() - 请求开始\n Middleware->>Handler: 执行工具处理\n Handler-->>Middleware: 处理结果\n alt 成功响应\n Middleware->>Logger: logRequest() - 请求成功\n else 错误响应\n Middleware->>Middleware: captureErrorContext()\n Middleware->>Logger: warn() - 请求错误\n end\n Middleware->>Monitoring: recordRequest()\n Middleware-->>Client: 返回响应\n```\n\n### 错误分类\n\n中间件能够自动识别并分类错误类型：\n\n| 错误类别 | 触发条件 | 示例 |\n|----------|----------|------|\n| validation | 包含 invalid、validation、required 等关键词 | 参数校验失败 |\n| resource | 浏览器断开、页面关闭、协议错误 | 浏览器未启动 |\n| authentication | 未授权、禁止访问、权限问题 | Token 无效 |\n| rate_limit | 速率限制、请求过多 | 请求频率超限 |\n| system | 超时、元素未找到、导航失败 | 元素等待超时 |\n| unknown | 无法归类的其他错误 | 未知异常 |\n\n资料来源：[src/logging/middleware.ts:80-110]()\n\n### 错误上下文捕获\n\n```typescript\ninterface ErrorContext {\n errorName: string; // 错误类型名称\n errorMessage: string; // 错误消息\n stack?: string; // 堆栈跟踪\n timestamp: string; // 错误发生时间\n nodeVersion: string; // Node.js 版本\n platform: string; // 操作系统平台\n arch: string; // CPU 架构\n memoryUsage: object; // 内存使用情况\n uptime: number; // 进程运行时间\n toolName?: string; // 调用的工具名称\n toolCategory?: string; // 工具分类\n}\n```\n\n资料来源：[src/logging/middleware.ts:120-145]()\n\n## 敏感数据保护\n\n### 脱敏策略\n\n日志中间件包含智能数据脱敏功能，防止敏感信息泄露：\n\n| 数据类型 | 脱敏规则 | 示例 |\n|----------|----------|------|\n| 密码字段 | 替换为 `[REDACTED]` | `password: \"***\"` |\n| Token 字段 | 替换为 `[REDACTED]` | `token: \"***\"` |\n| Secret 字段 | 替换为 `[REDACTED]` | `secret: \"***\"` |\n| Key 字段 | 替换为 `[REDACTED]` | `apiKey: \"***\"` |\n| Auth 字段 | 替换为 `[REDACTED]` | `auth: \"***\"` |\n| 长请求体 | 截断并标注长度 | `[TRUNCATED:5000chars]` |\n\n资料来源：[src/logging/middleware.ts:160-180]()\n\n### 工具参数过滤\n\n```typescript\nprivate sanitizeToolArgs(toolName: string, args: any): any {\n // 检测包含敏感关键词的参数\n const sensitiveFields = ['password', 'token', 'secret', 'key', 'auth'];\n // 将敏感字段值替换为 [REDACTED]\n}\n```\n\n## 监控系统\n\n### HealthStatus 系统状态\n\n系统健康状态包含多个检查项：\n\n| 检查项 | 指标 | 阈值 | 状态 |\n|--------|------|------|------|\n| CPU | 使用率 | >80% 警告, >90% 失败 | pass/warn/fail |\n| Memory | 使用率 | >80% 警告, >90% 失败 | pass/warn/fail |\n| Error Rate | 错误率 | >1% 警告, >5% 失败 | pass/warn/fail |\n\n资料来源：[src/monitoring/system.ts:80-120]()\n\n### 健康状态响应格式\n\n```typescript\ninterface HealthStatus {\n status: 'healthy' | 'degraded' | 'unhealthy';\n checks: {\n [key: string]: {\n status: 'pass' | 'warn' | 'fail';\n description: string;\n data: Record;\n };\n };\n timestamp: number;\n version: string;\n}\n```\n\n### 指标收集\n\n监控系统持续收集以下指标：\n\n- **请求计数**：总请求数、成功/失败数\n- **响应时长**：平均、最小、最大响应时间\n- **错误分类统计**：按错误类型分类的错误计数\n- **系统资源**：CPU、内存使用率\n- **分类指标**：按工具分类的请求统计\n\n资料来源：[src/monitoring/system.ts:1-50]()\n\n### HTTP 健康检查服务器\n\n监控系统可启动独立的 HTTP 服务器提供健康检查端点：\n\n```typescript\nasync startMetricsCollection(port: number = 3001): Promise {\n // 启动 HTTP 服务器用于健康检查\n await this.startHttpServer(port);\n}\n```\n\n## 日志输出模式\n\n### STDIO 模式\n\n在标准 MCP stdio 通信模式下，日志自动写入文件而非控制台：\n\n> 日志会自动定向到文件（而非控制台），以保持 JSON-RPC 通信的清洁性。\n\n日志文件位置：`~/playwright-mcp-server.log`\n\n资料来源：[README.md:1-30]()\n\n### HTTP 模式\n\n在 HTTP 服务模式下，可通过以下端点访问：\n\n```\nGET /health - 健康检查端点\nGET /sse - SSE 流式端点\nPOST /messages - 消息处理端点\nGET /mcp - MCP 统一端点\n```\n\n资料来源：[examples/http-mode-example.md:1-30]()\n\n## 日志文件管理\n\n### 日志轮转机制\n\nLogger 实现自动日志轮转功能：\n\n1. **大小检查**：每次写入前检查当前文件大小\n2. **阈值触发**：超过 `maxFileSize` 触发轮转\n3. **文件重命名**：当前日志文件重命名为 `.1` 后缀\n4. **序号递进**：现有轮转文件序号递增（`.1` → `.2` → ...）\n5. **旧文件清理**：超过 `maxFiles` 数量的最旧文件被删除\n\n```mermaid\ngraph LR\n A[app.log] -->|超过 10MB| B[app.log.1]\n B -->|再次轮转| C[app.log.2]\n C -->|再次轮转| D[app.log.3]\n D -->|超过最大数量| X[删除]\n```\n\n资料来源：[src/logging/logger.ts:100-140]()\n\n## 集成使用\n\n### 请求处理中的集成\n\n日志和监控系统通过 `wrapWithMonitoring` 包装器集成到请求处理流程中：\n\n```typescript\nconst wrapWithMonitoring = (\n fn: T,\n category: string\n): T => {\n return (async (...args: any[]) => {\n const startTime = Date.now();\n let success = true;\n \n try {\n const result = await fn(...args);\n // 记录成功指标\n monitoringSystem.recordRequest(duration, true, category);\n return result;\n } catch (error) {\n // 记录失败指标\n monitoringSystem.recordRequest(duration, false, category);\n throw error;\n }\n }) as T;\n};\n```\n\n资料来源：[src/requestHandler.ts:1-50]()\n\n### 资源暴露\n\n日志系统通过 MCP 资源机制暴露以下信息：\n\n| 资源 URI | 类型 | 内容 |\n|----------|------|------|\n| `console://logs` | text/plain | 浏览器控制台日志 |\n| `screenshot://{name}` | image/png | 已存储的截图 |\n\n```typescript\nconst resources = [\n {\n uri: \"console://logs\",\n mimeType: \"text/plain\",\n name: \"Browser console logs\",\n },\n ...Array.from(getScreenshots().keys()).map(name => ({\n uri: `screenshot://${name}`,\n mimeType: \"image/png\",\n name: `Screenshot: ${name}`,\n })),\n];\n```\n\n资料来源：[src/requestHandler.ts:60-80]()\n\n## 配置参考\n\n### 日志配置\n\n```typescript\ninterface LoggerConfig {\n level: 'debug' | 'info' | 'warn' | 'error'; // 日志级别\n filePath: string; // 日志文件路径\n maxFileSize: number; // 单文件最大大小（字节）\n maxFiles: number; // 保留的最大文件数\n console?: boolean; // 是否输出到控制台\n}\n```\n\n### 监控配置\n\n```typescript\ninterface MonitoringConfig {\n enabled: boolean; // 是否启用监控\n metricsInterval: number; // 指标收集间隔（毫秒）\n healthCheckInterval: number; // 健康检查间隔（毫秒）\n}\n```\n\n## 总结\n\nmcp-playwright 的日志与监控系统提供了企业级的可观测性能力：\n\n- **统一日志层**：通过 LoggingMiddleware 拦截所有请求，提供一致的日志格式和错误处理\n- **智能错误分类**：自动识别错误类型并收集丰富的诊断上下文\n- **敏感数据保护**：内置敏感字段脱敏，防止日志泄露\n- **健康监测**：实时监控系统资源和错误率，及时发现服务异常\n- **日志轮转**：自动管理日志文件，避免磁盘空间问题\n\n这套系统确保了 MCP 服务器在生产环境中的可维护性和问题可追溯性。\n\n---\n\n\n\n## 故障排除指南\n\n### 相关页面\n\n相关主题：[Docker 容器化部署](#docker-deployment), [日志与监控](#logging-monitoring), [客户端配置指南](#client-configuration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [DOCKER.md](https://github.com/executeautomation/mcp-playwright/blob/main/DOCKER.md)\n- [README.md](https://github.com/executeautomation/mcp-playwright/blob/main/README.md)\n- [src/logging/middleware.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/middleware.ts)\n- [src/logging/logger.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/logging/logger.ts)\n- [src/http-server.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/http-server.ts)\n- [src/tools/browser/screenshot.ts](https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/browser/screenshot.ts)\n- [package.json](https://github.com/executeautomation/mcp-playwright/blob/main/package.json)\n \n\n# 故障排除指南\n\n本文档提供 mcp-playwright 项目的完整故障排除指南，帮助开发者诊断和解决常见问题。\n\n## 概述\n\nmcp-playwright 是一个基于 Playwright 的 MCP（Model Context Protocol）服务器，为 AI 助手提供浏览器自动化能力。故障排除系统采用多层次错误分类机制，能够自动识别和归类不同类型的错误。 资料来源：[src/logging/middleware.ts:1-50]()\n\n### 错误分类体系\n\n系统支持以下错误类别分类：\n\n| 错误类别 | 触发条件 | 处理建议 |\n|---------|---------|---------|\n| validation | 包含 invalid、validation、required、missing parameter | 检查参数格式和必填项 |\n| resource | 浏览器关闭、连接断开、协议错误 | 重启浏览器会话 |\n| system | 超时、元素未找到、导航失败 | 等待元素加载或重试操作 |\n| authentication | 未经授权、权限拒绝 | 检查认证信息 |\n| rate_limit | 请求过多、限流 | 降低请求频率 |\n\n 资料来源：[src/logging/middleware.ts:100-150]()\n\n## 常见问题与解决方案\n\n### 1. 服务器启动问题\n\n#### 1.1 服务无法启动\n\n**症状表现**：\n\n- 终端无响应或报错退出\n- 端口 8931 被占用\n- 连接被拒绝\n\n**诊断步骤**：\n\n```bash\n# 检查端口占用情况\nnetstat -an | grep 8931\n\n# Windows\nnetstat -ano | findstr 8931\n```\n\n**解决方案**：\n\n1. 确认端口 8931 未被其他进程占用\n2. 使用 `--port` 参数指定其他端口\n3. 检查配置文件中的 URL 配置是否正确\n\n 资料来源：[src/http-server.ts:1-30]()\n\n#### 1.2 HTTP 模式安全限制\n\n**重要说明**：HTTP 服务器默认绑定到 `127.0.0.1`（localhost）以确保安全，外部网络无法直接访问。\n\n```typescript\n// 安全绑定配置\nconst host = '127.0.0.1';\nconst httpServer = app.listen(port, host, () => {\n // 服务器仅接受本地连接\n});\n```\n\n**远程访问方案**：使用 SSH 隧道连接远程服务器\n\n```bash\nssh -L 8931:localhost:8931 user@remote-server\n```\n\n 资料来源：[src/http-server.ts:50-70]()\n\n### 2. Docker 相关问题\n\n#### 2.1 容器立即退出\n\n**症状**：容器启动后立即退出\n\n**原因**：MCP 服务器需要通过 stdin/stdout 进行通信，缺少必要的交互参数\n\n**解决方案**：使用 `-i` 参数保持标准输入打开\n\n```bash\ndocker run -i --rm mcp-playwright:latest\n```\n\n| 参数 | 作用 |\n|-----|------|\n| `-i` | 保持 STDIN 打开以支持交互通信 |\n| `--rm` | 容器退出时自动删除 |\n| `-v` | 挂载卷以持久化数据 |\n\n 资料来源：[DOCKER.md:1-50]()\n\n#### 2.2 浏览器未找到\n\n**症状**：`Browser not found` 或浏览器下载失败\n\n**原因**：Docker 镜像默认跳过浏览器下载以减小体积\n\n**解决方案**：创建自定义 Dockerfile 预安装浏览器\n\n```dockerfile\nFROM mcp-playwright:latest\n\n# 安装 Playwright 浏览器\nRUN npx playwright install chromium --with-deps\n```\n\n或者设置环境变量跳过浏览器下载检查：\n\n```bash\ndocker run -i --rm \\\n -e PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 \\\n mcp-playwright:latest\n```\n\n 资料来源：[DOCKER.md:60-80]()\n\n#### 2.3 挂载卷权限问题\n\n**症状**：容器内无法读写挂载的目录\n\n**解决方案**：使用 `--user` 参数指定用户身份\n\n```bash\ndocker run -i --rm \\\n -v $(pwd)/data:/app/data \\\n --user $(id -u):$(id -g) \\\n mcp-playwright:latest\n```\n\n 资料来源：[DOCKER.md:85-95]()\n\n### 3. 浏览器相关问题\n\n#### 3.1 浏览器自动安装\n\n系统支持浏览器自动安装，首次使用时自动检测并下载缺失的浏览器二进制文件：\n\n```mermaid\ngraph TD\n A[启动服务器] --> B{检测浏览器}\n B -->|浏览器缺失| C[自动下载安装]\n B -->|浏览器存在| D[继续执行]\n C --> E[显示安装进度]\n E --> D\n```\n\n**手动安装命令**：\n\n```bash\n# 安装所有浏览器\nnpx playwright install\n\n# 安装特定浏览器\nnpx playwright install chromium\nnpx playwright install firefox\nnpx playwright install webkit\n```\n\n**浏览器存储位置**：\n\n| 操作系统 | 存储路径 |\n|---------|---------|\n| Windows | `%USERPROFILE%\\AppData\\Local\\ms-playwright` |\n| macOS | `~/Library/Caches/ms-playwright` |\n| Linux | `~/.cache/ms-playwright` |\n\n 资料来源：[README.md:100-130]()\n\n#### 3.2 浏览器连接断开\n\n**症状**：`Target page, context or browser has been closed`\n\n**错误分类**：`resource` 类型错误\n\n**解决方案**：\n\n1. 检查浏览器实例是否正常启动\n2. 避免在页面加载完成前执行操作\n3. 使用适当的等待策略\n\n```typescript\n// 浏览器上下文捕获示例\nprivate captureBrowserContext(error: Error): Record {\n const context: Record = {};\n const message = error.message.toLowerCase();\n\n if (message.includes('closed') || message.includes('disconnected')) {\n context.browserState = 'disconnected';\n } else if (message.includes('timeout')) {\n context.browserState = 'timeout';\n } else if (message.includes('navigation')) {\n context.browserState = 'navigation_error';\n }\n\n return context;\n}\n```\n\n 资料来源：[src/logging/middleware.ts:150-200]()\n\n### 4. 工具执行问题\n\n#### 4.1 日志输出配置\n\n在 stdio 模式下，日志自动写入文件而非控制台，以保持 JSON-RPC 通信的清洁性。\n\n**日志文件位置**：`~/playwright-mcp-server.log`\n\n```mermaid\ngraph LR\n A[stdio 模式] --> B[日志写入文件]\n C[HTTP 模式] --> D[日志输出控制台]\n B --> E[~/playwright-mcp-server.log]\n```\n\n 资料来源：[README.md:50-60]()\n\n#### 4.2 工具执行流程监控\n\n系统提供完整的工具执行日志记录：\n\n```mermaid\nsequenceDiagram\n participant C as 客户端\n participant M as 日志中间件\n participant H as 处理器\n participant L as 日志记录器\n\n C->>M: 工具调用请求\n M->>L: 记录开始状态\n M->>H: 执行处理器\n H-->>M: 返回结果\n M->>L: 记录完成状态\n M-->>C: 返回响应\n```\n\n**请求日志上下文**：\n\n```typescript\ninterface RequestLogContext {\n method: 'TOOL_CALL' | 'HTTP_REQUEST';\n url: string;\n body?: any;\n statusCode?: number;\n duration?: number;\n}\n```\n\n 资料来源：[src/logging/middleware.ts:10-40]()\n\n#### 4.3 工具名称长度限制\n\n**重要提示**：部分客户端（如 Cursor）对工具名称有 60 字符限制。\n\n服务器名称：`playwright-mcp`\n\n确保工具名称足够简短，避免组合后超过限制。\n\n 资料来源：[README.md:140-150]()\n\n### 5. 截图功能问题\n\n#### 5.1 截图存储机制\n\n截图工具支持内存存储和文件存储两种模式：\n\n```mermaid\ngraph TD\n A[截图请求] --> B{storeBase64 参数}\n B -->|true| C[存入内存 Map]\n B -->|false| D[仅保存文件]\n C --> E[触发资源变更通知]\n D --> F[返回文件路径]\n E --> G[通知 MCP 客户端]\n```\n\n**存储配置**：\n\n```typescript\n// 截图参数配置\ninterface ScreenshotArgs {\n name?: string; // 截图标识名称\n downloadsDir?: string; // 下载目录路径\n storeBase64?: boolean; // 是否存入内存，默认为 true\n}\n```\n\n 资料来源：[src/tools/browser/screenshot.ts:20-50]()\n\n#### 5.2 获取已存储截图\n\n```typescript\n// 获取所有已存储的截图\ngetScreenshots(): Map {\n return this.screenshots;\n}\n```\n\n返回内存中所有 Base64 编码的截图数据。\n\n 资料来源：[src/tools/browser/screenshot.ts:80-90]()\n\n### 6. 连接问题诊断\n\n#### 6.1 连接问题排查清单\n\n| 检查项 | 验证方法 | 解决方案 |\n|-------|---------|---------|\n| 端口可用性 | `netstat -an \\| grep 8931` | 更换端口或终止占用进程 |\n| 本地访问 | `curl http://localhost:8931/health` | 检查服务器状态 |\n| 防火墙 | 检查入站规则 | 开放相应端口 |\n| 外部访问 | 远程主机测试 | 使用 SSH 隧道 |\n\n 资料来源：[README.md:80-100]()\n\n#### 6.2 健康检查端点\n\n```bash\n# HTTP 模式健康检查\ncurl http://localhost:8931/health\n```\n\n**响应示例**：\n\n```json\n{\n \"status\": \"ok\",\n \"version\": \"1.x.x\",\n \"activeSessions\": 0\n}\n```\n\n 资料来源：[src/http-server.ts:30-45]()\n\n### 7. 日志系统调试\n\n#### 7.1 日志级别\n\n```typescript\n// 日志方法\ninfo(message: string, context?: Record): void\nwarn(message: string, context?: Record): void\nerror(message: string, error?: Error, context?: Record): void\nlogRequest(message: string, requestContext: RequestLogContext): void\nlogError(message: string, error: Error, errorContext?: ErrorLogContext): void\n```\n\n#### 7.2 错误上下文捕获\n\n系统自动捕获丰富的错误上下文信息：\n\n```typescript\ncaptureErrorContext(error: Error, toolName?: string, args?: any): Record {\n return {\n errorName: error.name,\n errorMessage: error.message,\n stack: error.stack,\n timestamp: new Date().toISOString(),\n nodeVersion: process.version,\n platform: process.platform,\n arch: process.arch,\n memoryUsage: process.memoryUsage(),\n uptime: process.uptime(),\n toolName,\n toolCategory: toolName?.split('_')[0]\n };\n}\n```\n\n 资料来源：[src/logging/middleware.ts:180-220]()\n\n### 8. 性能与资源限制\n\n#### 8.1 Docker 资源限制\n\n```yaml\nservices:\n playwright-mcp:\n deploy:\n resources:\n limits:\n cpus: '2.0'\n memory: 2G\n```\n\n#### 8.2 健康检查配置\n\n```yaml\nservices:\n playwright-mcp:\n healthcheck:\n test: [\"CMD\", \"node\", \"-e\", \"process.exit(0)\"]\n interval: 30s\n timeout: 10s\n retries: 3\n```\n\n 资料来源：[DOCKER.md:100-130]()\n\n## 获取帮助\n\n如果问题仍未解决：\n\n1. 查看完整的 [README.md](README.md) 获取一般信息\n2. 在 [GitHub Issues](https://github.com/executeautomation/mcp-playwright/issues) 报告问题\n3. 为 Docker 相关问题添加 `docker` 标签\n4. 使用 `docker scan` 检查镜像安全漏洞\n\n## 依赖版本参考\n\n| 依赖包 | 版本 | 用途 |\n|-------|------|------|\n| @modelcontextprotocol/sdk | 1.24.3 | MCP 协议实现 |\n| playwright | 1.57.0 | 浏览器自动化核心 |\n| @playwright/browser-chromium | 1.57.0 | Chromium 浏览器 |\n| @playwright/browser-firefox | 1.57.0 | Firefox 浏览器 |\n| @playwright/browser-webkit | 1.57.0 | WebKit 浏览器 |\n\n 资料来源：[package.json:1-30]()\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：executeautomation/mcp-playwright\n\n摘要：发现 16 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Playwright is asking for an specific browser version.。\n\n## 1. 安装坑 · 来源证据：Playwright is asking for an specific browser version.\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Playwright is asking for an specific browser version.\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_38465ac94a9d4fb0bd352ba5209096ac | https://github.com/executeautomation/mcp-playwright/issues/117 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 2. 安全/权限坑 · 来源证据：How to configure proxy and storageState when launching browser in Playwright MCP?\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：How to configure proxy and storageState when launching browser in Playwright MCP?\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a2f7e4a410994d4195a9af9f139e0caa | https://github.com/executeautomation/mcp-playwright/issues/203 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | host_targets=mcp_host, claude, cursor\n\n## 4. 配置坑 · 来源证据：Add Clarvia AEO score badge to README (AEO 32/100)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Add Clarvia AEO score badge to README (AEO 32/100)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_74959d07d5f74165bcd9cae829d384ce | https://github.com/executeautomation/mcp-playwright/issues/212 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 配置坑 · 来源证据：Add policy enforcement for browser automation and HTTP request tools\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Add policy enforcement for browser automation and HTTP request tools\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_23a30d245f794b8db40c1d031b8be565 | https://github.com/executeautomation/mcp-playwright/issues/216 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | README/documentation is current enough for a first validation pass.\n\n## 7. 运行坑 · 来源证据：How to pass in the `--ignore-https-errors` parameter?\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：How to pass in the `--ignore-https-errors` parameter?\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_47d5e333819d49b4b8ce2abb9484b23d | https://github.com/executeautomation/mcp-playwright/issues/202 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 8. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | last_activity_observed missing\n\n## 9. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 11. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 来源证据：Feature Request: Add browser context persistence for login state (userDataDir/storageState)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature Request: Add browser context persistence for login state (userDataDir/storageState)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3632e6a11e044dda870b3267ccfa3040 | https://github.com/executeautomation/mcp-playwright/issues/201 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 13. 安全/权限坑 · 来源证据：Free MCP security scan report for @executeautomation/playwright-mcp-server\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Free MCP security scan report for @executeautomation/playwright-mcp-server\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9720dc9967444ed08710cdb0660a212a | https://github.com/executeautomation/mcp-playwright/issues/211 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 14. 安全/权限坑 · 来源证据：Security Advisory: SSRF, Prompt Injection, and Arbitrary JavaScript Execution via Browser Automation Tools\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security Advisory: SSRF, Prompt Injection, and Arbitrary JavaScript Execution via Browser Automation Tools\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ced642164084421f84bbb63681653057 | https://github.com/executeautomation/mcp-playwright/issues/209 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 15. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | issue_or_pr_quality=unknown\n\n## 16. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：executeautomation/mcp-playwright\n\n摘要：发现 16 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Playwright is asking for an specific browser version.。\n\n## 1. 安装坑 · 来源证据：Playwright is asking for an specific browser version.\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Playwright is asking for an specific browser version.\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_38465ac94a9d4fb0bd352ba5209096ac | https://github.com/executeautomation/mcp-playwright/issues/117 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 2. 安全/权限坑 · 来源证据：How to configure proxy and storageState when launching browser in Playwright MCP?\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：How to configure proxy and storageState when launching browser in Playwright MCP?\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a2f7e4a410994d4195a9af9f139e0caa | https://github.com/executeautomation/mcp-playwright/issues/203 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | host_targets=mcp_host, claude, cursor\n\n## 4. 配置坑 · 来源证据：Add Clarvia AEO score badge to README (AEO 32/100)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Add Clarvia AEO score badge to README (AEO 32/100)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_74959d07d5f74165bcd9cae829d384ce | https://github.com/executeautomation/mcp-playwright/issues/212 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 配置坑 · 来源证据：Add policy enforcement for browser automation and HTTP request tools\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Add policy enforcement for browser automation and HTTP request tools\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_23a30d245f794b8db40c1d031b8be565 | https://github.com/executeautomation/mcp-playwright/issues/216 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | README/documentation is current enough for a first validation pass.\n\n## 7. 运行坑 · 来源证据：How to pass in the `--ignore-https-errors` parameter?\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：How to pass in the `--ignore-https-errors` parameter?\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_47d5e333819d49b4b8ce2abb9484b23d | https://github.com/executeautomation/mcp-playwright/issues/202 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 8. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | last_activity_observed missing\n\n## 9. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 11. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 来源证据：Feature Request: Add browser context persistence for login state (userDataDir/storageState)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature Request: Add browser context persistence for login state (userDataDir/storageState)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3632e6a11e044dda870b3267ccfa3040 | https://github.com/executeautomation/mcp-playwright/issues/201 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 13. 安全/权限坑 · 来源证据：Free MCP security scan report for @executeautomation/playwright-mcp-server\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Free MCP security scan report for @executeautomation/playwright-mcp-server\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9720dc9967444ed08710cdb0660a212a | https://github.com/executeautomation/mcp-playwright/issues/211 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 14. 安全/权限坑 · 来源证据：Security Advisory: SSRF, Prompt Injection, and Arbitrary JavaScript Execution via Browser Automation Tools\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security Advisory: SSRF, Prompt Injection, and Arbitrary JavaScript Execution via Browser Automation Tools\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ced642164084421f84bbb63681653057 | https://github.com/executeautomation/mcp-playwright/issues/209 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 15. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | issue_or_pr_quality=unknown\n\n## 16. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# mcp-playwright - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 mcp-playwright 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client / claude / Cursor\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Playwright Model Context Protocol Server - Tool to automate Browsers and APIs in Claude Desktop, Cline, Cursor IDE and More 🔌 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. getting-started：快速入门指南。围绕“快速入门指南”模拟一次用户任务，不展示安装或运行结果。\n2. architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. tool-reference：工具参考手册。围绕“工具参考手册”模拟一次用户任务，不展示安装或运行结果。\n4. http-transport：HTTP/SSE 传输模式。围绕“HTTP/SSE 传输模式”模拟一次用户任务，不展示安装或运行结果。\n5. client-configuration：客户端配置指南。围绕“客户端配置指南”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. getting-started\n输入：用户提供的“快速入门指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. tool-reference\n输入：用户提供的“工具参考手册”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. http-transport\n输入：用户提供的“HTTP/SSE 传输模式”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. client-configuration\n输入：用户提供的“客户端配置指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / getting-started：Step 1 必须围绕“快速入门指南”形成一个小中间产物，并等待用户确认。\n- Step 2 / architecture：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / tool-reference：Step 3 必须围绕“工具参考手册”形成一个小中间产物，并等待用户确认。\n- Step 4 / http-transport：Step 4 必须围绕“HTTP/SSE 传输模式”形成一个小中间产物，并等待用户确认。\n- Step 5 / client-configuration：Step 5 必须围绕“客户端配置指南”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/executeautomation/mcp-playwright\n- https://github.com/executeautomation/mcp-playwright#readme\n- README.md\n- package.json\n- mcp-config.json\n- src/index.ts\n- src/http-server.ts\n- src/requestHandler.ts\n- src/toolHandler.ts\n- src/sse/server.ts\n- src/tools.ts\n- src/tools/index.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 mcp-playwright 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：executeautomation/mcp-playwright\n\n## 官方安装入口\n\n### Node.js / npm · 官方安装入口\n\n```bash\nnpm install -g @executeautomation/playwright-mcp-server\n```\n\n来源：https://github.com/executeautomation/mcp-playwright#readme\n\n## 来源\n\n- repo: https://github.com/executeautomation/mcp-playwright\n- docs: https://github.com/executeautomation/mcp-playwright#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_f8a266e7fd954a8a844a96cb7b062319"
}