{
  "canonical_name": "microsoft/playwright-mcp",
  "compilation_id": "pack_aed5374bdc504dd4ae500a5de6c0728b",
  "created_at": "2026-05-15T08:31:13.044186+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 `npx @playwright/mcp@latest` 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": "npx @playwright/mcp@latest",
      "sandbox_container_image": "node:22-slim",
      "sandbox_execution_backend": "docker",
      "sandbox_planner_decision": "deterministic_isolated_install",
      "sandbox_validation_id": "sbx_d4bb46027c0a4f8799c6b8d0f332e6e8"
    },
    "feedback_event_type": "project_pack_compilation_feedback",
    "learning_candidate_reasons": [],
    "template_gaps": []
  },
  "identity": {
    "canonical_id": "project_a3c11f41960345d1a9e184edf3d4f688",
    "canonical_name": "microsoft/playwright-mcp",
    "homepage_url": null,
    "license": "unknown",
    "repo_url": "https://github.com/microsoft/playwright-mcp",
    "slug": "playwright-mcp",
    "source_packet_id": "phit_2a173fe6035c4d3e87974f3f227649a5",
    "source_validation_id": "dval_55e0e2b586e44b66a56fc1af31bfbc46"
  },
  "merchandising": {
    "best_for": "需要工具连接与集成能力，并使用 mcp_host的用户",
    "github_forks": 2667,
    "github_stars": 32483,
    "one_liner_en": "Playwright MCP server",
    "one_liner_zh": "Playwright MCP server",
    "primary_category": {
      "category_id": "tool-integrations",
      "confidence": "high",
      "name_en": "Tool Integrations",
      "name_zh": "工具连接与集成",
      "reason": "matched_keywords:mcp, server, github"
    },
    "target_user": "使用 mcp_host 等宿主 AI 的用户",
    "title_en": "playwright-mcp",
    "title_zh": "playwright-mcp 能力包",
    "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": "Browser Automation",
        "label_zh": "浏览器自动化",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "core_capability-browser-automation",
        "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_2a173fe6035c4d3e87974f3f227649a5",
  "page_model": {
    "artifacts": {
      "artifact_slug": "playwright-mcp",
      "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": "npx @playwright/mcp@latest",
          "label": "Node.js / npx · 官方安装入口",
          "source": "https://github.com/microsoft/playwright-mcp#readme",
          "verified": true
        }
      ],
      "display_tags": [
        "浏览器 Agent",
        "网页任务自动化",
        "浏览器自动化",
        "节点式流程编排",
        "评测体系"
      ],
      "eyebrow": "工具连接与集成",
      "glance": [
        {
          "body": "判断自己是不是目标用户。",
          "label": "最适合谁",
          "value": "需要工具连接与集成能力，并使用 mcp_host的用户"
        },
        {
          "body": "先理解能力边界，再决定是否继续。",
          "label": "核心价值",
          "value": "Playwright MCP server"
        },
        {
          "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",
          "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": "仓库名 `playwright-mcp` 与安装入口 `@playwright/mcp@latest` 不完全一致。",
            "category": "身份坑",
            "evidence": [
              "identity.distribution | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | repo=playwright-mcp; install=@playwright/mcp@latest"
            ],
            "severity": "medium",
            "suggested_check": "在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。",
            "title": "仓库名和安装名不一致",
            "user_impact": "用户照着仓库名搜索包或照着包名找仓库时容易走错入口。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bad entrypoint in docker example",
            "category": "安装坑",
            "evidence": [
              "community_evidence:github | cevd_948f818745694481b19e883b3992d78b | https://github.com/microsoft/playwright-mcp/issues/1609 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
            ],
            "severity": "medium",
            "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
            "title": "来源证据：Bad entrypoint in docker example",
            "user_impact": "可能增加新用户试用和生产接入成本。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.0.72",
            "category": "安装坑",
            "evidence": [
              "community_evidence:github | cevd_2e67eb76e3c643e0a52a97e42eca4cb8 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.72 | 来源类型 github_release 暴露的待验证使用条件。"
            ],
            "severity": "medium",
            "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
            "title": "来源证据：v0.0.72",
            "user_impact": "可能阻塞安装或首次运行。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.0.69",
            "category": "配置坑",
            "evidence": [
              "community_evidence:github | cevd_6767d649d4934031b85ab0c5ffc2b324 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.69 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
            ],
            "severity": "medium",
            "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
            "title": "来源证据：v0.0.69",
            "user_impact": "可能增加新用户试用和生产接入成本。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.0.71",
            "category": "配置坑",
            "evidence": [
              "community_evidence:github | cevd_d5bcb1704c0e4a6fb375b18cda153fdd | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.71 | 来源类型 github_release 暴露的待验证使用条件。"
            ],
            "severity": "medium",
            "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
            "title": "来源证据：v0.0.71",
            "user_impact": "可能增加新用户试用和生产接入成本。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.0.73",
            "category": "配置坑",
            "evidence": [
              "community_evidence:github | cevd_a0d6aead61ad4c52ab738c6b556f2e27 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.73 | 来源类型 github_release 暴露的待验证使用条件。"
            ],
            "severity": "medium",
            "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
            "title": "来源证据：v0.0.73",
            "user_impact": "可能增加新用户试用和生产接入成本。"
          },
          {
            "body": "README/documentation is current enough for a first validation pass.",
            "category": "能力坑",
            "evidence": [
              "capability.assumptions | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | README/documentation is current enough for a first validation pass."
            ],
            "severity": "medium",
            "suggested_check": "将假设转成下游验证清单。",
            "title": "能力判断依赖假设",
            "user_impact": "假设不成立时，用户拿不到承诺的能力。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[Bug] Running multiple parallel async browsers in --isolated mode leaves orphan browsers. This has started happening after Release v0.0.69.",
            "category": "运行坑",
            "evidence": [
              "community_evidence:github | cevd_e8f29958fbbe48ce8381daa23333bdf4 | https://github.com/microsoft/playwright-mcp/issues/1607 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
            ],
            "severity": "medium",
            "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
            "title": "来源证据：[Bug] Running multiple parallel async browsers in --isolated mode leaves orphan browsers. This has started happening af…",
            "user_impact": "可能增加新用户试用和生产接入成本。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.0.67",
            "category": "运行坑",
            "evidence": [
              "community_evidence:github | cevd_3b13c720c21346bab9c08783c91acb95 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.67 | 来源类型 github_release 暴露的待验证使用条件。"
            ],
            "severity": "medium",
            "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
            "title": "来源证据：v0.0.67",
            "user_impact": "可能增加新用户试用和生产接入成本。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.0.68",
            "category": "运行坑",
            "evidence": [
              "community_evidence:github | cevd_c53eae5fa6a94d2e86bc60cf6b164d16 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.68 | 来源类型 github_release 暴露的待验证使用条件。"
            ],
            "severity": "medium",
            "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
            "title": "来源证据：v0.0.68",
            "user_impact": "可能增加新用户试用和生产接入成本。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.0.74",
            "category": "运行坑",
            "evidence": [
              "community_evidence:github | cevd_2c41b3bf29434fb48d51cb9ffc766fc2 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.74 | 来源类型 github_release 暴露的待验证使用条件。"
            ],
            "severity": "medium",
            "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
            "title": "来源证据：v0.0.74",
            "user_impact": "可能阻塞安装或首次运行。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.0.75",
            "category": "运行坑",
            "evidence": [
              "community_evidence:github | cevd_4e21e73e13dc471f90365f431d541143 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.75 | 来源类型 github_release 暴露的待验证使用条件。"
            ],
            "severity": "medium",
            "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
            "title": "来源证据：v0.0.75",
            "user_impact": "可能增加新用户试用和生产接入成本。"
          },
          {
            "body": "未记录 last_activity_observed。",
            "category": "维护坑",
            "evidence": [
              "evidence.maintainer_signals | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | 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:952688112 | https://github.com/microsoft/playwright-mcp | no_demo; severity=medium"
            ],
            "severity": "medium",
            "suggested_check": "进入安全/权限治理复核队列。",
            "title": "下游验证发现风险项",
            "user_impact": "下游已经要求复核，不能在页面中弱化。"
          },
          {
            "body": "no_demo",
            "category": "安全/权限坑",
            "evidence": [
              "risks.scoring_risks | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | no_demo; severity=medium"
            ],
            "severity": "medium",
            "suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
            "title": "存在评分风险",
            "user_impact": "风险会影响是否适合普通用户安装。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：VS Code installation buttons don't seem to work",
            "category": "安全/权限坑",
            "evidence": [
              "community_evidence:github | cevd_37c3461084f34d05856db207d12f8d9a | https://github.com/microsoft/playwright-mcp/issues/1608 | 来源类型 github_issue 暴露的待验证使用条件。"
            ],
            "severity": "medium",
            "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
            "title": "来源证据：VS Code installation buttons don't seem to work",
            "user_impact": "可能影响授权、密钥配置或安全边界。"
          }
        ],
        "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
        "summary": "发现 21 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。",
        "title": "踩坑日志"
      },
      "snapshot": {
        "contributors": 68,
        "forks": 2667,
        "license": "unknown",
        "note": "站点快照，非实时质量证明；用于开工前背景判断。",
        "stars": 32483
      },
      "source_url": "https://github.com/microsoft/playwright-mcp",
      "steps": [
        {
          "body": "不安装项目，先体验能力节奏。",
          "code": "preview",
          "title": "先试 Prompt"
        },
        {
          "body": "理解输入、输出、失败模式和边界。",
          "code": "manual",
          "title": "读说明书"
        },
        {
          "body": "把上下文交给宿主 AI 继续工作。",
          "code": "context",
          "title": "带给 AI"
        },
        {
          "body": "进入主力环境前先完成安装入口与风险边界验证。",
          "code": "verify",
          "title": "沙箱验证"
        }
      ],
      "subtitle": "Playwright MCP server",
      "title": "playwright-mcp 能力包",
      "trial_prompt": "# playwright-mcp - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 playwright-mcp 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Playwright MCP server 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. introduction：Introduction to Playwright MCP。围绕“Introduction to Playwright MCP”模拟一次用户任务，不展示安装或运行结果。\n2. key-concepts：Key Concepts。围绕“Key Concepts”模拟一次用户任务，不展示安装或运行结果。\n3. installation-guide：Installation Guide。围绕“Installation Guide”模拟一次用户任务，不展示安装或运行结果。\n4. client-integration：MCP Client Integration。围绕“MCP Client Integration”模拟一次用户任务，不展示安装或运行结果。\n5. browser-configuration：Browser Configuration。围绕“Browser Configuration”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. introduction\n输入：用户提供的“Introduction to Playwright MCP”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. key-concepts\n输入：用户提供的“Key Concepts”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. installation-guide\n输入：用户提供的“Installation Guide”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. client-integration\n输入：用户提供的“MCP Client Integration”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. browser-configuration\n输入：用户提供的“Browser Configuration”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / introduction：Step 1 必须围绕“Introduction to Playwright MCP”形成一个小中间产物，并等待用户确认。\n- Step 2 / key-concepts：Step 2 必须围绕“Key Concepts”形成一个小中间产物，并等待用户确认。\n- Step 3 / installation-guide：Step 3 必须围绕“Installation Guide”形成一个小中间产物，并等待用户确认。\n- Step 4 / client-integration：Step 4 必须围绕“MCP Client Integration”形成一个小中间产物，并等待用户确认。\n- Step 5 / browser-configuration：Step 5 必须围绕“Browser Configuration”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/microsoft/playwright-mcp\n- https://github.com/microsoft/playwright-mcp#readme\n- README.md\n- package.json\n- index.d.ts\n- config.d.ts\n- playwright.config.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 playwright-mcp 的核心服务。\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: [Feature Request] Support clientCertificates option for mTLS authenticat（https://github.com/microsoft/playwright-mcp/issues/1456）；github/github_issue: [Disclosure] Clarify browser/network action boundary in Playwright MCP s（https://github.com/microsoft/playwright-mcp/issues/1617）；github/github_issue: [Bug]: Windows taskkill output can pollute MCP stdio transport（https://github.com/microsoft/playwright-mcp/issues/1611）；github/github_issue: [Bug] Running multiple parallel async browsers in --isolated mode leaves（https://github.com/microsoft/playwright-mcp/issues/1607）；github/github_issue: VS Code installation buttons don't seem to work（https://github.com/microsoft/playwright-mcp/issues/1608）；github/github_issue: Bad entrypoint in docker example（https://github.com/microsoft/playwright-mcp/issues/1609）；github/github_release: v0.0.75（https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.75）；github/github_release: v0.0.74（https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.74）；github/github_release: v0.0.73（https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.73）；github/github_release: v0.0.72（https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.72）；github/github_release: v0.0.71（https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.71）；github/github_release: v0.0.69（https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.69）。这些是项目级外部声音，不作为单独质量证明。",
          "items": [
            {
              "kind": "github_issue",
              "source": "github",
              "title": "[Feature Request] Support clientCertificates option for mTLS authenticat",
              "url": "https://github.com/microsoft/playwright-mcp/issues/1456"
            },
            {
              "kind": "github_issue",
              "source": "github",
              "title": "[Disclosure] Clarify browser/network action boundary in Playwright MCP s",
              "url": "https://github.com/microsoft/playwright-mcp/issues/1617"
            },
            {
              "kind": "github_issue",
              "source": "github",
              "title": "[Bug]: Windows taskkill output can pollute MCP stdio transport",
              "url": "https://github.com/microsoft/playwright-mcp/issues/1611"
            },
            {
              "kind": "github_issue",
              "source": "github",
              "title": "[Bug] Running multiple parallel async browsers in --isolated mode leaves",
              "url": "https://github.com/microsoft/playwright-mcp/issues/1607"
            },
            {
              "kind": "github_issue",
              "source": "github",
              "title": "VS Code installation buttons don't seem to work",
              "url": "https://github.com/microsoft/playwright-mcp/issues/1608"
            },
            {
              "kind": "github_issue",
              "source": "github",
              "title": "Bad entrypoint in docker example",
              "url": "https://github.com/microsoft/playwright-mcp/issues/1609"
            },
            {
              "kind": "github_release",
              "source": "github",
              "title": "v0.0.75",
              "url": "https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.75"
            },
            {
              "kind": "github_release",
              "source": "github",
              "title": "v0.0.74",
              "url": "https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.74"
            },
            {
              "kind": "github_release",
              "source": "github",
              "title": "v0.0.73",
              "url": "https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.73"
            },
            {
              "kind": "github_release",
              "source": "github",
              "title": "v0.0.72",
              "url": "https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.72"
            },
            {
              "kind": "github_release",
              "source": "github",
              "title": "v0.0.71",
              "url": "https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.71"
            },
            {
              "kind": "github_release",
              "source": "github",
              "title": "v0.0.69",
              "url": "https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.69"
            }
          ],
          "status": "已收录 12 条来源",
          "title": "社区讨论"
        }
      ]
    },
    "homepage_card": {
      "category": "工具连接与集成",
      "desc": "Playwright MCP server",
      "effort": "安装已验证",
      "forks": 2667,
      "icon": "link",
      "name": "playwright-mcp 能力包",
      "risk": "可发布",
      "slug": "playwright-mcp",
      "stars": 32483,
      "tags": [
        "浏览器 Agent",
        "网页任务自动化",
        "浏览器自动化",
        "节点式流程编排",
        "评测体系"
      ],
      "thumb": "gray",
      "type": "MCP 配置"
    },
    "manual": {
      "markdown": "# https://github.com/microsoft/playwright-mcp 项目说明书\n\n生成时间：2026-05-15 08:14:48 UTC\n\n## 目录\n\n- [Introduction to Playwright MCP](#introduction)\n- [Key Concepts](#key-concepts)\n- [Installation Guide](#installation-guide)\n- [MCP Client Integration](#client-integration)\n- [Browser Configuration](#browser-configuration)\n- [Security Settings](#security-settings)\n- [Docker Deployment](#docker-deployment)\n- [Programmatic Usage](#programmatic-usage)\n- [User Profiles and Session Management](#user-profiles)\n- [Troubleshooting](#troubleshooting)\n\n<a id='introduction'></a>\n\n## Introduction to Playwright MCP\n\n### 相关页面\n\n相关主题：[Key Concepts](#key-concepts), [Installation Guide](#installation-guide)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/microsoft/playwright-mcp/blob/main/README.md)\n- [package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n- [config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n- [server.json](https://github.com/microsoft/playwright-mcp/blob/main/server.json)\n- [cli.js](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)\n- [index.js](https://github.com/microsoft/playwright-mcp/blob/main/index.js)\n- [CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n</details>\n\n# Introduction to Playwright MCP\n\nPlaywright MCP (Model Context Protocol) is a server implementation that exposes [Playwright](https://playwright.dev) browser automation capabilities through the MCP protocol. It enables AI models and tools to interact with web browsers using a standardized interface.\n\n## Overview\n\nPlaywright MCP acts as a bridge between AI systems and web browsers, providing a comprehensive set of tools for:\n\n- Browser automation and scraping\n- UI testing and verification\n- Network request monitoring\n- PDF generation\n- Vision-based interactions\n- Storage state management\n\n**Package Information**\n\n| Property | Value |\n|----------|-------|\n| Package Name | `@playwright/mcp` |\n| MCP Server Name | `io.github.microsoft/playwright-mcp` |\n| Current Version | `0.0.75` |\n| License | Apache-2.0 |\n| Node Requirement | `>=18` |\n| Transport Protocol | stdio |\n\n资料来源：[package.json:3-15](https://github.com/microsoft/playwright-mcp/blob/main/package.json), [server.json:1-15](https://github.com/microsoft/playwright-mcp/blob/main/server.json)\n\n## Architecture\n\nThe Playwright MCP implementation follows a layered architecture where the MCP server delegates browser operations to Playwright's core automation engine.\n\n```mermaid\ngraph TD\n    A[AI Client / MCP Host] -->|MCP Protocol| B[Playwright MCP Server]\n    B -->|STDIO Transport| C[playwright-core]\n    C -->|Browser Automation| D[Chromium / Firefox / WebKit]\n    C -->|PDF Generation| E[PDF Renderer]\n    C -->|Vision API| F[Image Processing]\n```\n\n资料来源：[index.js:1-25](https://github.com/microsoft/playwright-mcp/blob/main/index.js), [cli.js:1-35](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)\n\n### Source Code Location\n\n> [!IMPORTANT]\n> The core implementation has been migrated to the [Playwright monorepo](https://github.com/microsoft/playwright). The source code is now located at:\n>\n> `packages/playwright/src/mcp`\n\nThis repository (`microsoft/playwright-mcp`) serves as the npm distribution package and coordination point.\n\n资料来源：[src/README.md:1-5](https://github.com/microsoft/playwright-mcp/blob/main/src/README.md)\n\n## Tool Capabilities\n\nPlaywright MCP organizes its functionality into capability groups. Each capability can be individually enabled or disabled through configuration.\n\n| Capability | Description |\n|------------|-------------|\n| `config` | Server configuration and initialization |\n| `core` | Core browser operations |\n| `core-navigation` | Page navigation and URL handling |\n| `core-tabs` | Tab/window management |\n| `core-input` | Form input and user interactions |\n| `core-install` | Browser installation |\n| `network` | Network request/response monitoring |\n| `pdf` | PDF document generation |\n| `storage` | Session state persistence |\n| `testing` | Test assertion utilities |\n| `vision` | Screenshot and visual verification |\n| `devtools` | Developer tools integration |\n\n资料来源：[config.d.ts:25-40](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Configuration Options\n\nThe server behavior can be customized through the `Config` type defined in `config.d.ts`.\n\n### Browser Configuration\n\n```typescript\nbrowser?: {\n  browserName?: 'chromium' | 'firefox' | 'webkit';\n  isolated?: boolean;\n  userDataDir?: string;\n  launchOptions?: object;\n}\n```\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `browserName` | string | Browser type: chromium, firefox, or webkit |\n| `isolated` | boolean | Keep browser profile in memory only |\n| `userDataDir` | string | Path for browser profile persistence |\n\n资料来源：[config.d.ts:48-75](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n### Network Configuration\n\n```typescript\nnetwork?: {\n  allowedOrigins?: string[];\n  blockedOrigins?: string[];\n}\n```\n\nSupported origin formats:\n- Full origin: `https://example.com:8080`\n- Wildcard port: `http://localhost:*`\n\n资料来源：[config.d.ts:100-115](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n### Console Configuration\n\n```typescript\nconsole?: {\n  level?: 'error' | 'warning' | 'info' | 'debug';\n}\n```\n\n资料来源：[config.d.ts:95-98](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## CLI Usage\n\nThe Playwright MCP CLI is available via `cli.js` and supports several commands:\n\n```bash\n# Run with default settings\nnode cli.js\n\n# Install browser binaries\nnode cli.js install-browser\n\n# Show version\nnode cli.js --version\n\n# Show help\nnode cli.js --help\n```\n\nThe CLI is built on top of `playwright-core` and leverages its command-line utilities.\n\n资料来源：[cli.js:1-35](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)\n\n## Entry Point\n\nThe main entry point exports the `createConnection` function which establishes the MCP connection:\n\n```javascript\nconst { tools } = require('playwright-core/lib/coreBundle');\nmodule.exports = { createConnection: tools.createConnection };\n```\n\n资料来源：[index.js:1-25](https://github.com/microsoft/playwright-mcp/blob/main/index.js)\n\n## Package Scripts\n\n| Script | Purpose |\n|--------|---------|\n| `npm test` | Run all Playwright tests |\n| `npm run ctest` | Run tests in Chrome only |\n| `npm run ftest` | Run tests in Firefox only |\n| `npm run wtest` | Run tests in WebKit only |\n| `npm run lint` | Generate/update README |\n| `npm run roll` | Update Playwright version |\n| `npm run docker-build` | Build Docker image |\n| `npm run docker-run` | Run Docker container |\n\n资料来源：[package.json:18-35](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n\n## Testing\n\nTests are located in the `tests` directory and organized under `tests/mcp`. To run the test suite:\n\n```bash\n# Fast path - Chrome only\nnpm run ctest\n\n# Full path - All browsers\nnpm run mcp-test\n```\n\nTest execution uses Playwright itself, applying the same testing patterns documented in the official [Playwright testing guide](https://playwright.dev/docs/running-tests#running-tests).\n\n资料来源：[CONTRIBUTING.md:45-60](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md), [playwright.config.ts:1-30](https://github.com/microsoft/playwright-mcp/blob/main/playwright.config.ts)\n\n## Development Workflow\n\n```mermaid\ngraph LR\n    A[Fork Repository] --> B[Clone playwright monorepo]\n    B --> C[npm ci && npm run watch]\n    C --> D[npx playwright install]\n    D --> E[Make Changes]\n    E --> F[npm run flint]\n    F --> G[Add Tests]\n    G --> H[Open PR]\n```\n\n1. **Clone**: `git clone https://github.com/microsoft/playwright`\n2. **Install**: `npm ci && npx playwright install`\n3. **Develop**: Make changes in `packages/playwright/src/mcp`\n4. **Lint**: `npm run flint`\n5. **Test**: `npm run mcp-ctest` (fast) or `npm run mcp-test` (full)\n6. **Commit**: Follow [Semantic Commit Messages](https://www.conventionalcommits.org/en/v1.0.0/) format\n7. **PR**: Submit pull request for review\n\n资料来源：[CONTRIBUTING.md:10-55](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n\n## Commit Convention\n\nCommits must follow semantic format:\n\n```\n<label>(<scope>): <description>\n\n[optional body]\n\n[optional footer with fixes/references]\n```\n\n**Labels:**\n- `fix` - Bug fixes\n- `feat` - New features\n- `docs` - Documentation changes\n- `test` - Test-only changes\n- `devops` - CI/build changes\n- `chore` - Maintenance tasks\n\nBranch naming for fixes: `fix-<issue-number>`\n\n资料来源：[CONTRIBUTING.md:55-90](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n\n## Version Management\n\nThe `roll.js` script handles Playwright version updates across the project:\n\n```javascript\n// Key functions in roll.js\nupdatePlaywrightVersion(version)  // Update package.json\ncopyConfig()                      // Sync config.d.ts from monorepo\n```\n\nTo roll to a new Playwright version:\n1. Run `npm run roll`\n2. Create branch: `git checkout -b roll-pw-<suffix>`\n3. Run tests: `npm test`\n4. Commit and open PR\n\n资料来源：[roll.js:1-50](https://github.com/microsoft/playwright-mcp/blob/main/roll.js)\n\n## Summary\n\nPlaywright MCP provides a production-ready integration layer that brings Playwright's powerful browser automation capabilities to AI systems via the Model Context Protocol. With support for multiple browsers, comprehensive tool coverage, and enterprise-grade features like isolated browser contexts and network filtering, it serves as a robust foundation for AI-driven web interactions.\n\nThe project's move to the main Playwright monorepo ensures tight integration with Playwright's development cycle and guarantees that the MCP tools remain synchronized with the latest browser automation features.\n\n---\n\n<a id='key-concepts'></a>\n\n## Key Concepts\n\n### 相关页面\n\n相关主题：[Introduction to Playwright MCP](#introduction), [Browser Configuration](#browser-configuration)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [CLAUDE.md](https://github.com/microsoft/playwright-mcp/blob/main/CLAUDE.md)\n- [CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n- [config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n- [package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n- [cli.js](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)\n- [playwright.config.ts](https://github.com/microsoft/playwright-mcp/blob/main/playwright.config.ts)\n- [roll.js](https://github.com/microsoft/playwright-mcp/blob/main/roll.js)\n- [update-readme.js](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)\n</details>\n\n# Key Concepts\n\nPlaywright MCP (Model Context Protocol) is a server implementation that exposes Playwright browser automation capabilities through the MCP protocol. It enables AI assistants and other MCP clients to interact with web pages through a standardized tool interface, supporting automation, testing, and web scraping workflows.\n\n## Architecture Overview\n\nThe Playwright MCP server acts as a bridge between MCP clients and Playwright's browser automation engine. The core implementation resides in the [Playwright monorepo](https://github.com/microsoft/playwright) at `packages/playwright/src/mcp`, while this repository serves as the distribution package and configuration layer.\n\n```mermaid\ngraph TD\n    A[MCP Client<br>e.g., AI Assistant] --> B[Playwright MCP Server]\n    B --> C[Playwright Core]\n    C --> D[Chromium]\n    C --> E[Firefox]\n    C --> F[WebKit]\n    \n    B --> G[Browser Context]\n    G --> H[Pages/Tabs]\n    H --> I[DOM Elements]\n    \n    J[Config Options] --> B\n    K[Tool Capabilities] --> B\n```\n\n资料来源：[CONTRIBUTING.md:40-44](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n\n## Tool Capabilities System\n\nThe MCP server organizes its functionality into discrete capabilities that can be enabled or disabled based on use case requirements.\n\n### Capability Types\n\n| Capability | Description | Default |\n|------------|-------------|---------|\n| `config` | Server configuration management | Enabled |\n| `core` | Core browser automation (navigation, clicks, input) | Enabled |\n| `core-navigation` | Advanced navigation control | Enabled |\n| `core-tabs` | Multiple tab/window management | Enabled |\n| `core-input` | Form input handling | Enabled |\n| `core-install` | Browser installation | Enabled |\n| `network` | Network request interception | Opt-in |\n| `pdf` | PDF generation | Opt-in |\n| `storage` | Session storage management | Opt-in |\n| `testing` | Test assertions | Opt-in |\n| `vision` | Screenshot and visual comparisons | Opt-in |\n| `devtools` | Developer tools integration | Opt-in |\n\n资料来源：[config.d.ts:45-56](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n### Opt-in Capabilities\n\nCapabilities not listed in the `core` group require explicit enablement via the `--caps` configuration option. For example:\n\n```bash\n--caps=network,storage,testing\n```\n\nOpt-in capabilities are documented with the following pattern in user-facing documentation:\n\n```\nCapability Title (opt-in via --caps=capability-name)\n```\n\n资料来源：[update-readme.js:120-123](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)\n\n## Browser Configuration\n\n### Browser Types\n\n| Option | Description |\n|--------|-------------|\n| `chromium` | Chromium-based browser (default) |\n| `firefox` | Mozilla Firefox |\n| `webkit` | WebKit/Safari engine |\n\n### Browser Isolation\n\n```typescript\nbrowser?: {\n  browserName?: 'chromium' | 'firefox' | 'webkit';\n  isolated?: boolean;      // Keep profile in memory only\n  userDataDir?: string;    // Custom profile persistence path\n};\n```\n\n- **isolated (default: true)**: Browser profile is kept in memory, not saved to disk\n- **userDataDir**: Path for browser profile persistence across sessions\n\n资料来源：[config.d.ts:8-17](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Network Security\n\n### Origin-Based Filtering\n\n| Configuration | Purpose |\n|--------------|---------|\n| `allowedOrigins` | Whitelist of permitted origins |\n| `blockedOrigins` | Blacklist of denied origins |\n\nWhen an origin matches both lists, it will be **blocked**.\n\n**Supported formats:**\n- Full origin: `https://example.com:8080` - matches exact origin\n- Wildcard port: `http://localhost:*` - matches any port with specified protocol\n\n资料来源：[config.d.ts:20-35](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Timeouts\n\n| Timeout | Default | Description |\n|---------|---------|-------------|\n| `action` | 5000ms | Default action timeout |\n| `navigation` | 60000ms | Default navigation timeout |\n| `expect` | 5000ms | Default assertion/expect timeout |\n\nConfiguration location: `timeouts` in the Config type.\n\n资料来源：[config.d.ts:47-62](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Session Management\n\n### Save Session\n\nThe `saveSession` option controls whether Playwright session data is persisted to the output directory.\n\n### Shared Browser Context\n\nWhen `sharedBrowserContext` is enabled, the same browser context is reused across all connected HTTP clients, enabling state sharing between requests.\n\n```typescript\nsaveSession?: boolean;\nsharedBrowserContext?: boolean;\n```\n\n资料来源：[config.d.ts:65-70](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Secrets Management\n\nSecrets provide a mechanism to redact sensitive information from tool responses before sending them to clients.\n\n```typescript\nsecrets?: Record<string, string>;\n```\n\n**Important**: Secrets replacement is a convenience feature, not a security measure. Always examine incoming and outgoing data on the client side.\n\n资料来源：[config.d.ts:75-80](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Console Logging\n\n| Level | Description |\n|-------|-------------|\n| `error` | Only error messages |\n| `warning` | Errors and warnings |\n| `info` | Informational messages (default) |\n| `debug` | All messages including debug |\n\n```typescript\nconsole?: {\n  level?: 'error' | 'warning' | 'info' | 'debug';\n}\n```\n\n资料来源：[config.d.ts:91-96](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Image Responses\n\nControls whether image responses are sent to MCP clients:\n\n| Value | Behavior |\n|-------|----------|\n| `allow` | Always send images |\n| `omit` | Never send images |\n| `auto` | Send images if client can display them (default) |\n\n```typescript\nimageResponses?: 'allow' | 'omit' | 'auto';\n```\n\n资料来源：[config.d.ts:64](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Output Directory\n\nFiles generated during MCP operations (screenshots, downloads, traces) are saved to the configured output directory:\n\n```typescript\noutputDir?: string;\n```\n\n资料来源：[config.d.ts:83](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Test ID Attribute\n\nSpecify a custom attribute to use for test identification:\n\n```typescript\ntestIdAttribute?: string;  // Default: \"data-testid\"\n```\n\n资料来源：[config.d.ts:43](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Command-Line Interface\n\n### CLI Entry Point\n\nThe CLI is implemented in `cli.js` and supports several commands:\n\n```javascript\nconst { tools, libCli } = require('playwright-core/lib/coreBundle');\ntools.decorateMCPCommand(p, packageJSON.version);\n```\n\n### Available Commands\n\n| Command | Description |\n|---------|-------------|\n| Standard MCP tools | Browser automation operations |\n| `install-browser` | Install Playwright browsers |\n\nThe CLI can forward `install-browser` to `playwright install` for browser installation.\n\n资料来源：[cli.js:24-30](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)\n\n## Configuration Precedence\n\nEnvironment variables take precedence over default values. The mapping follows this pattern:\n\n| CLI Option | Environment Variable |\n|------------|---------------------|\n| `--secrets` | `PLAYWRIGHT_MCP_SECRETS_FILE` |\n| `--output-dir` | `PLAYWRIGHT_MCP_OUTPUT_DIR` |\n| Other options | `PLAYWRIGHT_MCP_<NAME>` (uppercase, hyphen → underscore) |\n\nExample: `--browser-name` → `PLAYWRIGHT_MCP_BROWSER_NAME`\n\n资料来源：[update-readme.js:86-90](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)\n\n## Build and Release Workflow\n\n### Version Management\n\nThe package version is defined in `package.json`:\n\n```json\n{\n  \"name\": \"@playwright/mcp\",\n  \"version\": \"0.0.75\"\n}\n```\n\n### Rolling Playwright Versions\n\nThe `roll.js` script handles updating Playwright dependencies:\n\n1. Updates `playwright`, `playwright-core`, and `@playwright/test` versions\n2. Copies `config.d.ts` from the Playwright monorepo\n3. Regenerates README documentation\n\n```bash\nnpm run roll\n```\n\n资料来源：[roll.js:1-30](https://github.com/microsoft/playwright-mcp/blob/main/roll.js)\n\n### Branch Naming Convention\n\n| Purpose | Pattern |\n|---------|---------|\n| Rolling Playwright | `roll-pw-<version-suffix>` |\n| Issue fixes | `fix-<issue-number>` |\n\n资料来源：[CLAUDE.md:5](https://github.com/microsoft/playwright-mcp/blob/main/CLAUDE.md)\n\n## Testing Infrastructure\n\n### Test Configuration\n\nTests are configured via `playwright.config.ts`:\n\n```typescript\nprojects: [\n  { name: 'chrome' },\n  ...process.env.MCP_IN_DOCKER ? [{\n    name: 'chromium-docker',\n    grep: /browser_navigate|browser_click/,\n    use: {\n      mcpBrowser: 'chromium',\n      mcpMode: 'docker' as const\n    }\n  }] : [],\n]\n```\n\n### Test Commands\n\n| Command | Scope |\n|---------|-------|\n| `npm test` | All tests across all browsers |\n| `npm run ctest` | Chrome only (fast path) |\n| `npm run ftest` | Firefox only |\n| `npm run wtest` | WebKit only |\n| `npm run dtest` | Docker-based Chromium |\n\nMCP tests are located in `tests/mcp` directory within the Playwright monorepo.\n\n资料来源：[playwright.config.ts:22-38](https://github.com/microsoft/playwright-mcp/blob/main/playwright.config.ts)\n资料来源：[CONTRIBUTING.md:67-72](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n\n### Test Requirements\n\n- Tests must be **hermetic** (self-contained, no external dependencies)\n- Must work on all three platforms: macOS, Linux, Windows\n- Tests are required for new functionality (exceptions for pure refactoring)\n\n资料来源：[CONTRIBUTING.md:83-85](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n\n## Commit Conventions\n\n### Semantic Commit Format\n\n```\nlabel(namespace): title\n\ndescription\n\nfooter\n```\n\n### Labels\n\n| Label | Purpose |\n|-------|---------|\n| `fix` | Bug fixes |\n| `feat` | New features |\n| `docs` | Documentation-only changes |\n| `test` | Test-only changes |\n| `devops` | CI or build changes |\n| `chore` | Miscellaneous (default) |\n\n### Example\n\n```\nfix(proxy): handle SOCKS proxy authentication\n\nFixes: https://github.com/microsoft/playwright/issues/39562\n```\n\n资料来源：[CONTRIBUTING.md:11-31](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n\n## Contribution Workflow\n\n```mermaid\ngraph LR\n    A[File Issue] --> B[Get Assignment]\n    B --> C[Clone Repository]\n    C --> D[Create Branch]\n    D --> E[Implement Changes]\n    E --> F[Add Tests]\n    F --> G[Run Tests]\n    G --> H{Linter Pass?}\n    H -->|No| I[Fix Issues]\n    I --> G\n    H -->|Yes| J[Commit Changes]\n    J --> K[Open PR]\n    K --> L[Code Review]\n    L --> M[Merge]\n```\n\n### Submission Requirements\n\n- **Issue required**: Every contribution needs a corresponding GitHub issue\n- **Prior approval**: Unsolicited PRs will be closed\n- **Human oversight**: Low-quality AI contributions without human review will be closed\n\n资料来源：[CONTRIBUTING.md:41-52](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n\n## Documentation Generation\n\nThe `update-readme.js` script automatically generates documentation sections:\n\n1. **Tools section**: Lists all MCP tools grouped by capability\n2. **Options section**: CLI options from `--help` output\n3. **Config section**: TypeScript Config type definition\n\nGenerated sections are delimited by markers:\n```markdown\n<!--- Tools generated by update-readme.js -->\n...\n<!--- End of tools generated section --->\n```\n\nRun `npm run lint` to regenerate documentation.\n\n资料来源：[update-readme.js:1-150](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)\n\n---\n\n<a id='installation-guide'></a>\n\n## Installation Guide\n\n### 相关页面\n\n相关主题：[MCP Client Integration](#client-integration), [Docker Deployment](#docker-deployment)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n- [CLAUDE.md](https://github.com/microsoft/playwright-mcp/blob/main/CLAUDE.md)\n- [CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n- [cli.js](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)\n- [config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n- [playwright.config.ts](https://github.com/microsoft/playwright-mcp/blob/main/playwright.config.ts)\n</details>\n\n# Installation Guide\n\nThis guide covers all aspects of installing, configuring, and setting up the Playwright MCP (Model Context Protocol) server for development and production use.\n\n## Overview\n\nPlaywright MCP is an npm package (`@playwright/mcp`) that provides browser automation tools via the MCP protocol. It enables AI assistants to interact with web browsers through a standardized interface, supporting capabilities like navigation, clicking, input handling, network interception, and testing assertions.\n\n资料来源：[package.json:1-15]()\n\n## System Requirements\n\n### Runtime Requirements\n\n| Requirement | Version | Description |\n|-------------|---------|-------------|\n| Node.js | >= 18 | JavaScript runtime environment |\n| npm | Latest | Package manager (bundled with Node.js) |\n\nThe package explicitly declares its Node.js engine requirement in `package.json`:\n\n```json\n\"engines\": {\n  \"node\": \">=18\"\n}\n```\n\n资料来源：[package.json:12-14]()\n\n### Browser Dependencies\n\nPlaywright MCP requires browser binaries to function. The supported browsers are:\n\n| Browser | Support Level | Notes |\n|---------|---------------|-------|\n| Chromium | Full | Primary development browser |\n| Firefox | Full | Cross-browser testing |\n| WebKit | Full | Safari compatibility testing |\n\n## Installation Methods\n\n### From npm (Global Installation)\n\nFor CLI usage across the system:\n\n```bash\nnpm install -g @playwright/mcp\n```\n\nThis makes the `playwright` command available globally:\n\n```bash\nplaywright --help\n```\n\n资料来源：[cli.js:23-26]()\n\n### From npm (Project Installation)\n\nFor use as a project dependency:\n\n```bash\nnpm install @playwright/mcp\n```\n\n### Using npx (No Installation)\n\nFor one-time execution without installing globally:\n\n```bash\nnpx @playwright/mcp [options]\n```\n\n## CLI Options\n\nThe MCP server accepts the following command-line options:\n\n| Option | Environment Variable | Description |\n|--------|---------------------|-------------|\n| `--secrets <file>` | `PLAYWRIGHT_MCP_SECRETS_FILE` | Path to secrets file |\n| `--browser <browser>` | `PLAYWRIGHT_MCP_BROWSER` | Browser to use (chromium, firefox, webkit) |\n| `--caps <capabilities>` | `PLAYWRIGHT_MCP_CAPS` | Enable additional capabilities |\n| `--output-dir <path>` | `PLAYWRIGHT_MCP_OUTPUT_DIR` | Directory for output files |\n| `--config <file>` | `PLAYWRIGHT_MCP_CONFIG` | Path to config file |\n| `--install-browser` | N/A | Install browser binaries |\n| `--version` | N/A | Show version information |\n| `--help` | N/A | Show help message |\n\n资料来源：[update-readme.js:89-111]()\n\n### Environment Variable Mapping\n\nEvery CLI option can be configured via environment variables by prefixing the option name with `PLAYWRIGHT_MCP_` and converting dashes to underscores:\n\n```bash\nexport PLAYWRIGHT_MCP_BROWSER=chromium\nexport PLAYWRIGHT_MCP_OUTPUT_DIR=/tmp/playwright-output\nexport PLAYWRIGHT_MCP_SECRETS_FILE=./secrets.json\n```\n\n## Configuration File\n\n### Config File Format\n\nCreate a TypeScript config file (e.g., `config.ts`) with the following structure:\n\n```typescript\nimport type { Config } from '@playwright/mcp';\n\nconst config: Config = {\n  browser: {\n    browserName: 'chromium',\n    isolated: true,\n  },\n  capabilities: ['core', 'network'],\n  outputDir: '/tmp/playwright-output',\n  timeouts: {\n    action: 5000,\n    navigation: 60000,\n    expect: 5000,\n  },\n};\n\nexport default config;\n```\n\n### Configuration Options\n\n#### Browser Configuration\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `browserName` | `'chromium' \\| 'firefox' \\| 'webkit'` | `'chromium'` | Browser type to launch |\n| `isolated` | `boolean` | `false` | Keep browser profile in memory |\n| `userDataDir` | `string` | `undefined` | Custom browser profile directory |\n\n资料来源：[config.d.ts:18-40]()\n\n#### Capabilities Configuration\n\nThe following tool capabilities are available:\n\n| Capability | Description | Notes |\n|------------|-------------|-------|\n| `core` | Core navigation and interaction tools | Always enabled |\n| `core-navigation` | Page navigation tools | Enabled by default |\n| `core-tabs` | Tab management tools | Enabled by default |\n| `core-input` | Input handling tools | Enabled by default |\n| `core-install` | Browser installation tools | Enabled by default |\n| `network` | Network request interception | Opt-in via `--caps=network` |\n| `pdf` | PDF generation | Opt-in via `--caps=pdf` |\n| `storage` | Storage and cookie management | Opt-in via `--caps=storage` |\n| `testing` | Test assertion tools | Opt-in via `--caps=testing` |\n| `vision` | Coordinate-based interactions | Opt-in via `--caps=vision` |\n| `devtools` | Developer tools features | Opt-in via `--caps=devtools` |\n| `config` | Configuration tools | Always enabled |\n\n资料来源：[config.d.ts:48-65]()\n\n#### Timeout Configuration\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `timeouts.action` | `5000ms` | Default action timeout |\n| `timeouts.navigation` | `60000ms` | Default navigation timeout |\n| `timeouts.expect` | `5000ms` | Default expect timeout |\n\n资料来源：[config.d.ts:83-97]()\n\n#### Network Configuration\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `network.allowedOrigins` | `string[]` | Allowed request origins |\n| `network.blockedOrigins` | `string[]` | Blocked request origins |\n\nOrigins can be specified as full URLs (`https://example.com:8080`) or with wildcard ports (`http://localhost:*`).\n\n资料来源：[config.d.ts:99-114]()\n\n## Development Setup\n\n### Clone the Repository\n\n> [!WARNING]\n> The core of the Playwright MCP was moved to the [Playwright monorepo](https://github.com/microsoft/playwright).\n\nClone the Playwright repository where Playwright MCP source is now located:\n\n```bash\ngit clone https://github.com/microsoft/playwright\ncd playwright\n```\n\n资料来源：[CONTRIBUTING.md:33-43]()\n\n### Install Dependencies\n\nInstall all project dependencies:\n\n```bash\nnpm ci\n```\n\n### Install Browser Binaries\n\nDownload and install the required browser binaries:\n\n```bash\nnpx playwright install\n```\n\nOr install specific browsers:\n\n```bash\nnpx playwright install chromium\nnpx playwright install firefox\nnpx playwright install webkit\n```\n\n资料来源：[CONTRIBUTING.md:44-50]()\n\n### Development Workflow\n\n#### Watch Mode\n\nFor active development with automatic rebuilding:\n\n```bash\nnpm run watch\n```\n\n#### Run Tests\n\nRun all MCP tests in Chromium (fast path):\n\n```bash\nnpm run mcp-ctest\n```\n\nRun all tests in three browsers (slow path):\n\n```bash\nnpm run mcp-test\n```\n\n#### Linting\n\nCheck code quality using the linter:\n\n```bash\nnpm run flint\n```\n\n资料来源：[CONTRIBUTING.md:51-70]()\n\n### Test Directory Structure\n\nTests for Playwright MCP are located at:\n\n```\ntests/mcp/\n```\n\nTo list test files:\n\n```bash\nls -la tests/mcp\n```\n\n资料来源：[CONTRIBUTING.md:59-66]()\n\n## Docker Installation\n\n### Build the Docker Image\n\n```bash\nnpm run docker-build\n```\n\nThis creates a Docker image named `playwright-mcp-dev:latest`.\n\n### Run the Docker Container\n\n```bash\nnpm run docker-run\n```\n\nThis starts an interactive session with port 8080 exposed.\n\n### Docker Test Mode\n\nRun tests within Docker using Chromium:\n\n```bash\nnpm run dtest\n```\n\n资料来源：[package.json:23-30]()\n\n## Testing Your Installation\n\n### Verify CLI Access\n\n```bash\nplaywright --version\n```\n\nExpected output:\n```\nVersion <version-number>\n```\n\n### Verify MCP Connection\n\nTest that the MCP server starts correctly:\n\n```bash\nplaywright --help\n```\n\n### Run Test Suite\n\nExecute the test suite to verify functionality:\n\n```bash\nnpm test\n```\n\nOnly proceed with deployment if all tests pass.\n\n资料来源：[CLAUDE.md:4-5]()\n\n## Package Scripts Reference\n\n| Script | Purpose |\n|--------|---------|\n| `npm run build` | Build the project (echoes \"OK\") |\n| `npm run lint` | Run update-readme.js script |\n| `npm run test` | Run all Playwright tests |\n| `npm run ctest` | Run Chrome tests only |\n| `npm run ftest` | Run Firefox tests only |\n| `npm run wtest` | Run WebKit tests only |\n| `npm run dtest` | Run Docker-based tests |\n| `npm run roll` | Update Playwright version |\n| `npm run npm-publish` | Lint, test, and publish |\n| `npm run docker-build` | Build Docker image |\n| `npm run docker-run` | Run Docker container |\n| `npm run docker-rm` | Remove Docker container |\n\n资料来源：[package.json:18-35]()\n\n## Troubleshooting\n\n### Node.js Version Error\n\nIf you see an engine version error, ensure you have Node.js 18 or later:\n\n```bash\nnode --version\n# Should be >= 18.0.0\n```\n\n### Browser Installation Failure\n\nIf browser installation fails, try with elevated permissions or check network connectivity:\n\n```bash\nnpx playwright install --with-deps\n```\n\n### Test Failures\n\n1. Ensure all dependencies are installed: `npm ci`\n2. Ensure browsers are installed: `npx playwright install`\n3. Verify Node.js version: `node --version`\n4. Clear any cached state and retry\n\n### Permission Errors\n\nFor global installations, you may need sudo on Unix systems:\n\n```bash\nsudo npm install -g @playwright/mcp\n```\n\nOr use a Node version manager like `nvm` to avoid permission issues.\n\n---\n\n<a id='client-integration'></a>\n\n## MCP Client Integration\n\n### 相关页面\n\n相关主题：[Installation Guide](#installation-guide), [Browser Configuration](#browser-configuration)\n\n<details>\n<summary>Relevant Source Files</summary>\n\n以下源码文件用于生成本页说明：\n\n- [config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n- [server.json](https://github.com/microsoft/playwright-mcp/blob/main/server.json)\n- [package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n- [cli.js](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)\n- [CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n- [update-readme.js](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)\n- [playwright.config.ts](https://github.com/microsoft/playwright-mcp/blob/main/playwright.config.ts)\n</details>\n\n# MCP Client Integration\n\n## Overview\n\nMCP Client Integration refers to the mechanism by which the Playwright MCP (Model Context Protocol) server exposes browser automation capabilities as tools that can be consumed by LLM clients. The integration provides a bridge between the MCP protocol and Playwright's browser automation APIs, enabling AI agents to control browsers through a standardized interface.\n\nThe MCP server implementation has been moved to the [Playwright monorepo](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/mcp), while this repository (`microsoft/playwright-mcp`) serves as a distribution package and coordination point for the MCP tooling.\n\n资料来源：[src/README.md](https://github.com/microsoft/playwright-mcp/blob/main/src/README.md)\n\n## Architecture\n\n### System Components\n\nThe MCP Client Integration consists of several interconnected components:\n\n```mermaid\ngraph TD\n    A[\"MCP Client<br/>(LLM Agent)\"] --> B[\"Playwright MCP Server\"]\n    B --> C[\"playwright-core<br/>coreBundle\"]\n    B --> D[\"playwright-core<br/>tools Bundle\"]\n    C --> E[\"Browser Process\"]\n    D --> E\n    E --> F[\"Page/Document\"]\n    \n    G[\"CLI Entry Point<br/>(cli.js)\"] --> B\n    H[\"Configuration<br/>(config.d.ts)\"] --> B\n    I[\"server.json<br/>(Transport Config)\"] --> B\n```\n\n### Transport Layer\n\nThe MCP server uses STDIO transport by default, as specified in the server manifest:\n\n```json\n{\n  \"transport\": {\n    \"type\": \"stdio\"\n  }\n}\n```\n\n资料来源：[server.json:13](https://github.com/microsoft/playwright-mcp/blob/main/server.json)\n\n## Configuration Reference\n\n### Config Type Definition\n\nThe `Config` type in `config.d.ts` defines all available configuration options for the MCP server:\n\n```typescript\nexport type ToolCapability =\n  | 'config'\n  | 'core'\n  | 'core-navigation'\n  | 'core-tabs'\n  | 'core-input'\n  | 'core-install'\n  | 'network'\n  | 'pdf'\n  | 'storage'\n  | 'testing'\n  | 'vision'\n  | 'devtools';\n```\n\n资料来源：[config.d.ts:20-30](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n### Configuration Options Table\n\n| Category | Option | Type | Default | Description |\n|----------|--------|------|---------|-------------|\n| **Browser** | `browser.browserName` | `'chromium' \\| 'firefox' \\| 'webkit'` | - | Browser type to use |\n| **Browser** | `browser.isolated` | `boolean` | - | Keep profile in memory only |\n| **Browser** | `browser.userDataDir` | `string` | - | Persistent profile directory |\n| **Browser** | `browser.launchOptions` | `object` | - | Browser launch options |\n| **Network** | `network.allowedOrigins` | `string[]` | All | Allowed request origins |\n| **Network** | `network.blockedOrigins` | `string[]` | - | Blocked request origins |\n| **Timeouts** | `timeouts.action` | `number` | 5000ms | Default action timeout |\n| **Timeouts** | `timeouts.navigation` | `number` | 60000ms | Default navigation timeout |\n| **Timeouts** | `timeouts.expect` | `number` | 5000ms | Default expect timeout |\n| **Output** | `imageResponses` | `'allow' \\| 'omit' \\| 'auto'` | `'auto'` | Image response handling |\n| **Output** | `outputDir` | `string` | - | Directory for output files |\n| **Session** | `saveSession` | `boolean` | - | Save Playwright session to output |\n| **Session** | `sharedBrowserContext` | `boolean` | - | Reuse context between clients |\n| **Server** | `server.port` | `number` | - | SSE/MCP transport port |\n| **Server** | `server.host` | `string` | - | Server bind host |\n| **Server** | `server.allowedHosts` | `string[]` | - | Allowed serving hosts |\n\n资料来源：[config.d.ts:31-150](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n### Secrets Management\n\nThe configuration supports secrets replacement for sensitive data:\n\n```typescript\nsecrets?: Record<string, string>;\n```\n\nSecrets are used to replace matching plain text in tool responses to prevent LLMs from accidentally receiving sensitive information. This is a convenience feature, not a security mechanism.\n\n资料来源：[config.d.ts:145-150](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Capabilities System\n\n### Capability Types\n\nCapabilities control which tool categories are exposed to the MCP client:\n\n| Capability | Purpose |\n|------------|---------|\n| `core` | Core browser automation features |\n| `core-navigation` | Navigation-related tools |\n| `core-tabs` | Tab management tools |\n| `core-input` | Input handling tools |\n| `core-install` | Browser installation tools |\n| `network` | Network request/response tools |\n| `pdf` | PDF generation and manipulation |\n| `storage` | Storage/state management tools |\n| `testing` | Testing utilities |\n| `vision` | Coordinate-based interactions |\n| `devtools` | Developer tools features |\n| `config` | Configuration tools |\n\n资料来源：[config.d.ts:20-29](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n### Capability Enablement\n\nCapabilities are specified in the `capabilities` array:\n\n```typescript\ncapabilities?: ToolCapability[];\n```\n\nOnly listed capabilities will be enabled. If not specified, all capabilities may be available.\n\n## Tool Schema and Generation\n\n### Tool Information Extraction\n\nThe `update-readme.js` script parses compiled modules to extract tool information for documentation:\n\n```javascript\nasync function updateTools(content) {\n  console.log('Loading tool information from compiled modules...');\n  const generatedLines = /** @type {string[]} */ ([]);\n  for (const [capability, tools] of Object.entries(toolsByCapability)) {\n    generatedLines.push(`<details>\\n<summary><b>${capability}</b></summary>`);\n    for (const tool of tools)\n      generatedLines.push(...formatToolForReadme(tool.schema));\n    generatedLines.push(`</details>`);\n  }\n  // ...\n}\n```\n\n资料来源：[update-readme.js:95-108](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)\n\n### Tool Schema Structure\n\nEach tool follows a standardized schema format:\n\n```javascript\nfunction formatToolForReadme(tool) {\n  const lines = /** @type {string[]} */ ([]);\n  lines.push(`- **${tool.name}**`);\n  lines.push(`  - Title: ${tool.title}`);\n  lines.push(`  - Description: ${tool.description}`);\n  \n  const inputSchema = tool.inputSchema ? tool.inputSchema.toJSONSchema() : {};\n  if (inputSchema.properties) {\n    lines.push(`  - Parameters:`);\n    Object.entries(inputSchema.properties).forEach(([name, param]) => {\n      lines.push(`    - \\`${name}\\`: ${param.description}`);\n    });\n  }\n  lines.push(`  - Read-only: **${tool.type === 'readOnly'}**`);\n  return lines;\n}\n```\n\n资料来源：[update-readme.js:145-167](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)\n\n### Config Schema Documentation\n\nThe config schema is extracted from `config.d.ts` and embedded into README:\n\n```javascript\nasync function updateConfig(content) {\n  const configPath = path.join(__dirname, 'config.d.ts');\n  const configContent = await fs.promises.readFile(configPath, 'utf-8');\n  const configTypeMatch = configContent.match(/export type Config = (\\{[\\s\\S]*?\\n\\});/);\n  // ...\n}\n```\n\n资料来源：[update-readme.js:115-126](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)\n\n## CLI Interface\n\n### Command-Line Entry Point\n\nThe CLI is implemented in `cli.js` and provides the primary interface for running the MCP server:\n\n```javascript\nconst { program } = require('playwright-core/lib/utilsBundle');\nconst { tools, libCli } = require('playwright-core/lib/coreBundle');\n\nconst packageJSON = require('./package.json');\nconst p = program.version('Version ' + packageJSON.version).name('Playwright MCP');\ntools.decorateMCPCommand(p, packageJSON.version);\n\nvoid program.parseAsync(process.argv);\n```\n\n资料来源：[cli.js:24-33](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)\n\n### CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `install-browser` | Install Playwright browsers |\n| MCP tools | Exposed via decorated command |\n\nThe CLI leverages Playwright's built-in command decoration system from `playwright-core`:\n\n```javascript\ntools.decorateMCPCommand(p, packageJSON.version);\n```\n\n资料来源：[cli.js:29](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)\n\n### CLI Options Generation\n\nOptions are dynamically generated from the CLI help output:\n\n```javascript\nasync function updateOptions(content) {\n  execSync('node cli.js --help > help.txt');\n  const lines = output.toString().split('\\n');\n  // Parse option lines starting with '  --'\n  for (let line of lines) {\n    if (line.startsWith('  --')) {\n      const l = line.substring('  --'.length);\n      const gapIndex = l.indexOf('  ');\n      const name = l.substring(0, gapIndex).trim();\n      const value = l.substring(gapIndex).trim();\n      options.push({ name, value });\n    }\n  }\n}\n```\n\n资料来源：[update-readme.js:52-65](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)\n\n## Testing\n\n### Test Configuration\n\nThe project uses Playwright's test framework with a dedicated MCP test configuration:\n\n```typescript\nimport { defineConfig } from '@playwright/test';\n\nexport default defineConfig<TestOptions>({\n  testDir: './tests',\n  fullyParallel: true,\n  forbidOnly: !!process.env.CI,\n  workers: process.env.CI ? 2 : undefined,\n  reporter: 'list',\n  projects: [\n    { name: 'chrome' },\n  ],\n});\n```\n\n资料来源：[playwright.config.ts:17-30](https://github.com/microsoft/playwright-mcp/blob/main/playwright.config.ts)\n\n### Test Commands\n\n| Command | Description |\n|---------|-------------|\n| `npm test` | Run all MCP tests |\n| `npm run ctest` | Run tests in Chromium only |\n| `npm run ftest` | Run tests in Firefox only |\n| `npm run wtest` | Run tests in WebKit only |\n| `npm run dtest` | Run tests in Docker (Chromium) |\n\n资料来源：[package.json:15-22](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n\n### Test Requirements\n\nTests must be:\n- **Hermetic**: No external service dependencies\n- **Cross-platform**: Work on macOS, Linux, and Windows\n- **Covered by tests**: New functionality requires corresponding tests\n\n资料来源：[CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n\n## Workflow: README Generation\n\nThe README is auto-generated from multiple sources:\n\n```mermaid\ngraph LR\n    A[\"config.d.ts\"] --> D[\"updateReadme()\"]\n    B[\"CLI --help\"] --> D\n    C[\"Tool Schemas\"] --> D\n    D --> E[\"README.md\"]\n```\n\n### Generation Pipeline\n\n```javascript\nasync function updateReadme() {\n  const readmePath = path.join(__dirname, 'README.md');\n  const readmeContent = await fs.promises.readFile(readmePath, 'utf-8');\n  const withTools = await updateTools(readmeContent);\n  const withOptions = await updateOptions(withTools);\n  const withConfig = await updateConfig(withOptions);\n  await fs.promises.writeFile(readmePath, withConfig, 'utf-8');\n}\n```\n\n资料来源：[update-readme.js:130-139](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)\n\n## Development Workflow\n\n### Local Development\n\n```bash\n# Clone the Playwright monorepo (source location)\ngit clone https://github.com/microsoft/playwright\ncd playwright\n\n# Install dependencies and run watch mode\nnpm ci\nnpm run watch\nnpx playwright install\n\n# Navigate to MCP source\ncd packages/playwright/src/mcp\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n\n### Rolling Playwright Updates\n\nThe repository maintains synchronization with the Playwright core:\n\n```bash\n# Run roll script to update dependencies\nnpm run roll\n# This bumps playwright, playwright-core, @playwright/test\n# Refreshes config.d.ts\n# Regenerates README\n```\n\n资料来源：[CLAUDE.md](https://github.com/microsoft/playwright-mcp/blob/main/CLAUDE.md)\n\n### Linting\n\nBefore submitting changes, run the linter:\n\n```bash\nnpm run lint\n```\n\nThis executes `update-readme.js` to validate and regenerate documentation.\n\n资料来源：[package.json:14](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n\n## Package Information\n\n### NPM Package Details\n\n| Property | Value |\n|----------|-------|\n| Package Name | `@playwright/mcp` |\n| MCP Name | `io.github.microsoft/playwright-mcp` |\n| Node Engine | `>=18` |\n| License | Apache-2.0 |\n| Transport | STDIO |\n\n资料来源：[package.json:1-12](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n\n---\n\n<a id='browser-configuration'></a>\n\n## Browser Configuration\n\n### 相关页面\n\n相关主题：[User Profiles and Session Management](#user-profiles), [Security Settings](#security-settings)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n- [playwright.config.ts](https://github.com/microsoft/playwright-mcp/blob/main/playwright.config.ts)\n- [README.md](https://github.com/microsoft/playwright-mcp/blob/main/README.md)\n- [package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n- [cli.js](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)\n</details>\n\n# Browser Configuration\n\n## Overview\n\nBrowser Configuration in playwright-mcp defines how the Playwright MCP server manages browser instances for automation tasks. The configuration is defined through the `Config` type in `config.d.ts` and controls browser selection, launch behavior, session persistence, and security policies.\n\n资料来源：[config.d.ts:48-120]()\n\n```mermaid\ngraph TD\n    A[Browser Configuration] --> B[Browser Selection]\n    A --> C[Launch Options]\n    A --> D[Session Management]\n    A --> E[Network Security]\n    A --> F[Server Binding]\n    \n    B --> B1[chromium]\n    B --> B2[firefox]\n    B --> B3[webkit]\n    \n    C --> C1[User Data Dir]\n    C --> C2[Init Scripts]\n    C --> C3[Launch Params]\n```\n\n## Browser Type Selection\n\n### Supported Browsers\n\nThe configuration supports three browser engines:\n\n| Browser | Identifier | Notes |\n|---------|------------|-------|\n| Chromium | `chromium` | Default, best compatibility |\n| Firefox | `firefox` | Gecko-based engine |\n| WebKit | `webkit` | Safari engine port |\n\n资料来源：[config.d.ts:57-64]()\n\n### Configuration Properties\n\n```typescript\nbrowser?: {\n  browserName?: 'chromium' | 'firefox' | 'webkit';\n  isolated?: boolean;\n  userDataDir?: string;\n  launchOptions?: Record<string, any>;\n  initPage?: string[];\n  initScript?: string[];\n}\n```\n\n| Property | Type | Default | Description |\n|----------|------|---------|-------------|\n| `browserName` | `'chromium' \\| 'firefox' \\| 'webkit'` | `chromium` | Browser engine to launch |\n| `isolated` | `boolean` | `false` | Keep browser profile in memory only |\n| `userDataDir` | `string` | system temp | Custom profile directory path |\n| `launchOptions` | `Record<string, any>` | `{}` | Playwright launch options |\n| `initPage` | `string[]` | `[]` | TypeScript initialization scripts |\n| `initScript` | `string[]` | `[]` | JavaScript initialization scripts |\n\n资料来源：[config.d.ts:48-87]()\n\n## Profile Management\n\n### Isolated Mode\n\nWhen `isolated: true`, the browser profile is kept entirely in memory without persisting to disk. This provides:\n\n- Better privacy between sessions\n- Clean state for each automation run\n- No leftover browser data\n\n### Custom User Data Directory\n\nThe `userDataDir` option allows specifying a persistent profile location:\n\n```typescript\n{\n  browser: {\n    userDataDir: '/path/to/custom/profile'\n  }\n}\n```\n\nIf not specified, the system creates a temporary directory automatically.\n\n资料来源：[config.d.ts:68-75]()\n\n## Initialization Scripts\n\nInitialization scripts run before any page content, enabling you to inject polyfills, modify prototypes, or set up testing utilities.\n\n### TypeScript Scripts (`initPage`)\n\nPaths to TypeScript files that are added as initialization scripts:\n\n```typescript\n{\n  browser: {\n    initPage: ['./setup.ts', './fixtures.ts']\n  }\n}\n```\n\n### JavaScript Scripts (`initScript`)\n\nPaths to JavaScript files evaluated in every page before page scripts:\n\n```typescript\n{\n  browser: {\n    initScript: ['./polyfills.js', './mocks.js']\n  }\n}\n```\n\nBoth script types are evaluated in every page created within the browser context.\n\n资料来源：[config.d.ts:81-87]()\n\n## Extension Support\n\nPlaywright MCP can connect to a running browser instance using the Playwright Extension (Chrome/Edge only):\n\n```typescript\n{\n  extension: true\n}\n```\n\nWhen `extension` is enabled:\n- The `browser` configuration is ignored\n- Requires the \"Playwright Extension\" browser add-on to be installed\n- Connects to the browser's debugging port\n\n资料来源：[config.d.ts:89-93]()\n\n## Server Configuration\n\nThe server section controls network binding for the MCP transport:\n\n```typescript\nserver?: {\n  port?: number;\n  host?: string;\n  allowedHosts?: string[];\n}\n```\n\n| Property | Type | Default | Description |\n|----------|------|---------|-------------|\n| `port` | `number` | undefined | Port for SSE or MCP transport |\n| `host` | `string` | `localhost` | Bind address; use `0.0.0.0` for all interfaces |\n| `allowedHosts` | `string[]` | server host | DNS rebinding protection |\n\n资料来源：[config.d.ts:95-107]()\n\n## Capability Management\n\nCapabilities control which tool sets are enabled for the MCP server:\n\n```typescript\ncapabilities?: ToolCapability[];\n```\n\n| Capability | Description |\n|-------------|-------------|\n| `config` | Configuration tools |\n| `core` | Core browser automation |\n| `core-navigation` | Navigation operations |\n| `core-tabs` | Tab management |\n| `core-input` | Input handling |\n| `core-install` | Browser installation |\n| `network` | Network request tools |\n| `pdf` | PDF generation |\n| `storage` | Storage APIs |\n| `testing` | Testing utilities |\n| `vision` | Coordinate-based interactions |\n| `devtools` | Developer tools |\n\n资料来源：[config.d.ts:33-46]()\n\n## Session Management\n\n### Save Session\n\nWhen enabled, the Playwright session state is persisted to the output directory:\n\n```typescript\n{\n  saveSession: true\n}\n```\n\n资料来源：[config.d.ts:115-117]()\n\n### Shared Browser Context\n\nMultiple HTTP clients can share the same browser context:\n\n```typescript\n{\n  sharedBrowserContext: true\n}\n```\n\nThis is useful for environments where multiple requests need to share session state.\n\n资料来源：[config.d.ts:119-121]()\n\n## Security Configuration\n\n### Network Origins\n\nControl which origins the browser can request:\n\n```typescript\nnetwork?: {\n  allowedOrigins?: string[];\n  blockedOrigins?: string[];\n}\n```\n\n**Supported formats:**\n- Full origin: `https://example.com:8080` - matches only that exact origin\n- Wildcard port: `http://localhost:*` - matches any port on localhost with http\n\nOrigins matching both lists will be blocked.\n\n资料来源：[config.d.ts:151-165]()\n\n### Secrets Management\n\nSecrets replace matching plain text in tool responses to prevent sensitive data exposure:\n\n```typescript\n{\n  secrets: {\n    API_KEY: 'sk-xxxxx',\n    DB_PASSWORD: 'secret123'\n  }\n}\n```\n\n> Note: This is a convenience feature, not a security measure. Always examine incoming data.\n\n资料来源：[config.d.ts:123-129]()\n\n### Console Level\n\nControl console message verbosity:\n\n```typescript\nconsole?: {\n  level?: 'error' | 'warning' | 'info' | 'debug';\n}\n```\n\nEach level includes messages from more severe levels. Defaults to `info`.\n\n资料来源：[config.d.ts:140-146]()\n\n## Timeout Configuration\n\nConfigure default timeouts for various operations:\n\n```typescript\ntimeouts?: {\n  action?: number;      // Default: 5000ms\n  navigation?: number; // Default: 60000ms\n  expect?: number;     // Default: 5000ms\n}\n```\n\n资料来源：[config.d.ts:131-144]()\n\n## Test Configuration\n\nThe test suite uses a dedicated Playwright configuration:\n\n```typescript\n// playwright.config.ts\nexport default defineConfig<TestOptions>({\n  testDir: './tests',\n  fullyParallel: true,\n  forbidOnly: !!process.env.CI,\n  workers: process.env.CI ? 2 : undefined,\n  projects: [\n    { name: 'chrome' },\n    ...process.env.MCP_IN_DOCKER ? [{\n      name: 'chromium-docker',\n      grep: /browser_navigate|browser_click/,\n      use: {\n        mcpBrowser: 'chromium',\n        mcpMode: 'docker' as const\n      }\n    }] : [],\n  ],\n});\n```\n\nThe configuration supports:\n- Running tests across browser projects\n- Docker-based testing environment\n- CI-specific constraints (`forbidOnly`, limited workers)\n\n资料来源：[playwright.config.ts:1-34]()\n\n## CLI Usage\n\nThe CLI provides commands for running and managing the MCP server:\n\n```bash\n# Run with custom config\nnpx playwright-mcp --config my-config.json\n\n# Install browser\nnpx playwright-mcp install-browser\n```\n\nThe CLI is decorated using Playwright's core tools and supports the MCP transport protocol.\n\n资料来源：[cli.js:1-35]()\n\n## Complete Configuration Example\n\n```typescript\nimport type { Config } from './config';\n\nconst config: Config = {\n  browser: {\n    browserName: 'chromium',\n    isolated: true,\n    initScript: ['./setup.js'],\n  },\n  server: {\n    port: 8080,\n    host: 'localhost',\n  },\n  capabilities: ['core', 'network', 'pdf'],\n  saveSession: false,\n  sharedBrowserContext: true,\n  secrets: {\n    API_KEY: process.env.API_KEY || '',\n  },\n  outputDir: './output',\n  network: {\n    allowedOrigins: ['https://example.com'],\n    blockedOrigins: ['https://malicious.com'],\n  },\n  console: {\n    level: 'info',\n  },\n  timeouts: {\n    action: 5000,\n    navigation: 30000,\n    expect: 3000,\n  },\n};\n```\n\n## Configuration Schema Summary\n\n| Section | Key Properties | File Source |\n|---------|----------------|-------------|\n| Browser | `browserName`, `isolated`, `userDataDir`, `launchOptions` | `config.d.ts:48-87` |\n| Extension | `extension: boolean` | `config.d.ts:89-93` |\n| Server | `port`, `host`, `allowedHosts` | `config.d.ts:95-107` |\n| Capabilities | `capabilities[]` | `config.d.ts:109-113` |\n| Session | `saveSession`, `sharedBrowserContext` | `config.d.ts:115-121` |\n| Security | `secrets`, `network` | `config.d.ts:123-165` |\n| Timeouts | `timeouts.action`, `timeouts.navigation`, `timeouts.expect` | `config.d.ts:131-144` |\n| Console | `console.level` | `config.d.ts:140-146` |\n\n## Related Commands\n\n| Command | Purpose |\n|---------|---------|\n| `npm run roll` | Update Playwright version and regenerate config |\n| `npm test` | Run test suite across all browsers |\n| `npm run ctest` | Run tests in Chromium only |\n| `npm run docker-run` | Start MCP in Docker container |\n\n资料来源：[package.json:8-27]()\n\n---\n\n<a id='security-settings'></a>\n\n## Security Settings\n\n### 相关页面\n\n相关主题：[Browser Configuration](#browser-configuration), [Docker Deployment](#docker-deployment)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n- [SECURITY.md](https://github.com/microsoft/playwright-mcp/blob/main/SECURITY.md)\n- [README.md](https://github.com/microsoft/playwright-mcp/blob/main/README.md)\n- [package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n- [playwright.config.ts](https://github.com/microsoft/playwright-mcp/blob/main/playwright.config.ts)\n</details>\n\n# Security Settings\n\nPlaywright MCP provides comprehensive security settings to protect sensitive data, control browser access, and prevent unauthorized network requests. These settings are configurable through the `Config` type defined in `config.d.ts`.\n\n## Overview\n\nThe Playwright MCP server handles browser automation with built-in security mechanisms that address common attack vectors including:\n\n- DNS rebinding attacks\n- Unauthorized network access\n- Sensitive data exposure\n- Session hijacking\n\nAll security configurations are optional and have sensible defaults. Administrators should review and configure these settings based on their deployment environment and security requirements.\n\n## Configuration Schema\n\nSecurity settings are defined within the main `Config` type. The following table summarizes available security-related configuration options:\n\n| Configuration Section | Purpose | Default |\n|----------------------|---------|---------|\n| `browser.isolated` | Keep browser profile in memory | `false` |\n| `browser.userDataDir` | Browser profile storage location | Temporary directory |\n| `network.allowedOrigins` | Permitted request origins | All origins |\n| `network.blockedOrigins` | Blocked request origins | None |\n| `secrets` | Sensitive data replacement | None |\n| `server.allowedHosts` | DNS rebinding protection | Server host only |\n| `console.level` | Console message filtering | `\"info\"` |\n| `imageResponses` | Image response handling | `\"auto\"` |\n\n## Network Security\n\n### Origin-Based Access Control\n\nPlaywright MCP implements origin-based network filtering to control which websites the browser can access.\n\n```typescript\nnetwork?: {\n  allowedOrigins?: string[];\n  blockedOrigins?: string[];\n};\n```\n\n**Supported Formats:**\n\n| Format | Example | Description |\n|--------|---------|-------------|\n| Full origin | `https://example.com:8080` | Matches exact origin with port |\n| Wildcard port | `http://localhost:*` | Matches any port on localhost with HTTP |\n| Protocol wildcard | `https://*` | Matches any origin with HTTPS |\n\n**Origin Matching Rules:**\n\n1. Origins specified in `blockedOrigins` take precedence over `allowedOrigins`\n2. If an origin matches both lists, it will be **blocked**\n3. If only `allowedOrigins` is set, only those origins are accessible\n4. If only `blockedOrigins` is set, all origins except blocked are accessible\n5. If neither is set, all origins are accessible\n\n**Example Configuration:**\n\n```typescript\n{\n  network: {\n    // Allow only specific domains\n    allowedOrigins: [\n      'https://myapp.example.com',\n      'https://api.example.com:8080',\n      'http://localhost:*'  // Allow any localhost port for development\n    ],\n    // Block specific origins\n    blockedOrigins: [\n      'https://malicious-site.com'\n    ]\n  }\n}\n```\n\n### Browser Isolation\n\nBrowser isolation ensures that browser profiles and session data are not persisted to disk, reducing the attack surface.\n\n```typescript\nbrowser?: {\n  browserName?: 'chromium' | 'firefox' | 'webkit';\n  isolated?: boolean;\n  userDataDir?: string;\n};\n```\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `isolated` | `boolean` | When `true`, keeps browser profile in memory without disk persistence |\n| `userDataDir` | `string` | Custom path for browser profile storage |\n\n**Security Implications:**\n\n- `isolated: true` - Maximum security, no persistent data\n- `isolated: false` - Session persistence, faster subsequent launches\n\n## Secrets Management\n\nThe secrets configuration provides a convenience mechanism to redact sensitive information from tool responses before they reach the client.\n\n```typescript\nsecrets?: Record<string, string>;\n```\n\n**How It Works:**\n\n1. Define key-value pairs where the key is the pattern to find and value is the replacement\n2. All occurrences of the key in tool response text are replaced with the value\n3. This is a **convenience feature**, not a security boundary\n\n**Important Security Note:**\n\n> Secrets are used to replace matching plain text in the tool responses to prevent the LLM from accidentally getting sensitive data. It is a convenience and not a security feature, make sure to always examine information coming in and from the tool on the client.\n> 资料来源：[config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n**Example Configuration:**\n\n```typescript\n{\n  secrets: {\n    'sk-1234567890abcdef': '[API_KEY_REDACTED]',\n    'my-secret-token': '[TOKEN_REDACTED]',\n    'password123': '[PASSWORD_REDACTED]'\n  }\n}\n```\n\n### Data Flow Diagram\n\n```mermaid\ngraph TD\n    A[Browser Automation] --> B[Tool Response Generated]\n    B --> C{Secrets Configured?}\n    C -->|Yes| D[Scan Response for Secret Patterns]\n    C -->|No| E[Return Original Response]\n    D --> F{Pattern Match Found?}\n    F -->|Yes| G[Replace with Redacted Value]\n    F -->|No| E\n    G --> H[Return Sanitized Response]\n    E --> H\n```\n\n## Server Security\n\n### Host-Based Access Control\n\nThe server configuration includes protection against DNS rebinding attacks through the `allowedHosts` option.\n\n```typescript\nserver?: {\n  port?: number;\n  host?: string;\n  allowedHosts?: string[];\n};\n```\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `port` | `number` | 8080 | Port to listen on |\n| `host` | `string` | localhost | Binding interface |\n| `allowedHosts` | `string[]` | Server host | Hosts allowed to connect |\n\n**DNS Rebinding Protection:**\n\nThe `allowedHosts` setting protects against DNS rebinding attacks where a malicious domain resolves to your server's IP address. By default, only the host the server is bound to is allowed.\n\n**Example Configuration:**\n\n```typescript\n{\n  server: {\n    port: 8080,\n    host: '0.0.0.0',  // Bind to all interfaces\n    allowedHosts: [\n      'localhost',\n      '127.0.0.1',\n      'my-secure-domain.com'\n    ]\n  }\n}\n```\n\n## Console Security\n\nConsole message filtering controls what level of browser console output is exposed to clients.\n\n```typescript\nconsole?: {\n  level?: 'error' | 'warning' | 'info' | 'debug';\n};\n```\n\n**Log Levels:**\n\n| Level | Includes | Description |\n|-------|----------|-------------|\n| `error` | Error messages only | Most restrictive |\n| `warning` | Errors + Warnings | Recommended for production |\n| `info` | Errors + Warnings + Info | Default level |\n| `debug` | All messages | Development only |\n\n**Security Consideration:**\n\nLower log levels reduce information leakage but may hide important diagnostic information. Choose the appropriate level based on your environment.\n\n## Image Response Handling\n\nControl how image responses are handled to prevent potential information disclosure through image metadata.\n\n```typescript\nimageResponses?: 'allow' | 'omit' | 'auto';\n```\n\n| Option | Description |\n|--------|-------------|\n| `allow` | Always send image responses to client |\n| `omit` | Never send image responses |\n| `auto` | Send images only if client can display them (default) |\n\n## Timeouts and Resource Limits\n\nTimeouts help prevent resource exhaustion attacks and ensure predictable behavior.\n\n```typescript\ntimeouts?: {\n  action?: number;      // Default: 5000ms\n  navigation?: number; // Default: 60000ms\n  expect?: number;     // Default: 5000ms\n};\n```\n\n**Security Benefits:**\n\n- Prevents hanging operations from consuming resources\n- Limits exposure time for potentially malicious pages\n- Enables faster failure detection\n\n## Security Architecture\n\n```mermaid\ngraph TD\n    subgraph \"Client Layer\"\n        A[MCP Client]\n    end\n    \n    subgraph \"Security Middleware\"\n        B[Host Validation]\n        C[Origin Filtering]\n        D[Secrets Replacement]\n    end\n    \n    subgraph \"Browser Layer\"\n        E[Playwright Browser]\n        F[Isolated Context]\n    end\n    \n    A --> B\n    B --> C\n    C --> D\n    D --> E\n    E --> F\n    \n    style A fill:#f9f,stroke:#333\n    style B fill:#ff9,stroke:#333\n    style C fill:#ff9,stroke:#333\n    style D fill:#ff9,stroke:#333\n```\n\n## Security Best Practices\n\n### Production Deployment\n\n1. **Enable Browser Isolation**\n   ```typescript\n   { browser: { isolated: true } }\n   ```\n\n2. **Configure Origin Restrictions**\n   ```typescript\n   { network: { allowedOrigins: ['https://your-domain.com'] } }\n   ```\n\n3. **Use Appropriate Console Level**\n   ```typescript\n   { console: { level: 'warning' } }  // Production\n   ```\n\n4. **Set Server Host Restrictions**\n   ```typescript\n   { server: { allowedHosts: ['your-domain.com'] } }\n   ```\n\n5. **Configure Reasonable Timeouts**\n   ```typescript\n   { timeouts: { action: 5000, navigation: 30000 } }\n   ```\n\n### Development Considerations\n\n- Use `console.level: 'debug'` only in development\n- Consider `imageResponses: 'auto'` for performance\n- Use `isolated: false` for faster iteration\n\n## Reporting Security Issues\n\nMicrosoft maintains a security response process for reporting vulnerabilities.\n\n**Please do not report security vulnerabilities through public GitHub issues.**\n\nInstead, report them to the Microsoft Security Response Center (MSRC):\n\n- **Online:** [https://msrc.microsoft.com/create-report](https://aka.ms/security.md/msrc/create-report)\n- **Email:** [secure@microsoft.com](mailto:secure@microsoft.com) (PGP encryption available)\n\nResponse timeline: You should receive a response within 24 hours.\n 资料来源：[SECURITY.md](https://github.com/microsoft/playwright-mcp/blob/main/SECURITY.md)\n\n## Complete Security Configuration Example\n\n```typescript\nimport { createConnection } from '@playwright/mcp';\n\nconst connection = createConnection({\n  browser: {\n    browserName: 'chromium',\n    isolated: true  // Maximum security\n  },\n  \n  network: {\n    allowedOrigins: [\n      'https://trusted-app.example.com',\n      'http://localhost:*'  // Development only\n    ],\n    blockedOrigins: [\n      'https://untrusted-source.com'\n    ]\n  },\n  \n  secrets: {\n    'sk-api-key': '[REDACTED]',\n    'password': '[REDACTED]'\n  },\n  \n  server: {\n    port: 8080,\n    host: '127.0.0.1',\n    allowedHosts: ['localhost', '127.0.0.1']\n  },\n  \n  console: {\n    level: 'warning'  // Only errors and warnings\n  },\n  \n  imageResponses: 'auto',\n  \n  timeouts: {\n    action: 5000,\n    navigation: 30000,\n    expect: 3000\n  }\n});\n```\n\n## Related Documentation\n\n- [Playwright MCP README](https://github.com/microsoft/playwright-mcp/blob/main/README.md) - Main project documentation\n- [Config Type Definition](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts) - Complete configuration types\n- [Playwright Documentation](https://playwright.dev/docs/api/class-browser) - Browser automation reference\n\n---\n\n<a id='docker-deployment'></a>\n\n## Docker Deployment\n\n### 相关页面\n\n相关主题：[Programmatic Usage](#programmatic-usage), [Installation Guide](#installation-guide)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n- [CLAUDE.md](https://github.com/microsoft/playwright-mcp/blob/main/CLAUDE.md)\n- [package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n- [playwright.config.ts](https://github.com/microsoft/playwright-mcp/blob/main/playwright.config.ts)\n- [config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n</details>\n\n# Docker Deployment\n\nThis page documents the Docker deployment capabilities for Playwright MCP, including container-based development, testing, and runtime configuration.\n\n## Overview\n\nPlaywright MCP supports Docker-based deployment to provide isolated, consistent browser automation environments. The Docker integration enables:\n\n- Containerized browser testing\n- Isolated development environments\n- Consistent CI/CD pipelines\n- Cross-platform browser automation\n\nDocker support is configured through npm scripts defined in `package.json` and dedicated test configurations in `playwright.config.ts`.\n\n## Docker Scripts\n\nThe project provides three npm scripts for managing Docker containers:\n\n| Script | Command | Purpose |\n|--------|---------|---------|\n| `docker-build` | `docker build --no-cache -t playwright-mcp-dev:latest .` | Build the Docker image with no cache |\n| `docker-rm` | `docker rm playwright-mcp-dev` | Remove the existing container |\n| `docker-run` | `docker run -it -p 8080:8080 --name playwright-mcp-dev playwright-mcp-dev:latest` | Run the container interactively |\n\n### Building the Docker Image\n\n```bash\nnpm run docker-build\n```\n\nThis creates an image tagged as `playwright-mcp-dev:latest`. The `--no-cache` flag ensures a fresh build.\n\n### Running the Container\n\n```bash\nnpm run docker-run\n```\n\nThe container maps port 8080 for external access and runs in interactive mode (`-it`).\n\n### Cleaning Up\n\n```bash\nnpm run docker-rm\n```\n\nRemoves the container to allow fresh deployments.\n\n资料来源：[package.json:17-19](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n\n## Docker Test Configuration\n\nPlaywright MCP includes dedicated configuration for running tests within Docker containers using Chromium.\n\n### Chromium Docker Project\n\n```typescript\n{\n  name: 'chromium-docker',\n  grep: /browser_navigate|browser_click/,\n  use: {\n    mcpBrowser: 'chromium',\n    mcpMode: 'docker' as const\n  }\n}\n```\n\n| Parameter | Value | Description |\n|-----------|-------|-------------|\n| `name` | `chromium-docker` | Project identifier for Docker-based Chromium tests |\n| `grep` | `/browser_navigate\\|browser_click/` | Test filter for Docker-specific tests |\n| `mcpBrowser` | `chromium` | Browser type for Docker testing |\n| `mcpMode` | `docker` | Execution mode set to Docker |\n\n### Running Docker Tests\n\n```bash\nMCP_IN_DOCKER=1 playwright test --project=chromium-docker\n```\n\nThe `MCP_IN_DOCKER` environment variable enables Docker-specific test behavior.\n\n资料来源：[playwright.config.ts:27-34](https://github.com/microsoft/playwright-mcp/blob/main/playwright.config.ts)\n资料来源：[CONTRIBUTING.md:58-60](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n\n## Browser Configuration for Docker\n\nThe `config.d.ts` file defines browser options that can be configured for Docker deployments.\n\n### Browser Configuration Schema\n\n```typescript\nbrowser?: {\n  browserName?: 'chromium' | 'firefox' | 'webkit';\n  isolated?: boolean;\n  userDataDir?: string;\n  launchOptions?: Record<string, unknown>;\n};\n```\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `browserName` | `chromium \\| firefox \\| webkit` | Browser type to use in container |\n| `isolated` | `boolean` | Keep browser profile in memory (default: true for containers) |\n| `userDataDir` | `string` | Path to persist browser profile across sessions |\n| `launchOptions` | `Record<string, unknown>` | Browser-specific launch arguments |\n\n### Docker-Specific Browser Settings\n\nFor containerized environments, consider these recommended configurations:\n\n| Scenario | Recommended Settings |\n|----------|----------------------|\n| Ephemeral testing | `isolated: true`, no `userDataDir` |\n| Session persistence | `userDataDir: '/data/browser-profile'` |\n| Headless CI | `launchOptions: { headless: true }` |\n\n资料来源：[config.d.ts:28-45](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Network Configuration for Containers\n\nPlaywright MCP supports fine-grained network control for browser instances within Docker:\n\n### Allowed and Blocked Origins\n\n```typescript\nnetwork?: {\n  allowedOrigins?: string[];\n  blockedOrigins?: string[];\n};\n```\n\n| Parameter | Description |\n|-----------|-------------|\n| `allowedOrigins` | List of origins the browser is permitted to request |\n| `blockedOrigins` | List of origins to block (takes precedence over allowed) |\n\n### Origin Format Examples\n\n| Format | Example | Matches |\n|--------|---------|---------|\n| Full origin | `https://example.com:8080` | Exact origin and port |\n| Wildcard port | `http://localhost:*` | Any port on localhost with HTTP |\n| Protocol wildcard | `https://*.example.com` | All subdomains |\n\n> **Note:** Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.\n\n资料来源：[config.d.ts:70-85](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Server Configuration for Docker\n\nThe server can be configured to run within Docker containers:\n\n```typescript\nserver?: {\n  port?: number;\n  host?: string;\n  allowedHosts?: string[];\n};\n```\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `port` | `8080` | Port for SSE or MCP transport |\n| `host` | `localhost` | Bind address (use `0.0.0.0` for Docker) |\n| `allowedHosts` | Same as host | Allowed serving hosts (DNS rebinding protection) |\n\n### Docker Server Deployment\n\nFor containerized deployments, configure the server to bind to all interfaces:\n\n```typescript\n{\n  server: {\n    host: '0.0.0.0',\n    port: 8080,\n    allowedHosts: ['*']\n  }\n}\n```\n\n资料来源：[config.d.ts:117-130](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n    A[Developer Machine] --> B[Docker Container]\n    B --> C[Playwright MCP Server]\n    C --> D[Browser Instance]\n    D --> E[Web Application]\n    \n    F[CI/CD Pipeline] --> B\n    G[External Client] --> |HTTP:8080| B\n    \n    style B fill:#e1f5fe\n    style C fill:#f3e5f5\n    style D fill:#fff3e0\n```\n\n## Deployment Workflow\n\n```mermaid\ngraph LR\n    A[Build Image] --> B[Create Container]\n    B --> C[Run Tests or Server]\n    C --> D{Pass?}\n    D -->|Yes| E[Success]\n    D -->|No| F[Debug & Fix]\n    F --> A\n    \n    G[Clean Up] --> H[Remove Container]\n    G --> I[Remove Image]\n```\n\n## Environment Variables\n\n| Variable | Description | Example |\n|----------|-------------|---------|\n| `MCP_IN_DOCKER` | Enables Docker-specific test behavior | `1` |\n| `CI` | Indicates CI environment (limits workers) | `true` |\n\n资料来源：[CONTRIBUTING.md:58-60](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n资料来源：[playwright.config.ts:13](https://github.com/microsoft/playwright-mcp/blob/main/playwright.config.ts)\n\n## Complete Docker Workflow Example\n\n```bash\n# 1. Build the Docker image\nnpm run docker-build\n\n# 2. Remove any existing container\nnpm run docker-rm\n\n# 3. Run the container\nnpm run docker-run\n\n# 4. In another terminal, run Docker-specific tests\nMCP_IN_DOCKER=1 npm run dtest\n\n# 5. Clean up when done\nnpm run docker-rm\n```\n\n## Limitations and Considerations\n\n1. **No Dockerfile in Repository**: The repository does not include a `Dockerfile`. Users must create their own based on project requirements.\n2. **Browser Installation**: When building custom Docker images, ensure browsers are installed using `npx playwright install`.\n3. **Port Mapping**: The default configuration exposes port 8080; adjust as needed for your environment.\n4. **Browser Compatibility**: Docker testing is limited to Chromium (`chromium-docker` project).\n\n资料来源：[CLAUDE.md:11-16](https://github.com/microsoft/playwright-mcp/blob/main/CLAUDE.md)\n\n## Related Configuration\n\n| Configuration File | Purpose |\n|-------------------|---------|\n| `config.d.ts` | TypeScript definitions for all config options |\n| `playwright.config.ts` | Test runner configuration |\n| `package.json` | npm scripts for Docker operations |\n| `server.json` | MCP server metadata and transport |\n\n---\n\n<a id='programmatic-usage'></a>\n\n## Programmatic Usage\n\n### 相关页面\n\n相关主题：[Docker Deployment](#docker-deployment), [MCP Client Integration](#client-integration)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [index.js](https://github.com/microsoft/playwright-mcp/blob/main/index.js)\n- [cli.js](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)\n- [package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n- [config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n- [CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n- [src/README.md](https://github.com/microsoft/playwright-mcp/blob/main/src/README.md)\n</details>\n\n# Programmatic Usage\n\nThis page documents how to programmatically use Playwright MCP (Model Context Protocol) to integrate Playwright browser automation capabilities into your applications.\n\n## Overview\n\nPlaywright MCP provides browser automation tools that can be used by Large Language Models (LLMs) through the MCP protocol. The package exposes a `createConnection` function that enables programmatic integration with MCP-compatible clients.\n\nThe core implementation resides in the [Playwright monorepo](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/mcp), while this repository serves as the distribution package for the MCP tools.\n\n资料来源：[src/README.md:1-3](https://github.com/microsoft/playwright-mcp/blob/main/src/README.md)\n\n## Entry Points\n\nPlaywright MCP provides two primary entry points for programmatic usage:\n\n| Entry Point | File | Purpose |\n|-------------|------|---------|\n| Module | `index.js` | Programmatic import for Node.js applications |\n| CLI | `cli.js` | Command-line interface for direct execution |\n\n资料来源：[index.js:1-30](https://github.com/microsoft/playwright-mcp/blob/main/index.js)\n资料来源：[cli.js:1-45](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)\n\n### Module Import\n\nThe primary module export provides the `createConnection` function:\n\n```javascript\nconst { createConnection } = require('@playwright/mcp');\n```\n\n资料来源：[index.js:27-29](https://github.com/microsoft/playwright-mcp/blob/main/index.js)\n\nThe `createConnection` function is sourced from `playwright-core/lib/coreBundle`, which contains the core MCP implementation including tool definitions and connection handling logic.\n\n### CLI Usage\n\nThe CLI can be invoked directly via Node.js:\n\n```bash\nnode cli.js [command] [options]\n```\n\nThe CLI is decorated with Playwright's MCP command utilities, which handle transport negotiation and tool invocation.\n\n资料来源：[cli.js:24-28](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)\n\n## Configuration\n\nPlaywright MCP accepts configuration through the `Config` type defined in `config.d.ts`.\n\n### Tool Capabilities\n\nTool capabilities define which browser automation features are enabled:\n\n```typescript\nexport type ToolCapability =\n  | 'config'\n  | 'core'\n  | 'core-navigation'\n  | 'core-tabs'\n  | 'core-input'\n  | 'core-install'\n  | 'network'\n  | 'pdf'\n  | 'storage'\n  | 'testing'\n  | 'vision'\n  | 'devtools';\n```\n\n资料来源：[config.d.ts:17-30](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n| Capability | Description |\n|------------|-------------|\n| `core` | Core browser automation features |\n| `core-navigation` | Page navigation operations |\n| `core-tabs` | Browser tab management |\n| `core-input` | Input handling and form interaction |\n| `core-install` | Browser installation |\n| `network` | Network request interception |\n| `pdf` | PDF generation and manipulation |\n| `storage` | Local storage and session management |\n| `testing` | Test-related utilities |\n| `vision` | Coordinate-based interactions |\n| `devtools` | Developer tools features |\n| `config` | Configuration management |\n\n### Browser Configuration\n\n```typescript\nbrowser?: {\n  browserName?: 'chromium' | 'firefox' | 'webkit';\n  isolated?: boolean;\n  userDataDir?: string;\n  launchOptions?: object;\n}\n```\n\n资料来源：[config.d.ts:32-56](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n### Timeout Configuration\n\n```typescript\ntimeouts?: {\n  action?: number;      // Default: 5000ms\n  navigation?: number;  // Default: 60000ms\n  expect?: number;       // Default: 5000ms\n}\n```\n\n资料来源：[config.d.ts:98-110](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n### Server Configuration\n\n```typescript\nserver?: {\n  port?: number;\n  host?: string;\n  allowedHosts?: string[];\n}\n```\n\n资料来源：[config.d.ts:146-156](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Architecture\n\n```mermaid\ngraph TD\n    A[Client Application] -->|MCP Protocol| B[playwright-mcp]\n    B --> C[createConnection]\n    C --> D[playwright-core]\n    D --> E[Browser Automation]\n    E --> F[Chromium]\n    E --> G[Firefox]\n    E --> H[WebKit]\n    \n    I[CLI User] -->|cli.js| B\n    J[Module User] -->|index.js| B\n```\n\n## Available NPM Scripts\n\nThe `package.json` defines the following scripts for working with Playwright MCP:\n\n| Script | Command | Purpose |\n|--------|---------|---------|\n| `test` | `playwright test` | Run all tests |\n| `ctest` | `playwright test --project=chrome` | Run Chrome-only tests |\n| `ftest` | `playwright test --project=firefox` | Run Firefox-only tests |\n| `wtest` | `playwright test --project=webkit` | Run WebKit-only tests |\n| `lint` | `node update-readme.js` | Regenerate README |\n| `build` | `echo OK` | Build step (no-op) |\n| `roll` | `node roll.js` | Update Playwright version |\n\n资料来源：[package.json:13-24](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n\n## Package Metadata\n\n| Property | Value |\n|----------|-------|\n| Package Name | `@playwright/mcp` |\n| MCP Name | `io.github.microsoft/playwright-mcp` |\n| Node.js Requirement | `>=18` |\n| License | Apache-2.0 |\n\n资料来源：[package.json:1-16](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n\n## Browser Installation\n\nPlaywright MCP supports an `install-browser` command through the CLI:\n\n```bash\nnode cli.js install-browser\n```\n\nThis delegates to Playwright's browser installation mechanism, decorated via `libCli.decorateProgram`.\n\n资料来源：[cli.js:17-22](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)\n\n## Extension Mode\n\nPlaywright MCP supports connecting to a running browser instance through the Microsoft Edge/Chrome Playwright Extension:\n\n```typescript\nextension?: boolean;\n```\n\nWhen enabled, this allows connection to an existing browser instance rather than launching a new one.\n\n资料来源：[config.d.ts:134-140](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Network Configuration\n\nControl browser network access through origin-based filtering:\n\n```typescript\nnetwork?: {\n  allowedOrigins?: string[];   // List of allowed origins\n  blockedOrigins?: string[];   // List of blocked origins\n}\n```\n\nSupported formats:\n- Full origin: `https://example.com:8080`\n- Wildcard port: `http://localhost:*`\n\n资料来源：[config.d.ts:190-204](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Session Management\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `saveSession` | boolean | Save Playwright session to output directory |\n| `sharedBrowserContext` | boolean | Reuse browser context across HTTP clients |\n\n资料来源：[config.d.ts:166-173](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Console Configuration\n\n```typescript\nconsole?: {\n  level?: 'error' | 'warning' | 'info' | 'debug';\n}\n```\n\n资料来源：[config.d.ts:182-187](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n---\n\n<a id='user-profiles'></a>\n\n## User Profiles and Session Management\n\n### 相关页面\n\n相关主题：[Browser Configuration](#browser-configuration), [Troubleshooting](#troubleshooting)\n\n<details>\n<summary>Relevant Source Files</summary>\n\nThe following source files were used to generate this page:\n\n- [config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n- [package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n- [server.json](https://github.com/microsoft/playwright-mcp/blob/main/server.json)\n- [cli.js](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)\n- [roll.js](https://github.com/microsoft/playwright-mcp/blob/main/roll.js)\n- [CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n</details>\n\n# User Profiles and Session Management\n\n## Overview\n\nUser Profiles and Session Management in Playwright MCP controls how browser instances are created, persisted, and shared across multiple HTTP clients and tool invocations. This system enables sophisticated browser automation scenarios while maintaining security and resource efficiency.\n\nThe MCP server supports:\n- **Isolated browser instances** per request\n- **Persistent user data directories** for profile retention\n- **Shared browser contexts** across clients\n- **Session saving and restoration**\n- **Secrets masking** in responses\n\n资料来源：[config.d.ts:22-40]()\n\n## Architecture\n\n```mermaid\ngraph TD\n    A[MCP Client] -->|HTTP/STDIO| B[Playwright MCP Server]\n    B --> C[Browser Manager]\n    C --> D{Shared Context?}\n    D -->|Yes| E[Single Browser Context]\n    D -->|No| F[Per-Client Context]\n    E --> G[Browser Instance]\n    F --> G\n    G --> H[User Data Directory]\n    G --> I[Session Files]\n    H -->|Persistence| J[Output Directory]\n```\n\n### Core Components\n\n| Component | Purpose | Configuration Key |\n|-----------|---------|-------------------|\n| Browser Manager | Creates and manages browser instances | `browser.*` |\n| Session Manager | Handles session save/restore | `saveSession` |\n| Context Pool | Manages shared vs isolated contexts | `sharedBrowserContext` |\n| Secrets Handler | Masks sensitive data in responses | `secrets` |\n\n资料来源：[config.d.ts:1-50]()\n\n## Browser Configuration\n\n### Browser Type Selection\n\nThe MCP server supports three browser engines:\n\n```typescript\nbrowser?: {\n  browserName?: 'chromium' | 'firefox' | 'webkit';\n}\n```\n\n| Browser | Engine | Use Case |\n|---------|--------|----------|\n| `chromium` | Blink | General automation, Chrome/Edge compatibility |\n| `firefox` | Gecko | Cross-browser testing, Firefox-specific features |\n| `webkit` | WebKit | Safari compatibility testing |\n\n资料来源：[config.d.ts:24-30]()\n\n### User Data Directory\n\nThe user data directory stores browser profile data including cookies, local storage, and session state.\n\n```typescript\nbrowser?: {\n  /**\n   * Path to a user data directory for browser profile persistence.\n   * Temporary directory is created by default.\n   */\n  userDataDir?: string;\n}\n```\n\n**Behavior:**\n- When `userDataDir` is unspecified, a temporary directory is created automatically\n- Persistent directories survive browser restarts\n- Useful for maintaining login sessions across tool invocations\n\n资料来源：[config.d.ts:38-43]()\n\n### Isolated Mode\n\nWhen `isolated: true`, browser profiles are kept entirely in memory without disk persistence.\n\n```typescript\nbrowser?: {\n  /**\n   * Keep the browser profile in memory, do not save it to disk.\n   */\n  isolated?: boolean;\n}\n```\n\n| Mode | Persistence | Security | Performance |\n|------|-------------|----------|-------------|\n| `isolated: true` | Memory only | Higher | Faster startup |\n| `isolated: false` | Disk (userDataDir) | Standard | Slower startup |\n\n资料来源：[config.d.ts:32-37]()\n\n## Session Management\n\n### Session Saving\n\nThe `saveSession` option controls whether Playwright sessions are persisted to the output directory.\n\n```typescript\nexport type Config = {\n  /**\n   * Whether to save the Playwright session into the output directory.\n   */\n  saveSession?: boolean;\n}\n```\n\n**Use cases:**\n- Debugging failed automation workflows\n- Resuming interrupted sessions\n- Analyzing browser state post-execution\n\n资料来源：[config.d.ts:83-87]()\n\n### Output Directory\n\nSessions and output files are saved to the configured output directory.\n\n```typescript\nexport type Config = {\n  /**\n   * The directory to save output files.\n   */\n  outputDir?: string;\n}\n```\n\n**Default behavior:** If not specified, the MCP server uses a platform-specific temporary directory.\n\n资料来源：[config.d.ts:95-99]()\n\n## Browser Context Management\n\n### Shared Browser Context\n\nWhen multiple HTTP clients connect to the MCP server, `sharedBrowserContext` determines whether they share a single browser context or receive isolated contexts.\n\n```typescript\nexport type Config = {\n  /**\n   * Reuse the same browser context between all connected HTTP clients.\n   */\n  sharedBrowserContext?: boolean;\n}\n```\n\n```mermaid\ngraph LR\n    A[Client 1] -->|MCP| B{sharedBrowserContext}\n    C[Client 2] -->|MCP| B\n    D[Client N] -->|MCP| B\n    \n    B -->|true| E[Shared Context]\n    B -->|false| F[Client 1 Context]\n    B -->|false| G[Client 2 Context]\n    B -->|false| H[Client N Context]\n```\n\n| Setting | Pros | Cons |\n|---------|------|------|\n| `sharedBrowserContext: true` | Resource efficient, shared cookies/auth | State bleeding between clients |\n| `sharedBrowserContext: false` | Complete isolation | Higher resource usage |\n\n资料来源：[config.d.ts:89-94]()\n\n## Secrets Management\n\nThe secrets system prevents sensitive data from being exposed to LLM clients.\n\n```typescript\nexport type Config = {\n  /**\n   * Secrets are used to replace matching plain text in the tool responses to prevent the LLM\n   * from accidentally getting sensitive data. It is a convenience and not a security feature,\n   * make sure to always examine information coming in and from the tool on the client.\n   */\n  secrets?: Record<string, string>;\n}\n```\n\n**Key characteristics:**\n- **Not a security feature** - Use proper authentication for actual security\n- Pattern matching replaces plain text in responses\n- Prevents LLM accidental exposure of sensitive information\n\n资料来源：[config.d.ts:100-106]()\n\n## Configuration Schema\n\n### Complete Config Type\n\n```typescript\nexport type Config = {\n  browser?: {\n    browserName?: 'chromium' | 'firefox' | 'webkit';\n    isolated?: boolean;\n    userDataDir?: string;\n    // ... launch options\n  };\n  \n  capabilities?: ToolCapability[];\n  saveSession?: boolean;\n  sharedBrowserContext?: boolean;\n  secrets?: Record<string, string>;\n  outputDir?: string;\n  \n  console?: {\n    level?: 'error' | 'warning' | 'info' | 'debug';\n  };\n  \n  network?: {\n    allowedOrigins?: string[];\n    blockedOrigins?: string[];\n  };\n  \n  testIdAttribute?: string;\n  \n  timeouts?: {\n    action?: number;\n    navigation?: number;\n    expect?: number;\n  };\n  \n  imageResponses?: 'allow' | 'omit';\n  \n  // ... additional options\n};\n```\n\n资料来源：[config.d.ts:1-180]()\n\n## Tool Capabilities\n\nThe MCP server exposes browser automation through categorized tool capabilities:\n\n| Capability | Description |\n|------------|-------------|\n| `config` | Configuration management |\n| `core` | Core browser automation |\n| `core-navigation` | Page navigation and routing |\n| `core-tabs` | Tab/window management |\n| `core-input` | Form input handling |\n| `core-install` | Browser installation |\n| `network` | Network request interception |\n| `pdf` | PDF generation |\n| `storage` | Storage management |\n| `testing` | Test-related tools |\n| `vision` | Coordinate-based interactions |\n| `devtools` | Developer tools features |\n\n资料来源：[config.d.ts:13-26]()\n\n## Server Configuration\n\nThe MCP server uses STDIO transport by default for optimal integration with MCP clients.\n\n```json\n{\n  \"name\": \"io.github.microsoft/playwright-mcp\",\n  \"description\": \"Playwright Tools for MCP\",\n  \"version\": \"0.0.75\",\n  \"packages\": [\n    {\n      \"registryType\": \"npm\",\n      \"identifier\": \"@playwright/mcp\",\n      \"version\": \"0.0.75\",\n      \"transport\": {\n        \"type\": \"stdio\"\n      }\n    }\n  ]\n}\n```\n\n资料来源：[server.json:1-15]()\n\n## CLI Options\n\nThe MCP server can be configured via command-line arguments:\n\n```bash\nnode cli.js --help\n```\n\nKey CLI commands:\n- `install-browser` - Install required browser binaries\n- Standard Playwright CLI options for browser management\n\n资料来源：[cli.js:1-35]()\n\n## Best Practices\n\n### Security Recommendations\n\n1. **Do not rely on secrets masking for security** - Treat it as UI/UX convenience only\n2. **Use isolated mode** for untrusted content\n3. **Configure network restrictions** using `allowedOrigins` and `blockedOrigins`\n\n### Performance Optimization\n\n| Scenario | Recommended Setting |\n|----------|---------------------|\n| Single client, high throughput | `sharedBrowserContext: true` |\n| Multiple clients requiring isolation | `sharedBrowserContext: false` |\n| Resource-constrained environment | `isolated: true` |\n| Need session persistence | `saveSession: true`, specify `outputDir` |\n\n### Testing Workflow\n\nFor testing MCP functionality:\n\n```bash\n# Fast path - Chromium only\nnpm run ctest\n\n# Full test suite - All browsers\nnpm run mcp-test\n\n# Docker environment\nnpm run dtest\n```\n\n资料来源：[package.json:18-25]()\n\n## Rolling Updates\n\nThe Playwright version can be updated while maintaining configuration compatibility:\n\n```bash\nnpm run roll\n```\n\nThis command:\n1. Updates `playwright`, `playwright-core`, and `@playwright/test` versions\n2. Refreshes `config.d.ts` from the Playwright monorepo\n3. Regenerates the README documentation\n\n资料来源：[roll.js:1-40](), [CLAUDE.md:1-35]()\n\n---\n\n<a id='troubleshooting'></a>\n\n## Troubleshooting\n\n### 相关页面\n\n相关主题：[User Profiles and Session Management](#user-profiles), [Browser Configuration](#browser-configuration)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [CLAUDE.md](https://github.com/microsoft/playwright-mcp/blob/main/CLAUDE.md)\n- [CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n- [package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n- [playwright.config.ts](https://github.com/microsoft/playwright-mcp/blob/main/playwright.config.ts)\n- [cli.js](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)\n</details>\n\n# Troubleshooting\n\nThis page documents common issues, debugging strategies, and resolution steps when working with Playwright MCP.\n\n## Overview\n\nTroubleshooting in Playwright MCP primarily involves:\n\n- Test execution failures\n- Browser launch and context issues\n- MCP tool invocation problems\n- Configuration mismatches\n- Dependency and version compatibility\n\n## Common Issues and Resolutions\n\n### Test Failures\n\n#### All Tests Failing\n\nIf all tests fail, verify the test environment is properly configured:\n\n```bash\n# Ensure dependencies are installed\nnpm ci\n\n# Install Playwright browsers\nnpx playwright install\n\n# Run tests in a single browser (faster feedback)\nnpm run ctest\n```\n\n**Source:** [package.json:11](https://github.com/microsoft/playwright-mcp/blob/main/package.json#L11)\n\n#### Cross-Browser Test Inconsistencies\n\nPlaywright MCP tests run in Chromium, Firefox, and WebKit. If failures occur in specific browsers:\n\n```bash\n# Test individual browsers\nnpm run ctest   # Chrome only\nnpm run ftest   # Firefox only\nnpm run wtest   # WebKit only\n```\n\nTests should be hermetic and work on all three platforms: macOS, Linux, and Windows. 资料来源：[CONTRIBUTING.md:71-72](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md#L71-L72)\n\n### Browser Launch Issues\n\n#### Persistent Context Problems\n\nThe `isolated` option controls whether browser profiles are saved to disk:\n\n```typescript\n{\n  browser: {\n    isolated: true   // Keeps profile in memory\n  }\n}\n```\n\nDefault behavior creates temporary directories for user data. 资料来源：[config.d.ts:35-38](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts#L35-L38)\n\n#### Network Requests Blocked\n\nConfigure allowed and blocked origins in the `network` section:\n\n```typescript\n{\n  network: {\n    allowedOrigins: ['https://example.com:8080'],\n    blockedOrigins: ['https://ads.example.com']\n  }\n}\n```\n\nOrigins matching both lists will be blocked. 资料来源：[config.d.ts:100-112](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts#L100-L112)\n\n### MCP Tool Invocation Errors\n\n#### Tool Not Found\n\nMCP tools are exposed through the connection interface. Ensure the server is properly initialized:\n\n```javascript\nconst { createConnection } = require('@playwright/mcp');\n```\n\nThe `createConnection` function is exported from the core bundle. 资料来源：[index.js:27-28](https://github.com/microsoft/playwright-mcp/blob/main/index.js#L27-L28)\n\n### Configuration Schema Errors\n\nTypeScript errors related to `Config` type indicate schema mismatches. The `config.d.ts` file defines the expected structure:\n\n```typescript\nexport type Config = {\n  browser?: { ... };\n  timeouts?: { ... };\n  capabilities?: ToolCapability[];\n  secrets?: Record<string, string>;\n  outputDir?: string;\n  console?: { level?: 'error' | 'warning' | 'info' | 'debug' };\n  network?: { allowedOrigins?: string[]; blockedOrigins?: string[] };\n}\n```\n\n## Debugging Strategies\n\n### Enabling Debug Logs\n\nConfigure console log levels to control verbosity:\n\n```typescript\n{\n  console: {\n    level: 'debug'  // 'error' | 'warning' | 'info' | 'debug'\n  }\n}\n```\n\nDefault level is `'info'`. 资料来源：[config.d.ts:88-91](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts#L88-L91)\n\n### Timeouts Configuration\n\nAdjust timeouts for slow environments:\n\n```typescript\n{\n  timeouts: {\n    action: 10000,     // Default: 5000ms\n    navigation: 120000, // Default: 60000ms\n    expect: 10000      // Default: 5000ms\n  }\n}\n```\n\n资料来源：[config.d.ts:64-77](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts#L64-L77)\n\n### Saving Sessions for Analysis\n\nEnable `saveSession` to persist Playwright session data for debugging:\n\n```typescript\n{\n  saveSession: true\n}\n```\n\nSessions are saved to the configured `outputDir`. 资料来源：[config.d.ts:81-84](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts#L81-L84)\n\n## Docker Environment Issues\n\nWhen running tests in Docker containers:\n\n```bash\n# Build Docker image\nnpm run docker-build\n\n# Run container\nnpm run docker-run\n\n# Execute tests in Docker\nnpm run dtest\n```\n\nDocker tests run with `MCP_IN_DOCKER=1` environment variable. 资料来源：[package.json:16-18](https://github.com/microsoft/playwright-mcp/blob/main/package.json#L16-L18)\n\n## Version Rollback Problems\n\nIf rolling Playwright causes issues:\n\n1. The `roll.js` script updates dependencies and regenerates configuration\n2. After running `npm run roll`, always run tests before committing\n\n```bash\nnpm run roll\nnpm test  # Must pass before proceeding\n```\n\nIf tests fail after a roll, revert changes and investigate the version bump. 资料来源：[CLAUDE.md:12-14](https://github.com/microsoft/playwright-mcp/blob/main/CLAUDE.md#L12-L14)\n\n## Contributing Troubleshooting\n\n### PR Closed Without Review\n\n> **Unsolicited PRs:** Pull requests submitted without a linked issue or prior approval will be closed. 资料来源：[CONTRIBUTING.md:29-30](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md#L29-L30)\n\nAlways file an issue first before submitting changes.\n\n### Linting Failures\n\nRun the linter before submitting:\n\n```bash\nnpm run lint\n```\n\nThis also regenerates the README documentation. 资料来源：[package.json:9](https://github.com/microsoft/playwright-mcp/blob/main/package.json#L9)\n\n## Workflow Diagram\n\n```mermaid\ngraph TD\n    A[Start] --> B{Issue?</B]\n    B -->|Yes| C[File GitHub Issue]\n    B -->|No| D[Check Existing Issues]\n    C --> E{Assigned?}\n    D --> E\n    E -->|Yes| F[Create Branch]\n    E -->|No| G[Wait for Assignment]\n    G --> E\n    F --> H[Make Changes]\n    H --> I[Add Tests]\n    I --> J[Run Tests]\n    J -->|Pass| K[Run Linter]\n    J -->|Fail| L[Debug & Fix]\n    L --> J\n    K -->|Pass| M[Commit Changes]\n    K -->|Fail| N[Fix Lint Errors]\n    N --> K\n    M --> O[Open PR]\n```\n\n## Quick Reference Commands\n\n| Command | Purpose | Source |\n|---------|---------|--------|\n| `npm test` | Run all tests | [package.json:10](https://github.com/microsoft/playwright-mcp/blob/main/package.json#L10) |\n| `npm run ctest` | Chrome-only tests | [package.json:11](https://github.com/microsoft/playwright-mcp/blob/main/package.json#L11) |\n| `npm run lint` | Regenerate docs | [package.json:9](https://github.com/microsoft/playwright-mcp/blob/main/package.json#L9) |\n| `npm run roll` | Bump Playwright version | [package.json:20](https://github.com/microsoft/playwright-mcp/blob/main/package.json#L20) |\n| `npm run docker-build` | Build Docker image | [package.json:17](https://github.com/microsoft/playwright-mcp/blob/main/package.json#L17) |\n\n## Getting Help\n\nIf issues persist after following this guide:\n\n1. Search existing [GitHub Issues](https://github.com/microsoft/playwright-mcp/issues)\n2. Check the [Playwright Documentation](https://playwright.dev/docs)\n3. Review the [main Playwright repository](https://github.com/microsoft/playwright) for upstream issues\n\nThe core of Playwright MCP was moved to the [Playwright monorepo](https://github.com/microsoft/playwright). 资料来源：[CONTRIBUTING.md:23-24](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md#L23-L24)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：microsoft/playwright-mcp\n\n摘要：发现 21 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。\n\n## 1. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `playwright-mcp` 与安装入口 `@playwright/mcp@latest` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`npx @playwright/mcp@latest`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | repo=playwright-mcp; install=@playwright/mcp@latest\n\n## 2. 安装坑 · 来源证据：Bad entrypoint in docker example\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bad entrypoint in docker example\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_948f818745694481b19e883b3992d78b | https://github.com/microsoft/playwright-mcp/issues/1609 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：v0.0.72\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.0.72\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2e67eb76e3c643e0a52a97e42eca4cb8 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.72 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 4. 配置坑 · 来源证据：v0.0.69\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.0.69\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6767d649d4934031b85ab0c5ffc2b324 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.69 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 5. 配置坑 · 来源证据：v0.0.71\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.0.71\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d5bcb1704c0e4a6fb375b18cda153fdd | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.71 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 配置坑 · 来源证据：v0.0.73\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.0.73\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a0d6aead61ad4c52ab738c6b556f2e27 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.73 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 能力坑 · 能力判断依赖假设\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:952688112 | https://github.com/microsoft/playwright-mcp | README/documentation is current enough for a first validation pass.\n\n## 8. 运行坑 · 来源证据：[Bug] Running multiple parallel async browsers in --isolated mode leaves orphan browsers. This has started happening af…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[Bug] Running multiple parallel async browsers in --isolated mode leaves orphan browsers. This has started happening after Release v0.0.69.\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e8f29958fbbe48ce8381daa23333bdf4 | https://github.com/microsoft/playwright-mcp/issues/1607 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 9. 运行坑 · 来源证据：v0.0.67\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.0.67\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3b13c720c21346bab9c08783c91acb95 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.67 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 10. 运行坑 · 来源证据：v0.0.68\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.0.68\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c53eae5fa6a94d2e86bc60cf6b164d16 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.68 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 11. 运行坑 · 来源证据：v0.0.74\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.0.74\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2c41b3bf29434fb48d51cb9ffc766fc2 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.74 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 12. 运行坑 · 来源证据：v0.0.75\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.0.75\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4e21e73e13dc471f90365f431d541143 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.75 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 13. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | last_activity_observed missing\n\n## 14. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | no_demo; severity=medium\n\n## 16. 安全/权限坑 · 来源证据：VS Code installation buttons don't seem to work\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：VS Code installation buttons don't seem to work\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_37c3461084f34d05856db207d12f8d9a | https://github.com/microsoft/playwright-mcp/issues/1608 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：[Bug]: Windows taskkill output can pollute MCP stdio transport\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: Windows taskkill output can pollute MCP stdio transport\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_789c261c74274d9d9a84d4b1fbf30d14 | https://github.com/microsoft/playwright-mcp/issues/1611 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：[Disclosure] Clarify browser/network action boundary in Playwright MCP server docs\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Disclosure] Clarify browser/network action boundary in Playwright MCP server docs\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fc2b3d242d67495f81f1bb1877e22f84 | https://github.com/microsoft/playwright-mcp/issues/1617 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 19. 安全/权限坑 · 来源证据：[Feature Request] Support clientCertificates option for mTLS authentication\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature Request] Support clientCertificates option for mTLS authentication\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b6f82bec73944aa5869030ad7db55b0c | https://github.com/microsoft/playwright-mcp/issues/1456 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 20. 维护坑 · 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:952688112 | https://github.com/microsoft/playwright-mcp | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | release_recency=unknown\n\n<!-- canonical_name: microsoft/playwright-mcp; human_manual_source: deepwiki_human_wiki -->\n",
      "markdown_key": "playwright-mcp",
      "pages": "draft",
      "source_refs": [
        {
          "evidence_id": "github_repo:952688112",
          "kind": "repo",
          "supports_claim_ids": [
            "claim_identity",
            "claim_distribution",
            "claim_capability"
          ],
          "url": "https://github.com/microsoft/playwright-mcp"
        },
        {
          "evidence_id": "art_f34667d91f394479afac3f750f54f8e6",
          "kind": "docs",
          "supports_claim_ids": [
            "claim_identity",
            "claim_distribution",
            "claim_capability"
          ],
          "url": "https://github.com/microsoft/playwright-mcp#readme"
        }
      ],
      "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
      "title": "playwright-mcp 说明书",
      "toc": [
        "https://github.com/microsoft/playwright-mcp 项目说明书",
        "目录",
        "Introduction to Playwright MCP",
        "Overview",
        "Architecture",
        "Tool Capabilities",
        "Configuration Options",
        "CLI Usage",
        "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": "ae27b8638aaf3a6be17d378964ae683864d20440",
    "repo_inspection_error": null,
    "repo_inspection_files": [
      "Dockerfile",
      "package.json",
      "README.md",
      "src/README.md"
    ],
    "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": "# @playwright/mcp - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 @playwright/mcp 编译的 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- `claude mcp add playwright npx @playwright/mcp@latest` 证据：`README.md` Claim：`clm_0003` supported 0.86\n- `npx @playwright/mcp@latest --config path/to/config.json` 证据：`README.md` Claim：`clm_0004` supported 0.86\n- `npx @playwright/mcp@latest --port 8931` 证据：`README.md` Claim：`clm_0005` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\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 的默认行为。 证据：`CLAUDE.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`CLAUDE.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`README.md`, `update-readme.js`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\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_0006` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0007` 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- 文件总数：31\n- 重要文件覆盖：26/31\n- 证据索引条目：26\n- 角色 / Skill 条目：6\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请基于 @playwright/mcp 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 @playwright/mcp 当作安装前体验资产，而不是已安装工具或真实运行环境。\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请基于 @playwright/mcp 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 6 个角色 / Skill / 项目文档条目。\n\n- **Commit Convention**（project_doc）：Semantic commit messages: label scope : description 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CLAUDE.md`\n- **Playwright MCP**（project_doc）：A Model Context Protocol MCP server that provides browser automation capabilities using Playwright https://playwright.dev . This server enables LLMs to interact with web pages through structured accessibility snapshots, bypassing the need for screenshots or visually-tuned models. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Where is the source?**（project_doc）：Playwright MCP source code is located in the Playwright monorepo https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/mcp . Please refer to the contributor's guide in CONTRIBUTING.md ../CONTRIBUTING.md for more details. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`src/README.md`\n- **Contributing**（project_doc）：To maintain project quality and focus, Playwright requires a corresponding issue for every contribution, with the exception of minor documentation fixes. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`\n- **Security**（project_doc）：Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include Microsoft https://github.com/Microsoft , Azure https://github.com/Azure , DotNet https://github.com/dotnet , AspNet https://github.com/aspnet and Xamarin https://github.com/xamarin . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`SECURITY.md`\n- **release**（project_doc）：Prepare a playwright-mcp release — roll Playwright, bump the version, and write GitHub release notes that combine changes from this repo and upstream microsoft/playwright since the last release. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/skills/release.md`\n\n## 证据索引\n\n- 共索引 26 条证据。\n\n- **Commit Convention**（documentation）：Semantic commit messages: label scope : description 证据：`CLAUDE.md`\n- **Playwright MCP**（documentation）：A Model Context Protocol MCP server that provides browser automation capabilities using Playwright https://playwright.dev . This server enables LLMs to interact with web pages through structured accessibility snapshots, bypassing the need for screenshots or visually-tuned models. 证据：`README.md`\n- **Where is the source?**（documentation）：Playwright MCP source code is located in the Playwright monorepo https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/mcp . Please refer to the contributor's guide in CONTRIBUTING.md ../CONTRIBUTING.md for more details. 证据：`src/README.md`\n- **Package**（package_manifest）：{ \"name\": \"@playwright/mcp\", \"version\": \"0.0.75\", \"description\": \"Playwright Tools for MCP\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/microsoft/playwright-mcp.git\" }, \"homepage\": \"https://playwright.dev\", \"engines\": { \"node\": \" =18\" }, \"author\": { \"name\": \"Microsoft Corporation\" }, \"license\": \"Apache-2.0\", \"mcpName\": \"io.github.microsoft/playwright-mcp\", \"scripts\": { \"lint\": \"node update-readme.js\", \"test\": \"playwright test\", \"ctest\": \"playwright test --project=chrome\", \"ftest\": \"playwright test --project=firefox\", \"wtest\": \"playwright test --project=webkit\", \"dtest\": \"MCP IN DOCKER=1 playwright test --project=chromium-docker\", \"build\": \"echo OK\", \"npm-publish\": \"npm ru… 证据：`package.json`\n- **Contributing**（documentation）：To maintain project quality and focus, Playwright requires a corresponding issue for every contribution, with the exception of minor documentation fixes. 证据：`CONTRIBUTING.md`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`\n- **Security**（documentation）：Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include Microsoft https://github.com/Microsoft , Azure https://github.com/Azure , DotNet https://github.com/dotnet , AspNet https://github.com/aspnet and Xamarin https://github.com/xamarin . 证据：`SECURITY.md`\n- **Preparing a Release**（documentation）：Most MCP source lives upstream at ~/playwright/packages/playwright-core/src/tools/ and tests/mcp/ . A release combines an upstream Playwright roll, a version bump in this repo, and release notes that draw from both. 证据：`.claude/skills/release.md`\n- **Devcontainer**（structured_config）：{ \"$schema\": \"https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.schema.json\", \"name\": \"Playwright\", \"image\": \"mcr.microsoft.com/playwright:v1.58.2-noble\", \"privileged\": true, \"init\": true, \"remoteUser\": \"pwuser\", \"features\": { \"ghcr.io/devcontainers/features/desktop-lite:1\": {}, \"ghcr.io/devcontainers/features/github-cli:1\": {}, \"ghcr.io/devcontainers/features/docker-outside-of-docker:1\": {} }, \"forwardPorts\": 6080 , \"portsAttributes\": { \"6080\": { \"label\": \"noVNC\" } } } 证据：`.devcontainer/devcontainer.json`\n- **Server**（structured_config）：{ \"$schema\": \"https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json\", \"name\": \"io.github.microsoft/playwright-mcp\", \"description\": \"Playwright Tools for MCP\", \"repository\": { \"url\": \"https://github.com/microsoft/playwright-mcp\", \"source\": \"github\" }, \"version\": \"0.0.75\", \"packages\": { \"registryType\": \"npm\", \"identifier\": \"@playwright/mcp\", \"version\": \"0.0.75\", \"transport\": { \"type\": \"stdio\" } } } 证据：`server.json`\n- **.gitignore**（source_file）：node modules/ test-results/ playwright-report/ .vscode/mcp.json .idea .DS Store .env sessions/ 证据：`.gitignore`\n- **.npmignore**（source_file）：/ !README.md !LICENSE !cli.js !index. !config.d.ts 证据：`.npmignore`\n- **------------------------------**（source_file）：ARG PLAYWRIGHT BROWSERS PATH=/ms-playwright 证据：`Dockerfile`\n- **!/usr/bin/env node**（source_file）：!/usr/bin/env node / Copyright c Microsoft Corporation. Licensed under the Apache License, Version 2.0 the \"License\" ; you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. / 证据：`cli.js`\n- **Config.D**（source_file）：/ Copyright c Microsoft Corporation. Licensed under the Apache License, Version 2.0 the \"License\" ; you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. / 证据：`config.d.ts`\n- **!/usr/bin/env node**（source_file）：!/usr/bin/env node / Copyright c Microsoft Corporation. Licensed under the Apache License, Version 2.0 the \"License\" ; you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. / 证据：`index.d.ts`\n- **!/usr/bin/env node**（source_file）：!/usr/bin/env node / Copyright c Microsoft Corporation. Licensed under the Apache License, Version 2.0 the \"License\" ; you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. / 证据：`index.js`\n- **Playwright.Config**（source_file）：/ Copyright c Microsoft Corporation. Licensed under the Apache License, Version 2.0 the \"License\" ; you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. / 证据：`playwright.config.ts`\n- **Roll**（source_file）：const fs = require 'fs' ; const path = require 'path' ; const { execSync } = require 'child process' ; 证据：`roll.js`\n- **Capabilities.Spec**（source_file）：/ Copyright c Microsoft Corporation. Licensed under the Apache License, Version 2.0 the \"License\" ; you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. / 证据：`tests/capabilities.spec.ts`\n- **Cli.Spec**（source_file）：/ Copyright c Microsoft Corporation. Licensed under the Apache License, Version 2.0 the \"License\" ; you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. / import child process from 'child process'; import path from 'path'; import { test, expect } from './fixtures'; 证据：`tests/cli.spec.ts`\n- **Click.Spec**（source_file）：/ Copyright c Microsoft Corporation. Licensed under the Apache License, Version 2.0 the \"License\" ; you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. / 证据：`tests/click.spec.ts`\n- **Core.Spec**（source_file）：/ Copyright c Microsoft Corporation. Licensed under the Apache License, Version 2.0 the \"License\" ; you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. / 证据：`tests/core.spec.ts`\n- **Fixtures**（source_file）：/ Copyright c Microsoft Corporation. Licensed under the Apache License, Version 2.0 the \"License\" ; you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. / 证据：`tests/fixtures.ts`\n- **Library.Spec**（source_file）：/ Copyright c Microsoft Corporation. Licensed under the Apache License, Version 2.0 the \"License\" ; you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. / import child process from 'child process'; import fs from 'fs/promises'; import { test, expect } from './fixtures'; 证据：`tests/library.spec.ts`\n- **!/usr/bin/env node**（source_file）：!/usr/bin/env node / Copyright c Microsoft Corporation. Licensed under the Apache License, Version 2.0 the \"License\" ; you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. / // @ts-check 证据：`update-readme.js`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`CLAUDE.md`, `README.md`, `src/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`CLAUDE.md`, `README.md`, `src/README.md`\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- **Introduction to Playwright MCP**：importance `high`\n  - source_paths: README.md, package.json\n- **Key Concepts**：importance `high`\n  - source_paths: README.md, index.d.ts\n- **Installation Guide**：importance `high`\n  - source_paths: package.json, README.md\n- **MCP Client Integration**：importance `high`\n  - source_paths: README.md\n- **Browser Configuration**：importance `high`\n  - source_paths: config.d.ts, playwright.config.ts, README.md\n- **Security Settings**：importance `high`\n  - source_paths: README.md, config.d.ts, SECURITY.md\n- **Docker Deployment**：importance `medium`\n  - source_paths: Dockerfile, README.md, cli.js\n- **Programmatic Usage**：importance `medium`\n  - source_paths: index.js, index.d.ts, README.md\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `ae27b8638aaf3a6be17d378964ae683864d20440`\n- inspected_files: `Dockerfile`, `package.json`, `README.md`, `src/README.md`\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: 仓库名和安装名不一致\n\n- Trigger: 仓库名 `playwright-mcp` 与安装入口 `@playwright/mcp@latest` 不完全一致。\n- Host AI rule: 在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- Why it matters: 用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- Evidence: identity.distribution | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | repo=playwright-mcp; install=@playwright/mcp@latest\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：Bad entrypoint in docker example\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bad entrypoint in docker example\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_948f818745694481b19e883b3992d78b | https://github.com/microsoft/playwright-mcp/issues/1609 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：v0.0.72\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.0.72\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_2e67eb76e3c643e0a52a97e42eca4cb8 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.72 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：v0.0.69\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.0.69\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_6767d649d4934031b85ab0c5ffc2b324 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.69 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：v0.0.71\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.0.71\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_d5bcb1704c0e4a6fb375b18cda153fdd | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.71 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：v0.0.73\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.0.73\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_a0d6aead61ad4c52ab738c6b556f2e27 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.73 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 能力判断依赖假设\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:952688112 | https://github.com/microsoft/playwright-mcp | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：[Bug] Running multiple parallel async browsers in --isolated mode leaves orphan browsers. This has started happening af…\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[Bug] Running multiple parallel async browsers in --isolated mode leaves orphan browsers. This has started happening after Release v0.0.69.\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_e8f29958fbbe48ce8381daa23333bdf4 | https://github.com/microsoft/playwright-mcp/issues/1607 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：v0.0.67\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.0.67\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_3b13c720c21346bab9c08783c91acb95 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.67 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 来源证据：v0.0.68\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.0.68\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_c53eae5fa6a94d2e86bc60cf6b164d16 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.68 | 来源类型 github_release 暴露的待验证使用条件。\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项目：microsoft/playwright-mcp\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\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 仓库名和安装名不一致（medium）：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 来源证据：Bad entrypoint in docker example（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v0.0.72（medium）：可能阻塞安装或首次运行。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v0.0.69（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v0.0.71（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\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/microsoft/playwright-mcp 项目说明书\n\n生成时间：2026-05-15 08:14:48 UTC\n\n## 目录\n\n- [Introduction to Playwright MCP](#introduction)\n- [Key Concepts](#key-concepts)\n- [Installation Guide](#installation-guide)\n- [MCP Client Integration](#client-integration)\n- [Browser Configuration](#browser-configuration)\n- [Security Settings](#security-settings)\n- [Docker Deployment](#docker-deployment)\n- [Programmatic Usage](#programmatic-usage)\n- [User Profiles and Session Management](#user-profiles)\n- [Troubleshooting](#troubleshooting)\n\n<a id='introduction'></a>\n\n## Introduction to Playwright MCP\n\n### 相关页面\n\n相关主题：[Key Concepts](#key-concepts), [Installation Guide](#installation-guide)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/microsoft/playwright-mcp/blob/main/README.md)\n- [package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n- [config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n- [server.json](https://github.com/microsoft/playwright-mcp/blob/main/server.json)\n- [cli.js](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)\n- [index.js](https://github.com/microsoft/playwright-mcp/blob/main/index.js)\n- [CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n</details>\n\n# Introduction to Playwright MCP\n\nPlaywright MCP (Model Context Protocol) is a server implementation that exposes [Playwright](https://playwright.dev) browser automation capabilities through the MCP protocol. It enables AI models and tools to interact with web browsers using a standardized interface.\n\n## Overview\n\nPlaywright MCP acts as a bridge between AI systems and web browsers, providing a comprehensive set of tools for:\n\n- Browser automation and scraping\n- UI testing and verification\n- Network request monitoring\n- PDF generation\n- Vision-based interactions\n- Storage state management\n\n**Package Information**\n\n| Property | Value |\n|----------|-------|\n| Package Name | `@playwright/mcp` |\n| MCP Server Name | `io.github.microsoft/playwright-mcp` |\n| Current Version | `0.0.75` |\n| License | Apache-2.0 |\n| Node Requirement | `>=18` |\n| Transport Protocol | stdio |\n\n资料来源：[package.json:3-15](https://github.com/microsoft/playwright-mcp/blob/main/package.json), [server.json:1-15](https://github.com/microsoft/playwright-mcp/blob/main/server.json)\n\n## Architecture\n\nThe Playwright MCP implementation follows a layered architecture where the MCP server delegates browser operations to Playwright's core automation engine.\n\n```mermaid\ngraph TD\n    A[AI Client / MCP Host] -->|MCP Protocol| B[Playwright MCP Server]\n    B -->|STDIO Transport| C[playwright-core]\n    C -->|Browser Automation| D[Chromium / Firefox / WebKit]\n    C -->|PDF Generation| E[PDF Renderer]\n    C -->|Vision API| F[Image Processing]\n```\n\n资料来源：[index.js:1-25](https://github.com/microsoft/playwright-mcp/blob/main/index.js), [cli.js:1-35](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)\n\n### Source Code Location\n\n> [!IMPORTANT]\n> The core implementation has been migrated to the [Playwright monorepo](https://github.com/microsoft/playwright). The source code is now located at:\n>\n> `packages/playwright/src/mcp`\n\nThis repository (`microsoft/playwright-mcp`) serves as the npm distribution package and coordination point.\n\n资料来源：[src/README.md:1-5](https://github.com/microsoft/playwright-mcp/blob/main/src/README.md)\n\n## Tool Capabilities\n\nPlaywright MCP organizes its functionality into capability groups. Each capability can be individually enabled or disabled through configuration.\n\n| Capability | Description |\n|------------|-------------|\n| `config` | Server configuration and initialization |\n| `core` | Core browser operations |\n| `core-navigation` | Page navigation and URL handling |\n| `core-tabs` | Tab/window management |\n| `core-input` | Form input and user interactions |\n| `core-install` | Browser installation |\n| `network` | Network request/response monitoring |\n| `pdf` | PDF document generation |\n| `storage` | Session state persistence |\n| `testing` | Test assertion utilities |\n| `vision` | Screenshot and visual verification |\n| `devtools` | Developer tools integration |\n\n资料来源：[config.d.ts:25-40](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Configuration Options\n\nThe server behavior can be customized through the `Config` type defined in `config.d.ts`.\n\n### Browser Configuration\n\n```typescript\nbrowser?: {\n  browserName?: 'chromium' | 'firefox' | 'webkit';\n  isolated?: boolean;\n  userDataDir?: string;\n  launchOptions?: object;\n}\n```\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `browserName` | string | Browser type: chromium, firefox, or webkit |\n| `isolated` | boolean | Keep browser profile in memory only |\n| `userDataDir` | string | Path for browser profile persistence |\n\n资料来源：[config.d.ts:48-75](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n### Network Configuration\n\n```typescript\nnetwork?: {\n  allowedOrigins?: string[];\n  blockedOrigins?: string[];\n}\n```\n\nSupported origin formats:\n- Full origin: `https://example.com:8080`\n- Wildcard port: `http://localhost:*`\n\n资料来源：[config.d.ts:100-115](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n### Console Configuration\n\n```typescript\nconsole?: {\n  level?: 'error' | 'warning' | 'info' | 'debug';\n}\n```\n\n资料来源：[config.d.ts:95-98](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## CLI Usage\n\nThe Playwright MCP CLI is available via `cli.js` and supports several commands:\n\n```bash\n# Run with default settings\nnode cli.js\n\n# Install browser binaries\nnode cli.js install-browser\n\n# Show version\nnode cli.js --version\n\n# Show help\nnode cli.js --help\n```\n\nThe CLI is built on top of `playwright-core` and leverages its command-line utilities.\n\n资料来源：[cli.js:1-35](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)\n\n## Entry Point\n\nThe main entry point exports the `createConnection` function which establishes the MCP connection:\n\n```javascript\nconst { tools } = require('playwright-core/lib/coreBundle');\nmodule.exports = { createConnection: tools.createConnection };\n```\n\n资料来源：[index.js:1-25](https://github.com/microsoft/playwright-mcp/blob/main/index.js)\n\n## Package Scripts\n\n| Script | Purpose |\n|--------|---------|\n| `npm test` | Run all Playwright tests |\n| `npm run ctest` | Run tests in Chrome only |\n| `npm run ftest` | Run tests in Firefox only |\n| `npm run wtest` | Run tests in WebKit only |\n| `npm run lint` | Generate/update README |\n| `npm run roll` | Update Playwright version |\n| `npm run docker-build` | Build Docker image |\n| `npm run docker-run` | Run Docker container |\n\n资料来源：[package.json:18-35](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n\n## Testing\n\nTests are located in the `tests` directory and organized under `tests/mcp`. To run the test suite:\n\n```bash\n# Fast path - Chrome only\nnpm run ctest\n\n# Full path - All browsers\nnpm run mcp-test\n```\n\nTest execution uses Playwright itself, applying the same testing patterns documented in the official [Playwright testing guide](https://playwright.dev/docs/running-tests#running-tests).\n\n资料来源：[CONTRIBUTING.md:45-60](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md), [playwright.config.ts:1-30](https://github.com/microsoft/playwright-mcp/blob/main/playwright.config.ts)\n\n## Development Workflow\n\n```mermaid\ngraph LR\n    A[Fork Repository] --> B[Clone playwright monorepo]\n    B --> C[npm ci && npm run watch]\n    C --> D[npx playwright install]\n    D --> E[Make Changes]\n    E --> F[npm run flint]\n    F --> G[Add Tests]\n    G --> H[Open PR]\n```\n\n1. **Clone**: `git clone https://github.com/microsoft/playwright`\n2. **Install**: `npm ci && npx playwright install`\n3. **Develop**: Make changes in `packages/playwright/src/mcp`\n4. **Lint**: `npm run flint`\n5. **Test**: `npm run mcp-ctest` (fast) or `npm run mcp-test` (full)\n6. **Commit**: Follow [Semantic Commit Messages](https://www.conventionalcommits.org/en/v1.0.0/) format\n7. **PR**: Submit pull request for review\n\n资料来源：[CONTRIBUTING.md:10-55](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n\n## Commit Convention\n\nCommits must follow semantic format:\n\n```\n<label>(<scope>): <description>\n\n[optional body]\n\n[optional footer with fixes/references]\n```\n\n**Labels:**\n- `fix` - Bug fixes\n- `feat` - New features\n- `docs` - Documentation changes\n- `test` - Test-only changes\n- `devops` - CI/build changes\n- `chore` - Maintenance tasks\n\nBranch naming for fixes: `fix-<issue-number>`\n\n资料来源：[CONTRIBUTING.md:55-90](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n\n## Version Management\n\nThe `roll.js` script handles Playwright version updates across the project:\n\n```javascript\n// Key functions in roll.js\nupdatePlaywrightVersion(version)  // Update package.json\ncopyConfig()                      // Sync config.d.ts from monorepo\n```\n\nTo roll to a new Playwright version:\n1. Run `npm run roll`\n2. Create branch: `git checkout -b roll-pw-<suffix>`\n3. Run tests: `npm test`\n4. Commit and open PR\n\n资料来源：[roll.js:1-50](https://github.com/microsoft/playwright-mcp/blob/main/roll.js)\n\n## Summary\n\nPlaywright MCP provides a production-ready integration layer that brings Playwright's powerful browser automation capabilities to AI systems via the Model Context Protocol. With support for multiple browsers, comprehensive tool coverage, and enterprise-grade features like isolated browser contexts and network filtering, it serves as a robust foundation for AI-driven web interactions.\n\nThe project's move to the main Playwright monorepo ensures tight integration with Playwright's development cycle and guarantees that the MCP tools remain synchronized with the latest browser automation features.\n\n---\n\n<a id='key-concepts'></a>\n\n## Key Concepts\n\n### 相关页面\n\n相关主题：[Introduction to Playwright MCP](#introduction), [Browser Configuration](#browser-configuration)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [CLAUDE.md](https://github.com/microsoft/playwright-mcp/blob/main/CLAUDE.md)\n- [CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n- [config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n- [package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n- [cli.js](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)\n- [playwright.config.ts](https://github.com/microsoft/playwright-mcp/blob/main/playwright.config.ts)\n- [roll.js](https://github.com/microsoft/playwright-mcp/blob/main/roll.js)\n- [update-readme.js](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)\n</details>\n\n# Key Concepts\n\nPlaywright MCP (Model Context Protocol) is a server implementation that exposes Playwright browser automation capabilities through the MCP protocol. It enables AI assistants and other MCP clients to interact with web pages through a standardized tool interface, supporting automation, testing, and web scraping workflows.\n\n## Architecture Overview\n\nThe Playwright MCP server acts as a bridge between MCP clients and Playwright's browser automation engine. The core implementation resides in the [Playwright monorepo](https://github.com/microsoft/playwright) at `packages/playwright/src/mcp`, while this repository serves as the distribution package and configuration layer.\n\n```mermaid\ngraph TD\n    A[MCP Client<br>e.g., AI Assistant] --> B[Playwright MCP Server]\n    B --> C[Playwright Core]\n    C --> D[Chromium]\n    C --> E[Firefox]\n    C --> F[WebKit]\n    \n    B --> G[Browser Context]\n    G --> H[Pages/Tabs]\n    H --> I[DOM Elements]\n    \n    J[Config Options] --> B\n    K[Tool Capabilities] --> B\n```\n\n资料来源：[CONTRIBUTING.md:40-44](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n\n## Tool Capabilities System\n\nThe MCP server organizes its functionality into discrete capabilities that can be enabled or disabled based on use case requirements.\n\n### Capability Types\n\n| Capability | Description | Default |\n|------------|-------------|---------|\n| `config` | Server configuration management | Enabled |\n| `core` | Core browser automation (navigation, clicks, input) | Enabled |\n| `core-navigation` | Advanced navigation control | Enabled |\n| `core-tabs` | Multiple tab/window management | Enabled |\n| `core-input` | Form input handling | Enabled |\n| `core-install` | Browser installation | Enabled |\n| `network` | Network request interception | Opt-in |\n| `pdf` | PDF generation | Opt-in |\n| `storage` | Session storage management | Opt-in |\n| `testing` | Test assertions | Opt-in |\n| `vision` | Screenshot and visual comparisons | Opt-in |\n| `devtools` | Developer tools integration | Opt-in |\n\n资料来源：[config.d.ts:45-56](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n### Opt-in Capabilities\n\nCapabilities not listed in the `core` group require explicit enablement via the `--caps` configuration option. For example:\n\n```bash\n--caps=network,storage,testing\n```\n\nOpt-in capabilities are documented with the following pattern in user-facing documentation:\n\n```\nCapability Title (opt-in via --caps=capability-name)\n```\n\n资料来源：[update-readme.js:120-123](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)\n\n## Browser Configuration\n\n### Browser Types\n\n| Option | Description |\n|--------|-------------|\n| `chromium` | Chromium-based browser (default) |\n| `firefox` | Mozilla Firefox |\n| `webkit` | WebKit/Safari engine |\n\n### Browser Isolation\n\n```typescript\nbrowser?: {\n  browserName?: 'chromium' | 'firefox' | 'webkit';\n  isolated?: boolean;      // Keep profile in memory only\n  userDataDir?: string;    // Custom profile persistence path\n};\n```\n\n- **isolated (default: true)**: Browser profile is kept in memory, not saved to disk\n- **userDataDir**: Path for browser profile persistence across sessions\n\n资料来源：[config.d.ts:8-17](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Network Security\n\n### Origin-Based Filtering\n\n| Configuration | Purpose |\n|--------------|---------|\n| `allowedOrigins` | Whitelist of permitted origins |\n| `blockedOrigins` | Blacklist of denied origins |\n\nWhen an origin matches both lists, it will be **blocked**.\n\n**Supported formats:**\n- Full origin: `https://example.com:8080` - matches exact origin\n- Wildcard port: `http://localhost:*` - matches any port with specified protocol\n\n资料来源：[config.d.ts:20-35](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Timeouts\n\n| Timeout | Default | Description |\n|---------|---------|-------------|\n| `action` | 5000ms | Default action timeout |\n| `navigation` | 60000ms | Default navigation timeout |\n| `expect` | 5000ms | Default assertion/expect timeout |\n\nConfiguration location: `timeouts` in the Config type.\n\n资料来源：[config.d.ts:47-62](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Session Management\n\n### Save Session\n\nThe `saveSession` option controls whether Playwright session data is persisted to the output directory.\n\n### Shared Browser Context\n\nWhen `sharedBrowserContext` is enabled, the same browser context is reused across all connected HTTP clients, enabling state sharing between requests.\n\n```typescript\nsaveSession?: boolean;\nsharedBrowserContext?: boolean;\n```\n\n资料来源：[config.d.ts:65-70](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Secrets Management\n\nSecrets provide a mechanism to redact sensitive information from tool responses before sending them to clients.\n\n```typescript\nsecrets?: Record<string, string>;\n```\n\n**Important**: Secrets replacement is a convenience feature, not a security measure. Always examine incoming and outgoing data on the client side.\n\n资料来源：[config.d.ts:75-80](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Console Logging\n\n| Level | Description |\n|-------|-------------|\n| `error` | Only error messages |\n| `warning` | Errors and warnings |\n| `info` | Informational messages (default) |\n| `debug` | All messages including debug |\n\n```typescript\nconsole?: {\n  level?: 'error' | 'warning' | 'info' | 'debug';\n}\n```\n\n资料来源：[config.d.ts:91-96](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Image Responses\n\nControls whether image responses are sent to MCP clients:\n\n| Value | Behavior |\n|-------|----------|\n| `allow` | Always send images |\n| `omit` | Never send images |\n| `auto` | Send images if client can display them (default) |\n\n```typescript\nimageResponses?: 'allow' | 'omit' | 'auto';\n```\n\n资料来源：[config.d.ts:64](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Output Directory\n\nFiles generated during MCP operations (screenshots, downloads, traces) are saved to the configured output directory:\n\n```typescript\noutputDir?: string;\n```\n\n资料来源：[config.d.ts:83](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Test ID Attribute\n\nSpecify a custom attribute to use for test identification:\n\n```typescript\ntestIdAttribute?: string;  // Default: \"data-testid\"\n```\n\n资料来源：[config.d.ts:43](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Command-Line Interface\n\n### CLI Entry Point\n\nThe CLI is implemented in `cli.js` and supports several commands:\n\n```javascript\nconst { tools, libCli } = require('playwright-core/lib/coreBundle');\ntools.decorateMCPCommand(p, packageJSON.version);\n```\n\n### Available Commands\n\n| Command | Description |\n|---------|-------------|\n| Standard MCP tools | Browser automation operations |\n| `install-browser` | Install Playwright browsers |\n\nThe CLI can forward `install-browser` to `playwright install` for browser installation.\n\n资料来源：[cli.js:24-30](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)\n\n## Configuration Precedence\n\nEnvironment variables take precedence over default values. The mapping follows this pattern:\n\n| CLI Option | Environment Variable |\n|------------|---------------------|\n| `--secrets` | `PLAYWRIGHT_MCP_SECRETS_FILE` |\n| `--output-dir` | `PLAYWRIGHT_MCP_OUTPUT_DIR` |\n| Other options | `PLAYWRIGHT_MCP_<NAME>` (uppercase, hyphen → underscore) |\n\nExample: `--browser-name` → `PLAYWRIGHT_MCP_BROWSER_NAME`\n\n资料来源：[update-readme.js:86-90](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)\n\n## Build and Release Workflow\n\n### Version Management\n\nThe package version is defined in `package.json`:\n\n```json\n{\n  \"name\": \"@playwright/mcp\",\n  \"version\": \"0.0.75\"\n}\n```\n\n### Rolling Playwright Versions\n\nThe `roll.js` script handles updating Playwright dependencies:\n\n1. Updates `playwright`, `playwright-core`, and `@playwright/test` versions\n2. Copies `config.d.ts` from the Playwright monorepo\n3. Regenerates README documentation\n\n```bash\nnpm run roll\n```\n\n资料来源：[roll.js:1-30](https://github.com/microsoft/playwright-mcp/blob/main/roll.js)\n\n### Branch Naming Convention\n\n| Purpose | Pattern |\n|---------|---------|\n| Rolling Playwright | `roll-pw-<version-suffix>` |\n| Issue fixes | `fix-<issue-number>` |\n\n资料来源：[CLAUDE.md:5](https://github.com/microsoft/playwright-mcp/blob/main/CLAUDE.md)\n\n## Testing Infrastructure\n\n### Test Configuration\n\nTests are configured via `playwright.config.ts`:\n\n```typescript\nprojects: [\n  { name: 'chrome' },\n  ...process.env.MCP_IN_DOCKER ? [{\n    name: 'chromium-docker',\n    grep: /browser_navigate|browser_click/,\n    use: {\n      mcpBrowser: 'chromium',\n      mcpMode: 'docker' as const\n    }\n  }] : [],\n]\n```\n\n### Test Commands\n\n| Command | Scope |\n|---------|-------|\n| `npm test` | All tests across all browsers |\n| `npm run ctest` | Chrome only (fast path) |\n| `npm run ftest` | Firefox only |\n| `npm run wtest` | WebKit only |\n| `npm run dtest` | Docker-based Chromium |\n\nMCP tests are located in `tests/mcp` directory within the Playwright monorepo.\n\n资料来源：[playwright.config.ts:22-38](https://github.com/microsoft/playwright-mcp/blob/main/playwright.config.ts)\n资料来源：[CONTRIBUTING.md:67-72](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n\n### Test Requirements\n\n- Tests must be **hermetic** (self-contained, no external dependencies)\n- Must work on all three platforms: macOS, Linux, Windows\n- Tests are required for new functionality (exceptions for pure refactoring)\n\n资料来源：[CONTRIBUTING.md:83-85](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n\n## Commit Conventions\n\n### Semantic Commit Format\n\n```\nlabel(namespace): title\n\ndescription\n\nfooter\n```\n\n### Labels\n\n| Label | Purpose |\n|-------|---------|\n| `fix` | Bug fixes |\n| `feat` | New features |\n| `docs` | Documentation-only changes |\n| `test` | Test-only changes |\n| `devops` | CI or build changes |\n| `chore` | Miscellaneous (default) |\n\n### Example\n\n```\nfix(proxy): handle SOCKS proxy authentication\n\nFixes: https://github.com/microsoft/playwright/issues/39562\n```\n\n资料来源：[CONTRIBUTING.md:11-31](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n\n## Contribution Workflow\n\n```mermaid\ngraph LR\n    A[File Issue] --> B[Get Assignment]\n    B --> C[Clone Repository]\n    C --> D[Create Branch]\n    D --> E[Implement Changes]\n    E --> F[Add Tests]\n    F --> G[Run Tests]\n    G --> H{Linter Pass?}\n    H -->|No| I[Fix Issues]\n    I --> G\n    H -->|Yes| J[Commit Changes]\n    J --> K[Open PR]\n    K --> L[Code Review]\n    L --> M[Merge]\n```\n\n### Submission Requirements\n\n- **Issue required**: Every contribution needs a corresponding GitHub issue\n- **Prior approval**: Unsolicited PRs will be closed\n- **Human oversight**: Low-quality AI contributions without human review will be closed\n\n资料来源：[CONTRIBUTING.md:41-52](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n\n## Documentation Generation\n\nThe `update-readme.js` script automatically generates documentation sections:\n\n1. **Tools section**: Lists all MCP tools grouped by capability\n2. **Options section**: CLI options from `--help` output\n3. **Config section**: TypeScript Config type definition\n\nGenerated sections are delimited by markers:\n```markdown\n<!--- Tools generated by update-readme.js -->\n...\n<!--- End of tools generated section --->\n```\n\nRun `npm run lint` to regenerate documentation.\n\n资料来源：[update-readme.js:1-150](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)\n\n---\n\n<a id='installation-guide'></a>\n\n## Installation Guide\n\n### 相关页面\n\n相关主题：[MCP Client Integration](#client-integration), [Docker Deployment](#docker-deployment)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n- [CLAUDE.md](https://github.com/microsoft/playwright-mcp/blob/main/CLAUDE.md)\n- [CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n- [cli.js](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)\n- [config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n- [playwright.config.ts](https://github.com/microsoft/playwright-mcp/blob/main/playwright.config.ts)\n</details>\n\n# Installation Guide\n\nThis guide covers all aspects of installing, configuring, and setting up the Playwright MCP (Model Context Protocol) server for development and production use.\n\n## Overview\n\nPlaywright MCP is an npm package (`@playwright/mcp`) that provides browser automation tools via the MCP protocol. It enables AI assistants to interact with web browsers through a standardized interface, supporting capabilities like navigation, clicking, input handling, network interception, and testing assertions.\n\n资料来源：[package.json:1-15]()\n\n## System Requirements\n\n### Runtime Requirements\n\n| Requirement | Version | Description |\n|-------------|---------|-------------|\n| Node.js | >= 18 | JavaScript runtime environment |\n| npm | Latest | Package manager (bundled with Node.js) |\n\nThe package explicitly declares its Node.js engine requirement in `package.json`:\n\n```json\n\"engines\": {\n  \"node\": \">=18\"\n}\n```\n\n资料来源：[package.json:12-14]()\n\n### Browser Dependencies\n\nPlaywright MCP requires browser binaries to function. The supported browsers are:\n\n| Browser | Support Level | Notes |\n|---------|---------------|-------|\n| Chromium | Full | Primary development browser |\n| Firefox | Full | Cross-browser testing |\n| WebKit | Full | Safari compatibility testing |\n\n## Installation Methods\n\n### From npm (Global Installation)\n\nFor CLI usage across the system:\n\n```bash\nnpm install -g @playwright/mcp\n```\n\nThis makes the `playwright` command available globally:\n\n```bash\nplaywright --help\n```\n\n资料来源：[cli.js:23-26]()\n\n### From npm (Project Installation)\n\nFor use as a project dependency:\n\n```bash\nnpm install @playwright/mcp\n```\n\n### Using npx (No Installation)\n\nFor one-time execution without installing globally:\n\n```bash\nnpx @playwright/mcp [options]\n```\n\n## CLI Options\n\nThe MCP server accepts the following command-line options:\n\n| Option | Environment Variable | Description |\n|--------|---------------------|-------------|\n| `--secrets <file>` | `PLAYWRIGHT_MCP_SECRETS_FILE` | Path to secrets file |\n| `--browser <browser>` | `PLAYWRIGHT_MCP_BROWSER` | Browser to use (chromium, firefox, webkit) |\n| `--caps <capabilities>` | `PLAYWRIGHT_MCP_CAPS` | Enable additional capabilities |\n| `--output-dir <path>` | `PLAYWRIGHT_MCP_OUTPUT_DIR` | Directory for output files |\n| `--config <file>` | `PLAYWRIGHT_MCP_CONFIG` | Path to config file |\n| `--install-browser` | N/A | Install browser binaries |\n| `--version` | N/A | Show version information |\n| `--help` | N/A | Show help message |\n\n资料来源：[update-readme.js:89-111]()\n\n### Environment Variable Mapping\n\nEvery CLI option can be configured via environment variables by prefixing the option name with `PLAYWRIGHT_MCP_` and converting dashes to underscores:\n\n```bash\nexport PLAYWRIGHT_MCP_BROWSER=chromium\nexport PLAYWRIGHT_MCP_OUTPUT_DIR=/tmp/playwright-output\nexport PLAYWRIGHT_MCP_SECRETS_FILE=./secrets.json\n```\n\n## Configuration File\n\n### Config File Format\n\nCreate a TypeScript config file (e.g., `config.ts`) with the following structure:\n\n```typescript\nimport type { Config } from '@playwright/mcp';\n\nconst config: Config = {\n  browser: {\n    browserName: 'chromium',\n    isolated: true,\n  },\n  capabilities: ['core', 'network'],\n  outputDir: '/tmp/playwright-output',\n  timeouts: {\n    action: 5000,\n    navigation: 60000,\n    expect: 5000,\n  },\n};\n\nexport default config;\n```\n\n### Configuration Options\n\n#### Browser Configuration\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `browserName` | `'chromium' \\| 'firefox' \\| 'webkit'` | `'chromium'` | Browser type to launch |\n| `isolated` | `boolean` | `false` | Keep browser profile in memory |\n| `userDataDir` | `string` | `undefined` | Custom browser profile directory |\n\n资料来源：[config.d.ts:18-40]()\n\n#### Capabilities Configuration\n\nThe following tool capabilities are available:\n\n| Capability | Description | Notes |\n|------------|-------------|-------|\n| `core` | Core navigation and interaction tools | Always enabled |\n| `core-navigation` | Page navigation tools | Enabled by default |\n| `core-tabs` | Tab management tools | Enabled by default |\n| `core-input` | Input handling tools | Enabled by default |\n| `core-install` | Browser installation tools | Enabled by default |\n| `network` | Network request interception | Opt-in via `--caps=network` |\n| `pdf` | PDF generation | Opt-in via `--caps=pdf` |\n| `storage` | Storage and cookie management | Opt-in via `--caps=storage` |\n| `testing` | Test assertion tools | Opt-in via `--caps=testing` |\n| `vision` | Coordinate-based interactions | Opt-in via `--caps=vision` |\n| `devtools` | Developer tools features | Opt-in via `--caps=devtools` |\n| `config` | Configuration tools | Always enabled |\n\n资料来源：[config.d.ts:48-65]()\n\n#### Timeout Configuration\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `timeouts.action` | `5000ms` | Default action timeout |\n| `timeouts.navigation` | `60000ms` | Default navigation timeout |\n| `timeouts.expect` | `5000ms` | Default expect timeout |\n\n资料来源：[config.d.ts:83-97]()\n\n#### Network Configuration\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `network.allowedOrigins` | `string[]` | Allowed request origins |\n| `network.blockedOrigins` | `string[]` | Blocked request origins |\n\nOrigins can be specified as full URLs (`https://example.com:8080`) or with wildcard ports (`http://localhost:*`).\n\n资料来源：[config.d.ts:99-114]()\n\n## Development Setup\n\n### Clone the Repository\n\n> [!WARNING]\n> The core of the Playwright MCP was moved to the [Playwright monorepo](https://github.com/microsoft/playwright).\n\nClone the Playwright repository where Playwright MCP source is now located:\n\n```bash\ngit clone https://github.com/microsoft/playwright\ncd playwright\n```\n\n资料来源：[CONTRIBUTING.md:33-43]()\n\n### Install Dependencies\n\nInstall all project dependencies:\n\n```bash\nnpm ci\n```\n\n### Install Browser Binaries\n\nDownload and install the required browser binaries:\n\n```bash\nnpx playwright install\n```\n\nOr install specific browsers:\n\n```bash\nnpx playwright install chromium\nnpx playwright install firefox\nnpx playwright install webkit\n```\n\n资料来源：[CONTRIBUTING.md:44-50]()\n\n### Development Workflow\n\n#### Watch Mode\n\nFor active development with automatic rebuilding:\n\n```bash\nnpm run watch\n```\n\n#### Run Tests\n\nRun all MCP tests in Chromium (fast path):\n\n```bash\nnpm run mcp-ctest\n```\n\nRun all tests in three browsers (slow path):\n\n```bash\nnpm run mcp-test\n```\n\n#### Linting\n\nCheck code quality using the linter:\n\n```bash\nnpm run flint\n```\n\n资料来源：[CONTRIBUTING.md:51-70]()\n\n### Test Directory Structure\n\nTests for Playwright MCP are located at:\n\n```\ntests/mcp/\n```\n\nTo list test files:\n\n```bash\nls -la tests/mcp\n```\n\n资料来源：[CONTRIBUTING.md:59-66]()\n\n## Docker Installation\n\n### Build the Docker Image\n\n```bash\nnpm run docker-build\n```\n\nThis creates a Docker image named `playwright-mcp-dev:latest`.\n\n### Run the Docker Container\n\n```bash\nnpm run docker-run\n```\n\nThis starts an interactive session with port 8080 exposed.\n\n### Docker Test Mode\n\nRun tests within Docker using Chromium:\n\n```bash\nnpm run dtest\n```\n\n资料来源：[package.json:23-30]()\n\n## Testing Your Installation\n\n### Verify CLI Access\n\n```bash\nplaywright --version\n```\n\nExpected output:\n```\nVersion <version-number>\n```\n\n### Verify MCP Connection\n\nTest that the MCP server starts correctly:\n\n```bash\nplaywright --help\n```\n\n### Run Test Suite\n\nExecute the test suite to verify functionality:\n\n```bash\nnpm test\n```\n\nOnly proceed with deployment if all tests pass.\n\n资料来源：[CLAUDE.md:4-5]()\n\n## Package Scripts Reference\n\n| Script | Purpose |\n|--------|---------|\n| `npm run build` | Build the project (echoes \"OK\") |\n| `npm run lint` | Run update-readme.js script |\n| `npm run test` | Run all Playwright tests |\n| `npm run ctest` | Run Chrome tests only |\n| `npm run ftest` | Run Firefox tests only |\n| `npm run wtest` | Run WebKit tests only |\n| `npm run dtest` | Run Docker-based tests |\n| `npm run roll` | Update Playwright version |\n| `npm run npm-publish` | Lint, test, and publish |\n| `npm run docker-build` | Build Docker image |\n| `npm run docker-run` | Run Docker container |\n| `npm run docker-rm` | Remove Docker container |\n\n资料来源：[package.json:18-35]()\n\n## Troubleshooting\n\n### Node.js Version Error\n\nIf you see an engine version error, ensure you have Node.js 18 or later:\n\n```bash\nnode --version\n# Should be >= 18.0.0\n```\n\n### Browser Installation Failure\n\nIf browser installation fails, try with elevated permissions or check network connectivity:\n\n```bash\nnpx playwright install --with-deps\n```\n\n### Test Failures\n\n1. Ensure all dependencies are installed: `npm ci`\n2. Ensure browsers are installed: `npx playwright install`\n3. Verify Node.js version: `node --version`\n4. Clear any cached state and retry\n\n### Permission Errors\n\nFor global installations, you may need sudo on Unix systems:\n\n```bash\nsudo npm install -g @playwright/mcp\n```\n\nOr use a Node version manager like `nvm` to avoid permission issues.\n\n---\n\n<a id='client-integration'></a>\n\n## MCP Client Integration\n\n### 相关页面\n\n相关主题：[Installation Guide](#installation-guide), [Browser Configuration](#browser-configuration)\n\n<details>\n<summary>Relevant Source Files</summary>\n\n以下源码文件用于生成本页说明：\n\n- [config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n- [server.json](https://github.com/microsoft/playwright-mcp/blob/main/server.json)\n- [package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n- [cli.js](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)\n- [CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n- [update-readme.js](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)\n- [playwright.config.ts](https://github.com/microsoft/playwright-mcp/blob/main/playwright.config.ts)\n</details>\n\n# MCP Client Integration\n\n## Overview\n\nMCP Client Integration refers to the mechanism by which the Playwright MCP (Model Context Protocol) server exposes browser automation capabilities as tools that can be consumed by LLM clients. The integration provides a bridge between the MCP protocol and Playwright's browser automation APIs, enabling AI agents to control browsers through a standardized interface.\n\nThe MCP server implementation has been moved to the [Playwright monorepo](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/mcp), while this repository (`microsoft/playwright-mcp`) serves as a distribution package and coordination point for the MCP tooling.\n\n资料来源：[src/README.md](https://github.com/microsoft/playwright-mcp/blob/main/src/README.md)\n\n## Architecture\n\n### System Components\n\nThe MCP Client Integration consists of several interconnected components:\n\n```mermaid\ngraph TD\n    A[\"MCP Client<br/>(LLM Agent)\"] --> B[\"Playwright MCP Server\"]\n    B --> C[\"playwright-core<br/>coreBundle\"]\n    B --> D[\"playwright-core<br/>tools Bundle\"]\n    C --> E[\"Browser Process\"]\n    D --> E\n    E --> F[\"Page/Document\"]\n    \n    G[\"CLI Entry Point<br/>(cli.js)\"] --> B\n    H[\"Configuration<br/>(config.d.ts)\"] --> B\n    I[\"server.json<br/>(Transport Config)\"] --> B\n```\n\n### Transport Layer\n\nThe MCP server uses STDIO transport by default, as specified in the server manifest:\n\n```json\n{\n  \"transport\": {\n    \"type\": \"stdio\"\n  }\n}\n```\n\n资料来源：[server.json:13](https://github.com/microsoft/playwright-mcp/blob/main/server.json)\n\n## Configuration Reference\n\n### Config Type Definition\n\nThe `Config` type in `config.d.ts` defines all available configuration options for the MCP server:\n\n```typescript\nexport type ToolCapability =\n  | 'config'\n  | 'core'\n  | 'core-navigation'\n  | 'core-tabs'\n  | 'core-input'\n  | 'core-install'\n  | 'network'\n  | 'pdf'\n  | 'storage'\n  | 'testing'\n  | 'vision'\n  | 'devtools';\n```\n\n资料来源：[config.d.ts:20-30](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n### Configuration Options Table\n\n| Category | Option | Type | Default | Description |\n|----------|--------|------|---------|-------------|\n| **Browser** | `browser.browserName` | `'chromium' \\| 'firefox' \\| 'webkit'` | - | Browser type to use |\n| **Browser** | `browser.isolated` | `boolean` | - | Keep profile in memory only |\n| **Browser** | `browser.userDataDir` | `string` | - | Persistent profile directory |\n| **Browser** | `browser.launchOptions` | `object` | - | Browser launch options |\n| **Network** | `network.allowedOrigins` | `string[]` | All | Allowed request origins |\n| **Network** | `network.blockedOrigins` | `string[]` | - | Blocked request origins |\n| **Timeouts** | `timeouts.action` | `number` | 5000ms | Default action timeout |\n| **Timeouts** | `timeouts.navigation` | `number` | 60000ms | Default navigation timeout |\n| **Timeouts** | `timeouts.expect` | `number` | 5000ms | Default expect timeout |\n| **Output** | `imageResponses` | `'allow' \\| 'omit' \\| 'auto'` | `'auto'` | Image response handling |\n| **Output** | `outputDir` | `string` | - | Directory for output files |\n| **Session** | `saveSession` | `boolean` | - | Save Playwright session to output |\n| **Session** | `sharedBrowserContext` | `boolean` | - | Reuse context between clients |\n| **Server** | `server.port` | `number` | - | SSE/MCP transport port |\n| **Server** | `server.host` | `string` | - | Server bind host |\n| **Server** | `server.allowedHosts` | `string[]` | - | Allowed serving hosts |\n\n资料来源：[config.d.ts:31-150](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n### Secrets Management\n\nThe configuration supports secrets replacement for sensitive data:\n\n```typescript\nsecrets?: Record<string, string>;\n```\n\nSecrets are used to replace matching plain text in tool responses to prevent LLMs from accidentally receiving sensitive information. This is a convenience feature, not a security mechanism.\n\n资料来源：[config.d.ts:145-150](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Capabilities System\n\n### Capability Types\n\nCapabilities control which tool categories are exposed to the MCP client:\n\n| Capability | Purpose |\n|------------|---------|\n| `core` | Core browser automation features |\n| `core-navigation` | Navigation-related tools |\n| `core-tabs` | Tab management tools |\n| `core-input` | Input handling tools |\n| `core-install` | Browser installation tools |\n| `network` | Network request/response tools |\n| `pdf` | PDF generation and manipulation |\n| `storage` | Storage/state management tools |\n| `testing` | Testing utilities |\n| `vision` | Coordinate-based interactions |\n| `devtools` | Developer tools features |\n| `config` | Configuration tools |\n\n资料来源：[config.d.ts:20-29](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n### Capability Enablement\n\nCapabilities are specified in the `capabilities` array:\n\n```typescript\ncapabilities?: ToolCapability[];\n```\n\nOnly listed capabilities will be enabled. If not specified, all capabilities may be available.\n\n## Tool Schema and Generation\n\n### Tool Information Extraction\n\nThe `update-readme.js` script parses compiled modules to extract tool information for documentation:\n\n```javascript\nasync function updateTools(content) {\n  console.log('Loading tool information from compiled modules...');\n  const generatedLines = /** @type {string[]} */ ([]);\n  for (const [capability, tools] of Object.entries(toolsByCapability)) {\n    generatedLines.push(`<details>\\n<summary><b>${capability}</b></summary>`);\n    for (const tool of tools)\n      generatedLines.push(...formatToolForReadme(tool.schema));\n    generatedLines.push(`</details>`);\n  }\n  // ...\n}\n```\n\n资料来源：[update-readme.js:95-108](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)\n\n### Tool Schema Structure\n\nEach tool follows a standardized schema format:\n\n```javascript\nfunction formatToolForReadme(tool) {\n  const lines = /** @type {string[]} */ ([]);\n  lines.push(`- **${tool.name}**`);\n  lines.push(`  - Title: ${tool.title}`);\n  lines.push(`  - Description: ${tool.description}`);\n  \n  const inputSchema = tool.inputSchema ? tool.inputSchema.toJSONSchema() : {};\n  if (inputSchema.properties) {\n    lines.push(`  - Parameters:`);\n    Object.entries(inputSchema.properties).forEach(([name, param]) => {\n      lines.push(`    - \\`${name}\\`: ${param.description}`);\n    });\n  }\n  lines.push(`  - Read-only: **${tool.type === 'readOnly'}**`);\n  return lines;\n}\n```\n\n资料来源：[update-readme.js:145-167](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)\n\n### Config Schema Documentation\n\nThe config schema is extracted from `config.d.ts` and embedded into README:\n\n```javascript\nasync function updateConfig(content) {\n  const configPath = path.join(__dirname, 'config.d.ts');\n  const configContent = await fs.promises.readFile(configPath, 'utf-8');\n  const configTypeMatch = configContent.match(/export type Config = (\\{[\\s\\S]*?\\n\\});/);\n  // ...\n}\n```\n\n资料来源：[update-readme.js:115-126](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)\n\n## CLI Interface\n\n### Command-Line Entry Point\n\nThe CLI is implemented in `cli.js` and provides the primary interface for running the MCP server:\n\n```javascript\nconst { program } = require('playwright-core/lib/utilsBundle');\nconst { tools, libCli } = require('playwright-core/lib/coreBundle');\n\nconst packageJSON = require('./package.json');\nconst p = program.version('Version ' + packageJSON.version).name('Playwright MCP');\ntools.decorateMCPCommand(p, packageJSON.version);\n\nvoid program.parseAsync(process.argv);\n```\n\n资料来源：[cli.js:24-33](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)\n\n### CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `install-browser` | Install Playwright browsers |\n| MCP tools | Exposed via decorated command |\n\nThe CLI leverages Playwright's built-in command decoration system from `playwright-core`:\n\n```javascript\ntools.decorateMCPCommand(p, packageJSON.version);\n```\n\n资料来源：[cli.js:29](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)\n\n### CLI Options Generation\n\nOptions are dynamically generated from the CLI help output:\n\n```javascript\nasync function updateOptions(content) {\n  execSync('node cli.js --help > help.txt');\n  const lines = output.toString().split('\\n');\n  // Parse option lines starting with '  --'\n  for (let line of lines) {\n    if (line.startsWith('  --')) {\n      const l = line.substring('  --'.length);\n      const gapIndex = l.indexOf('  ');\n      const name = l.substring(0, gapIndex).trim();\n      const value = l.substring(gapIndex).trim();\n      options.push({ name, value });\n    }\n  }\n}\n```\n\n资料来源：[update-readme.js:52-65](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)\n\n## Testing\n\n### Test Configuration\n\nThe project uses Playwright's test framework with a dedicated MCP test configuration:\n\n```typescript\nimport { defineConfig } from '@playwright/test';\n\nexport default defineConfig<TestOptions>({\n  testDir: './tests',\n  fullyParallel: true,\n  forbidOnly: !!process.env.CI,\n  workers: process.env.CI ? 2 : undefined,\n  reporter: 'list',\n  projects: [\n    { name: 'chrome' },\n  ],\n});\n```\n\n资料来源：[playwright.config.ts:17-30](https://github.com/microsoft/playwright-mcp/blob/main/playwright.config.ts)\n\n### Test Commands\n\n| Command | Description |\n|---------|-------------|\n| `npm test` | Run all MCP tests |\n| `npm run ctest` | Run tests in Chromium only |\n| `npm run ftest` | Run tests in Firefox only |\n| `npm run wtest` | Run tests in WebKit only |\n| `npm run dtest` | Run tests in Docker (Chromium) |\n\n资料来源：[package.json:15-22](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n\n### Test Requirements\n\nTests must be:\n- **Hermetic**: No external service dependencies\n- **Cross-platform**: Work on macOS, Linux, and Windows\n- **Covered by tests**: New functionality requires corresponding tests\n\n资料来源：[CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n\n## Workflow: README Generation\n\nThe README is auto-generated from multiple sources:\n\n```mermaid\ngraph LR\n    A[\"config.d.ts\"] --> D[\"updateReadme()\"]\n    B[\"CLI --help\"] --> D\n    C[\"Tool Schemas\"] --> D\n    D --> E[\"README.md\"]\n```\n\n### Generation Pipeline\n\n```javascript\nasync function updateReadme() {\n  const readmePath = path.join(__dirname, 'README.md');\n  const readmeContent = await fs.promises.readFile(readmePath, 'utf-8');\n  const withTools = await updateTools(readmeContent);\n  const withOptions = await updateOptions(withTools);\n  const withConfig = await updateConfig(withOptions);\n  await fs.promises.writeFile(readmePath, withConfig, 'utf-8');\n}\n```\n\n资料来源：[update-readme.js:130-139](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)\n\n## Development Workflow\n\n### Local Development\n\n```bash\n# Clone the Playwright monorepo (source location)\ngit clone https://github.com/microsoft/playwright\ncd playwright\n\n# Install dependencies and run watch mode\nnpm ci\nnpm run watch\nnpx playwright install\n\n# Navigate to MCP source\ncd packages/playwright/src/mcp\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n\n### Rolling Playwright Updates\n\nThe repository maintains synchronization with the Playwright core:\n\n```bash\n# Run roll script to update dependencies\nnpm run roll\n# This bumps playwright, playwright-core, @playwright/test\n# Refreshes config.d.ts\n# Regenerates README\n```\n\n资料来源：[CLAUDE.md](https://github.com/microsoft/playwright-mcp/blob/main/CLAUDE.md)\n\n### Linting\n\nBefore submitting changes, run the linter:\n\n```bash\nnpm run lint\n```\n\nThis executes `update-readme.js` to validate and regenerate documentation.\n\n资料来源：[package.json:14](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n\n## Package Information\n\n### NPM Package Details\n\n| Property | Value |\n|----------|-------|\n| Package Name | `@playwright/mcp` |\n| MCP Name | `io.github.microsoft/playwright-mcp` |\n| Node Engine | `>=18` |\n| License | Apache-2.0 |\n| Transport | STDIO |\n\n资料来源：[package.json:1-12](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n\n---\n\n<a id='browser-configuration'></a>\n\n## Browser Configuration\n\n### 相关页面\n\n相关主题：[User Profiles and Session Management](#user-profiles), [Security Settings](#security-settings)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n- [playwright.config.ts](https://github.com/microsoft/playwright-mcp/blob/main/playwright.config.ts)\n- [README.md](https://github.com/microsoft/playwright-mcp/blob/main/README.md)\n- [package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n- [cli.js](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)\n</details>\n\n# Browser Configuration\n\n## Overview\n\nBrowser Configuration in playwright-mcp defines how the Playwright MCP server manages browser instances for automation tasks. The configuration is defined through the `Config` type in `config.d.ts` and controls browser selection, launch behavior, session persistence, and security policies.\n\n资料来源：[config.d.ts:48-120]()\n\n```mermaid\ngraph TD\n    A[Browser Configuration] --> B[Browser Selection]\n    A --> C[Launch Options]\n    A --> D[Session Management]\n    A --> E[Network Security]\n    A --> F[Server Binding]\n    \n    B --> B1[chromium]\n    B --> B2[firefox]\n    B --> B3[webkit]\n    \n    C --> C1[User Data Dir]\n    C --> C2[Init Scripts]\n    C --> C3[Launch Params]\n```\n\n## Browser Type Selection\n\n### Supported Browsers\n\nThe configuration supports three browser engines:\n\n| Browser | Identifier | Notes |\n|---------|------------|-------|\n| Chromium | `chromium` | Default, best compatibility |\n| Firefox | `firefox` | Gecko-based engine |\n| WebKit | `webkit` | Safari engine port |\n\n资料来源：[config.d.ts:57-64]()\n\n### Configuration Properties\n\n```typescript\nbrowser?: {\n  browserName?: 'chromium' | 'firefox' | 'webkit';\n  isolated?: boolean;\n  userDataDir?: string;\n  launchOptions?: Record<string, any>;\n  initPage?: string[];\n  initScript?: string[];\n}\n```\n\n| Property | Type | Default | Description |\n|----------|------|---------|-------------|\n| `browserName` | `'chromium' \\| 'firefox' \\| 'webkit'` | `chromium` | Browser engine to launch |\n| `isolated` | `boolean` | `false` | Keep browser profile in memory only |\n| `userDataDir` | `string` | system temp | Custom profile directory path |\n| `launchOptions` | `Record<string, any>` | `{}` | Playwright launch options |\n| `initPage` | `string[]` | `[]` | TypeScript initialization scripts |\n| `initScript` | `string[]` | `[]` | JavaScript initialization scripts |\n\n资料来源：[config.d.ts:48-87]()\n\n## Profile Management\n\n### Isolated Mode\n\nWhen `isolated: true`, the browser profile is kept entirely in memory without persisting to disk. This provides:\n\n- Better privacy between sessions\n- Clean state for each automation run\n- No leftover browser data\n\n### Custom User Data Directory\n\nThe `userDataDir` option allows specifying a persistent profile location:\n\n```typescript\n{\n  browser: {\n    userDataDir: '/path/to/custom/profile'\n  }\n}\n```\n\nIf not specified, the system creates a temporary directory automatically.\n\n资料来源：[config.d.ts:68-75]()\n\n## Initialization Scripts\n\nInitialization scripts run before any page content, enabling you to inject polyfills, modify prototypes, or set up testing utilities.\n\n### TypeScript Scripts (`initPage`)\n\nPaths to TypeScript files that are added as initialization scripts:\n\n```typescript\n{\n  browser: {\n    initPage: ['./setup.ts', './fixtures.ts']\n  }\n}\n```\n\n### JavaScript Scripts (`initScript`)\n\nPaths to JavaScript files evaluated in every page before page scripts:\n\n```typescript\n{\n  browser: {\n    initScript: ['./polyfills.js', './mocks.js']\n  }\n}\n```\n\nBoth script types are evaluated in every page created within the browser context.\n\n资料来源：[config.d.ts:81-87]()\n\n## Extension Support\n\nPlaywright MCP can connect to a running browser instance using the Playwright Extension (Chrome/Edge only):\n\n```typescript\n{\n  extension: true\n}\n```\n\nWhen `extension` is enabled:\n- The `browser` configuration is ignored\n- Requires the \"Playwright Extension\" browser add-on to be installed\n- Connects to the browser's debugging port\n\n资料来源：[config.d.ts:89-93]()\n\n## Server Configuration\n\nThe server section controls network binding for the MCP transport:\n\n```typescript\nserver?: {\n  port?: number;\n  host?: string;\n  allowedHosts?: string[];\n}\n```\n\n| Property | Type | Default | Description |\n|----------|------|---------|-------------|\n| `port` | `number` | undefined | Port for SSE or MCP transport |\n| `host` | `string` | `localhost` | Bind address; use `0.0.0.0` for all interfaces |\n| `allowedHosts` | `string[]` | server host | DNS rebinding protection |\n\n资料来源：[config.d.ts:95-107]()\n\n## Capability Management\n\nCapabilities control which tool sets are enabled for the MCP server:\n\n```typescript\ncapabilities?: ToolCapability[];\n```\n\n| Capability | Description |\n|-------------|-------------|\n| `config` | Configuration tools |\n| `core` | Core browser automation |\n| `core-navigation` | Navigation operations |\n| `core-tabs` | Tab management |\n| `core-input` | Input handling |\n| `core-install` | Browser installation |\n| `network` | Network request tools |\n| `pdf` | PDF generation |\n| `storage` | Storage APIs |\n| `testing` | Testing utilities |\n| `vision` | Coordinate-based interactions |\n| `devtools` | Developer tools |\n\n资料来源：[config.d.ts:33-46]()\n\n## Session Management\n\n### Save Session\n\nWhen enabled, the Playwright session state is persisted to the output directory:\n\n```typescript\n{\n  saveSession: true\n}\n```\n\n资料来源：[config.d.ts:115-117]()\n\n### Shared Browser Context\n\nMultiple HTTP clients can share the same browser context:\n\n```typescript\n{\n  sharedBrowserContext: true\n}\n```\n\nThis is useful for environments where multiple requests need to share session state.\n\n资料来源：[config.d.ts:119-121]()\n\n## Security Configuration\n\n### Network Origins\n\nControl which origins the browser can request:\n\n```typescript\nnetwork?: {\n  allowedOrigins?: string[];\n  blockedOrigins?: string[];\n}\n```\n\n**Supported formats:**\n- Full origin: `https://example.com:8080` - matches only that exact origin\n- Wildcard port: `http://localhost:*` - matches any port on localhost with http\n\nOrigins matching both lists will be blocked.\n\n资料来源：[config.d.ts:151-165]()\n\n### Secrets Management\n\nSecrets replace matching plain text in tool responses to prevent sensitive data exposure:\n\n```typescript\n{\n  secrets: {\n    API_KEY: 'sk-xxxxx',\n    DB_PASSWORD: 'secret123'\n  }\n}\n```\n\n> Note: This is a convenience feature, not a security measure. Always examine incoming data.\n\n资料来源：[config.d.ts:123-129]()\n\n### Console Level\n\nControl console message verbosity:\n\n```typescript\nconsole?: {\n  level?: 'error' | 'warning' | 'info' | 'debug';\n}\n```\n\nEach level includes messages from more severe levels. Defaults to `info`.\n\n资料来源：[config.d.ts:140-146]()\n\n## Timeout Configuration\n\nConfigure default timeouts for various operations:\n\n```typescript\ntimeouts?: {\n  action?: number;      // Default: 5000ms\n  navigation?: number; // Default: 60000ms\n  expect?: number;     // Default: 5000ms\n}\n```\n\n资料来源：[config.d.ts:131-144]()\n\n## Test Configuration\n\nThe test suite uses a dedicated Playwright configuration:\n\n```typescript\n// playwright.config.ts\nexport default defineConfig<TestOptions>({\n  testDir: './tests',\n  fullyParallel: true,\n  forbidOnly: !!process.env.CI,\n  workers: process.env.CI ? 2 : undefined,\n  projects: [\n    { name: 'chrome' },\n    ...process.env.MCP_IN_DOCKER ? [{\n      name: 'chromium-docker',\n      grep: /browser_navigate|browser_click/,\n      use: {\n        mcpBrowser: 'chromium',\n        mcpMode: 'docker' as const\n      }\n    }] : [],\n  ],\n});\n```\n\nThe configuration supports:\n- Running tests across browser projects\n- Docker-based testing environment\n- CI-specific constraints (`forbidOnly`, limited workers)\n\n资料来源：[playwright.config.ts:1-34]()\n\n## CLI Usage\n\nThe CLI provides commands for running and managing the MCP server:\n\n```bash\n# Run with custom config\nnpx playwright-mcp --config my-config.json\n\n# Install browser\nnpx playwright-mcp install-browser\n```\n\nThe CLI is decorated using Playwright's core tools and supports the MCP transport protocol.\n\n资料来源：[cli.js:1-35]()\n\n## Complete Configuration Example\n\n```typescript\nimport type { Config } from './config';\n\nconst config: Config = {\n  browser: {\n    browserName: 'chromium',\n    isolated: true,\n    initScript: ['./setup.js'],\n  },\n  server: {\n    port: 8080,\n    host: 'localhost',\n  },\n  capabilities: ['core', 'network', 'pdf'],\n  saveSession: false,\n  sharedBrowserContext: true,\n  secrets: {\n    API_KEY: process.env.API_KEY || '',\n  },\n  outputDir: './output',\n  network: {\n    allowedOrigins: ['https://example.com'],\n    blockedOrigins: ['https://malicious.com'],\n  },\n  console: {\n    level: 'info',\n  },\n  timeouts: {\n    action: 5000,\n    navigation: 30000,\n    expect: 3000,\n  },\n};\n```\n\n## Configuration Schema Summary\n\n| Section | Key Properties | File Source |\n|---------|----------------|-------------|\n| Browser | `browserName`, `isolated`, `userDataDir`, `launchOptions` | `config.d.ts:48-87` |\n| Extension | `extension: boolean` | `config.d.ts:89-93` |\n| Server | `port`, `host`, `allowedHosts` | `config.d.ts:95-107` |\n| Capabilities | `capabilities[]` | `config.d.ts:109-113` |\n| Session | `saveSession`, `sharedBrowserContext` | `config.d.ts:115-121` |\n| Security | `secrets`, `network` | `config.d.ts:123-165` |\n| Timeouts | `timeouts.action`, `timeouts.navigation`, `timeouts.expect` | `config.d.ts:131-144` |\n| Console | `console.level` | `config.d.ts:140-146` |\n\n## Related Commands\n\n| Command | Purpose |\n|---------|---------|\n| `npm run roll` | Update Playwright version and regenerate config |\n| `npm test` | Run test suite across all browsers |\n| `npm run ctest` | Run tests in Chromium only |\n| `npm run docker-run` | Start MCP in Docker container |\n\n资料来源：[package.json:8-27]()\n\n---\n\n<a id='security-settings'></a>\n\n## Security Settings\n\n### 相关页面\n\n相关主题：[Browser Configuration](#browser-configuration), [Docker Deployment](#docker-deployment)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n- [SECURITY.md](https://github.com/microsoft/playwright-mcp/blob/main/SECURITY.md)\n- [README.md](https://github.com/microsoft/playwright-mcp/blob/main/README.md)\n- [package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n- [playwright.config.ts](https://github.com/microsoft/playwright-mcp/blob/main/playwright.config.ts)\n</details>\n\n# Security Settings\n\nPlaywright MCP provides comprehensive security settings to protect sensitive data, control browser access, and prevent unauthorized network requests. These settings are configurable through the `Config` type defined in `config.d.ts`.\n\n## Overview\n\nThe Playwright MCP server handles browser automation with built-in security mechanisms that address common attack vectors including:\n\n- DNS rebinding attacks\n- Unauthorized network access\n- Sensitive data exposure\n- Session hijacking\n\nAll security configurations are optional and have sensible defaults. Administrators should review and configure these settings based on their deployment environment and security requirements.\n\n## Configuration Schema\n\nSecurity settings are defined within the main `Config` type. The following table summarizes available security-related configuration options:\n\n| Configuration Section | Purpose | Default |\n|----------------------|---------|---------|\n| `browser.isolated` | Keep browser profile in memory | `false` |\n| `browser.userDataDir` | Browser profile storage location | Temporary directory |\n| `network.allowedOrigins` | Permitted request origins | All origins |\n| `network.blockedOrigins` | Blocked request origins | None |\n| `secrets` | Sensitive data replacement | None |\n| `server.allowedHosts` | DNS rebinding protection | Server host only |\n| `console.level` | Console message filtering | `\"info\"` |\n| `imageResponses` | Image response handling | `\"auto\"` |\n\n## Network Security\n\n### Origin-Based Access Control\n\nPlaywright MCP implements origin-based network filtering to control which websites the browser can access.\n\n```typescript\nnetwork?: {\n  allowedOrigins?: string[];\n  blockedOrigins?: string[];\n};\n```\n\n**Supported Formats:**\n\n| Format | Example | Description |\n|--------|---------|-------------|\n| Full origin | `https://example.com:8080` | Matches exact origin with port |\n| Wildcard port | `http://localhost:*` | Matches any port on localhost with HTTP |\n| Protocol wildcard | `https://*` | Matches any origin with HTTPS |\n\n**Origin Matching Rules:**\n\n1. Origins specified in `blockedOrigins` take precedence over `allowedOrigins`\n2. If an origin matches both lists, it will be **blocked**\n3. If only `allowedOrigins` is set, only those origins are accessible\n4. If only `blockedOrigins` is set, all origins except blocked are accessible\n5. If neither is set, all origins are accessible\n\n**Example Configuration:**\n\n```typescript\n{\n  network: {\n    // Allow only specific domains\n    allowedOrigins: [\n      'https://myapp.example.com',\n      'https://api.example.com:8080',\n      'http://localhost:*'  // Allow any localhost port for development\n    ],\n    // Block specific origins\n    blockedOrigins: [\n      'https://malicious-site.com'\n    ]\n  }\n}\n```\n\n### Browser Isolation\n\nBrowser isolation ensures that browser profiles and session data are not persisted to disk, reducing the attack surface.\n\n```typescript\nbrowser?: {\n  browserName?: 'chromium' | 'firefox' | 'webkit';\n  isolated?: boolean;\n  userDataDir?: string;\n};\n```\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `isolated` | `boolean` | When `true`, keeps browser profile in memory without disk persistence |\n| `userDataDir` | `string` | Custom path for browser profile storage |\n\n**Security Implications:**\n\n- `isolated: true` - Maximum security, no persistent data\n- `isolated: false` - Session persistence, faster subsequent launches\n\n## Secrets Management\n\nThe secrets configuration provides a convenience mechanism to redact sensitive information from tool responses before they reach the client.\n\n```typescript\nsecrets?: Record<string, string>;\n```\n\n**How It Works:**\n\n1. Define key-value pairs where the key is the pattern to find and value is the replacement\n2. All occurrences of the key in tool response text are replaced with the value\n3. This is a **convenience feature**, not a security boundary\n\n**Important Security Note:**\n\n> Secrets are used to replace matching plain text in the tool responses to prevent the LLM from accidentally getting sensitive data. It is a convenience and not a security feature, make sure to always examine information coming in and from the tool on the client.\n> 资料来源：[config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n**Example Configuration:**\n\n```typescript\n{\n  secrets: {\n    'sk-1234567890abcdef': '[API_KEY_REDACTED]',\n    'my-secret-token': '[TOKEN_REDACTED]',\n    'password123': '[PASSWORD_REDACTED]'\n  }\n}\n```\n\n### Data Flow Diagram\n\n```mermaid\ngraph TD\n    A[Browser Automation] --> B[Tool Response Generated]\n    B --> C{Secrets Configured?}\n    C -->|Yes| D[Scan Response for Secret Patterns]\n    C -->|No| E[Return Original Response]\n    D --> F{Pattern Match Found?}\n    F -->|Yes| G[Replace with Redacted Value]\n    F -->|No| E\n    G --> H[Return Sanitized Response]\n    E --> H\n```\n\n## Server Security\n\n### Host-Based Access Control\n\nThe server configuration includes protection against DNS rebinding attacks through the `allowedHosts` option.\n\n```typescript\nserver?: {\n  port?: number;\n  host?: string;\n  allowedHosts?: string[];\n};\n```\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `port` | `number` | 8080 | Port to listen on |\n| `host` | `string` | localhost | Binding interface |\n| `allowedHosts` | `string[]` | Server host | Hosts allowed to connect |\n\n**DNS Rebinding Protection:**\n\nThe `allowedHosts` setting protects against DNS rebinding attacks where a malicious domain resolves to your server's IP address. By default, only the host the server is bound to is allowed.\n\n**Example Configuration:**\n\n```typescript\n{\n  server: {\n    port: 8080,\n    host: '0.0.0.0',  // Bind to all interfaces\n    allowedHosts: [\n      'localhost',\n      '127.0.0.1',\n      'my-secure-domain.com'\n    ]\n  }\n}\n```\n\n## Console Security\n\nConsole message filtering controls what level of browser console output is exposed to clients.\n\n```typescript\nconsole?: {\n  level?: 'error' | 'warning' | 'info' | 'debug';\n};\n```\n\n**Log Levels:**\n\n| Level | Includes | Description |\n|-------|----------|-------------|\n| `error` | Error messages only | Most restrictive |\n| `warning` | Errors + Warnings | Recommended for production |\n| `info` | Errors + Warnings + Info | Default level |\n| `debug` | All messages | Development only |\n\n**Security Consideration:**\n\nLower log levels reduce information leakage but may hide important diagnostic information. Choose the appropriate level based on your environment.\n\n## Image Response Handling\n\nControl how image responses are handled to prevent potential information disclosure through image metadata.\n\n```typescript\nimageResponses?: 'allow' | 'omit' | 'auto';\n```\n\n| Option | Description |\n|--------|-------------|\n| `allow` | Always send image responses to client |\n| `omit` | Never send image responses |\n| `auto` | Send images only if client can display them (default) |\n\n## Timeouts and Resource Limits\n\nTimeouts help prevent resource exhaustion attacks and ensure predictable behavior.\n\n```typescript\ntimeouts?: {\n  action?: number;      // Default: 5000ms\n  navigation?: number; // Default: 60000ms\n  expect?: number;     // Default: 5000ms\n};\n```\n\n**Security Benefits:**\n\n- Prevents hanging operations from consuming resources\n- Limits exposure time for potentially malicious pages\n- Enables faster failure detection\n\n## Security Architecture\n\n```mermaid\ngraph TD\n    subgraph \"Client Layer\"\n        A[MCP Client]\n    end\n    \n    subgraph \"Security Middleware\"\n        B[Host Validation]\n        C[Origin Filtering]\n        D[Secrets Replacement]\n    end\n    \n    subgraph \"Browser Layer\"\n        E[Playwright Browser]\n        F[Isolated Context]\n    end\n    \n    A --> B\n    B --> C\n    C --> D\n    D --> E\n    E --> F\n    \n    style A fill:#f9f,stroke:#333\n    style B fill:#ff9,stroke:#333\n    style C fill:#ff9,stroke:#333\n    style D fill:#ff9,stroke:#333\n```\n\n## Security Best Practices\n\n### Production Deployment\n\n1. **Enable Browser Isolation**\n   ```typescript\n   { browser: { isolated: true } }\n   ```\n\n2. **Configure Origin Restrictions**\n   ```typescript\n   { network: { allowedOrigins: ['https://your-domain.com'] } }\n   ```\n\n3. **Use Appropriate Console Level**\n   ```typescript\n   { console: { level: 'warning' } }  // Production\n   ```\n\n4. **Set Server Host Restrictions**\n   ```typescript\n   { server: { allowedHosts: ['your-domain.com'] } }\n   ```\n\n5. **Configure Reasonable Timeouts**\n   ```typescript\n   { timeouts: { action: 5000, navigation: 30000 } }\n   ```\n\n### Development Considerations\n\n- Use `console.level: 'debug'` only in development\n- Consider `imageResponses: 'auto'` for performance\n- Use `isolated: false` for faster iteration\n\n## Reporting Security Issues\n\nMicrosoft maintains a security response process for reporting vulnerabilities.\n\n**Please do not report security vulnerabilities through public GitHub issues.**\n\nInstead, report them to the Microsoft Security Response Center (MSRC):\n\n- **Online:** [https://msrc.microsoft.com/create-report](https://aka.ms/security.md/msrc/create-report)\n- **Email:** [secure@microsoft.com](mailto:secure@microsoft.com) (PGP encryption available)\n\nResponse timeline: You should receive a response within 24 hours.\n 资料来源：[SECURITY.md](https://github.com/microsoft/playwright-mcp/blob/main/SECURITY.md)\n\n## Complete Security Configuration Example\n\n```typescript\nimport { createConnection } from '@playwright/mcp';\n\nconst connection = createConnection({\n  browser: {\n    browserName: 'chromium',\n    isolated: true  // Maximum security\n  },\n  \n  network: {\n    allowedOrigins: [\n      'https://trusted-app.example.com',\n      'http://localhost:*'  // Development only\n    ],\n    blockedOrigins: [\n      'https://untrusted-source.com'\n    ]\n  },\n  \n  secrets: {\n    'sk-api-key': '[REDACTED]',\n    'password': '[REDACTED]'\n  },\n  \n  server: {\n    port: 8080,\n    host: '127.0.0.1',\n    allowedHosts: ['localhost', '127.0.0.1']\n  },\n  \n  console: {\n    level: 'warning'  // Only errors and warnings\n  },\n  \n  imageResponses: 'auto',\n  \n  timeouts: {\n    action: 5000,\n    navigation: 30000,\n    expect: 3000\n  }\n});\n```\n\n## Related Documentation\n\n- [Playwright MCP README](https://github.com/microsoft/playwright-mcp/blob/main/README.md) - Main project documentation\n- [Config Type Definition](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts) - Complete configuration types\n- [Playwright Documentation](https://playwright.dev/docs/api/class-browser) - Browser automation reference\n\n---\n\n<a id='docker-deployment'></a>\n\n## Docker Deployment\n\n### 相关页面\n\n相关主题：[Programmatic Usage](#programmatic-usage), [Installation Guide](#installation-guide)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n- [CLAUDE.md](https://github.com/microsoft/playwright-mcp/blob/main/CLAUDE.md)\n- [package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n- [playwright.config.ts](https://github.com/microsoft/playwright-mcp/blob/main/playwright.config.ts)\n- [config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n</details>\n\n# Docker Deployment\n\nThis page documents the Docker deployment capabilities for Playwright MCP, including container-based development, testing, and runtime configuration.\n\n## Overview\n\nPlaywright MCP supports Docker-based deployment to provide isolated, consistent browser automation environments. The Docker integration enables:\n\n- Containerized browser testing\n- Isolated development environments\n- Consistent CI/CD pipelines\n- Cross-platform browser automation\n\nDocker support is configured through npm scripts defined in `package.json` and dedicated test configurations in `playwright.config.ts`.\n\n## Docker Scripts\n\nThe project provides three npm scripts for managing Docker containers:\n\n| Script | Command | Purpose |\n|--------|---------|---------|\n| `docker-build` | `docker build --no-cache -t playwright-mcp-dev:latest .` | Build the Docker image with no cache |\n| `docker-rm` | `docker rm playwright-mcp-dev` | Remove the existing container |\n| `docker-run` | `docker run -it -p 8080:8080 --name playwright-mcp-dev playwright-mcp-dev:latest` | Run the container interactively |\n\n### Building the Docker Image\n\n```bash\nnpm run docker-build\n```\n\nThis creates an image tagged as `playwright-mcp-dev:latest`. The `--no-cache` flag ensures a fresh build.\n\n### Running the Container\n\n```bash\nnpm run docker-run\n```\n\nThe container maps port 8080 for external access and runs in interactive mode (`-it`).\n\n### Cleaning Up\n\n```bash\nnpm run docker-rm\n```\n\nRemoves the container to allow fresh deployments.\n\n资料来源：[package.json:17-19](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n\n## Docker Test Configuration\n\nPlaywright MCP includes dedicated configuration for running tests within Docker containers using Chromium.\n\n### Chromium Docker Project\n\n```typescript\n{\n  name: 'chromium-docker',\n  grep: /browser_navigate|browser_click/,\n  use: {\n    mcpBrowser: 'chromium',\n    mcpMode: 'docker' as const\n  }\n}\n```\n\n| Parameter | Value | Description |\n|-----------|-------|-------------|\n| `name` | `chromium-docker` | Project identifier for Docker-based Chromium tests |\n| `grep` | `/browser_navigate\\|browser_click/` | Test filter for Docker-specific tests |\n| `mcpBrowser` | `chromium` | Browser type for Docker testing |\n| `mcpMode` | `docker` | Execution mode set to Docker |\n\n### Running Docker Tests\n\n```bash\nMCP_IN_DOCKER=1 playwright test --project=chromium-docker\n```\n\nThe `MCP_IN_DOCKER` environment variable enables Docker-specific test behavior.\n\n资料来源：[playwright.config.ts:27-34](https://github.com/microsoft/playwright-mcp/blob/main/playwright.config.ts)\n资料来源：[CONTRIBUTING.md:58-60](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n\n## Browser Configuration for Docker\n\nThe `config.d.ts` file defines browser options that can be configured for Docker deployments.\n\n### Browser Configuration Schema\n\n```typescript\nbrowser?: {\n  browserName?: 'chromium' | 'firefox' | 'webkit';\n  isolated?: boolean;\n  userDataDir?: string;\n  launchOptions?: Record<string, unknown>;\n};\n```\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `browserName` | `chromium \\| firefox \\| webkit` | Browser type to use in container |\n| `isolated` | `boolean` | Keep browser profile in memory (default: true for containers) |\n| `userDataDir` | `string` | Path to persist browser profile across sessions |\n| `launchOptions` | `Record<string, unknown>` | Browser-specific launch arguments |\n\n### Docker-Specific Browser Settings\n\nFor containerized environments, consider these recommended configurations:\n\n| Scenario | Recommended Settings |\n|----------|----------------------|\n| Ephemeral testing | `isolated: true`, no `userDataDir` |\n| Session persistence | `userDataDir: '/data/browser-profile'` |\n| Headless CI | `launchOptions: { headless: true }` |\n\n资料来源：[config.d.ts:28-45](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Network Configuration for Containers\n\nPlaywright MCP supports fine-grained network control for browser instances within Docker:\n\n### Allowed and Blocked Origins\n\n```typescript\nnetwork?: {\n  allowedOrigins?: string[];\n  blockedOrigins?: string[];\n};\n```\n\n| Parameter | Description |\n|-----------|-------------|\n| `allowedOrigins` | List of origins the browser is permitted to request |\n| `blockedOrigins` | List of origins to block (takes precedence over allowed) |\n\n### Origin Format Examples\n\n| Format | Example | Matches |\n|--------|---------|---------|\n| Full origin | `https://example.com:8080` | Exact origin and port |\n| Wildcard port | `http://localhost:*` | Any port on localhost with HTTP |\n| Protocol wildcard | `https://*.example.com` | All subdomains |\n\n> **Note:** Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.\n\n资料来源：[config.d.ts:70-85](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Server Configuration for Docker\n\nThe server can be configured to run within Docker containers:\n\n```typescript\nserver?: {\n  port?: number;\n  host?: string;\n  allowedHosts?: string[];\n};\n```\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `port` | `8080` | Port for SSE or MCP transport |\n| `host` | `localhost` | Bind address (use `0.0.0.0` for Docker) |\n| `allowedHosts` | Same as host | Allowed serving hosts (DNS rebinding protection) |\n\n### Docker Server Deployment\n\nFor containerized deployments, configure the server to bind to all interfaces:\n\n```typescript\n{\n  server: {\n    host: '0.0.0.0',\n    port: 8080,\n    allowedHosts: ['*']\n  }\n}\n```\n\n资料来源：[config.d.ts:117-130](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n    A[Developer Machine] --> B[Docker Container]\n    B --> C[Playwright MCP Server]\n    C --> D[Browser Instance]\n    D --> E[Web Application]\n    \n    F[CI/CD Pipeline] --> B\n    G[External Client] --> |HTTP:8080| B\n    \n    style B fill:#e1f5fe\n    style C fill:#f3e5f5\n    style D fill:#fff3e0\n```\n\n## Deployment Workflow\n\n```mermaid\ngraph LR\n    A[Build Image] --> B[Create Container]\n    B --> C[Run Tests or Server]\n    C --> D{Pass?}\n    D -->|Yes| E[Success]\n    D -->|No| F[Debug & Fix]\n    F --> A\n    \n    G[Clean Up] --> H[Remove Container]\n    G --> I[Remove Image]\n```\n\n## Environment Variables\n\n| Variable | Description | Example |\n|----------|-------------|---------|\n| `MCP_IN_DOCKER` | Enables Docker-specific test behavior | `1` |\n| `CI` | Indicates CI environment (limits workers) | `true` |\n\n资料来源：[CONTRIBUTING.md:58-60](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n资料来源：[playwright.config.ts:13](https://github.com/microsoft/playwright-mcp/blob/main/playwright.config.ts)\n\n## Complete Docker Workflow Example\n\n```bash\n# 1. Build the Docker image\nnpm run docker-build\n\n# 2. Remove any existing container\nnpm run docker-rm\n\n# 3. Run the container\nnpm run docker-run\n\n# 4. In another terminal, run Docker-specific tests\nMCP_IN_DOCKER=1 npm run dtest\n\n# 5. Clean up when done\nnpm run docker-rm\n```\n\n## Limitations and Considerations\n\n1. **No Dockerfile in Repository**: The repository does not include a `Dockerfile`. Users must create their own based on project requirements.\n2. **Browser Installation**: When building custom Docker images, ensure browsers are installed using `npx playwright install`.\n3. **Port Mapping**: The default configuration exposes port 8080; adjust as needed for your environment.\n4. **Browser Compatibility**: Docker testing is limited to Chromium (`chromium-docker` project).\n\n资料来源：[CLAUDE.md:11-16](https://github.com/microsoft/playwright-mcp/blob/main/CLAUDE.md)\n\n## Related Configuration\n\n| Configuration File | Purpose |\n|-------------------|---------|\n| `config.d.ts` | TypeScript definitions for all config options |\n| `playwright.config.ts` | Test runner configuration |\n| `package.json` | npm scripts for Docker operations |\n| `server.json` | MCP server metadata and transport |\n\n---\n\n<a id='programmatic-usage'></a>\n\n## Programmatic Usage\n\n### 相关页面\n\n相关主题：[Docker Deployment](#docker-deployment), [MCP Client Integration](#client-integration)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [index.js](https://github.com/microsoft/playwright-mcp/blob/main/index.js)\n- [cli.js](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)\n- [package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n- [config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n- [CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n- [src/README.md](https://github.com/microsoft/playwright-mcp/blob/main/src/README.md)\n</details>\n\n# Programmatic Usage\n\nThis page documents how to programmatically use Playwright MCP (Model Context Protocol) to integrate Playwright browser automation capabilities into your applications.\n\n## Overview\n\nPlaywright MCP provides browser automation tools that can be used by Large Language Models (LLMs) through the MCP protocol. The package exposes a `createConnection` function that enables programmatic integration with MCP-compatible clients.\n\nThe core implementation resides in the [Playwright monorepo](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/mcp), while this repository serves as the distribution package for the MCP tools.\n\n资料来源：[src/README.md:1-3](https://github.com/microsoft/playwright-mcp/blob/main/src/README.md)\n\n## Entry Points\n\nPlaywright MCP provides two primary entry points for programmatic usage:\n\n| Entry Point | File | Purpose |\n|-------------|------|---------|\n| Module | `index.js` | Programmatic import for Node.js applications |\n| CLI | `cli.js` | Command-line interface for direct execution |\n\n资料来源：[index.js:1-30](https://github.com/microsoft/playwright-mcp/blob/main/index.js)\n资料来源：[cli.js:1-45](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)\n\n### Module Import\n\nThe primary module export provides the `createConnection` function:\n\n```javascript\nconst { createConnection } = require('@playwright/mcp');\n```\n\n资料来源：[index.js:27-29](https://github.com/microsoft/playwright-mcp/blob/main/index.js)\n\nThe `createConnection` function is sourced from `playwright-core/lib/coreBundle`, which contains the core MCP implementation including tool definitions and connection handling logic.\n\n### CLI Usage\n\nThe CLI can be invoked directly via Node.js:\n\n```bash\nnode cli.js [command] [options]\n```\n\nThe CLI is decorated with Playwright's MCP command utilities, which handle transport negotiation and tool invocation.\n\n资料来源：[cli.js:24-28](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)\n\n## Configuration\n\nPlaywright MCP accepts configuration through the `Config` type defined in `config.d.ts`.\n\n### Tool Capabilities\n\nTool capabilities define which browser automation features are enabled:\n\n```typescript\nexport type ToolCapability =\n  | 'config'\n  | 'core'\n  | 'core-navigation'\n  | 'core-tabs'\n  | 'core-input'\n  | 'core-install'\n  | 'network'\n  | 'pdf'\n  | 'storage'\n  | 'testing'\n  | 'vision'\n  | 'devtools';\n```\n\n资料来源：[config.d.ts:17-30](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n| Capability | Description |\n|------------|-------------|\n| `core` | Core browser automation features |\n| `core-navigation` | Page navigation operations |\n| `core-tabs` | Browser tab management |\n| `core-input` | Input handling and form interaction |\n| `core-install` | Browser installation |\n| `network` | Network request interception |\n| `pdf` | PDF generation and manipulation |\n| `storage` | Local storage and session management |\n| `testing` | Test-related utilities |\n| `vision` | Coordinate-based interactions |\n| `devtools` | Developer tools features |\n| `config` | Configuration management |\n\n### Browser Configuration\n\n```typescript\nbrowser?: {\n  browserName?: 'chromium' | 'firefox' | 'webkit';\n  isolated?: boolean;\n  userDataDir?: string;\n  launchOptions?: object;\n}\n```\n\n资料来源：[config.d.ts:32-56](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n### Timeout Configuration\n\n```typescript\ntimeouts?: {\n  action?: number;      // Default: 5000ms\n  navigation?: number;  // Default: 60000ms\n  expect?: number;       // Default: 5000ms\n}\n```\n\n资料来源：[config.d.ts:98-110](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n### Server Configuration\n\n```typescript\nserver?: {\n  port?: number;\n  host?: string;\n  allowedHosts?: string[];\n}\n```\n\n资料来源：[config.d.ts:146-156](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Architecture\n\n```mermaid\ngraph TD\n    A[Client Application] -->|MCP Protocol| B[playwright-mcp]\n    B --> C[createConnection]\n    C --> D[playwright-core]\n    D --> E[Browser Automation]\n    E --> F[Chromium]\n    E --> G[Firefox]\n    E --> H[WebKit]\n    \n    I[CLI User] -->|cli.js| B\n    J[Module User] -->|index.js| B\n```\n\n## Available NPM Scripts\n\nThe `package.json` defines the following scripts for working with Playwright MCP:\n\n| Script | Command | Purpose |\n|--------|---------|---------|\n| `test` | `playwright test` | Run all tests |\n| `ctest` | `playwright test --project=chrome` | Run Chrome-only tests |\n| `ftest` | `playwright test --project=firefox` | Run Firefox-only tests |\n| `wtest` | `playwright test --project=webkit` | Run WebKit-only tests |\n| `lint` | `node update-readme.js` | Regenerate README |\n| `build` | `echo OK` | Build step (no-op) |\n| `roll` | `node roll.js` | Update Playwright version |\n\n资料来源：[package.json:13-24](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n\n## Package Metadata\n\n| Property | Value |\n|----------|-------|\n| Package Name | `@playwright/mcp` |\n| MCP Name | `io.github.microsoft/playwright-mcp` |\n| Node.js Requirement | `>=18` |\n| License | Apache-2.0 |\n\n资料来源：[package.json:1-16](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n\n## Browser Installation\n\nPlaywright MCP supports an `install-browser` command through the CLI:\n\n```bash\nnode cli.js install-browser\n```\n\nThis delegates to Playwright's browser installation mechanism, decorated via `libCli.decorateProgram`.\n\n资料来源：[cli.js:17-22](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)\n\n## Extension Mode\n\nPlaywright MCP supports connecting to a running browser instance through the Microsoft Edge/Chrome Playwright Extension:\n\n```typescript\nextension?: boolean;\n```\n\nWhen enabled, this allows connection to an existing browser instance rather than launching a new one.\n\n资料来源：[config.d.ts:134-140](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Network Configuration\n\nControl browser network access through origin-based filtering:\n\n```typescript\nnetwork?: {\n  allowedOrigins?: string[];   // List of allowed origins\n  blockedOrigins?: string[];   // List of blocked origins\n}\n```\n\nSupported formats:\n- Full origin: `https://example.com:8080`\n- Wildcard port: `http://localhost:*`\n\n资料来源：[config.d.ts:190-204](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Session Management\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `saveSession` | boolean | Save Playwright session to output directory |\n| `sharedBrowserContext` | boolean | Reuse browser context across HTTP clients |\n\n资料来源：[config.d.ts:166-173](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## Console Configuration\n\n```typescript\nconsole?: {\n  level?: 'error' | 'warning' | 'info' | 'debug';\n}\n```\n\n资料来源：[config.d.ts:182-187](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n---\n\n<a id='user-profiles'></a>\n\n## User Profiles and Session Management\n\n### 相关页面\n\n相关主题：[Browser Configuration](#browser-configuration), [Troubleshooting](#troubleshooting)\n\n<details>\n<summary>Relevant Source Files</summary>\n\nThe following source files were used to generate this page:\n\n- [config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n- [package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n- [server.json](https://github.com/microsoft/playwright-mcp/blob/main/server.json)\n- [cli.js](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)\n- [roll.js](https://github.com/microsoft/playwright-mcp/blob/main/roll.js)\n- [CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n</details>\n\n# User Profiles and Session Management\n\n## Overview\n\nUser Profiles and Session Management in Playwright MCP controls how browser instances are created, persisted, and shared across multiple HTTP clients and tool invocations. This system enables sophisticated browser automation scenarios while maintaining security and resource efficiency.\n\nThe MCP server supports:\n- **Isolated browser instances** per request\n- **Persistent user data directories** for profile retention\n- **Shared browser contexts** across clients\n- **Session saving and restoration**\n- **Secrets masking** in responses\n\n资料来源：[config.d.ts:22-40]()\n\n## Architecture\n\n```mermaid\ngraph TD\n    A[MCP Client] -->|HTTP/STDIO| B[Playwright MCP Server]\n    B --> C[Browser Manager]\n    C --> D{Shared Context?}\n    D -->|Yes| E[Single Browser Context]\n    D -->|No| F[Per-Client Context]\n    E --> G[Browser Instance]\n    F --> G\n    G --> H[User Data Directory]\n    G --> I[Session Files]\n    H -->|Persistence| J[Output Directory]\n```\n\n### Core Components\n\n| Component | Purpose | Configuration Key |\n|-----------|---------|-------------------|\n| Browser Manager | Creates and manages browser instances | `browser.*` |\n| Session Manager | Handles session save/restore | `saveSession` |\n| Context Pool | Manages shared vs isolated contexts | `sharedBrowserContext` |\n| Secrets Handler | Masks sensitive data in responses | `secrets` |\n\n资料来源：[config.d.ts:1-50]()\n\n## Browser Configuration\n\n### Browser Type Selection\n\nThe MCP server supports three browser engines:\n\n```typescript\nbrowser?: {\n  browserName?: 'chromium' | 'firefox' | 'webkit';\n}\n```\n\n| Browser | Engine | Use Case |\n|---------|--------|----------|\n| `chromium` | Blink | General automation, Chrome/Edge compatibility |\n| `firefox` | Gecko | Cross-browser testing, Firefox-specific features |\n| `webkit` | WebKit | Safari compatibility testing |\n\n资料来源：[config.d.ts:24-30]()\n\n### User Data Directory\n\nThe user data directory stores browser profile data including cookies, local storage, and session state.\n\n```typescript\nbrowser?: {\n  /**\n   * Path to a user data directory for browser profile persistence.\n   * Temporary directory is created by default.\n   */\n  userDataDir?: string;\n}\n```\n\n**Behavior:**\n- When `userDataDir` is unspecified, a temporary directory is created automatically\n- Persistent directories survive browser restarts\n- Useful for maintaining login sessions across tool invocations\n\n资料来源：[config.d.ts:38-43]()\n\n### Isolated Mode\n\nWhen `isolated: true`, browser profiles are kept entirely in memory without disk persistence.\n\n```typescript\nbrowser?: {\n  /**\n   * Keep the browser profile in memory, do not save it to disk.\n   */\n  isolated?: boolean;\n}\n```\n\n| Mode | Persistence | Security | Performance |\n|------|-------------|----------|-------------|\n| `isolated: true` | Memory only | Higher | Faster startup |\n| `isolated: false` | Disk (userDataDir) | Standard | Slower startup |\n\n资料来源：[config.d.ts:32-37]()\n\n## Session Management\n\n### Session Saving\n\nThe `saveSession` option controls whether Playwright sessions are persisted to the output directory.\n\n```typescript\nexport type Config = {\n  /**\n   * Whether to save the Playwright session into the output directory.\n   */\n  saveSession?: boolean;\n}\n```\n\n**Use cases:**\n- Debugging failed automation workflows\n- Resuming interrupted sessions\n- Analyzing browser state post-execution\n\n资料来源：[config.d.ts:83-87]()\n\n### Output Directory\n\nSessions and output files are saved to the configured output directory.\n\n```typescript\nexport type Config = {\n  /**\n   * The directory to save output files.\n   */\n  outputDir?: string;\n}\n```\n\n**Default behavior:** If not specified, the MCP server uses a platform-specific temporary directory.\n\n资料来源：[config.d.ts:95-99]()\n\n## Browser Context Management\n\n### Shared Browser Context\n\nWhen multiple HTTP clients connect to the MCP server, `sharedBrowserContext` determines whether they share a single browser context or receive isolated contexts.\n\n```typescript\nexport type Config = {\n  /**\n   * Reuse the same browser context between all connected HTTP clients.\n   */\n  sharedBrowserContext?: boolean;\n}\n```\n\n```mermaid\ngraph LR\n    A[Client 1] -->|MCP| B{sharedBrowserContext}\n    C[Client 2] -->|MCP| B\n    D[Client N] -->|MCP| B\n    \n    B -->|true| E[Shared Context]\n    B -->|false| F[Client 1 Context]\n    B -->|false| G[Client 2 Context]\n    B -->|false| H[Client N Context]\n```\n\n| Setting | Pros | Cons |\n|---------|------|------|\n| `sharedBrowserContext: true` | Resource efficient, shared cookies/auth | State bleeding between clients |\n| `sharedBrowserContext: false` | Complete isolation | Higher resource usage |\n\n资料来源：[config.d.ts:89-94]()\n\n## Secrets Management\n\nThe secrets system prevents sensitive data from being exposed to LLM clients.\n\n```typescript\nexport type Config = {\n  /**\n   * Secrets are used to replace matching plain text in the tool responses to prevent the LLM\n   * from accidentally getting sensitive data. It is a convenience and not a security feature,\n   * make sure to always examine information coming in and from the tool on the client.\n   */\n  secrets?: Record<string, string>;\n}\n```\n\n**Key characteristics:**\n- **Not a security feature** - Use proper authentication for actual security\n- Pattern matching replaces plain text in responses\n- Prevents LLM accidental exposure of sensitive information\n\n资料来源：[config.d.ts:100-106]()\n\n## Configuration Schema\n\n### Complete Config Type\n\n```typescript\nexport type Config = {\n  browser?: {\n    browserName?: 'chromium' | 'firefox' | 'webkit';\n    isolated?: boolean;\n    userDataDir?: string;\n    // ... launch options\n  };\n  \n  capabilities?: ToolCapability[];\n  saveSession?: boolean;\n  sharedBrowserContext?: boolean;\n  secrets?: Record<string, string>;\n  outputDir?: string;\n  \n  console?: {\n    level?: 'error' | 'warning' | 'info' | 'debug';\n  };\n  \n  network?: {\n    allowedOrigins?: string[];\n    blockedOrigins?: string[];\n  };\n  \n  testIdAttribute?: string;\n  \n  timeouts?: {\n    action?: number;\n    navigation?: number;\n    expect?: number;\n  };\n  \n  imageResponses?: 'allow' | 'omit';\n  \n  // ... additional options\n};\n```\n\n资料来源：[config.d.ts:1-180]()\n\n## Tool Capabilities\n\nThe MCP server exposes browser automation through categorized tool capabilities:\n\n| Capability | Description |\n|------------|-------------|\n| `config` | Configuration management |\n| `core` | Core browser automation |\n| `core-navigation` | Page navigation and routing |\n| `core-tabs` | Tab/window management |\n| `core-input` | Form input handling |\n| `core-install` | Browser installation |\n| `network` | Network request interception |\n| `pdf` | PDF generation |\n| `storage` | Storage management |\n| `testing` | Test-related tools |\n| `vision` | Coordinate-based interactions |\n| `devtools` | Developer tools features |\n\n资料来源：[config.d.ts:13-26]()\n\n## Server Configuration\n\nThe MCP server uses STDIO transport by default for optimal integration with MCP clients.\n\n```json\n{\n  \"name\": \"io.github.microsoft/playwright-mcp\",\n  \"description\": \"Playwright Tools for MCP\",\n  \"version\": \"0.0.75\",\n  \"packages\": [\n    {\n      \"registryType\": \"npm\",\n      \"identifier\": \"@playwright/mcp\",\n      \"version\": \"0.0.75\",\n      \"transport\": {\n        \"type\": \"stdio\"\n      }\n    }\n  ]\n}\n```\n\n资料来源：[server.json:1-15]()\n\n## CLI Options\n\nThe MCP server can be configured via command-line arguments:\n\n```bash\nnode cli.js --help\n```\n\nKey CLI commands:\n- `install-browser` - Install required browser binaries\n- Standard Playwright CLI options for browser management\n\n资料来源：[cli.js:1-35]()\n\n## Best Practices\n\n### Security Recommendations\n\n1. **Do not rely on secrets masking for security** - Treat it as UI/UX convenience only\n2. **Use isolated mode** for untrusted content\n3. **Configure network restrictions** using `allowedOrigins` and `blockedOrigins`\n\n### Performance Optimization\n\n| Scenario | Recommended Setting |\n|----------|---------------------|\n| Single client, high throughput | `sharedBrowserContext: true` |\n| Multiple clients requiring isolation | `sharedBrowserContext: false` |\n| Resource-constrained environment | `isolated: true` |\n| Need session persistence | `saveSession: true`, specify `outputDir` |\n\n### Testing Workflow\n\nFor testing MCP functionality:\n\n```bash\n# Fast path - Chromium only\nnpm run ctest\n\n# Full test suite - All browsers\nnpm run mcp-test\n\n# Docker environment\nnpm run dtest\n```\n\n资料来源：[package.json:18-25]()\n\n## Rolling Updates\n\nThe Playwright version can be updated while maintaining configuration compatibility:\n\n```bash\nnpm run roll\n```\n\nThis command:\n1. Updates `playwright`, `playwright-core`, and `@playwright/test` versions\n2. Refreshes `config.d.ts` from the Playwright monorepo\n3. Regenerates the README documentation\n\n资料来源：[roll.js:1-40](), [CLAUDE.md:1-35]()\n\n---\n\n<a id='troubleshooting'></a>\n\n## Troubleshooting\n\n### 相关页面\n\n相关主题：[User Profiles and Session Management](#user-profiles), [Browser Configuration](#browser-configuration)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [CLAUDE.md](https://github.com/microsoft/playwright-mcp/blob/main/CLAUDE.md)\n- [CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n- [package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n- [playwright.config.ts](https://github.com/microsoft/playwright-mcp/blob/main/playwright.config.ts)\n- [cli.js](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)\n</details>\n\n# Troubleshooting\n\nThis page documents common issues, debugging strategies, and resolution steps when working with Playwright MCP.\n\n## Overview\n\nTroubleshooting in Playwright MCP primarily involves:\n\n- Test execution failures\n- Browser launch and context issues\n- MCP tool invocation problems\n- Configuration mismatches\n- Dependency and version compatibility\n\n## Common Issues and Resolutions\n\n### Test Failures\n\n#### All Tests Failing\n\nIf all tests fail, verify the test environment is properly configured:\n\n```bash\n# Ensure dependencies are installed\nnpm ci\n\n# Install Playwright browsers\nnpx playwright install\n\n# Run tests in a single browser (faster feedback)\nnpm run ctest\n```\n\n**Source:** [package.json:11](https://github.com/microsoft/playwright-mcp/blob/main/package.json#L11)\n\n#### Cross-Browser Test Inconsistencies\n\nPlaywright MCP tests run in Chromium, Firefox, and WebKit. If failures occur in specific browsers:\n\n```bash\n# Test individual browsers\nnpm run ctest   # Chrome only\nnpm run ftest   # Firefox only\nnpm run wtest   # WebKit only\n```\n\nTests should be hermetic and work on all three platforms: macOS, Linux, and Windows. 资料来源：[CONTRIBUTING.md:71-72](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md#L71-L72)\n\n### Browser Launch Issues\n\n#### Persistent Context Problems\n\nThe `isolated` option controls whether browser profiles are saved to disk:\n\n```typescript\n{\n  browser: {\n    isolated: true   // Keeps profile in memory\n  }\n}\n```\n\nDefault behavior creates temporary directories for user data. 资料来源：[config.d.ts:35-38](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts#L35-L38)\n\n#### Network Requests Blocked\n\nConfigure allowed and blocked origins in the `network` section:\n\n```typescript\n{\n  network: {\n    allowedOrigins: ['https://example.com:8080'],\n    blockedOrigins: ['https://ads.example.com']\n  }\n}\n```\n\nOrigins matching both lists will be blocked. 资料来源：[config.d.ts:100-112](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts#L100-L112)\n\n### MCP Tool Invocation Errors\n\n#### Tool Not Found\n\nMCP tools are exposed through the connection interface. Ensure the server is properly initialized:\n\n```javascript\nconst { createConnection } = require('@playwright/mcp');\n```\n\nThe `createConnection` function is exported from the core bundle. 资料来源：[index.js:27-28](https://github.com/microsoft/playwright-mcp/blob/main/index.js#L27-L28)\n\n### Configuration Schema Errors\n\nTypeScript errors related to `Config` type indicate schema mismatches. The `config.d.ts` file defines the expected structure:\n\n```typescript\nexport type Config = {\n  browser?: { ... };\n  timeouts?: { ... };\n  capabilities?: ToolCapability[];\n  secrets?: Record<string, string>;\n  outputDir?: string;\n  console?: { level?: 'error' | 'warning' | 'info' | 'debug' };\n  network?: { allowedOrigins?: string[]; blockedOrigins?: string[] };\n}\n```\n\n## Debugging Strategies\n\n### Enabling Debug Logs\n\nConfigure console log levels to control verbosity:\n\n```typescript\n{\n  console: {\n    level: 'debug'  // 'error' | 'warning' | 'info' | 'debug'\n  }\n}\n```\n\nDefault level is `'info'`. 资料来源：[config.d.ts:88-91](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts#L88-L91)\n\n### Timeouts Configuration\n\nAdjust timeouts for slow environments:\n\n```typescript\n{\n  timeouts: {\n    action: 10000,     // Default: 5000ms\n    navigation: 120000, // Default: 60000ms\n    expect: 10000      // Default: 5000ms\n  }\n}\n```\n\n资料来源：[config.d.ts:64-77](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts#L64-L77)\n\n### Saving Sessions for Analysis\n\nEnable `saveSession` to persist Playwright session data for debugging:\n\n```typescript\n{\n  saveSession: true\n}\n```\n\nSessions are saved to the configured `outputDir`. 资料来源：[config.d.ts:81-84](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts#L81-L84)\n\n## Docker Environment Issues\n\nWhen running tests in Docker containers:\n\n```bash\n# Build Docker image\nnpm run docker-build\n\n# Run container\nnpm run docker-run\n\n# Execute tests in Docker\nnpm run dtest\n```\n\nDocker tests run with `MCP_IN_DOCKER=1` environment variable. 资料来源：[package.json:16-18](https://github.com/microsoft/playwright-mcp/blob/main/package.json#L16-L18)\n\n## Version Rollback Problems\n\nIf rolling Playwright causes issues:\n\n1. The `roll.js` script updates dependencies and regenerates configuration\n2. After running `npm run roll`, always run tests before committing\n\n```bash\nnpm run roll\nnpm test  # Must pass before proceeding\n```\n\nIf tests fail after a roll, revert changes and investigate the version bump. 资料来源：[CLAUDE.md:12-14](https://github.com/microsoft/playwright-mcp/blob/main/CLAUDE.md#L12-L14)\n\n## Contributing Troubleshooting\n\n### PR Closed Without Review\n\n> **Unsolicited PRs:** Pull requests submitted without a linked issue or prior approval will be closed. 资料来源：[CONTRIBUTING.md:29-30](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md#L29-L30)\n\nAlways file an issue first before submitting changes.\n\n### Linting Failures\n\nRun the linter before submitting:\n\n```bash\nnpm run lint\n```\n\nThis also regenerates the README documentation. 资料来源：[package.json:9](https://github.com/microsoft/playwright-mcp/blob/main/package.json#L9)\n\n## Workflow Diagram\n\n```mermaid\ngraph TD\n    A[Start] --> B{Issue?</B]\n    B -->|Yes| C[File GitHub Issue]\n    B -->|No| D[Check Existing Issues]\n    C --> E{Assigned?}\n    D --> E\n    E -->|Yes| F[Create Branch]\n    E -->|No| G[Wait for Assignment]\n    G --> E\n    F --> H[Make Changes]\n    H --> I[Add Tests]\n    I --> J[Run Tests]\n    J -->|Pass| K[Run Linter]\n    J -->|Fail| L[Debug & Fix]\n    L --> J\n    K -->|Pass| M[Commit Changes]\n    K -->|Fail| N[Fix Lint Errors]\n    N --> K\n    M --> O[Open PR]\n```\n\n## Quick Reference Commands\n\n| Command | Purpose | Source |\n|---------|---------|--------|\n| `npm test` | Run all tests | [package.json:10](https://github.com/microsoft/playwright-mcp/blob/main/package.json#L10) |\n| `npm run ctest` | Chrome-only tests | [package.json:11](https://github.com/microsoft/playwright-mcp/blob/main/package.json#L11) |\n| `npm run lint` | Regenerate docs | [package.json:9](https://github.com/microsoft/playwright-mcp/blob/main/package.json#L9) |\n| `npm run roll` | Bump Playwright version | [package.json:20](https://github.com/microsoft/playwright-mcp/blob/main/package.json#L20) |\n| `npm run docker-build` | Build Docker image | [package.json:17](https://github.com/microsoft/playwright-mcp/blob/main/package.json#L17) |\n\n## Getting Help\n\nIf issues persist after following this guide:\n\n1. Search existing [GitHub Issues](https://github.com/microsoft/playwright-mcp/issues)\n2. Check the [Playwright Documentation](https://playwright.dev/docs)\n3. Review the [main Playwright repository](https://github.com/microsoft/playwright) for upstream issues\n\nThe core of Playwright MCP was moved to the [Playwright monorepo](https://github.com/microsoft/playwright). 资料来源：[CONTRIBUTING.md:23-24](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md#L23-L24)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：microsoft/playwright-mcp\n\n摘要：发现 21 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。\n\n## 1. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `playwright-mcp` 与安装入口 `@playwright/mcp@latest` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`npx @playwright/mcp@latest`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | repo=playwright-mcp; install=@playwright/mcp@latest\n\n## 2. 安装坑 · 来源证据：Bad entrypoint in docker example\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bad entrypoint in docker example\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_948f818745694481b19e883b3992d78b | https://github.com/microsoft/playwright-mcp/issues/1609 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：v0.0.72\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.0.72\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2e67eb76e3c643e0a52a97e42eca4cb8 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.72 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 4. 配置坑 · 来源证据：v0.0.69\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.0.69\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6767d649d4934031b85ab0c5ffc2b324 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.69 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 5. 配置坑 · 来源证据：v0.0.71\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.0.71\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d5bcb1704c0e4a6fb375b18cda153fdd | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.71 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 配置坑 · 来源证据：v0.0.73\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.0.73\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a0d6aead61ad4c52ab738c6b556f2e27 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.73 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 能力坑 · 能力判断依赖假设\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:952688112 | https://github.com/microsoft/playwright-mcp | README/documentation is current enough for a first validation pass.\n\n## 8. 运行坑 · 来源证据：[Bug] Running multiple parallel async browsers in --isolated mode leaves orphan browsers. This has started happening af…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[Bug] Running multiple parallel async browsers in --isolated mode leaves orphan browsers. This has started happening after Release v0.0.69.\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e8f29958fbbe48ce8381daa23333bdf4 | https://github.com/microsoft/playwright-mcp/issues/1607 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 9. 运行坑 · 来源证据：v0.0.67\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.0.67\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3b13c720c21346bab9c08783c91acb95 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.67 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 10. 运行坑 · 来源证据：v0.0.68\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.0.68\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c53eae5fa6a94d2e86bc60cf6b164d16 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.68 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 11. 运行坑 · 来源证据：v0.0.74\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.0.74\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2c41b3bf29434fb48d51cb9ffc766fc2 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.74 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 12. 运行坑 · 来源证据：v0.0.75\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.0.75\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4e21e73e13dc471f90365f431d541143 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.75 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 13. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | last_activity_observed missing\n\n## 14. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | no_demo; severity=medium\n\n## 16. 安全/权限坑 · 来源证据：VS Code installation buttons don't seem to work\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：VS Code installation buttons don't seem to work\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_37c3461084f34d05856db207d12f8d9a | https://github.com/microsoft/playwright-mcp/issues/1608 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：[Bug]: Windows taskkill output can pollute MCP stdio transport\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: Windows taskkill output can pollute MCP stdio transport\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_789c261c74274d9d9a84d4b1fbf30d14 | https://github.com/microsoft/playwright-mcp/issues/1611 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：[Disclosure] Clarify browser/network action boundary in Playwright MCP server docs\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Disclosure] Clarify browser/network action boundary in Playwright MCP server docs\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fc2b3d242d67495f81f1bb1877e22f84 | https://github.com/microsoft/playwright-mcp/issues/1617 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 19. 安全/权限坑 · 来源证据：[Feature Request] Support clientCertificates option for mTLS authentication\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature Request] Support clientCertificates option for mTLS authentication\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b6f82bec73944aa5869030ad7db55b0c | https://github.com/microsoft/playwright-mcp/issues/1456 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 20. 维护坑 · 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:952688112 | https://github.com/microsoft/playwright-mcp | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | release_recency=unknown\n\n<!-- canonical_name: microsoft/playwright-mcp; human_manual_source: deepwiki_human_wiki -->\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项目：microsoft/playwright-mcp\n\n摘要：发现 21 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。\n\n## 1. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `playwright-mcp` 与安装入口 `@playwright/mcp@latest` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`npx @playwright/mcp@latest`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | repo=playwright-mcp; install=@playwright/mcp@latest\n\n## 2. 安装坑 · 来源证据：Bad entrypoint in docker example\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bad entrypoint in docker example\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_948f818745694481b19e883b3992d78b | https://github.com/microsoft/playwright-mcp/issues/1609 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：v0.0.72\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.0.72\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2e67eb76e3c643e0a52a97e42eca4cb8 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.72 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 4. 配置坑 · 来源证据：v0.0.69\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.0.69\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6767d649d4934031b85ab0c5ffc2b324 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.69 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 5. 配置坑 · 来源证据：v0.0.71\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.0.71\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d5bcb1704c0e4a6fb375b18cda153fdd | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.71 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 配置坑 · 来源证据：v0.0.73\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.0.73\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a0d6aead61ad4c52ab738c6b556f2e27 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.73 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 能力坑 · 能力判断依赖假设\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:952688112 | https://github.com/microsoft/playwright-mcp | README/documentation is current enough for a first validation pass.\n\n## 8. 运行坑 · 来源证据：[Bug] Running multiple parallel async browsers in --isolated mode leaves orphan browsers. This has started happening af…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[Bug] Running multiple parallel async browsers in --isolated mode leaves orphan browsers. This has started happening after Release v0.0.69.\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e8f29958fbbe48ce8381daa23333bdf4 | https://github.com/microsoft/playwright-mcp/issues/1607 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 9. 运行坑 · 来源证据：v0.0.67\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.0.67\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3b13c720c21346bab9c08783c91acb95 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.67 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 10. 运行坑 · 来源证据：v0.0.68\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.0.68\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c53eae5fa6a94d2e86bc60cf6b164d16 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.68 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 11. 运行坑 · 来源证据：v0.0.74\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.0.74\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2c41b3bf29434fb48d51cb9ffc766fc2 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.74 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 12. 运行坑 · 来源证据：v0.0.75\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.0.75\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4e21e73e13dc471f90365f431d541143 | https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.75 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 13. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | last_activity_observed missing\n\n## 14. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | no_demo; severity=medium\n\n## 16. 安全/权限坑 · 来源证据：VS Code installation buttons don't seem to work\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：VS Code installation buttons don't seem to work\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_37c3461084f34d05856db207d12f8d9a | https://github.com/microsoft/playwright-mcp/issues/1608 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：[Bug]: Windows taskkill output can pollute MCP stdio transport\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: Windows taskkill output can pollute MCP stdio transport\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_789c261c74274d9d9a84d4b1fbf30d14 | https://github.com/microsoft/playwright-mcp/issues/1611 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：[Disclosure] Clarify browser/network action boundary in Playwright MCP server docs\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Disclosure] Clarify browser/network action boundary in Playwright MCP server docs\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fc2b3d242d67495f81f1bb1877e22f84 | https://github.com/microsoft/playwright-mcp/issues/1617 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 19. 安全/权限坑 · 来源证据：[Feature Request] Support clientCertificates option for mTLS authentication\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature Request] Support clientCertificates option for mTLS authentication\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b6f82bec73944aa5869030ad7db55b0c | https://github.com/microsoft/playwright-mcp/issues/1456 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 20. 维护坑 · 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:952688112 | https://github.com/microsoft/playwright-mcp | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | release_recency=unknown\n",
      "summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
      "title": "Pitfall Log / 踩坑日志"
    },
    "prompt_preview": {
      "asset_id": "prompt_preview",
      "filename": "PROMPT_PREVIEW.md",
      "markdown": "# playwright-mcp - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 playwright-mcp 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Playwright MCP server 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. introduction：Introduction to Playwright MCP。围绕“Introduction to Playwright MCP”模拟一次用户任务，不展示安装或运行结果。\n2. key-concepts：Key Concepts。围绕“Key Concepts”模拟一次用户任务，不展示安装或运行结果。\n3. installation-guide：Installation Guide。围绕“Installation Guide”模拟一次用户任务，不展示安装或运行结果。\n4. client-integration：MCP Client Integration。围绕“MCP Client Integration”模拟一次用户任务，不展示安装或运行结果。\n5. browser-configuration：Browser Configuration。围绕“Browser Configuration”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. introduction\n输入：用户提供的“Introduction to Playwright MCP”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. key-concepts\n输入：用户提供的“Key Concepts”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. installation-guide\n输入：用户提供的“Installation Guide”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. client-integration\n输入：用户提供的“MCP Client Integration”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. browser-configuration\n输入：用户提供的“Browser Configuration”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / introduction：Step 1 必须围绕“Introduction to Playwright MCP”形成一个小中间产物，并等待用户确认。\n- Step 2 / key-concepts：Step 2 必须围绕“Key Concepts”形成一个小中间产物，并等待用户确认。\n- Step 3 / installation-guide：Step 3 必须围绕“Installation Guide”形成一个小中间产物，并等待用户确认。\n- Step 4 / client-integration：Step 4 必须围绕“MCP Client Integration”形成一个小中间产物，并等待用户确认。\n- Step 5 / browser-configuration：Step 5 必须围绕“Browser Configuration”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/microsoft/playwright-mcp\n- https://github.com/microsoft/playwright-mcp#readme\n- README.md\n- package.json\n- index.d.ts\n- config.d.ts\n- playwright.config.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 playwright-mcp 的核心服务。\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项目：microsoft/playwright-mcp\n\n## 官方安装入口\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx @playwright/mcp@latest\n```\n\n来源：https://github.com/microsoft/playwright-mcp#readme\n\n## 来源\n\n- repo: https://github.com/microsoft/playwright-mcp\n- docs: https://github.com/microsoft/playwright-mcp#readme\n",
      "summary": "从项目官方 README 或安装文档提取的开工入口。",
      "title": "Quick Start / 官方入口"
    }
  },
  "validation_id": "dval_55e0e2b586e44b66a56fc1af31bfbc46"
}