{
  "canonical_name": "microsoft/playwright-mcp",
  "compilation_id": "pack_5ba666547bda402888e8a9da5beb7bdd",
  "created_at": "2026-05-14T10:57:03.631125+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": "Local-first",
        "label_zh": "本地优先",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "selection_signal-local-first",
        "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. page-introduction：Playwright MCP 简介。围绕“Playwright MCP 简介”模拟一次用户任务，不展示安装或运行结果。\n2. page-quickstart：快速入门。围绕“快速入门”模拟一次用户任务，不展示安装或运行结果。\n3. page-client-integration：客户端集成指南。围绕“客户端集成指南”模拟一次用户任务，不展示安装或运行结果。\n4. page-core-architecture：核心架构。围绕“核心架构”模拟一次用户任务，不展示安装或运行结果。\n5. page-tools-capabilities：MCP 工具与能力。围绕“MCP 工具与能力”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“Playwright MCP 简介”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-quickstart\n输入：用户提供的“快速入门”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-client-integration\n输入：用户提供的“客户端集成指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-core-architecture\n输入：用户提供的“核心架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-tools-capabilities\n输入：用户提供的“MCP 工具与能力”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“Playwright MCP 简介”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-quickstart：Step 2 必须围绕“快速入门”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-client-integration：Step 3 必须围绕“客户端集成指南”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-core-architecture：Step 4 必须围绕“核心架构”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-tools-capabilities：Step 5 必须围绕“MCP 工具与能力”形成一个小中间产物，并等待用户确认。\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.js\n- index.d.ts\n- cli.js\n- config.d.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-14 08:48:11 UTC\n\n## 目录\n\n- [Playwright MCP 简介](#page-introduction)\n- [Playwright MCP vs Playwright CLI](#page-comparison)\n- [快速入门](#page-quickstart)\n- [客户端集成指南](#page-client-integration)\n- [核心架构](#page-core-architecture)\n- [MCP 工具与能力](#page-tools-capabilities)\n- [浏览器配置文件管理](#page-browser-profiles)\n- [初始状态配置](#page-initial-state)\n- [安全与网络配置](#page-security-config)\n- [部署选项](#page-deployment)\n\n<a id='page-introduction'></a>\n\n## Playwright MCP 简介\n\n### 相关页面\n\n相关主题：[Playwright MCP vs Playwright CLI](#page-comparison), [快速入门](#page-quickstart)\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- [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- [server.json](https://github.com/microsoft/playwright-mcp/blob/main/server.json)\n</details>\n\n# Playwright MCP 简介\n\n## 项目概述\n\nPlaywright MCP（Model Context Protocol）是一个为 MCP（Model Context Protocol）协议提供 Playwright 工具的官方实现。该项目由 Microsoft 开发维护，为大语言模型（LLM）代理提供浏览器自动化能力，使其能够与网页进行交互、操作 DOM 元素、执行网络请求等操作。\n\nPlaywright MCP 作为 MCP 服务器运行，通过标准输入输出（stdio）传输协议与 MCP 客户端通信 资料来源：[server.json:1-13]()。\n\n### 核心特性\n\n| 特性 | 描述 |\n|------|------|\n| MCP 协议兼容 | 符合 Model Context Protocol 规范 |\n| 多浏览器支持 | Chromium、Firefox、WebKit |\n| 工具化能力 | 将 Playwright API 暴露为 MCP 工具 |\n| 可配置性 | 支持丰富的运行时配置选项 |\n| 安全沙箱 | 支持浏览器隔离和来源限制 |\n\n## 架构设计\n\n### 系统架构\n\n```mermaid\ngraph TD\n    A[MCP 客户端] -->|stdio| B[Playwright MCP 服务器]\n    B --> C[Playwright Core]\n    C --> D[Chromium]\n    C --> E[Firefox]\n    C --> F[WebKit]\n    B --> G[工具注册表]\n    G --> H[Core 工具]\n    G --> I[Navigation 工具]\n    G --> J[Input 工具]\n    G --> K[Network 工具]\n    G --> L[Testing 工具]\n    G --> M[Vision 工具]\n```\n\n### 源码位置\n\n> [!WARNING]\n> Playwright MCP 的核心代码已迁移至 [Playwright 主仓库](https://github.com/microsoft/playwright)。当前仓库主要用于打包和发布。\n\n核心源码位于 `packages/playwright/src/mcp` 目录下 资料来源：[CONTRIBUTING.md:1-20]()。\n\n### 模块导出\n\n主入口文件通过 `playwright-core/lib/coreBundle` 导出 `createConnection` 函数：\n\n```javascript\nconst { tools } = require('playwright-core/lib/coreBundle');\nmodule.exports = { createConnection: tools.createConnection };\n```\n\n资料来源：[index.js:1-24]()\n\n## 工具能力体系\n\nPlaywright MCP 将功能组织为多个能力（Capability）模块，每个模块提供一组相关的 MCP 工具。\n\n### 能力类型定义\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' |           // PDF 生成\n  'storage' |       // 存储管理\n  'testing' |       // 测试功能\n  'vision' |        // 视觉功能\n  'devtools';       // 开发者工具\n```\n\n资料来源：[config.d.ts:1-20]()\n\n### 工具注册机制\n\n工具信息通过 `update-readme.js` 脚本从编译后的模块中提取，并自动生成 README 文档：\n\n```javascript\nasync function updateTools(content) {\n  console.log('Loading tool information from compiled modules...');\n  // 按能力分组列出工具\n  for (const [capability, tools] of Object.entries(toolsByCapability)) {\n    generatedLines.push(`<details>\\n<summary><b>${capability}</b></summary>`);\n    // ...\n  }\n}\n```\n\n资料来源：[update-readme.js:1-80]()\n\n## 配置选项\n\nPlaywright MCP 提供丰富的配置选项，通过 `Config` 类型定义。\n\n### 基础配置结构\n\n```typescript\nexport type Config = {\n  browser?: {\n    browserName?: 'chromium' | 'firefox' | 'webkit';\n    isolated?: boolean;\n    userDataDir?: string;\n    // 浏览器启动选项\n  };\n  capabilities?: ToolCapability[];\n  saveSession?: boolean;\n  sharedBrowserContext?: boolean;\n  secrets?: Record<string, string>;\n  outputDir?: string;\n  console?: {\n    level?: 'error' | 'warning' | 'info' | 'debug';\n  };\n  network?: {\n    allowedOrigins?: string[];\n    blockedOrigins?: string[];\n  };\n  testIdAttribute?: string;\n  timeouts?: {\n    action?: number;\n    navigation?: number;\n    expect?: number;\n  };\n  imageResponses?: 'allow' | 'omit';\n  snapshot?: { /* 快照配置 */ };\n};\n```\n\n资料来源：[config.d.ts:20-100]()\n\n### 浏览器配置\n\n| 参数 | 类型 | 默认值 | 描述 |\n|------|------|--------|------|\n| `browserName` | string | - | 浏览器类型：`chromium`、`firefox`、`webkit` |\n| `isolated` | boolean | - | 是否在内存中保持浏览器配置文件 |\n| `userDataDir` | string | 临时目录 | 浏览器配置文件保存路径 |\n\n### 超时配置\n\n| 参数 | 类型 | 默认值 | 描述 |\n|------|------|--------|------|\n| `timeouts.action` | number | 5000ms | 默认操作超时 |\n| `timeouts.navigation` | number | 60000ms | 默认导航超时 |\n| `timeouts.expect` | number | 5000ms | 默认断言超时 |\n\n### 网络安全配置\n\n| 参数 | 类型 | 描述 |\n|------|------|------|\n| `network.allowedOrigins` | string[] | 允许浏览器请求的来源列表 |\n| `network.blockedOrigins` | string[] | 阻止浏览器请求的来源列表 |\n\n支持的来源格式：\n- 完整来源：`https://example.com:8080`\n- 通配符端口：`http://localhost:*`\n\n资料来源：[config.d.ts:50-75]()\n\n## CLI 命令行工具\n\n### 入口脚本\n\n`cli.js` 是 MCP 服务器的命令行入口，负责解析参数并启动服务：\n\n```javascript\nconst { program } = require('playwright-core/lib/utilsBundle');\nconst { tools, libCli } = require('playwright-core/lib/coreBundle');\n\nif (process.argv.includes('install-browser')) {\n  const argv = process.argv.map(arg => arg === 'install-browser' ? 'install' : arg);\n  libCli.decorateProgram(program);\n  void program.parseAsync(argv);\n  return;\n}\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:1-35]()\n\n### 可用命令\n\n| 命令 | 描述 |\n|------|------|\n| `playwright-mcp install-browser` | 安装浏览器依赖 |\n| `playwright-mcp --help` | 显示帮助信息 |\n| `playwright-mcp --version` | 显示版本信息 |\n\n### npm 脚本\n\n| 脚本 | 描述 |\n|------|------|\n| `npm run lint` | 运行代码检查 |\n| `npm test` | 运行完整测试套件 |\n| `npm run ctest` | 仅运行 Chrome 测试 |\n| `npm run ftest` | 仅运行 Firefox 测试 |\n| `npm run wtest` | 仅运行 WebKit 测试 |\n| `npm run roll` | 更新 Playwright 版本 |\n\n资料来源：[package.json:1-40]()\n\n## 开发与测试\n\n### 环境搭建\n\n由于核心代码已迁移至 Playwright 主仓库，开发需克隆主仓库：\n\n```bash\ngit clone https://github.com/microsoft/playwright\ncd playwright\nnpm ci\nnpm run watch\nnpx playwright install\n```\n\n资料来源：[CONTRIBUTING.md:20-35]()\n\n### 测试执行\n\n#### 快速测试（仅 Chromium）\n\n```bash\nnpm run mcp-ctest\n```\n\n#### 完整测试（三浏览器）\n\n```bash\nnpm run mcp-test\n```\n\n#### Docker 环境测试\n\n```bash\nnpm run dtest  # MCP_IN_DOCKER=1 playwright test --project=chromium-docker\n```\n\n资料来源：[CONTRIBUTING.md:60-80]()\n\n### 代码规范\n\n代码风格由 `eslint.config.mjs` 定义，提交前应运行：\n\n```bash\nnpm run flint\n```\n\n资料来源：[CONTRIBUTING.md:40-45]()\n\n## 版本管理\n\n### 当前版本\n\n```json\n{\n  \"name\": \"@playwright/mcp\",\n  \"version\": \"0.0.75\"\n}\n```\n\n资料来源：[package.json:1-5]()\n\n### 版本更新流程\n\n1. 运行 `node roll.js` 更新 `playwright`、`playwright-core` 和 `@playwright/test` 依赖\n2. 创建分支：`git checkout -b roll-pw-<version-suffix>`\n3. 运行测试：`npm test`\n4. 提交并推送 PR\n\n分支命名规范：`roll-pw-<版本后缀>`\n\n资料来源：[CLAUDE.md:15-25]()\n\n## 提交规范\n\n### 提交信息格式\n\n```\nlabel(namespace): 标题\n\n描述（可选）\n\nFooter（可选）\n```\n\n### 标签类型\n\n| 标签 | 用途 |\n|------|------|\n| `fix` | 错误修复 |\n| `feat` | 新功能 |\n| `docs` | 文档更改 |\n| `test` | 测试更改 |\n| `devops` | CI 或构建更改 |\n| `chore` | 其他更改 |\n\n资料来源：[CONTRIBUTING.md:1-30]()\n\n### 示例\n\n```\nfix(proxy): handle SOCKS proxy authentication\n\nFixes: https://github.com/microsoft/playwright/issues/39562\n```\n\n## 贡献指南\n\n### 提交流程\n\n1. **创建 Issue**：任何贡献都需要先创建对应的 Issue（文档修复除外）\n2. **获取分配**：等待维护者分配任务\n3. **开发实现**：遵循代码规范进行开发\n4. **编写测试**：确保新功能有对应的测试\n5. **提交 PR**：保持 PR 小而精炼，便于审查\n\n### PR 要求\n\n- 必须关联已创建并分配的 Issue\n- 需要通过所有测试\n- 代码风格需符合 ESLint 规则\n- 提交信息遵循语义化规范\n\n> [!WARNING]\n> 未关联 Issue 或未获批准的 PR 将被关闭。\n\n资料来源：[CONTRIBUTING.md:80-110]()\n\n## 总结\n\nPlaywright MCP 为大语言模型代理提供了强大的浏览器自动化能力，通过 MCP 协议将 Playwright 的丰富功能工具化。其配置灵活、支持多种浏览器，并提供完整的安全控制机制。随着代码迁移至 Playwright 主仓库，该项目作为 npm 包发布渠道继续为社区提供支持。\n\n---\n\n<a id='page-comparison'></a>\n\n## Playwright MCP vs Playwright CLI\n\n### 相关页面\n\n相关主题：[Playwright MCP 简介](#page-introduction)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\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- [update-readme.js](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)\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- [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</details>\n\n# Playwright MCP vs Playwright CLI\n\n## 概述\n\nPlaywright MCP (Model Context Protocol) 和 Playwright CLI 是 Playwright 生态系统中的两个不同入口点，它们服务于不同的使用场景和集成模式。\n\n**Playwright MCP** 是一个基于 Model Context Protocol 的服务器实现，允许 AI 模型通过标准化的 MCP 协议与 Playwright 浏览器自动化功能进行交互。它以 npm 包 `@playwright/mcp` 的形式发布，版本为 `0.0.75`，MCP 名称为 `io.github.microsoft/playwright-mcp` 资料来源：[package.json:1-20]()\n\n**Playwright CLI** 是传统的命令行工具，通过终端命令直接调用 Playwright 的各项功能，如启动浏览器、安装浏览器、执行测试等。资料来源：[cli.js:1-35]()\n\n> **重要说明**：Playwright MCP 的核心代码已迁移至 [Playwright 主仓库](https://github.com/microsoft/playwright)，位于 `packages/playwright/src/mcp` 目录。资料来源：[CONTRIBUTING.md:1-10]()\n\n---\n\n## 架构对比\n\n### Playwright MCP 架构\n\n```mermaid\ngraph TD\n    A[AI Model] -->|MCP Protocol| B[Playwright MCP Server]\n    B -->|Tool Calls| C[playwright-core<br/>lib/coreBundle]\n    C --> D[Browser Automation]\n    E[Configuration] --> B\n    F[Capabilities] --> B\n```\n\nPlaywright MCP 基于 MCP 协议工作，核心连接功能通过 `playwright-core/lib/coreBundle` 中的 `createConnection` 方法导出：\n\n```javascript\nconst { tools } = require('playwright-core/lib/coreBundle');\nmodule.exports = { createConnection: tools.createConnection };\n```\n\n资料来源：[index.js:15-20]()\n\n### Playwright CLI 架构\n\n```mermaid\ngraph TD\n    A[Terminal/Command] -->|CLI Args| B[cli.js]\n    B -->|Commands| C[playwright-core<br/>lib/utilsBundle]\n    C -->|Program| D[libCli]\n    D --> E[playwright-core<br/>lib/coreBundle]\n    E --> F[Browser Automation]\n```\n\nCLI 入口整合了多个模块：\n\n```javascript\nconst { program } = require('playwright-core/lib/utilsBundle');\nconst { tools, libCli } = require('playwright-core/lib/coreBundle');\n```\n\n资料来源：[cli.js:19-25]()\n\n---\n\n## 功能能力对比\n\n| 能力维度 | Playwright MCP | Playwright CLI |\n|---------|---------------|----------------|\n| **集成目标** | AI 模型交互 | 开发者直接使用 |\n| **通信协议** | MCP (STDIO) | 命令行参数 |\n| **交互模式** | 请求-响应工具调用 | 批处理命令执行 |\n| **状态管理** | 持久化会话支持 | 临时会话 |\n| **配置方式** | config.d.ts 类型定义 | 命令行参数 |\n\n---\n\n## Playwright MCP 配置系统\n\nPlaywright MCP 通过 `config.d.ts` 提供完整的类型化配置：\n\n```typescript\nexport type Config = {\n  browser?: {\n    browserName?: 'chromium' | 'firefox' | 'webkit';\n    isolated?: boolean;\n    userDataDir?: string;\n    launchOptions?: any;\n    initPage?: string[];\n    initScript?: string[];\n  },\n  extension?: boolean;\n  server?: {\n    port?: number;\n    host?: string;\n    allowedHosts?: string[];\n  },\n  capabilities?: ToolCapability[];\n  saveSession?: boolean;\n  sharedBrowserContext?: boolean;\n  secrets?: Record<string, string>;\n  outputDir?: string;\n  console?: { level?: 'error' | 'warning' | 'info' | 'debug' };\n  network?: {\n    allowedOrigins?: string[];\n    blockedOrigins?: string[];\n  };\n};\n```\n\n资料来源：[config.d.ts:20-85]()\n\n### 工具能力类型\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:16-27]()\n\n---\n\n## Playwright CLI 命令行接口\n\n### cli.js 入口点\n\ncli.js 是 MCP 服务器的主入口，支持两种工作模式：\n\n```mermaid\ngraph TD\n    A[cli.js] --> B{参数判断}\n    B -->|包含 install-browser| C[libCli<br/>install 命令]\n    B -->|其他情况| D[tools.decorateMCPCommand<br/>MCP 模式]\n```\n\n关键实现逻辑：\n\n```javascript\nif (process.argv.includes('install-browser')) {\n  const argv = process.argv.map(arg => arg === 'install-browser' ? 'install' : arg);\n  libCli.decorateProgram(program);\n  void program.parseAsync(argv);\n  return;\n}\n\nconst packageJSON = require('./package.json');\nconst p = program.version('Version ' + packageJSON.version).name('Playwright MCP');\ntools.decorateMCPCommand(p, packageJSON.version);\n```\n\n资料来源：[cli.js:22-35]()\n\n### 可用命令\n\n| 命令 | 功能 | 来源模块 |\n|-----|------|---------|\n| `install-browser` | 安装 Playwright 浏览器 | libCli |\n| MCP Tools | 浏览器自动化工具集 | tools |\n| `--help` | 显示帮助信息 | program |\n\n---\n\n## MCP 服务器配置\n\nserver.json 定义了 MCP 服务器的元数据：\n\n```json\n{\n  \"$schema\": \"https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json\",\n  \"name\": \"io.github.microsoft/playwright-mcp\",\n  \"description\": \"Playwright Tools for MCP\",\n  \"version\": \"0.0.75\",\n  \"packages\": [{\n    \"registryType\": \"npm\",\n    \"identifier\": \"@playwright/mcp\",\n    \"version\": \"0.0.75\",\n    \"transport\": { \"type\": \"stdio\" }\n  }]\n}\n```\n\n资料来源：[server.json:1-20]()\n\n---\n\n## 自动化工具生成\n\n`update-readme.js` 脚本负责从编译后的模块中提取工具信息并生成文档：\n\n```mermaid\ngraph LR\n    A[编译模块] --> B[update-readme.js]\n    B --> C[工具信息提取]\n    C --> D[formatToolForReadme]\n    D --> E[README.md<br/>自动更新]\n```\n\n工具格式化函数提取每个工具的：\n\n- **名称** (name)\n- **标题** (title)\n- **描述** (description)\n- **参数** (parameters)\n- **是否只读** (read-only)\n\n资料来源：[update-readme.js:1-150]()\n\n---\n\n## 包结构与导出\n\n### 入口点配置\n\npackage.json 定义了导出结构：\n\n```json\n{\n  \"exports\": {\n    \"./package.json\": \"./package.json\",\n    \".\": { \"types\": \"./index.d.ts\" }\n  },\n  \"mcpName\": \"io.github.microsoft/playwright-mcp\"\n}\n```\n\n资料来源：[package.json:25-32]()\n\n### 版本与依赖\n\n| 项目 | 值 |\n|-----|---|\n| 包名 | @playwright/mcp |\n| 版本 | 0.0.75 |\n| Node 要求 | >=18 |\n| 许可证 | Apache-2.0 |\n| 作者 | Microsoft Corporation |\n\n---\n\n## 发布与维护流程\n\n### 更新 Playwright 版本\n\n根据 CLAUDE.md，维护者需要运行 `roll.js` 脚本：\n\n1. 执行 `npm run roll` 更新 Playwright 版本\n2. 从主仓库复制 `config.d.ts`\n3. 刷新 README 文档\n4. 提交更新并创建 PR\n\n```javascript\nfunction doRoll(version) {\n  updatePlaywrightVersion(version);\n  copyConfig();\n  execSync('npm run lint', { cwd: __dirname, stdio: 'inherit' });\n}\n```\n\n资料来源：[roll.js:1-50]()\n\n### 测试配置\n\n项目使用 Playwright 自身进行测试：\n\n```typescript\nexport default defineConfig<TestOptions>({\n  testDir: './tests',\n  fullyParallel: true,\n  reporter: 'list',\n  projects: [\n    { name: 'chrome' },\n    // Docker 测试配置\n  ],\n});\n```\n\n资料来源：[playwright.config.ts:1-30]()\n\n---\n\n## 使用场景选择\n\n```mermaid\ngraph TD\n    A[开始] --> B{使用场景}\n    B -->|AI 模型集成| C[Playwright MCP]\n    B -->|开发者自动化| D[Playwright CLI]\n    B -->|脚本批处理| E[Playwright CLI]\n    B -->|测试执行| F[Playwright CLI / Test]\n```\n\n### 选择 Playwright MCP 的场景\n\n- AI 代理需要浏览器自动化能力\n- 通过标准化协议集成多个工具\n- 需要 MCP 生态系统兼容性\n\n### 选择 Playwright CLI 的场景\n\n- 终端直接操作浏览器\n- CI/CD 管道集成\n- 快速调试和原型开发\n- 安装和管理浏览器\n\n---\n\n## 总结\n\n| 特性 | Playwright MCP | Playwright CLI |\n|-----|----------------|----------------|\n| **设计目标** | AI 代理集成 | 开发者工具 |\n| **协议** | Model Context Protocol | 命令行参数 |\n| **传输** | STDIO | 标准输入/输出 |\n| **状态** | 持久化、可共享 | 临时会话 |\n| **配置复杂度** | 高（完整类型系统） | 低（命令行参数） |\n| **适用人群** | AI 开发者、系统集成商 | 开发者、测试工程师 |\n\n两者本质上是同一底层能力的不同封装形式，Playwright MCP 建立在 Playwright CLI 的基础之上，通过 MCP 协议提供更高级别的抽象，使 AI 模型能够以结构化的方式调用浏览器自动化功能。\n\n---\n\n<a id='page-quickstart'></a>\n\n## 快速入门\n\n### 相关页面\n\n相关主题：[客户端集成指南](#page-client-integration), [部署选项](#page-deployment)\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- [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# 快速入门\n\n## 概述\n\nPlaywright MCP（Model Context Protocol）是由微软开发的Playwright工具集，通过MCP协议为大型语言模型提供浏览器自动化能力。该项目允许AI代理通过标准化的工具接口执行网页导航、元素交互、截图捕获等浏览器操作。资料来源：[README.md](https://github.com/microsoft/playwright-mcp/blob/main/README.md)\n\n> [!IMPORTANT]\n> Playwright MCP的核心代码已迁移至 [Playwright 主仓库](https://github.com/microsoft/playwright)，源代码位于 `packages/playwright/src/mcp` 目录。资料来源：[CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n\n## 环境要求\n\n| 要求项 | 最低版本 | 说明 |\n|--------|----------|------|\n| Node.js | >= 18 | 运行时环境 |\n| npm | 最新稳定版 | 包管理器 |\n| 浏览器 | Chromium/Firefox/WebKit | 测试浏览器（按需安装） |\n\n## 安装步骤\n\n### 1. 克隆仓库\n\n由于核心代码已迁移至Playwright主仓库，推荐从主仓库克隆：\n\n```bash\ngit clone https://github.com/microsoft/playwright\ncd playwright\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n\n### 2. 安装依赖并构建\n\n```bash\n# 安装项目依赖\nnpm ci\n\n# 以监视模式运行构建\nnpm run watch\n\n# 安装浏览器（根据需要选择）\nnpx playwright install\n```\n\n### 3. 验证安装\n\n运行快速测试验证安装是否成功：\n\n```bash\n# 仅在Chromium中运行MCP测试（快速路径）\nnpm run mcp-ctest\n\n# 在三个浏览器中运行完整测试（慢速路径）\nnpm run mcp-test\n```\n\n## 项目结构\n\n```\nplaywright/\n├── packages/\n│   └── playwright/\n│       └── src/\n│           └── mcp/          # MCP核心源代码\n├── tests/\n│   └── mcp/                  # MCP测试套件\n├── config.d.ts               # 配置类型定义\n├── playwright.config.ts     # 测试配置\n└── package.json             # 项目配置\n```\n\n## 可用工具分类\n\nPlaywright MCP提供以下能力类别：\n\n| 能力类别 | 说明 |\n|----------|------|\n| `config` | 配置管理 |\n| `core` | 核心浏览器操作 |\n| `core-navigation` | 页面导航 |\n| `core-tabs` | 标签页管理 |\n| `core-input` | 输入操作 |\n| `core-install` | 浏览器安装 |\n| `network` | 网络请求监控 |\n| `pdf` | PDF生成 |\n| `storage` | 存储管理 |\n| `testing` | 测试相关功能 |\n| `vision` | 视觉相关（截图、可视化） |\n| `devtools` | 开发者工具 |\n\n资料来源：[config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## 配置选项\n\n### 浏览器配置\n\n```typescript\n{\n  browser: {\n    browserName?: 'chromium' | 'firefox' | 'webkit';\n    isolated?: boolean;        // 是否保持浏览器配置在内存中\n    userDataDir?: string;      // 用户数据目录路径\n  };\n}\n```\n\n### 超时配置\n\n```typescript\n{\n  timeouts: {\n    action?: number;      // 默认操作超时，默认5000ms\n    navigation?: number;  // 默认导航超时，默认60000ms\n    expect?: number;      // 默认expect超时，默认5000ms\n  };\n}\n```\n\n### 网络配置\n\n```typescript\n{\n  network: {\n    allowedOrigins?: string[];   // 允许的请求来源\n    blockedOrigins?: string[];   // 阻止的请求来源\n  };\n}\n```\n\n资料来源：[config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## 命令行工具\n\n项目提供以下npm脚本命令：\n\n| 命令 | 说明 |\n|------|------|\n| `npm run mcp-ctest` | 在Chromium中运行所有MCP测试 |\n| `npm run mcp-test` | 在三个浏览器中运行所有MCP测试 |\n| `npm run lint` | 运行代码检查和更新README |\n| `npm run watch` | 监视模式构建 |\n| `npm run flint` | 运行完整代码检查 |\n\n资料来源：[package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n\n### 直接使用CLI\n\n```bash\n# 启动MCP服务器\nnode index.js\n\n# 安装浏览器\nnode cli.js install-browser\n\n# 获取帮助\nnode cli.js --help\n```\n\n资料来源：[cli.js](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)，[index.js](https://github.com/microsoft/playwright-mcp/blob/main/index.js)\n\n## 测试运行流程\n\n```mermaid\ngraph TD\n    A[开始测试] --> B{环境变量CI}\n    B -->|是| C[设置2个workers]\n    B -->|否| D[使用全部CPU核心]\n    C --> E[运行playwright test]\n    D --> E\n    E --> F{测试结果}\n    F -->|通过| G[测试完成]\n    F -->|失败| H[报告错误]\n```\n\n## 开发工作流\n\n### 提交规范\n\n项目使用语义化提交信息格式：\n\n```\nlabel(namespace): 标题\n\n描述\n\nfooter\n```\n\n可用标签：\n\n| 标签 | 用途 |\n|------|------|\n| `fix` | 错误修复 |\n| `feat` | 新功能 |\n| `docs` | 文档更改 |\n| `test` | 测试相关 |\n| `devops` | CI或构建相关 |\n| `chore` | 其他杂项 |\n\n资料来源：[CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n\n### 分支命名\n\n- 错误修复：`fix-<issue-number>`\n- Playwright版本滚动：`roll-pw-<version-suffix>`\n\n### 代码规范\n\n- 代码风格定义在 `eslint.config.mjs`\n- 提交前运行代码检查：`npm run flint`\n- 注释应有明确目的，避免冗余\n- 代码应尽可能自解释\n\n资料来源：[CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n\n## 常见问题\n\n### Q: 测试无法通过怎么办？\n\n1. 确保所有依赖已正确安装：`npm ci`\n2. 确保浏览器已安装：`npx playwright install`\n3. 清除缓存后重试\n\n### Q: 如何仅测试特定浏览器？\n\n```bash\n# 仅Chrome\nnpm run ctest\n\n# 仅Firefox\nnpm run ftest\n\n# 仅WebKit\nnpm run wtest\n```\n\n### Q: 如何在Docker中运行测试？\n\n```bash\nMCP_IN_DOCKER=1 npm run dtest\n```\n\n## 下一步\n\n- 阅读完整 [README.md](https://github.com/microsoft/playwright-mcp/blob/main/README.md) 了解所有可用工具\n- 查看 [tests/mcp](https://github.com/microsoft/playwright/blob/main/tests/mcp) 目录中的测试示例\n- 参考 [Playwright 官方文档](https://playwright.dev/docs/api/class-page) 了解底层API\n\n---\n\n<a id='page-client-integration'></a>\n\n## 客户端集成指南\n\n### 相关页面\n\n相关主题：[快速入门](#page-quickstart), [部署选项](#page-deployment)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\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- [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- [server.json](https://github.com/microsoft/playwright-mcp/blob/main/server.json)\n- [CLAUDE.md](https://github.com/microsoft/playwright-mcp/blob/main/CLAUDE.md)\n- [playwright.config.ts](https://github.com/microsoft/playwright-mcp/blob/main/playwright.config.ts)\n</details>\n\n# 客户端集成指南\n\n## 概述\n\nPlaywright MCP (Model Context Protocol) 是微软提供的 Playwright 浏览器自动化工具的 MCP（Model Context Protocol）实现。它允许 AI 模型通过标准化协议与浏览器进行交互，执行网页自动化、测试和内容抓取等任务。\n\n核心代码已迁移至 [Playwright 主仓库](https://github.com/microsoft/playwright)，位于 `packages/playwright/src/mcp` 目录。资料来源：[CONTRIBUTING.md:43]()\n\n## 架构概览\n\n```mermaid\ngraph TD\n    A[AI Client / MCP Host] -->|MCP Protocol| B[Playwright MCP Server]\n    B -->|STDIO Transport| C[Browser Automation]\n    C -->|Playwright API| D[Chromium / Firefox / WebKit]\n    B --> E[Local Browser]\n    B --> F[Docker Container]\n    \n    G[Config File / CLI Args] --> B\n    H[Environment Variables] --> B\n```\n\n服务器通过 STDIO 传输协议与 MCP Host 进行通信，支持本地浏览器启动和 Docker 容器模式。资料来源：[server.json:12]()\n\n## 安装与依赖\n\n### 系统要求\n\n- **Node.js**: 需要版本 >= 18\n- **浏览器**: 支持 Chromium、Firefox、WebKit\n\n### 安装步骤\n\n```bash\nnpm install @playwright/mcp\n```\n\n或从源码构建：\n\n```bash\ngit clone https://github.com/microsoft/playwright\ncd playwright\nnpm ci\nnpm run watch\nnpx playwright install\n```\n\n资料来源：[CONTRIBUTING.md:51-60]()\n\n### Docker 部署\n\n```bash\n# 构建镜像\nnpm run docker-build\n\n# 运行容器\nnpm run docker-run\n```\n\n资料来源：[package.json:25-27]()\n\n## 配置选项\n\nPlaywright MCP 支持丰富的配置选项，定义在 `config.d.ts` 中。\n\n### 配置类型定义\n\n```typescript\nexport type Config = {\n  browser?: {\n    browserName?: 'chromium' | 'firefox' | 'webkit';\n    isolated?: boolean;\n    userDataDir?: string;\n    // 浏览器启动选项\n  };\n  allowedOrigins?: string[];      // 允许的请求来源\n  blockedOrigins?: string[];      // 阻止的请求来源\n  testIdAttribute?: string;       // 测试 ID 属性，默认 \"data-testid\"\n  timeouts?: {\n    action?: number;              // 操作超时，默认 5000ms\n    navigation?: number;         // 导航超时，默认 60000ms\n    expect?: number;              // 断言超时，默认 5000ms\n  };\n  imageResponses?: 'allow' | 'omit' | 'auto';\n};\n```\n\n资料来源：[config.d.ts:31-85]()\n\n### 工具能力列表\n\n| 能力分类 | 标识符 | 说明 | 启用方式 |\n|---------|--------|------|---------|\n| 核心能力 | `core` | 基础浏览器操作 | 默认启用 |\n| 导航能力 | `core-navigation` | 页面导航相关 | 默认启用 |\n| 标签页能力 | `core-tabs` | 多标签页管理 | 默认启用 |\n| 输入能力 | `core-input` | 表单输入操作 | 默认启用 |\n| 安装能力 | `core-install` | 浏览器安装 | 默认启用 |\n| 网络能力 | `network` | 网络请求拦截 | `--caps=network` |\n| PDF 能力 | `pdf` | PDF 生成 | `--caps=pdf` |\n| 存储能力 | `storage` | 本地存储管理 | `--caps=storage` |\n| 测试能力 | `testing` | 测试断言 | `--caps=testing` |\n| 视觉能力 | `vision` | 视觉对比 | `--caps=vision` |\n| 开发者工具 | `devtools` | DevTools 协议 | `--caps=devtools` |\n\n资料来源：[config.d.ts:12-25]()\n\n### 来源过滤配置\n\n#### 允许来源 (allowedOrigins)\n\n```typescript\nallowedOrigins?: string[];\n```\n\n支持的格式：\n\n| 格式 | 示例 | 匹配范围 |\n|------|------|---------|\n| 完整来源 | `https://example.com:8080` | 仅该来源 |\n| 通配符协议 | `*://example.com` | http 和 https |\n| 通配符子域 | `https://*.example.com` | 所有子域 |\n| 通配符端口 | `http://localhost:*` | localhost 所有端口 |\n\n资料来源：[config.d.ts:38-45]()\n\n#### 阻止来源 (blockedOrigins)\n\n```typescript\nblockedOrigins?: string[];\n```\n\n同时匹配 `allowedOrigins` 和 `blockedOrigins` 的来源将被阻止。\n\n## 命令行接口\n\n### CLI 入口点\n\n服务器通过 `cli.js` 启动，使用 `playwright-core` 的命令行框架：\n\n```bash\nnode cli.js [options]\n```\n\n资料来源：[cli.js:1-32]()\n\n### 可用命令\n\n| 命令 | 说明 |\n|------|------|\n| `node cli.js --help` | 显示帮助信息 |\n| `node cli.js --version` | 显示版本信息 |\n| `node cli.js install-browser` | 安装浏览器 |\n\n### 主要选项\n\n| 选项 | 说明 | 环境变量 |\n|------|------|---------|\n| `--caps` | 启用的能力列表 | `PLAYWRIGHT_MCP_CAPS` |\n| `--secrets` | 密钥文件路径 | `PLAYWRIGHT_MCP_SECRETS_FILE` |\n| `--browser` | 指定浏览器类型 | `PLAYWRIGHT_MCP_BROWSER` |\n| `--headless` | 无头模式运行 | `PLAYWRIGHT_MCP_HEADLESS` |\n\n环境变量格式为 `PLAYWRIGHT_MCP_` 前缀加上选项名称的大写形式，中划线替换为下划线。\n\n资料来源：[update-readme.js:1-60]()\n\n### 特殊命令\n\n#### install-browser\n\n```bash\nnode cli.js install-browser\n```\n\n该命令实际上是 `playwright install` 的别名，用于安装必要的浏览器二进制文件。\n\n## 工具能力详解\n\n### 核心能力 (core)\n\n默认启用的核心工具集，提供基础的浏览器操作能力：\n\n| 工具 | 说明 | 只读 |\n|------|------|------|\n| 导航工具 | 页面跳转、前进后退 | ✓ |\n| 点击工具 | 元素点击交互 | ✗ |\n| 填充工具 | 表单填充 | ✗ |\n| 截图工具 | 页面截图 | ✓ |\n\n### 网络能力 (network)\n\n通过 `--caps=network` 启用，提供网络请求拦截和管理功能：\n\n```mermaid\ngraph LR\n    A[Browser Request] --> B{MCP Network Filter}\n    B -->|Allowed| C[Network]\n    B -->|Blocked| D[Blocked Response]\n```\n\n### 测试能力 (testing)\n\n通过 `--caps=testing` 启用，提供测试断言功能：\n\n- `expect`: 断言验证\n- `toHaveTitle`: 标题验证\n- `toContainText`: 文本内容验证\n- `toBeVisible`: 元素可见性验证\n\n资料来源：[update-readme.js:70-100]()\n\n## 环境变量\n\n| 环境变量 | 对应选项 | 说明 |\n|----------|---------|------|\n| `PLAYWRIGHT_MCP_CAPS` | `--caps` | 启用的能力列表 |\n| `PLAYWRIGHT_MCP_SECRETS_FILE` | `--secrets` | 密钥文件路径 |\n| `PLAYWRIGHT_MCP_BROWSER` | `--browser` | 默认浏览器类型 |\n| `MCP_IN_DOCKER` | - | Docker 模式标志 |\n\n## 测试指南\n\n### 运行测试\n\n```bash\n# 快速测试（仅 Chromium）\nnpm run ctest\n\n# 完整测试（三浏览器）\nnpm run test\n\n# Firefox 专项测试\nnpm run ftest\n\n# WebKit 专项测试\nnpm run wtest\n\n# Docker 模式测试\nnpm run dtest\n```\n\n资料来源：[package.json:20-24]()\n\n### 测试配置\n\n测试配置文件位于 `playwright.config.ts`：\n\n```typescript\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测试文件位于 `tests/mcp` 目录。资料来源：[playwright.config.ts:1-30]()\n\n### 测试要求\n\n- 测试必须是**自包含的**，不依赖外部服务\n- 测试必须在三个平台都能运行：macOS、Linux、Windows\n- 新功能必须包含对应的测试用例\n- 纯重构可以例外\n\n资料来源：[CONTRIBUTING.md:90-95]()\n\n## 集成示例\n\n### 基本集成配置\n\n```json\n{\n  \"mcpServers\": {\n    \"playwright\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@playwright/mcp\"],\n      \"env\": {\n        \"PLAYWRIGHT_MCP_CAPS\": \"core,network\",\n        \"PLAYWRIGHT_MCP_BROWSER\": \"chromium\"\n      }\n    }\n  }\n}\n```\n\n### 使用 Docker 模式\n\n```bash\nnpm run docker-build\nnpm run docker-run\n```\n\nDocker 模式会启动隔离的容器环境运行浏览器。\n\n## 版本管理\n\n### 版本信息\n\n当前版本：`0.0.75`\n\n资料来源：[package.json:3]()\n\n### 滚动更新\n\n使用 `roll.js` 脚本更新 Playwright 版本：\n\n```bash\nnpm run roll\n```\n\n该脚本会：\n1. 更新 `package.json` 中的 Playwright 依赖版本\n2. 从 Playwright 主仓库复制 `config.d.ts`\n3. 重新生成 README 文档\n\n更新后需要创建分支并提交 PR：\n\n```bash\ngit checkout -b roll-pw-<version-suffix>\nnpm test\ngit commit -m \"chore: roll Playwright to <version>\"\n```\n\n资料来源：[CLAUDE.md:14-23]()\n\n## 贡献指南\n\n### 提交流流程\n\n```mermaid\ngraph TD\n    A[创建 Issue] --> B{是否需要新功能?}\n    B -->|是| C[描述问题并申请处理]\n    B -->|否| D[找到已有 Issue]\n    C --> E{是否分配给你?}\n    D --> E\n    E -->|否| F[等待分配]\n    E -->|是| G[创建分支 fix-<issue-number>]\n    G --> H[开发并添加测试]\n    H --> I[提交 PR]\n    I --> J[代码审查]\n    J -->|通过| K[合并]\n    J -->|拒绝| L[修改后重新提交]\n```\n\n### 提交规范\n\n提交信息必须遵循 Semantic Commit Messages 格式：\n\n```\n<label>(<namespace>): <title>\n\n<description>\n\n<footer>\n```\n\n标签类型：\n- `fix`: Bug 修复\n- `feat`: 新功能\n- `docs`: 文档更改\n- `test`: 测试更改\n- `devops`: CI/构建更改\n- `chore`: 其他更改\n\n### PR 要求\n\n- PR 必须关联一个 Issue 或经过批准\n- PR 必须通过所有测试\n- 代码必须通过 lint 检查：`npm run lint`\n- PR 内容应保持小而可读\n\n资料来源：[CONTRIBUTING.md:1-40]()\n\n## 常见问题\n\n### 浏览器无法启动\n\n确保已安装浏览器：\n```bash\nnpx playwright install\n```\n\n### 测试超时\n\n调整配置中的超时设置：\n```typescript\ntimeouts: {\n  action: 10000,      // 增加操作超时\n  navigation: 120000 // 增加导航超时\n}\n```\n\n### 网络请求被阻止\n\n检查 `allowedOrigins` 和 `blockedOrigins` 配置，确保目标域名在允许列表中。\n\n---\n\n<a id='page-core-architecture'></a>\n\n## 核心架构\n\n### 相关页面\n\n相关主题：[MCP 工具与能力](#page-tools-capabilities), [浏览器配置文件管理](#page-browser-profiles)\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- [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- [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# 核心架构\n\n## 概述\n\nplaywright-mcp 是 Microsoft Playwright 的 MCP（Model Context Protocol）实现，为大语言模型提供浏览器自动化能力。该项目作为 Playwright 与 MCP 协议之间的桥梁，使 AI Agent 能够通过标准化的 MCP 接口控制浏览器执行自动化任务。\n\n核心架构采用模块化设计，核心功能依赖于 playwright-core 库，并通过 CLI 和 API 两种方式暴露能力。\n\n## 系统架构图\n\n```mermaid\ngraph TD\n    subgraph 客户端层\n        MCP_Client[MCP 客户端]\n    end\n    \n    subgraph 核心模块\n        Connection[createConnection]\n        Tools[工具集合]\n        CLI[CLI 入口]\n    end\n    \n    subgraph Playwright 核心\n        CoreBundle[coreBundle]\n        Browser[浏览器自动化]\n        Page[页面控制]\n    end\n    \n    subgraph 配置系统\n        Config[Config 类型定义]\n        EnvVars[环境变量映射]\n    end\n    \n    MCP_Client --> Connection\n    Connection --> Tools\n    Connection --> CoreBundle\n    Tools --> Browser\n    CoreBundle --> Browser\n    CLI --> CoreBundle\n    Config --> Connection\n```\n\n## 入口点设计\n\n### API 入口：index.js\n\n主入口文件负责导出 MCP 连接工厂函数，供外部系统集成使用。\n\n资料来源：[index.js:25-27]()\n\n```javascript\nconst { tools } = require('playwright-core/lib/coreBundle');\nmodule.exports = { createConnection: tools.createConnection };\n```\n\n**设计特点**：\n- 极简导出设计，仅暴露 `createConnection` 函数\n- 底层实现委托给 playwright-core 的 coreBundle\n- 支持 Node.js 和 ES Module 环境\n\n### CLI 入口：cli.js\n\n命令行入口点，支持多种操作模式。\n\n资料来源：[cli.js:1-34]()\n\n```javascript\nconst { program } = require('playwright-core/lib/utilsBundle');\nconst { tools, libCli } = require('playwright-core/lib/coreBundle');\n\nif (process.argv.includes('install-browser')) {\n  const argv = process.argv.map(arg => arg === 'install-browser' ? 'install' : arg);\n  libCli.decorateProgram(program);\n  void program.parseAsync(argv);\n  return;\n}\n\nconst packageJSON = require('./package.json');\nconst p = program.version('Version ' + packageJSON.version).name('Playwright MCP');\ntools.decorateMCPCommand(p, packageJSON.version);\n```\n\n**CLI 功能**：\n| 命令 | 说明 | 资料来源 |\n|------|------|----------|\n| `playwright-mcp install-browser` | 安装浏览器驱动 | cli.js:13 |\n| MCP 工具命令 | 通过 playwright-core 提供 | cli.js:28 |\n\n## 工具能力体系\n\n### 能力分类\n\n工具按照功能被组织为多个能力类别（ToolCapability）。\n\n资料来源：[config.d.ts:6-20]()\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### 能力详情表\n\n| 能力标识 | 功能描述 |\n|----------|----------|\n| config | 配置管理 |\n| core | 核心浏览器自动化 |\n| core-navigation | 页面导航控制 |\n| core-tabs | 多标签页管理 |\n| core-input | 输入交互处理 |\n| core-install | 浏览器安装 |\n| network | 网络请求拦截 |\n| pdf | PDF 生成操作 |\n| storage | 存储状态管理 |\n| testing | 测试相关功能 |\n| vision | 视觉坐标交互 |\n| devtools | 开发者工具 |\n\n## 配置系统\n\n### 配置类型定义\n\n配置系统采用 TypeScript 类型定义，提供完整的类型安全配置。\n\n资料来源：[config.d.ts:23-150]()\n\n**核心配置结构**：\n\n```typescript\nexport type Config = {\n  browser?: {\n    browserName?: 'chromium' | 'firefox' | 'webkit';\n    isolated?: boolean;\n    userDataDir?: string;\n    launchOptions?: Record<string, any>;\n    initPage?: string[];\n    initScript?: string[];\n  },\n  extension?: boolean;\n  server?: {\n    port?: number;\n    host?: string;\n    allowedHosts?: string[];\n  },\n  capabilities?: ToolCapability[];\n  saveSession?: boolean;\n  sharedBrowserContext?: boolean;\n  secrets?: Record<string, string>;\n  origins?: {\n    allowedOrigins?: string[];\n    blockedOrigins?: string[];\n  };\n  testIdAttribute?: string;\n  timeouts?: {\n    action?: number;\n    navigation?: number;\n    expect?: number;\n  };\n  imageResponses?: 'allow' | 'omit' | 'auto';\n  snapshot?: /* ... */;\n}\n```\n\n### 配置项分类表\n\n| 分类 | 配置项 | 默认值 | 说明 |\n|------|--------|--------|------|\n| **浏览器** | browserName | - | 浏览器类型：chromium/firefox/webkit |\n| | isolated | false | 是否保持浏览器隔离 |\n| | userDataDir | 临时目录 | 用户数据目录路径 |\n| **服务器** | port | - | SSE/MCP 传输监听端口 |\n| | host | localhost | 服务器绑定地址 |\n| | allowedHosts | 同 host | 允许服务的主机列表 |\n| **功能开关** | capabilities | - | 启用的工具能力列表 |\n| | saveSession | false | 是否保存 Playwright 会话 |\n| | sharedBrowserContext | false | 跨客户端共享浏览器上下文 |\n| **超时配置** | timeouts.action | 5000ms | 默认动作超时 |\n| | timeouts.navigation | 60000ms | 默认导航超时 |\n| | timeouts.expect | 5000ms | 默认断言超时 |\n| **安全** | secrets | - | 密钥配置映射 |\n| | origins.allowedOrigins | - | 允许的请求来源 |\n| | origins.blockedOrigins | - | 阻止的请求来源 |\n\n### 环境变量映射\n\nCLI 选项自动映射为环境变量，提供灵活的部署配置。\n\n资料来源：[update-readme.js:66-85]()\n\n| CLI 选项 | 环境变量 | 说明 |\n|----------|----------|------|\n| --secrets | PLAYWRIGHT_MCP_SECRETS_FILE | 密钥文件路径 |\n| --port | PLAYWRIGHT_MCP_PORT | 服务端口 |\n| --host | PLAYWRIGHT_MCP_HOST | 服务主机 |\n| 其他选项 | PLAYWRIGHT_MCP_<选项大写> | 标准前缀映射 |\n\n## 模块依赖关系\n\n```mermaid\ngraph LR\n    subgraph 依赖层\n        playwright-core\n        playwright\n        @playwright/test\n    end\n    \n    subgraph 本项目\n        index.js\n        cli.js\n        config.d.ts\n    end\n    \n    playwright --> playwright-core\n    @playwright/test --> playwright-core\n    \n    index.js --> playwright-core\n    cli.js --> playwright-core\n```\n\n资料来源：[package.json:17-40]()\n\n```json\n{\n  \"name\": \"@playwright/mcp\",\n  \"version\": \"0.0.75\",\n  \"mcpName\": \"io.github.microsoft/playwright-mcp\",\n  \"scripts\": {\n    \"build\": \"echo OK\",\n    \"test\": \"playwright test\"\n  },\n  \"dependencies\": {\n    \"playwright-core\": \"...\"\n  },\n  \"devDependencies\": {\n    \"@playwright/test\": \"...\",\n    \"playwright\": \"...\"\n  }\n}\n```\n\n## 构建与发布流程\n\n### 版本管理机制\n\n项目使用 roll.js 脚本同步 Playwright 依赖版本。\n\n资料来源：[roll.js:1-35]()\n\n```javascript\nfunction copyConfig() {\n  const src = path.join(__dirname, '..', 'playwright', 'packages', 'playwright-core', 'src', 'tools', 'mcp', 'config.d.ts');\n  const dst = path.join(__dirname, 'config.d.ts');\n  // 复制并替换导入路径\n  content = content.replace(\n    \"import type * as playwright from 'playwright-core';\",\n    \"import type * as playwright from 'playwright';\"\n  );\n}\n\nfunction updatePlaywrightVersion(version) {\n  // 更新 package.json 中的依赖版本\n}\n\nfunction doRoll(version) {\n  updatePlaywrightVersion(version);\n  copyConfig();\n  execSync('npm run lint', { cwd: __dirname });\n}\n```\n\n### 版本更新流程\n\n```mermaid\nflowchart TD\n    A[运行 npm run roll] --> B[updatePlaywrightVersion]\n    B --> C[copyConfig 同步 config.d.ts]\n    C --> D[npm install 安装依赖]\n    D --> E[npm run lint 更新 README]\n    E --> F[生成新版本提交]\n```\n\n### npm Scripts 说明\n\n| 脚本 | 命令 | 用途 |\n|------|------|------|\n| build | `echo OK` | 构建检查（无编译步骤） |\n| lint | `node update-readme.js` | 更新自动生成的 README |\n| test | `playwright test` | 运行完整测试套件 |\n| ctest | `playwright test --project=chrome` | 仅 Chrome 测试 |\n| ftest | `playwright test --project=firefox` | 仅 Firefox 测试 |\n| wtest | `playwright test --project=webkit` | 仅 WebKit 测试 |\n| roll | `node roll.js` | 同步 Playwright 版本 |\n\n## MCP 工具注册机制\n\n### 工具装饰器模式\n\n工具通过 playwright-core 提供的装饰器注册到 MCP 命令系统。\n\n资料来源：[cli.js:28]()\n\n```javascript\ntools.decorateMCPCommand(p, packageJSON.version);\n```\n\n### README 自动生成\n\nupdate-readme.js 脚本从编译后的模块自动提取工具信息并生成文档。\n\n资料来源：[update-readme.js:130-150]()\n\n```javascript\nasync function updateTools(content) {\n  const generatedLines = [];\n  for (const [capability, tools] of Object.entries(toolsByCapability)) {\n    generatedLines.push(`<details>`);\n    generatedLines.push(`<summary><b>${capability}</b></summary>`);\n    for (const tool of tools)\n      generatedLines.push(...formatToolForReadme(tool.schema));\n    generatedLines.push(`</details>`);\n  }\n  // 使用标记替换机制更新 README\n}\n```\n\n## 测试架构\n\n### 测试配置\n\n项目使用 @playwright/test 定义测试配置。\n\n资料来源：[playwright.config.ts:1-40]()\n\n```typescript\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    ...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\n### 测试项目矩阵\n\n| 项目名称 | 浏览器 | 环境 | 说明 |\n|----------|--------|------|------|\n| chrome | Chromium | 标准 | 主要测试环境 |\n| chromium-docker | Chromium | Docker | Docker 环境测试 |\n\n## 数据流向\n\n```mermaid\nsequenceDiagram\n    participant MCP as MCP 客户端\n    participant Server as MCP 服务器\n    participant Tools as 工具层\n    participant PW as Playwright Core\n    participant Browser as 浏览器实例\n    \n    MCP->>Server: MCP 请求\n    Server->>Tools: 调用工具\n    Tools->>PW: Playwright API\n    PW->>Browser: 浏览器控制\n    Browser-->>PW: 执行结果\n    PW-->>Tools: 返回结果\n    Tools-->>Server: 格式化响应\n    Server-->>MCP: MCP 响应\n```\n\n## 安全机制\n\n### 来源控制\n\n支持细粒度的请求来源控制。\n\n资料来源：[config.d.ts:88-100]()\n\n```typescript\norigins?: {\n  /**\n   * 允许浏览器请求的来源列表\n   * 支持格式：\n   * - 完整来源: `https://example.com:8080`\n   * - 通配符端口: `http://localhost:*`\n   */\n  allowedOrigins?: string[];\n\n  /**\n   * 阻止浏览器请求的来源列表\n   * 同时匹配 allowedOrigins 和 blockedOrigins 的请求将被阻止\n   */\n  blockedOrigins?: string[];\n};\n```\n\n### 密钥管理\n\n通过 secrets 配置支持敏感信息的安全传递。\n\n| 配置项 | 说明 |\n|--------|------|\n| secrets | 密钥名称到值的映射，用于环境变量注入 |\n\n## 与 Playwright 主仓库的关系\n\n根据 CLAUDE.md 和 CONTRIBUTING.md 的说明：\n\n> [!WARNING]\n> The core of the Playwright MCP was moved to the [Playwright monorepo](https://github.com/microsoft/playwright).\n\n当前仓库作为 Playwright 主仓库的 MCP 能力抽象层：\n\n| 职责 | 仓库位置 |\n|------|----------|\n| 核心实现 | [packages/playwright/src/mcp](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/mcp) |\n| 测试代码 | [tests/mcp](https://github.com/microsoft/playwright/blob/main/tests/mcp) |\n| 本仓库 | 独立打包和分发 |\n\n## 总结\n\nplaywright-mcp 的核心架构具有以下特点：\n\n1. **极简入口设计**：仅通过 `createConnection` 暴露核心功能\n2. **委托实现模式**：核心逻辑委托给 playwright-core\n3. **类型安全配置**：完整的 TypeScript 类型定义\n4. **自动化文档**：从源码自动生成 README\n5. **版本同步机制**：与 Playwright 主仓库保持同步\n6. **灵活部署**：支持环境变量、CLI 参数和编程式配置\n\n---\n\n<a id='page-tools-capabilities'></a>\n\n## MCP 工具与能力\n\n### 相关页面\n\n相关主题：[核心架构](#page-core-architecture), [初始状态配置](#page-initial-state)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/microsoft/playwright-mcp/blob/main/README.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- [index.js](https://github.com/microsoft/playwright-mcp/blob/main/index.js)\n</details>\n\n# MCP 工具与能力\n\n## 概述\n\nPlaywright MCP (Model Context Protocol) 是微软官方提供的 Playwright 工具集，为大语言模型 (LLM) 提供浏览器自动化能力。该项目通过 MCP 协议暴露一系列可调用的工具，使 AI Agent 能够执行网页导航、元素交互、网络监控、PDF 操作等浏览器自动化任务。\n\n根据 `config.d.ts` 中的定义，MCP 工具被组织为多个**能力域 (Capability)**，每个能力域包含一组相关的工具函数。资料来源：[config.d.ts:20-33]()\n\n## 架构概览\n\nPlaywright MCP 的源代码已迁移至 [Playwright 主仓库](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/mcp)，当前的 `playwright-mcp` 仓库作为依赖包装和分发层存在。资料来源：[CONTRIBUTING.md:1-10]()\n\n```mermaid\ngraph TD\n    A[LLM / AI Agent] -->|MCP Protocol| B[Playwright MCP Server]\n    B -->|工具调用| C[playwright-core]\n    C --> D[Browser Automation]\n    \n    E[CLI / Config] -->|配置| B\n    F[config.d.ts] -->|类型定义| E\n```\n\n## 能力域 (Tool Capabilities)\n\nPlaywright MCP 将工具划分为以下能力域，每个能力域对应不同的功能模块：\n\n| 能力域 | 说明 | 典型工具示例 |\n|--------|------|-------------|\n| `config` | 配置管理 | 服务端配置读取 |\n| `core` | 核心浏览器操作 | 导航、元素操作 |\n| `core-navigation` | 页面导航 | 打开 URL、前进/后退 |\n| `core-tabs` | 多标签页管理 | 创建/关闭标签页、切换 |\n| `core-input` | 输入处理 | 填写表单、键盘输入 |\n| `core-install` | 浏览器安装 | 安装浏览器驱动 |\n| `network` | 网络监控 | 请求拦截、响应捕获 |\n| `pdf` | PDF 生成 | 页面导出为 PDF |\n| `storage` | 存储管理 | Cookie、LocalStorage |\n| `testing` | 测试断言 | 元素存在性验证 |\n| `vision` | 视觉交互 | 坐标点击、截图 |\n| `devtools` | 开发者工具 | Chrome DevTools 协议 |\n\n资料来源：[config.d.ts:20-33]()\n\n## 配置选项详解\n\n### 基本配置结构\n\n```typescript\ntype Config = {\n  browser?: BrowserConfig;\n  capabilities?: ToolCapability[];\n  saveSession?: boolean;\n  sharedBrowserContext?: boolean;\n  secrets?: Record<string, string>;\n  outputDir?: string;\n  console?: ConsoleConfig;\n  network?: NetworkConfig;\n  testIdAttribute?: string;\n  timeouts?: TimeoutsConfig;\n  imageResponses?: 'allow' | 'omit' | 'auto';\n  snapshot?: SnapshotConfig;\n};\n```\n\n资料来源：[config.d.ts:36-120]()\n\n### 浏览器配置\n\n```typescript\nbrowser?: {\n  browserName?: 'chromium' | 'firefox' | 'webkit';\n  isolated?: boolean;\n  userDataDir?: string;\n  // ... launch options\n}\n```\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `browserName` | `chromium` \\| `firefox` \\| `webkit` | 指定使用的浏览器引擎 |\n| `isolated` | `boolean` | 是否保持浏览器配置文件在内存中，不写入磁盘 |\n| `userDataDir` | `string` | 浏览器用户数据目录路径，默认为临时目录 |\n\n### 超时配置\n\n```typescript\ntimeouts?: {\n  action?: number;      // 默认动作超时，默认 5000ms\n  navigation?: number;  // 默认导航超时，默认 60000ms\n  expect?: number;      // 默认断言超时，默认 5000ms\n}\n```\n\n资料来源：[config.d.ts:60-74]()\n\n### 网络安全配置\n\n```typescript\nnetwork?: {\n  allowedOrigins?: string[];   // 允许的请求来源\n  blockedOrigins?: string[];  // 阻止的请求来源\n}\n```\n\n**支持的格式：**\n\n| 格式 | 示例 | 匹配范围 |\n|------|------|----------|\n| 完整来源 | `https://example.com:8080` | 仅匹配该精确来源 |\n| 通配符端口 | `http://localhost:*` | localhost 上任意端口的 HTTP 请求 |\n\n资料来源：[config.d.ts:84-95]()\n\n### 控制台配置\n\n```typescript\nconsole?: {\n  level?: 'error' | 'warning' | 'info' | 'debug';\n}\n```\n\n| 级别 | 包含的消息 |\n|------|-----------|\n| `error` | 仅错误消息 |\n| `warning` | 错误 + 警告 |\n| `info` | 警告 + 信息（默认） |\n| `debug` | 所有消息 |\n\n### 图片响应配置\n\n```typescript\nimageResponses?: 'allow' | 'omit' | 'auto';\n```\n\n| 值 | 说明 |\n|----|------|\n| `allow` | 始终发送图片响应 |\n| `omit` | 从不发送图片响应 |\n| `auto` | 如果客户端能显示则发送（默认） |\n\n资料来源：[config.d.ts:76-79]()\n\n## MCP 工具生成机制\n\nREADME 文档中的工具列表通过 `update-readme.js` 脚本自动生成。脚本从编译后的模块加载工具信息，生成格式化的 Markdown 文档。资料来源：[update-readme.js:1-100]()\n\n```mermaid\ngraph LR\n    A[编译后的模块] -->|加载工具| B[update-readme.js]\n    B -->|生成 Markdown| C[README.md]\n    \n    D[cli.js --help] -->|CLI 选项| B\n    E[config.d.ts] -->|配置类型| B\n```\n\n### 工具描述格式\n\n每个工具在 README 中以折叠块形式展示：\n\n```markdown\n<details>\n<summary><b>能力域名称</b></summary>\n\n<!-- NOTE: This has been generated via update-readme.js -->\n\n- **tool_name**\n  - Title: 工具标题\n  - Description: 工具描述\n  - Parameters:\n    - `param_name` (type, optional): 参数描述\n  - Read-only: **true/false**\n```\n\n资料来源：[update-readme.js:170-190]()\n\n## 命令行接口\n\nMCP 服务通过 CLI 启动，支持以下操作模式：\n\n| 命令 | 说明 |\n|------|------|\n| `npm run ctest` | 仅在 Chromium 中运行测试 |\n| `npm run ftest` | 仅在 Firefox 中运行测试 |\n| `npm run wtest` | 仅在 WebKit 中运行测试 |\n| `npm run dtest` | 在 Docker 容器中运行 Chromium 测试 |\n| `npm run roll` | 更新 Playwright 版本 |\n\n资料来源：[package.json:14-24]()\n\n### CLI 入口点\n\nCLI 通过 `cli.js` 实现，集成了 `playwright-core` 的命令处理：\n\n```javascript\nconst { tools, libCli } = require('playwright-core/lib/coreBundle');\ntools.decorateMCPCommand(p, packageJSON.version);\n```\n\n特殊命令 `install-browser` 被映射为标准的 `playwright install`：\n\n```javascript\nif (process.argv.includes('install-browser')) {\n  const argv = process.argv.map(arg => arg === 'install-browser' ? 'install' : arg);\n  libCli.decorateProgram(program);\n}\n```\n\n资料来源：[cli.js:24-32]()\n\n## 核心入口点\n\nMCP 的主入口通过 `index.js` 导出 `createConnection` 函数：\n\n```javascript\nconst { tools } = require('playwright-core/lib/coreBundle');\nmodule.exports = { createConnection: tools.createConnection };\n```\n\n这使得其他 MCP 客户端能够通过标准的方式连接到 Playwright MCP 服务。资料来源：[index.js:26-27]()\n\n## 版本更新机制\n\n`roll.js` 脚本负责更新 Playwright 依赖版本：\n\n1. 从 Playwright 主仓库复制 `config.d.ts`\n2. 更新 `package.json` 中的 `playwright`、`playwright-core`、`@playwright/test` 版本\n3. 执行 `npm install` 安装新版本\n4. 运行 `npm run lint` 更新 README 文档\n\n```javascript\nfunction doRoll(version) {\n  updatePlaywrightVersion(version);\n  copyConfig();\n  execSync('npm run lint', { cwd: __dirname });\n}\n```\n\n资料来源：[roll.js:1-40]()\n\n## 会话管理\n\n| 配置项 | 说明 |\n|--------|------|\n| `saveSession` | 是否将会话保存到输出目录 |\n| `sharedBrowserContext` | 是否在所有 HTTP 客户端间共享浏览器上下文 |\n| `secrets` | 敏感信息替换映射，防止 LLM 意外暴露 |\n\n> **注意**：`secrets` 功能是便利性措施而非安全特性，客户端仍需自行审查传入和传出的数据。\n\n资料来源：[config.d.ts:96-107]()\n\n## 测试框架\n\n测试配置位于 `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资料来源：[playwright.config.ts:22-32]()\n\n## 总结\n\nPlaywright MCP 通过模块化的**能力域**设计，将浏览器自动化功能组织为可配置的逻辑单元。开发者可以通过 `config.d.ts` 中定义的类型精确配置所需功能，包括浏览器选择、超时策略、网络安全、存储管理等。这种设计使得 MCP 工具既保持了灵活性，又通过类型系统确保了配置的正确性。\n\n---\n\n<a id='page-browser-profiles'></a>\n\n## 浏览器配置文件管理\n\n### 相关页面\n\n相关主题：[初始状态配置](#page-initial-state), [核心架构](#page-core-architecture)\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- [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- [README.md](https://github.com/microsoft/playwright-mcp/blob/main/README.md)\n- [index.js](https://github.com/microsoft/playwright-mcp/blob/main/index.js)\n</details>\n\n# 浏览器配置文件管理\n\n## 概述\n\n浏览器配置文件管理是 Playwright MCP 的核心功能之一，允许用户通过配置对象自定义浏览器的启动行为、会话持久化方式以及浏览器上下文的安全策略。该模块通过 `config.d.ts` 中定义的 `Config` 类型提供类型安全的配置接口，支持多种浏览器引擎（Chromium、Firefox、WebKit）的灵活配置与管理。\n\nPlaywright MCP 的浏览器配置文件管理主要负责以下职责：\n\n| 职责 | 说明 |\n|------|------|\n| 浏览器选择 | 指定使用哪种浏览器引擎 |\n| 会话持久化 | 管理浏览器用户数据目录，支持会话恢复 |\n| 安全策略 | 控制浏览器请求的来源限制（允许/阻止的域名） |\n| 隔离模式 | 支持内存级浏览器配置文件，防止数据持久化 |\n| 启动参数 | 传递自定义浏览器启动选项 |\n\n资料来源：[config.d.ts:29-62]()\n\n## 配置结构\n\n### 顶级配置对象\n\nPlaywright MCP 的配置通过 `Config` 类型定义，核心结构如下：\n\n```typescript\nexport type Config = {\n  browser?: {\n    browserName?: 'chromium' | 'firefox' | 'webkit';\n    isolated?: boolean;\n    userDataDir?: string;\n    // 浏览器启动选项\n  };\n  // ... 其他配置项\n};\n```\n\n资料来源：[config.d.ts:35-45]()\n\n### 配置参数详解\n\n#### 浏览器配置（browser）\n\n浏览器配置对象包含以下可选参数：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `browserName` | `'chromium' \\| 'firefox' \\| 'webkit'` | `'chromium'` | 指定要使用的浏览器引擎 |\n| `isolated` | `boolean` | `undefined` | 是否在内存中运行浏览器，不保存配置文件到磁盘 |\n| `userDataDir` | `string` | `undefined` | 自定义浏览器用户数据目录路径 |\n\n```typescript\n// 浏览器配置示例\nconst config = {\n  browser: {\n    browserName: 'chromium',\n    isolated: true,\n    userDataDir: '/path/to/custom/profile'\n  }\n};\n```\n\n资料来源：[config.d.ts:35-62]()\n\n#### 起源安全策略（network）\n\n浏览器网络请求的安全策略通过 `network` 配置项管理：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `allowedOrigins` | `string[]` | 允许浏览器请求的来源列表，支持完整域名和通配符端口 |\n| `blockedOrigins` | `string[]` | 阻止浏览器请求的来源列表，同时匹配两个列表的请求将被阻止 |\n\n支持的来源格式：\n\n- **完整域名**：`https://example.com:8080` - 仅匹配该具体地址\n- **通配符端口**：`http://localhost:*` - 匹配 localhost 上任意端口的 HTTP 请求\n\n```typescript\nconst config = {\n  network: {\n    allowedOrigins: ['https://trusted-site.com'],\n    blockedOrigins: ['https://untrusted-site.com']\n  }\n};\n```\n\n资料来源：[config.d.ts:103-126]()\n\n#### 浏览器上下文配置（browserContext）\n\n用于配置浏览器的上下文级设置：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `screenSize` | `{ width: number, height: number }` | 浏览器视口尺寸 |\n| `timezoneId` | `string` | 浏览器的时区设置 |\n| `locale` | `string` | 浏览器的区域设置 |\n| `permissions` | `string[]` | 授予的浏览器权限列表 |\n| `viewport` | `{ width: number, height: number }` | 默认视口大小 |\n\n#### 测试标识属性（testIdAttribute）\n\n指定用于测试 ID 的 HTML 属性，默认值为 `\"data-testid\"`：\n\n```typescript\nconst config = {\n  testIdAttribute: 'data-testid'\n};\n```\n\n资料来源：[config.d.ts:71-77]()\n\n#### 超时配置（timeouts）\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `action` | `number` | `5000` | 操作超时时间（毫秒） |\n| `navigation` | `number` | `60000` | 导航超时时间（毫秒） |\n| `expect` | `number` | `5000` | 断言超时时间（毫秒） |\n\n```typescript\nconst config = {\n  timeouts: {\n    action: 5000,\n    navigation: 60000,\n    expect: 5000\n  }\n};\n```\n\n资料来源：[config.d.ts:79-94]()\n\n## 浏览器配置文件生命周期\n\n### 配置文件创建流程\n\n```mermaid\ngraph TD\n    A[配置对象创建] --> B{userDataDir 设置?}\n    B -->|是| C[使用指定目录]\n    B -->|否| D{isolated 为 true?}\n    D -->|是| E[创建临时内存目录]\n    D -->|否| F[创建临时持久化目录]\n    C --> G[浏览器启动]\n    E --> G\n    F --> G\n    G --> H[浏览器上下文创建]\n    H --> I[会话就绪]\n```\n\n### 会话持久化策略\n\nPlaywright MCP 支持三种会话持久化模式：\n\n| 模式 | `isolated` | `userDataDir` | 行为 |\n|------|------------|---------------|------|\n| 完全隔离 | `true` | 未设置 | 浏览器配置存储在内存中，进程结束后丢失 |\n| 临时持久化 | `false` | 未设置 | 临时目录存储配置，进程结束后自动清理 |\n| 自定义持久化 | 任意 | 已设置 | 使用指定目录存储配置，可跨会话复用 |\n\n```typescript\n// 完全隔离模式示例\nconst isolatedConfig = {\n  browser: {\n    browserName: 'chromium',\n    isolated: true\n  }\n};\n\n// 跨会话复用配置示例\nconst persistentConfig = {\n  browser: {\n    browserName: 'chromium',\n    userDataDir: '/path/to/persistent/profile'\n  }\n};\n```\n\n资料来源：[config.d.ts:35-56]()\n\n## 架构集成\n\n### 组件关系图\n\n```mermaid\ngraph TD\n    subgraph \"MCP 服务器层\"\n        A[index.js - createConnection]\n        B[cli.js - 命令行解析]\n    end\n    \n    subgraph \"配置管理层\"\n        C[config.d.ts - 类型定义]\n        D[Config 验证器]\n    end\n    \n    subgraph \"Playwright 核心\"\n        E[playwright-core]\n        F[浏览器引擎]\n    end\n    \n    A --> B\n    B --> D\n    C --> D\n    D --> E\n    E --> F\n    \n    style C fill:#e1f5fe\n    style F fill:#fff3e0\n```\n\n### 配置文件加载流程\n\n```mermaid\nsequenceDiagram\n    participant CLI as 命令行接口\n    participant Config as 配置加载器\n    participant Playwright as Playwright Core\n    participant Browser as 浏览器引擎\n\n    CLI->>Config: 解析用户配置\n    Config->>Config: 验证配置类型\n    Config->>Playwright: 传递配置参数\n    Playwright->>Browser: 初始化浏览器\n    Browser-->>Playwright: 浏览器实例\n    Playwright-->>Config: 会话就绪\n    Config-->>CLI: MCP 服务启动\n```\n\n资料来源：[index.js:1-28]()\n\n## 工具能力与浏览器配置\n\n浏览器配置文件管理与 MCP 工具能力紧密集成，支持通过 `capabilities` 配置启用或禁用特定功能：\n\n| 能力标识 | 说明 | 默认状态 |\n|----------|------|----------|\n| `core` | 核心浏览器操作 | 默认启用 |\n| `core-navigation` | 页面导航功能 | 默认启用 |\n| `core-tabs` | 多标签页管理 | 默认启用 |\n| `core-input` | 输入操作 | 默认启用 |\n| `core-install` | 浏览器安装 | 默认启用 |\n| `network` | 网络请求拦截 | 需显式启用 |\n| `pdf` | PDF 生成 | 需显式启用 |\n| `storage` | 存储管理 | 需显式启用 |\n| `testing` | 测试断言 | 需显式启用 |\n| `vision` | 视觉交互 | 需显式启用 |\n| `devtools` | 开发者工具 | 需显式启用 |\n\n```typescript\nconst config = {\n  browser: {\n    browserName: 'chromium'\n  },\n  capabilities: ['core', 'network', 'pdf']\n};\n```\n\n资料来源：[config.d.ts:28-32]()\n\n## 使用示例\n\n### 基础配置\n\n```typescript\nimport { createConnection } from '@playwright/mcp';\n\nconst server = createConnection({\n  browser: {\n    browserName: 'chromium'\n  }\n});\n```\n\n### 高级配置\n\n```typescript\nimport { createConnection } from '@playwright/mcp';\n\nconst server = createConnection({\n  browser: {\n    browserName: 'firefox',\n    isolated: false,\n    userDataDir: '/home/user/.playwright-profiles/firefox',\n  },\n  network: {\n    allowedOrigins: ['https://example.com'],\n    blockedOrigins: ['https://ads.example.com']\n  },\n  timeouts: {\n    action: 10000,\n    navigation: 120000\n  },\n  testIdAttribute: 'data-testid',\n  outputDir: '/tmp/playwright-output'\n});\n```\n\n资料来源：[config.d.ts:35-140]()\n\n### 命令行配置\n\nPlaywright MCP 通过 `cli.js` 提供命令行接口，支持通过命令行参数配置浏览器行为：\n\n```bash\n# 使用指定浏览器\nnpx playwright-mcp --browser=chromium\n\n# 安装浏览器\nnpx playwright-mcp install-browser\n\n# 查看帮助\nnpx playwright-mcp --help\n```\n\n资料来源：[cli.js:1-31]()\n\n## 相关源码文件索引\n\n| 文件路径 | 作用 |\n|----------|------|\n| `config.d.ts` | 配置类型定义，包含所有浏览器配置接口 |\n| `index.js` | MCP 连接入口，导出 `createConnection` |\n| `cli.js` | 命令行工具，处理用户输入和参数解析 |\n| `playwright.config.ts` | 测试框架配置，用于项目内部测试 |\n| `package.json` | 包元数据，定义 MCP 服务名称和版本 |\n\n## 配置验证\n\nPlaywright MCP 在启动时会验证配置对象的有效性。配置验证主要包括：\n\n1. **类型检查**：确保所有配置项符合 TypeScript 类型定义\n2. **值域验证**：检查枚举值（如浏览器类型）是否有效\n3. **路径验证**：验证 `userDataDir` 等路径是否存在或可创建\n\n配置验证失败时，MCP 服务器将抛出类型错误并拒绝启动，确保用户能够及时发现配置问题。\n\n资料来源：[config.d.ts:1-140]()\n\n---\n\n<a id='page-initial-state'></a>\n\n## 初始状态配置\n\n### 相关页面\n\n相关主题：[浏览器配置文件管理](#page-browser-profiles), [MCP 工具与能力](#page-tools-capabilities)\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- [package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n- [update-readme.js](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)\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- [CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n</details>\n\n# 初始状态配置\n\n## 概述\n\n初始状态配置（Initial State Configuration）是指 Playwright MCP Server 启动时的各项运行时参数与选项。这些配置项决定了浏览器的启动方式、会话管理策略、网络安全策略、超时行为等核心功能。配置文件采用 TypeScript 类型定义，统一存放在 `config.d.ts` 中，并通过 CLI 参数、环境变量或编程方式传递给服务端。\n\n## 配置架构\n\n```mermaid\ngraph TD\n    A[Playwright MCP Server] --> B[配置加载层]\n    B --> C[CLI 参数]\n    B --> D[环境变量]\n    B --> E[配置文件]\n    \n    C --> F[配置合并与验证]\n    D --> F\n    E --> F\n    \n    F --> G[Config 对象]\n    \n    G --> H[browser 配置]\n    G --> I[capabilities 配置]\n    G --> J[network 配置]\n    G --> K[timeouts 配置]\n    G --> L[其他选项]\n    \n    H --> M[Playwright Browser]\n    I --> N[可用工具集]\n    J --> O[网络请求过滤]\n    K --> P[超时策略]\n```\n\n## 核心配置项\n\n### 浏览器配置\n\n浏览器配置通过 `browser` 字段定义，控制浏览器实例的创建与生命周期管理。\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `browserName` | `'chromium' \\| 'firefox' \\| 'webkit'` | - | 指定使用的浏览器类型 |\n| `isolated` | `boolean` | `true` | 是否将浏览器配置文件保存在内存中，不写入磁盘 |\n| `userDataDir` | `string` | 临时目录 | 浏览器用户数据目录的路径，用于持久化浏览器状态 |\n\n**isolated 模式说明**：`isolated` 为 `true` 时，浏览器配置不会保存到磁盘，所有会话数据存储在内存中，浏览器关闭后自动清除。设置为 `false` 并配合 `userDataDir` 可实现浏览器状态的持久化保存。\n\n### 能力配置\n\n`capabilities` 数组定义了 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| 能力标识 | 说明 | 必需 |\n|----------|------|------|\n| `core` | 核心功能 | 默认启用 |\n| `core-navigation` | 页面导航功能 | 可选 |\n| `core-tabs` | 多标签页管理 | 可选 |\n| `core-input` | 输入处理功能 | 可选 |\n| `core-install` | 浏览器安装功能 | 可选 |\n| `network` | 网络请求拦截与修改 | 可选 |\n| `pdf` | PDF 生成功能 | 可选 |\n| `storage` | 存储管理功能 | 可选 |\n| `testing` | 测试断言功能 | 可选 |\n| `vision` | 视觉识别功能 | 可选 |\n| `devtools` | 开发者工具集成 | 可选 |\n\n## 网络安全配置\n\n`network` 字段用于控制浏览器可访问的网络来源，实现请求来源的白名单与黑名单管理。\n\n```typescript\nnetwork?: {\n  allowedOrigins?: string[];\n  blockedOrigins?: string[];\n};\n```\n\n### 支持的格式\n\n| 格式类型 | 示例 | 匹配范围 |\n|----------|------|----------|\n| 完整 origin | `https://example.com:8080` | 仅匹配该特定地址 |\n| 协议通配符 | `http://localhost:*` | localhost 任意端口的 HTTP 请求 |\n\n**匹配优先级**：当某个 origin 同时匹配 `allowedOrigins` 和 `blockedOrigins` 时，该请求将被**阻止**。\n\n## 超时配置\n\n`timeouts` 对象定义了各类操作的默认超时时间。\n\n```typescript\ntimeouts?: {\n  action?: number;      // 默认: 5000ms\n  navigation?: number; // 默认: 60000ms\n  expect?: number;      // 默认: 5000ms\n};\n```\n\n| 配置项 | 默认值 | 说明 | 相关文档 |\n|--------|--------|------|----------|\n| `action` | 5000ms | 默认操作超时 | [page.setDefaultTimeout](https://playwright.dev/docs/api/class-page#page-set-default-timeout) |\n| `navigation` | 60000ms | 默认导航超时 | [page.setDefaultNavigationTimeout](https://playwright.dev/docs/api/class-page#page-set-default-navigation-timeout) |\n| `expect` | 5000ms | 默认断言超时 | [test timeouts](https://playwright.dev/docs/test-timeouts#expect-timeout) |\n\n## 会话与上下文管理\n\n### 会话保存\n\n| 配置项 | 类型 | 说明 |\n|--------|------|------|\n| `saveSession` | `boolean` | 是否将 Playwright 会话保存到输出目录 |\n\n### 浏览器上下文共享\n\n| 配置项 | 类型 | 说明 |\n|--------|------|------|\n| `sharedBrowserContext` | `boolean` | 是否在所有连接的 HTTP 客户端之间重用同一个浏览器上下文 |\n\n## 安全配置\n\n### 密钥管理\n\n```typescript\nsecrets?: Record<string, string>;\n```\n\n`secrets` 用于替换工具响应中的匹配明文文本，防止 LLM 意外获取敏感数据。\n\n> 注意：这是便利性功能而非安全特性，客户端仍需始终检查传入和来自工具的信息。\n\n### 图片响应控制\n\n```typescript\nimageResponses?: 'allow' | 'omit' | 'auto';\n```\n\n| 值 | 说明 |\n|----|------|\n| `allow` | 始终发送图片响应 |\n| `omit` | 始终省略图片响应 |\n| `auto` | 如果客户端能显示图片则发送（默认行为） |\n\n## 其他配置项\n\n### 测试 ID 属性\n\n```typescript\ntestIdAttribute?: string;\n```\n\n指定用于测试 ID 的属性，默认为 `data-testid`。\n\n### 输出目录\n\n```typescript\noutputDir?: string;\n```\n\n保存输出文件的目录路径。\n\n### 控制台日志级别\n\n```typescript\nconsole?: {\n  level?: 'error' | 'warning' | 'info' | 'debug';\n};\n```\n\n每种级别包含更严重级别的消息：`debug` < `info` < `warning` < `error`。\n\n## 配置传递方式\n\nPlaywright MCP 支持多种配置传递方式：\n\n### 1. CLI 参数\n\n通过命令行启动时传递参数：\n\n```bash\nnpx playwright-mcp --browser-name=chromium --output-dir=/tmp/pw-output\n```\n\n### 2. 环境变量\n\n每个 CLI 参数都有对应的环境变量：\n\n| CLI 参数前缀 | 环境变量前缀 |\n|--------------|--------------|\n| `--browser-name` | `PLAYWRIGHT_MCP_BROWSER_NAME` |\n| `--output-dir` | `PLAYWRIGHT_MCP_OUTPUT_DIR` |\n| `--secrets` | `PLAYWRIGHT_MCP_SECRETS_FILE` |\n\n环境变量通过 `update-readme.js` 脚本自动从 CLI 定义生成。资料来源：[update-readme.js:62-67](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)\n\n### 3. 编程配置\n\n通过 `Config` 类型定义配置对象：\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  timeouts: {\n    action: 10000,\n    navigation: 30000\n  }\n};\n```\n\n## 配置类型定义\n\n完整的 `Config` 类型定义如下：\n\n```typescript\nexport type Config = {\n  browser?: {\n    browserName?: 'chromium' | 'firefox' | 'webkit';\n    isolated?: boolean;\n    userDataDir?: string;\n    // ... 其他启动选项\n  };\n  capabilities?: ToolCapability[];\n  saveSession?: boolean;\n  sharedBrowserContext?: boolean;\n  secrets?: Record<string, string>;\n  outputDir?: string;\n  console?: {\n    level?: 'error' | 'warning' | 'info' | 'debug';\n  };\n  network?: {\n    allowedOrigins?: string[];\n    blockedOrigins?: string[];\n  };\n  testIdAttribute?: string;\n  timeouts?: {\n    action?: number;\n    navigation?: number;\n    expect?: number;\n  };\n  imageResponses?: 'allow' | 'omit' | 'auto';\n  snapshot?: /* Snapshot 配置 */;\n};\n```\n\n资料来源：[config.d.ts:1-100](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## 测试配置\n\n对于测试场景，Playwright MCP 使用独立的 `playwright.config.ts` 配置文件：\n\n```typescript\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:1-30](https://github.com/microsoft/playwright-mcp/blob/main/playwright.config.ts)\n\n## 配置验证流程\n\n```mermaid\ngraph LR\n    A[输入配置] --> B[类型检查]\n    B --> C{合法?}\n    C -->|是| D[应用配置]\n    C -->|否| E[抛出错误]\n    \n    D --> F[浏览器启动]\n    D --> G[工具注册]\n    D --> H[网络策略应用]\n    D --> I[超时设置]\n```\n\n## 最佳实践\n\n1. **隔离环境**：使用 `isolated: true` 避免浏览器状态污染\n2. **超时设置**：根据网络环境调整 `timeouts` 数值\n3. **网络安全**：生产环境应明确设置 `allowedOrigins` 白名单\n4. **密钥保护**：通过 `secrets` 配置敏感信息，避免硬编码\n5. **能力精简**：仅启用必需的 `capabilities`，减少攻击面\n\n---\n\n<a id='page-security-config'></a>\n\n## 安全与网络配置\n\n### 相关页面\n\n相关主题：[MCP 工具与能力](#page-tools-capabilities), [部署选项](#page-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- [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- [update-readme.js](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)\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</details>\n\n# 安全与网络配置\n\nPlaywright MCP 提供了全面的安全与网络配置功能，允许用户精细控制浏览器的网络请求、敏感信息处理以及浏览器实例的安全策略。本文档详细介绍这些配置选项的用途、使用方法和最佳实践。\n\n## 概述\n\nPlaywright MCP 是一个为 MCP（Model Context Protocol）协议提供 Playwright 工具的项目。它允许 AI 助手通过标准化的接口控制浏览器执行各种自动化任务，包括导航、点击、输入、网络请求拦截等操作。资料来源：[package.json:1-10]()\n\n为了确保在自动化浏览器操作过程中的安全性，项目提供了多层次的安全配置机制：\n\n- **网络请求控制**：通过 `allowedOrigins` 和 `blockedOrigins` 白名单/黑名单机制\n- **敏感信息保护**：通过 `secrets` 配置实现敏感数据的自动替换\n- **浏览器隔离**：通过 `browser.isolated` 等选项控制浏览器实例的生命周期\n\n资料来源：[config.d.ts:1-150]()\n\n## 网络配置\n\n### 源地址过滤\n\nPlaywright MCP 提供了精细的网络请求控制功能，允许管理员指定允许或阻止的请求源地址。\n\n#### allowedOrigins（允许的源地址）\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| 类型 | `string[]` | 允许浏览器请求的源地址列表 |\n| 默认值 | 全部允许 | 若未配置，默认允许所有源地址的请求 |\n\n支持的匹配格式：\n\n| 格式 | 示例 | 匹配范围 |\n|------|------|----------|\n| 完整源地址 | `https://example.com:8080` | 仅匹配指定协议、域名和端口的请求 |\n| 通配符端口 | `http://localhost:*` | 匹配 localhost 上任意端口的 HTTP 请求 |\n\n当请求同时匹配 `allowedOrigins` 和 `blockedOrigins` 时，该请求将被阻止。\n\n资料来源：[config.d.ts:50-75]()\n\n#### blockedOrigins（阻止的源地址）\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| 类型 | `string[]` | 阻止浏览器请求的源地址列表 |\n| 默认值 | 空数组 | 若未配置，默认不阻止任何源地址 |\n\n```mermaid\ngraph TD\n    A[浏览器发起请求] --> B{检查 blockedOrigins}\n    B -->|匹配黑名单| C[阻止请求]\n    B -->|未匹配黑名单| D{检查 allowedOrigins}\n    D -->|已配置且匹配| E[允许请求]\n    D -->|已配置但未匹配| C\n    D -->|未配置| E\n```\n\n**配置示例**：\n\n```typescript\n{\n  network: {\n    // 允许所有本地开发服务器\n    allowedOrigins: [\n      'http://localhost:3000',\n      'http://localhost:8080',\n      'http://127.0.0.1:*'\n    ],\n    // 阻止所有外部 API 请求\n    blockedOrigins: [\n      'https://api.external-service.com'\n    ]\n  }\n}\n```\n\n资料来源：[config.d.ts:60-90]()\n\n### 网络配置结构\n\n完整的网络配置类型定义如下：\n\n```typescript\nnetwork?: {\n  allowedOrigins?: string[];\n  blockedOrigins?: string[];\n};\n```\n\n## 浏览器配置与安全隔离\n\n### 浏览器实例选项\n\nPlaywright MCP 支持配置浏览器实例的各项参数，以满足不同的安全需求。\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `browser.browserName` | `'chromium' \\| 'firefox' \\| 'webkit'` | `'chromium'` | 指定使用的浏览器类型 |\n| `browser.isolated` | `boolean` | `true` | 浏览器配置文件是否仅保留在内存中，不写入磁盘 |\n| `browser.userDataDir` | `string` | 系统临时目录 | 浏览器配置文件的存储路径 |\n\n#### 隔离模式（isolated）\n\n启用隔离模式后，浏览器不会将任何持久化数据（如 Cookie、缓存、本地存储）写入磁盘。这对于安全性要求较高的自动化场景特别有用。\n\n```typescript\n{\n  browser: {\n    browserName: 'chromium',\n    isolated: true  // 启用内存隔离模式\n  }\n}\n```\n\n资料来源：[config.d.ts:30-55]()\n\n### 用户数据目录管理\n\n通过 `userDataDir` 可以自定义浏览器配置文件的存储位置。默认情况下，系统会创建临时目录存储浏览器数据。\n\n| 模式 | userDataDir | 行为 |\n|------|-------------|------|\n| 临时模式 | 未指定 | 创建临时目录，测试结束后自动清理 |\n| 持久模式 | 指定路径 | 使用指定目录，可在多次运行间保持浏览器状态 |\n\n资料来源：[config.d.ts:35-45]()\n\n## 敏感信息安全\n\n### Secrets 配置\n\nPlaywright MCP 提供了 `secrets` 配置选项，用于在工具响应中自动替换敏感信息，防止大语言模型意外获取敏感数据。\n\n> **重要提示**：secrets 功能是便利性功能而非安全特性。它主要用于防止 LLM 意外泄露敏感数据，但不应将其视为真正的安全加密手段。请确保始终对客户端传入的信息进行仔细检查。\n\n资料来源：[config.d.ts:110-120]()\n\n#### Secrets 配置结构\n\n```typescript\nsecrets?: Record<string, string>;\n```\n\n#### 使用方式\n\n```typescript\n{\n  secrets: {\n    // key: 要替换的敏感值\n    // value: 替换后的显示值\n    'my-api-key-12345': '[REDACTED]',\n    'Bearer token_xyz': '[REDACTED]'\n  }\n}\n```\n\n#### 替换机制\n\n当工具响应中包含匹配 `secrets` 中定义的键值时，对应的敏感信息会被替换为预设的显示值：\n\n```mermaid\ngraph LR\n    A[工具响应生成] --> B{检查 secrets 配置}\n    B -->|发现敏感信息| C[替换为预设值]\n    B -->|无敏感信息| D[保持原样]\n    C --> E[返回处理后的响应]\n    D --> E\n```\n\n资料来源：[update-readme.js:80-95]()\n\n### Console 日志级别控制\n\n通过 `console.level` 配置可以控制返回给客户端的日志消息级别：\n\n| 级别 | 包含消息 | 使用场景 |\n|------|----------|----------|\n| `error` | 仅错误信息 | 生产环境，减少数据量 |\n| `warning` | 错误 + 警告 | 标准生产环境 |\n| `info` | 警告 + 信息 | 开发调试 |\n| `debug` | 所有消息 | 详细调试 |\n\n```typescript\n{\n  console: {\n    level: 'info'  // 默认值\n  }\n}\n```\n\n资料来源：[config.d.ts:125-135]()\n\n## 配置选项参考\n\n### 完整配置类型定义\n\n```typescript\nexport type Config = {\n  browser?: {\n    browserName?: 'chromium' | 'firefox' | 'webkit';\n    isolated?: boolean;\n    userDataDir?: string;\n    launchOptions?: Record<string, any>;\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' | 'auto';\n  snapshot?: Record<string, any>;\n};\n```\n\n资料来源：[config.d.ts:95-145]()\n\n### CLI 环境变量映射\n\nCLI 选项与环境变量的映射关系：\n\n| CLI 选项 | 环境变量 | 说明 |\n|----------|----------|------|\n| `--secrets` | `PLAYWRIGHT_MCP_SECRETS_FILE` | secrets 文件路径 |\n| `--browser` | `PLAYWRIGHT_MCP_BROWSER` | 浏览器类型 |\n| `--output-dir` | `PLAYWRIGHT_MCP_OUTPUT_DIR` | 输出目录 |\n| 其他选项 | `PLAYWRIGHT_MCP_<OPTION>` | 通用前缀映射 |\n\n资料来源：[update-readme.js:60-80]()\n\n## 安全最佳实践\n\n### 开发环境配置\n\n```typescript\n// 开发环境配置示例\n{\n  browser: {\n    browserName: 'chromium',\n    isolated: false  // 开发环境可复用浏览器状态\n  },\n  network: {\n    allowedOrigins: ['http://localhost:*'],\n    blockedOrigins: ['https://production-api.example.com']\n  },\n  console: {\n    level: 'debug'\n  }\n}\n```\n\n### 生产环境配置\n\n```typescript\n// 生产环境配置示例\n{\n  browser: {\n    browserName: 'chromium',\n    isolated: true  // 生产环境启用隔离\n  },\n  network: {\n    allowedOrigins: [\n      'https://app.example.com',\n      'https://cdn.example.com'\n    ],\n    blockedOrigins: ['*']\n  },\n  secrets: {\n    'api-key-xxx': '[REDACTED]',\n    'session-token': '[REDACTED]'\n  },\n  console: {\n    level: 'error'  // 仅返回错误信息\n  }\n}\n```\n\n### 安全检查清单\n\n在部署 Playwright MCP 之前，建议检查以下安全配置：\n\n| 检查项 | 推荐配置 | 说明 |\n|--------|----------|------|\n| 浏览器隔离 | `isolated: true` | 防止数据持久化泄露 |\n| 网络白名单 | 配置明确的 allowedOrigins | 限制仅访问必要的域 |\n| 敏感信息 | 配置 secrets | 防止 LLM 意外获取敏感数据 |\n| Console 日志 | 生产环境使用 `error` 级别 | 减少敏感信息泄露风险 |\n| 临时文件 | 使用默认临时目录 | 避免在持久化存储中遗留数据 |\n\n## 安全漏洞报告\n\n微软对软件产品的安全性非常重视，包括所有通过 GitHub 组织管理的源代码仓库。\n\n### 报告流程\n\n**请勿通过公开的 GitHub Issues 报告安全漏洞。**\n\n应按照以下方式向 Microsoft Security Response Center (MSRC) 报告：\n\n1. 访问：[https://msrc.microsoft.com/create-report](https://aka.ms/security.md/msrc/create-report)\n2. 或发送邮件至：[secure@microsoft.com](mailto:secure@microsoft.com)\n3. 如可能，请使用 PGP 密钥加密消息（可从 Microsoft Security Response Center PGP Key 页面下载）\n\n通常情况下，您将在 24 小时内收到回复。\n\n资料来源：[SECURITY.md:1-30]()\n\n### 报告内容建议\n\n在报告时，请尽可能提供以下信息以帮助我们更好地理解和处理问题：\n\n- 问题类型\n- 完整的产品路径\n- 受影响的组件\n- 复现步骤\n- 建议的修复方案（可选）\n\n## 相关文档\n\n| 文档 | 说明 |\n|------|------|\n| [配置参考](./config.md) | 完整的配置选项详细说明 |\n| [工具列表](./tools.md) | 可用工具及其参数说明 |\n| [CLI 使用指南](./cli.md) | 命令行工具使用方法 |\n| [测试指南](../tests/mcp) | 测试用例编写规范 |\n\n## 贡献指南\n\n如果发现安全相关问题或希望为项目贡献代码，请注意以下事项：\n\n1. **问题优先**：在提交 PR 之前，请先提交或查找相关的问题（issue）\n2. **提交规范**：提交信息应遵循语义化提交规范（Semantic Commit Messages）\n3. **分支命名**：问题修复的分支命名格式为 `fix-<issue-number>`\n\n资料来源：[CONTRIBUTING.md:1-50]()\n\n```bash\n# 创建修复分支示例\ngit checkout -b fix-39562\n\n# 提交修复\ngit commit -m \"fix(proxy): handle SOCKS proxy authentication\"\n```\n\n资料来源：[CLAUDE.md:1-40]()\n\n---\n\n<a id='page-deployment'></a>\n\n## 部署选项\n\n### 相关页面\n\n相关主题：[快速入门](#page-quickstart)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\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- [Dockerfile](https://github.com/microsoft/playwright-mcp/blob/main/Dockerfile)\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- [update-readme.js](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)\n</details>\n\n# 部署选项\n\nPlaywright MCP 提供了多种部署方式，以适应不同的使用场景和环境需求。本页面详细介绍如何通过 Node.js 环境、Docker 容器以及 CLI 命令行工具等方式部署和运行 Playwright MCP。\n\n## 概述\n\nPlaywright MCP 是一个基于 Model Context Protocol (MCP) 的浏览器自动化工具，它将 Playwright 的强大功能封装为一组 MCP 工具，供 AI 代理和自动化系统使用。部署选项的设计目标是为开发者提供灵活的选择，无论是本地开发、测试环境还是生产环境，都能找到合适的部署方式。\n\n根据 package.json 中的配置，Playwright MCP 需要 Node.js 18 或更高版本运行环境，并通过 npm 进行包管理 资料来源：[package.json:8]()\n\n## Node.js 环境部署\n\n### 环境要求\n\n| 组件 | 最低版本 | 说明 |\n|------|----------|------|\n| Node.js | >= 18 | JavaScript 运行时环境 |\n| npm | 内置 | Node.js 包管理器 |\n| Playwright 浏览器 | 自动安装 | 通过 `npx playwright install` 安装 |\n\n### 安装步骤\n\n在 Node.js 环境中部署 Playwright MCP 的标准流程如下：\n\n```bash\n# 克隆仓库\ngit clone https://github.com/microsoft/playwright-mcp\ncd playwright-mcp\n\n# 安装依赖\nnpm ci\n\n# 安装浏览器（Chromium、Firefox、WebKit）\nnpx playwright install\n```\n\n### 运行 MCP 服务器\n\nPlaywright MCP 提供了两种运行模式：通过 CLI 直接运行或作为模块导入使用。\n\n#### CLI 模式\n\n直接使用 CLI 运行 MCP 服务器：\n\n```bash\n# 查看可用选项\nnpm run lint\n\n# 运行测试\nnpm test\n\n# 仅运行 Chromium 测试\nnpm run ctest\n```\n\n#### 模块导入模式\n\n在 JavaScript 或 TypeScript 项目中作为模块使用：\n\n```javascript\nconst { createConnection } = require('@playwright/mcp');\n// 或 ESM\nimport { createConnection } from '@playwright/mcp';\n```\n\n资料来源：[index.js:25]()\n\n### MCP 测试配置\n\n在 playwright.config.ts 中，测试配置支持多种运行方式：\n\n```typescript\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:20-30]()\n\n## Docker 容器部署\n\nDocker 部署提供了一致的运行环境，特别适合 CI/CD 场景和需要隔离环境的开发团队。\n\n### Dockerfile 构建\n\nPlaywright MCP 提供了预配置的 Dockerfile 用于构建容器镜像：\n\n```bash\n# 构建镜像\nnpm run docker-build\n\n# 运行容器\nnpm run docker-run\n```\n\n手动构建命令：\n\n```bash\ndocker build --no-cache -t playwright-mcp-dev:latest .\n```\n\n### 容器运行参数\n\n| 参数 | 说明 |\n|------|------|\n| `-it` | 交互式终端模式 |\n| `-p 8080:8080` | 端口映射（主机:容器） |\n| `--name playwright-mcp-dev` | 容器命名 |\n| `playwright-mcp-dev:latest` | 镜像名称 |\n\n### Docker 测试模式\n\n在 Docker 环境中运行测试需要设置特定的环境变量：\n\n```bash\n# 在 Docker 中运行 Chromium 测试\nnpm run dtest\n```\n\n内部实现使用 `MCP_IN_DOCKER=1` 环境变量触发特殊配置：\n\n```bash\nMCP_IN_DOCKER=1 playwright test --project=chromium-docker\n```\n\nplaywright.config.ts 中 Docker 测试配置：\n\n```typescript\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资料来源：[playwright.config.ts:21-27]()\n\n### 容器生命周期管理\n\n```bash\n# 构建镜像\nnpm run docker-build\n\n# 运行容器\nnpm run docker-run\n\n# 停止并删除容器\nnpm run docker-rm\n```\n\n资料来源：[package.json:15-17]()\n\n## CLI 命令行工具\n\n### CLI 入口点\n\nCLI 通过 cli.js 实现，基于 commander.js 构建：\n\n```javascript\nconst { program } = require('playwright-core/lib/utilsBundle');\nconst { tools, libCli } = require('playwright-core/lib/coreBundle');\n```\n\n资料来源：[cli.js:15-16]()\n\n### install-browser 命令\n\nCLI 支持通过 `install-browser` 别名安装浏览器：\n\n```bash\nnpx playwright-mcp install-browser\n# 或\nnode cli.js install-browser\n```\n\n内部实现将 `install-browser` 转换为 `install` 命令：\n\n```javascript\nif (process.argv.includes('install-browser')) {\n  const argv = process.argv.map(arg => arg === 'install-browser' ? 'install' : arg);\n  libCli.decorateProgram(program);\n  void program.parseAsync(argv);\n  return;\n}\n```\n\n资料来源：[cli.js:12-18]()\n\n### MCP 命令装饰\n\nCLI 使用 Playwright Core 的 MCP 工具装饰功能：\n\n```javascript\nconst packageJSON = require('./package.json');\nconst p = program.version('Version ' + packageJSON.version).name('Playwright MCP');\ntools.decorateMCPCommand(p, packageJSON.version);\n```\n\n资料来源：[cli.js:21-24]()\n\n## 配置选项\n\n### 配置类型定义\n\nPlaywright MCP 的配置通过 TypeScript 类型定义在 config.d.ts 中，支持多种配置选项。\n\n资料来源：[config.d.ts:1-100]()\n\n### 浏览器配置\n\n| 选项 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `browser.browserName` | `chromium \\| firefox \\| webkit` | - | 指定浏览器类型 |\n| `browser.isolated` | `boolean` | - | 保持浏览器配置在内存中，不保存到磁盘 |\n| `browser.userDataDir` | `string` | - | 浏览器配置持久化目录 |\n\n### 超时配置\n\n```typescript\ntimeouts?: {\n  action?: number;      // 默认操作超时，默认 5000ms\n  navigation?: number; // 默认导航超时，默认 60000ms\n  expect?: number;     // 默认 expect 超时，默认 5000ms\n};\n```\n\n### 来源控制配置\n\nPlaywright MCP 支持细粒度的来源控制：\n\n| 选项 | 说明 |\n|------|------|\n| `allowedOrigins` | 允许浏览器请求的来源列表 |\n| `blockedOrigins` | 阻止浏览器请求的来源列表 |\n\n支持的格式：\n- 完整来源：`https://example.com:8080` - 仅匹配该来源\n- 通配符端口：`http://localhost:*` - 匹配 localhost 上任意端口的 HTTP 请求\n\n### 图像响应配置\n\n```typescript\nimageResponses?: 'allow' | 'omit' | 'auto';\n// 默认值为 \"auto\"，如果客户端可以显示则发送图像\n```\n\n### 测试 ID 属性\n\n```typescript\ntestIdAttribute?: string;\n// 指定用于测试 ID 的属性，默认为 \"data-testid\"\n```\n\n### 快照配置\n\n```typescript\nsnapshot?: {\n  // 快照相关配置选项\n};\n```\n\n## 功能模块与部署关系\n\n### 可用功能模块\n\nPlaywright MCP 将工具按功能模块组织，不同的模块可能需要不同的部署配置：\n\n| 模块标识 | 功能描述 | 部署要求 |\n|----------|----------|----------|\n| `config` | 配置管理 | 基础部署 |\n| `core` | 核心功能 | 基础部署 |\n| `core-navigation` | 导航操作 | 浏览器实例 |\n| `core-tabs` | 标签页管理 | 浏览器实例 |\n| `core-input` | 输入处理 | 浏览器实例 |\n| `core-install` | 安装功能 | 系统依赖 |\n| `network` | 网络请求 | 浏览器实例 |\n| `pdf` | PDF 生成 | 浏览器实例 |\n| `storage` | 存储管理 | 浏览器实例 |\n| `testing` | 测试断言 | Playwright Test |\n| `vision` | 视觉功能 | 浏览器实例 |\n| `devtools` | 开发者工具 | 浏览器实例 |\n\nOpt-in 模块可通过 `--caps` 参数启用：\n\n```bash\n--caps=network,pdf,storage\n```\n\n资料来源：[config.d.ts:13-28]()\n\n## 部署架构图\n\n```mermaid\ngraph TD\n    A[开发者环境] --> B[Node.js 部署]\n    A --> C[Docker 容器部署]\n    A --> D[CLI 工具部署]\n    \n    B --> B1[直接运行]\n    B --> B2[模块导入]\n    \n    C --> C1[容器构建]\n    C --> C2[容器运行]\n    C --> C3[测试模式]\n    \n    D --> D1[install-browser]\n    D --> D2[MCP 命令]\n    \n    B1 --> E[playwright-core]\n    B2 --> E\n    C2 --> E\n    E --> F[浏览器实例]\n    \n    F --> G[Chromium]\n    F --> H[Firefox]\n    F --> I[WebKit]\n```\n\n## 环境变量\n\n| 环境变量 | 说明 | 使用场景 |\n|----------|------|----------|\n| `MCP_IN_DOCKER` | 标记运行在 Docker 环境中 | Docker 测试 |\n| `CI` | 标记 CI 环境 | 持续集成 |\n| `PRINT_ENV` | 打印环境变量配置 | 调试 |\n\n## 最佳实践\n\n### 开发环境\n\n- 使用 `npm ci` 安装依赖确保构建一致性\n- 本地运行 `npx playwright install` 安装所需浏览器\n- 使用 `npm run ctest` 快速验证 Chromium 功能\n\n### CI/CD 环境\n\n- 优先使用 Docker 容器确保环境一致性\n- 设置 `CI=true` 以启用严格的测试模式\n- 使用 `npm test` 运行完整测试套件\n\n### 生产环境\n\n- 考虑使用 `browser.isolated` 选项提高安全性\n- 根据需求配置 `allowedOrigins` 和 `blockedOrigins`\n- 设置合适的 `timeouts` 值避免长时间等待\n\n## 故障排查\n\n### 常见问题\n\n| 问题 | 解决方案 |\n|------|----------|\n| 浏览器未安装 | 运行 `npx playwright install` |\n| 端口冲突 | 修改 `-p` 参数使用其他端口 |\n| 权限错误 | 确保 Docker 有足够的系统权限 |\n| 超时错误 | 调整 config 中的 `timeouts` 配置 |\n\n### 诊断命令\n\n```bash\n# 检查 Node.js 版本\nnode --version\n\n# 检查 Playwright 安装\nnpx playwright --version\n\n# 查看 CLI 帮助\nnode cli.js --help\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 项目说明书",
        "目录",
        "Playwright MCP 简介",
        "项目概述",
        "架构设计",
        "工具能力体系",
        "配置选项",
        "CLI 命令行工具",
        "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- **Playwright MCP 简介**：importance `high`\n  - source_paths: README.md, package.json\n- **Playwright MCP vs Playwright CLI**：importance `medium`\n  - source_paths: README.md\n- **快速入门**：importance `high`\n  - source_paths: README.md, package.json\n- **客户端集成指南**：importance `high`\n  - source_paths: README.md\n- **核心架构**：importance `high`\n  - source_paths: index.js, index.d.ts, cli.js\n- **MCP 工具与能力**：importance `high`\n  - source_paths: README.md, config.d.ts\n- **浏览器配置文件管理**：importance `high`\n  - source_paths: README.md, playwright.config.ts\n- **初始状态配置**：importance `medium`\n  - source_paths: 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-14 08:48:11 UTC\n\n## 目录\n\n- [Playwright MCP 简介](#page-introduction)\n- [Playwright MCP vs Playwright CLI](#page-comparison)\n- [快速入门](#page-quickstart)\n- [客户端集成指南](#page-client-integration)\n- [核心架构](#page-core-architecture)\n- [MCP 工具与能力](#page-tools-capabilities)\n- [浏览器配置文件管理](#page-browser-profiles)\n- [初始状态配置](#page-initial-state)\n- [安全与网络配置](#page-security-config)\n- [部署选项](#page-deployment)\n\n<a id='page-introduction'></a>\n\n## Playwright MCP 简介\n\n### 相关页面\n\n相关主题：[Playwright MCP vs Playwright CLI](#page-comparison), [快速入门](#page-quickstart)\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- [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- [server.json](https://github.com/microsoft/playwright-mcp/blob/main/server.json)\n</details>\n\n# Playwright MCP 简介\n\n## 项目概述\n\nPlaywright MCP（Model Context Protocol）是一个为 MCP（Model Context Protocol）协议提供 Playwright 工具的官方实现。该项目由 Microsoft 开发维护，为大语言模型（LLM）代理提供浏览器自动化能力，使其能够与网页进行交互、操作 DOM 元素、执行网络请求等操作。\n\nPlaywright MCP 作为 MCP 服务器运行，通过标准输入输出（stdio）传输协议与 MCP 客户端通信 资料来源：[server.json:1-13]()。\n\n### 核心特性\n\n| 特性 | 描述 |\n|------|------|\n| MCP 协议兼容 | 符合 Model Context Protocol 规范 |\n| 多浏览器支持 | Chromium、Firefox、WebKit |\n| 工具化能力 | 将 Playwright API 暴露为 MCP 工具 |\n| 可配置性 | 支持丰富的运行时配置选项 |\n| 安全沙箱 | 支持浏览器隔离和来源限制 |\n\n## 架构设计\n\n### 系统架构\n\n```mermaid\ngraph TD\n    A[MCP 客户端] -->|stdio| B[Playwright MCP 服务器]\n    B --> C[Playwright Core]\n    C --> D[Chromium]\n    C --> E[Firefox]\n    C --> F[WebKit]\n    B --> G[工具注册表]\n    G --> H[Core 工具]\n    G --> I[Navigation 工具]\n    G --> J[Input 工具]\n    G --> K[Network 工具]\n    G --> L[Testing 工具]\n    G --> M[Vision 工具]\n```\n\n### 源码位置\n\n> [!WARNING]\n> Playwright MCP 的核心代码已迁移至 [Playwright 主仓库](https://github.com/microsoft/playwright)。当前仓库主要用于打包和发布。\n\n核心源码位于 `packages/playwright/src/mcp` 目录下 资料来源：[CONTRIBUTING.md:1-20]()。\n\n### 模块导出\n\n主入口文件通过 `playwright-core/lib/coreBundle` 导出 `createConnection` 函数：\n\n```javascript\nconst { tools } = require('playwright-core/lib/coreBundle');\nmodule.exports = { createConnection: tools.createConnection };\n```\n\n资料来源：[index.js:1-24]()\n\n## 工具能力体系\n\nPlaywright MCP 将功能组织为多个能力（Capability）模块，每个模块提供一组相关的 MCP 工具。\n\n### 能力类型定义\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' |           // PDF 生成\n  'storage' |       // 存储管理\n  'testing' |       // 测试功能\n  'vision' |        // 视觉功能\n  'devtools';       // 开发者工具\n```\n\n资料来源：[config.d.ts:1-20]()\n\n### 工具注册机制\n\n工具信息通过 `update-readme.js` 脚本从编译后的模块中提取，并自动生成 README 文档：\n\n```javascript\nasync function updateTools(content) {\n  console.log('Loading tool information from compiled modules...');\n  // 按能力分组列出工具\n  for (const [capability, tools] of Object.entries(toolsByCapability)) {\n    generatedLines.push(`<details>\\n<summary><b>${capability}</b></summary>`);\n    // ...\n  }\n}\n```\n\n资料来源：[update-readme.js:1-80]()\n\n## 配置选项\n\nPlaywright MCP 提供丰富的配置选项，通过 `Config` 类型定义。\n\n### 基础配置结构\n\n```typescript\nexport type Config = {\n  browser?: {\n    browserName?: 'chromium' | 'firefox' | 'webkit';\n    isolated?: boolean;\n    userDataDir?: string;\n    // 浏览器启动选项\n  };\n  capabilities?: ToolCapability[];\n  saveSession?: boolean;\n  sharedBrowserContext?: boolean;\n  secrets?: Record<string, string>;\n  outputDir?: string;\n  console?: {\n    level?: 'error' | 'warning' | 'info' | 'debug';\n  };\n  network?: {\n    allowedOrigins?: string[];\n    blockedOrigins?: string[];\n  };\n  testIdAttribute?: string;\n  timeouts?: {\n    action?: number;\n    navigation?: number;\n    expect?: number;\n  };\n  imageResponses?: 'allow' | 'omit';\n  snapshot?: { /* 快照配置 */ };\n};\n```\n\n资料来源：[config.d.ts:20-100]()\n\n### 浏览器配置\n\n| 参数 | 类型 | 默认值 | 描述 |\n|------|------|--------|------|\n| `browserName` | string | - | 浏览器类型：`chromium`、`firefox`、`webkit` |\n| `isolated` | boolean | - | 是否在内存中保持浏览器配置文件 |\n| `userDataDir` | string | 临时目录 | 浏览器配置文件保存路径 |\n\n### 超时配置\n\n| 参数 | 类型 | 默认值 | 描述 |\n|------|------|--------|------|\n| `timeouts.action` | number | 5000ms | 默认操作超时 |\n| `timeouts.navigation` | number | 60000ms | 默认导航超时 |\n| `timeouts.expect` | number | 5000ms | 默认断言超时 |\n\n### 网络安全配置\n\n| 参数 | 类型 | 描述 |\n|------|------|------|\n| `network.allowedOrigins` | string[] | 允许浏览器请求的来源列表 |\n| `network.blockedOrigins` | string[] | 阻止浏览器请求的来源列表 |\n\n支持的来源格式：\n- 完整来源：`https://example.com:8080`\n- 通配符端口：`http://localhost:*`\n\n资料来源：[config.d.ts:50-75]()\n\n## CLI 命令行工具\n\n### 入口脚本\n\n`cli.js` 是 MCP 服务器的命令行入口，负责解析参数并启动服务：\n\n```javascript\nconst { program } = require('playwright-core/lib/utilsBundle');\nconst { tools, libCli } = require('playwright-core/lib/coreBundle');\n\nif (process.argv.includes('install-browser')) {\n  const argv = process.argv.map(arg => arg === 'install-browser' ? 'install' : arg);\n  libCli.decorateProgram(program);\n  void program.parseAsync(argv);\n  return;\n}\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:1-35]()\n\n### 可用命令\n\n| 命令 | 描述 |\n|------|------|\n| `playwright-mcp install-browser` | 安装浏览器依赖 |\n| `playwright-mcp --help` | 显示帮助信息 |\n| `playwright-mcp --version` | 显示版本信息 |\n\n### npm 脚本\n\n| 脚本 | 描述 |\n|------|------|\n| `npm run lint` | 运行代码检查 |\n| `npm test` | 运行完整测试套件 |\n| `npm run ctest` | 仅运行 Chrome 测试 |\n| `npm run ftest` | 仅运行 Firefox 测试 |\n| `npm run wtest` | 仅运行 WebKit 测试 |\n| `npm run roll` | 更新 Playwright 版本 |\n\n资料来源：[package.json:1-40]()\n\n## 开发与测试\n\n### 环境搭建\n\n由于核心代码已迁移至 Playwright 主仓库，开发需克隆主仓库：\n\n```bash\ngit clone https://github.com/microsoft/playwright\ncd playwright\nnpm ci\nnpm run watch\nnpx playwright install\n```\n\n资料来源：[CONTRIBUTING.md:20-35]()\n\n### 测试执行\n\n#### 快速测试（仅 Chromium）\n\n```bash\nnpm run mcp-ctest\n```\n\n#### 完整测试（三浏览器）\n\n```bash\nnpm run mcp-test\n```\n\n#### Docker 环境测试\n\n```bash\nnpm run dtest  # MCP_IN_DOCKER=1 playwright test --project=chromium-docker\n```\n\n资料来源：[CONTRIBUTING.md:60-80]()\n\n### 代码规范\n\n代码风格由 `eslint.config.mjs` 定义，提交前应运行：\n\n```bash\nnpm run flint\n```\n\n资料来源：[CONTRIBUTING.md:40-45]()\n\n## 版本管理\n\n### 当前版本\n\n```json\n{\n  \"name\": \"@playwright/mcp\",\n  \"version\": \"0.0.75\"\n}\n```\n\n资料来源：[package.json:1-5]()\n\n### 版本更新流程\n\n1. 运行 `node roll.js` 更新 `playwright`、`playwright-core` 和 `@playwright/test` 依赖\n2. 创建分支：`git checkout -b roll-pw-<version-suffix>`\n3. 运行测试：`npm test`\n4. 提交并推送 PR\n\n分支命名规范：`roll-pw-<版本后缀>`\n\n资料来源：[CLAUDE.md:15-25]()\n\n## 提交规范\n\n### 提交信息格式\n\n```\nlabel(namespace): 标题\n\n描述（可选）\n\nFooter（可选）\n```\n\n### 标签类型\n\n| 标签 | 用途 |\n|------|------|\n| `fix` | 错误修复 |\n| `feat` | 新功能 |\n| `docs` | 文档更改 |\n| `test` | 测试更改 |\n| `devops` | CI 或构建更改 |\n| `chore` | 其他更改 |\n\n资料来源：[CONTRIBUTING.md:1-30]()\n\n### 示例\n\n```\nfix(proxy): handle SOCKS proxy authentication\n\nFixes: https://github.com/microsoft/playwright/issues/39562\n```\n\n## 贡献指南\n\n### 提交流程\n\n1. **创建 Issue**：任何贡献都需要先创建对应的 Issue（文档修复除外）\n2. **获取分配**：等待维护者分配任务\n3. **开发实现**：遵循代码规范进行开发\n4. **编写测试**：确保新功能有对应的测试\n5. **提交 PR**：保持 PR 小而精炼，便于审查\n\n### PR 要求\n\n- 必须关联已创建并分配的 Issue\n- 需要通过所有测试\n- 代码风格需符合 ESLint 规则\n- 提交信息遵循语义化规范\n\n> [!WARNING]\n> 未关联 Issue 或未获批准的 PR 将被关闭。\n\n资料来源：[CONTRIBUTING.md:80-110]()\n\n## 总结\n\nPlaywright MCP 为大语言模型代理提供了强大的浏览器自动化能力，通过 MCP 协议将 Playwright 的丰富功能工具化。其配置灵活、支持多种浏览器，并提供完整的安全控制机制。随着代码迁移至 Playwright 主仓库，该项目作为 npm 包发布渠道继续为社区提供支持。\n\n---\n\n<a id='page-comparison'></a>\n\n## Playwright MCP vs Playwright CLI\n\n### 相关页面\n\n相关主题：[Playwright MCP 简介](#page-introduction)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\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- [update-readme.js](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)\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- [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</details>\n\n# Playwright MCP vs Playwright CLI\n\n## 概述\n\nPlaywright MCP (Model Context Protocol) 和 Playwright CLI 是 Playwright 生态系统中的两个不同入口点，它们服务于不同的使用场景和集成模式。\n\n**Playwright MCP** 是一个基于 Model Context Protocol 的服务器实现，允许 AI 模型通过标准化的 MCP 协议与 Playwright 浏览器自动化功能进行交互。它以 npm 包 `@playwright/mcp` 的形式发布，版本为 `0.0.75`，MCP 名称为 `io.github.microsoft/playwright-mcp` 资料来源：[package.json:1-20]()\n\n**Playwright CLI** 是传统的命令行工具，通过终端命令直接调用 Playwright 的各项功能，如启动浏览器、安装浏览器、执行测试等。资料来源：[cli.js:1-35]()\n\n> **重要说明**：Playwright MCP 的核心代码已迁移至 [Playwright 主仓库](https://github.com/microsoft/playwright)，位于 `packages/playwright/src/mcp` 目录。资料来源：[CONTRIBUTING.md:1-10]()\n\n---\n\n## 架构对比\n\n### Playwright MCP 架构\n\n```mermaid\ngraph TD\n    A[AI Model] -->|MCP Protocol| B[Playwright MCP Server]\n    B -->|Tool Calls| C[playwright-core<br/>lib/coreBundle]\n    C --> D[Browser Automation]\n    E[Configuration] --> B\n    F[Capabilities] --> B\n```\n\nPlaywright MCP 基于 MCP 协议工作，核心连接功能通过 `playwright-core/lib/coreBundle` 中的 `createConnection` 方法导出：\n\n```javascript\nconst { tools } = require('playwright-core/lib/coreBundle');\nmodule.exports = { createConnection: tools.createConnection };\n```\n\n资料来源：[index.js:15-20]()\n\n### Playwright CLI 架构\n\n```mermaid\ngraph TD\n    A[Terminal/Command] -->|CLI Args| B[cli.js]\n    B -->|Commands| C[playwright-core<br/>lib/utilsBundle]\n    C -->|Program| D[libCli]\n    D --> E[playwright-core<br/>lib/coreBundle]\n    E --> F[Browser Automation]\n```\n\nCLI 入口整合了多个模块：\n\n```javascript\nconst { program } = require('playwright-core/lib/utilsBundle');\nconst { tools, libCli } = require('playwright-core/lib/coreBundle');\n```\n\n资料来源：[cli.js:19-25]()\n\n---\n\n## 功能能力对比\n\n| 能力维度 | Playwright MCP | Playwright CLI |\n|---------|---------------|----------------|\n| **集成目标** | AI 模型交互 | 开发者直接使用 |\n| **通信协议** | MCP (STDIO) | 命令行参数 |\n| **交互模式** | 请求-响应工具调用 | 批处理命令执行 |\n| **状态管理** | 持久化会话支持 | 临时会话 |\n| **配置方式** | config.d.ts 类型定义 | 命令行参数 |\n\n---\n\n## Playwright MCP 配置系统\n\nPlaywright MCP 通过 `config.d.ts` 提供完整的类型化配置：\n\n```typescript\nexport type Config = {\n  browser?: {\n    browserName?: 'chromium' | 'firefox' | 'webkit';\n    isolated?: boolean;\n    userDataDir?: string;\n    launchOptions?: any;\n    initPage?: string[];\n    initScript?: string[];\n  },\n  extension?: boolean;\n  server?: {\n    port?: number;\n    host?: string;\n    allowedHosts?: string[];\n  },\n  capabilities?: ToolCapability[];\n  saveSession?: boolean;\n  sharedBrowserContext?: boolean;\n  secrets?: Record<string, string>;\n  outputDir?: string;\n  console?: { level?: 'error' | 'warning' | 'info' | 'debug' };\n  network?: {\n    allowedOrigins?: string[];\n    blockedOrigins?: string[];\n  };\n};\n```\n\n资料来源：[config.d.ts:20-85]()\n\n### 工具能力类型\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:16-27]()\n\n---\n\n## Playwright CLI 命令行接口\n\n### cli.js 入口点\n\ncli.js 是 MCP 服务器的主入口，支持两种工作模式：\n\n```mermaid\ngraph TD\n    A[cli.js] --> B{参数判断}\n    B -->|包含 install-browser| C[libCli<br/>install 命令]\n    B -->|其他情况| D[tools.decorateMCPCommand<br/>MCP 模式]\n```\n\n关键实现逻辑：\n\n```javascript\nif (process.argv.includes('install-browser')) {\n  const argv = process.argv.map(arg => arg === 'install-browser' ? 'install' : arg);\n  libCli.decorateProgram(program);\n  void program.parseAsync(argv);\n  return;\n}\n\nconst packageJSON = require('./package.json');\nconst p = program.version('Version ' + packageJSON.version).name('Playwright MCP');\ntools.decorateMCPCommand(p, packageJSON.version);\n```\n\n资料来源：[cli.js:22-35]()\n\n### 可用命令\n\n| 命令 | 功能 | 来源模块 |\n|-----|------|---------|\n| `install-browser` | 安装 Playwright 浏览器 | libCli |\n| MCP Tools | 浏览器自动化工具集 | tools |\n| `--help` | 显示帮助信息 | program |\n\n---\n\n## MCP 服务器配置\n\nserver.json 定义了 MCP 服务器的元数据：\n\n```json\n{\n  \"$schema\": \"https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json\",\n  \"name\": \"io.github.microsoft/playwright-mcp\",\n  \"description\": \"Playwright Tools for MCP\",\n  \"version\": \"0.0.75\",\n  \"packages\": [{\n    \"registryType\": \"npm\",\n    \"identifier\": \"@playwright/mcp\",\n    \"version\": \"0.0.75\",\n    \"transport\": { \"type\": \"stdio\" }\n  }]\n}\n```\n\n资料来源：[server.json:1-20]()\n\n---\n\n## 自动化工具生成\n\n`update-readme.js` 脚本负责从编译后的模块中提取工具信息并生成文档：\n\n```mermaid\ngraph LR\n    A[编译模块] --> B[update-readme.js]\n    B --> C[工具信息提取]\n    C --> D[formatToolForReadme]\n    D --> E[README.md<br/>自动更新]\n```\n\n工具格式化函数提取每个工具的：\n\n- **名称** (name)\n- **标题** (title)\n- **描述** (description)\n- **参数** (parameters)\n- **是否只读** (read-only)\n\n资料来源：[update-readme.js:1-150]()\n\n---\n\n## 包结构与导出\n\n### 入口点配置\n\npackage.json 定义了导出结构：\n\n```json\n{\n  \"exports\": {\n    \"./package.json\": \"./package.json\",\n    \".\": { \"types\": \"./index.d.ts\" }\n  },\n  \"mcpName\": \"io.github.microsoft/playwright-mcp\"\n}\n```\n\n资料来源：[package.json:25-32]()\n\n### 版本与依赖\n\n| 项目 | 值 |\n|-----|---|\n| 包名 | @playwright/mcp |\n| 版本 | 0.0.75 |\n| Node 要求 | >=18 |\n| 许可证 | Apache-2.0 |\n| 作者 | Microsoft Corporation |\n\n---\n\n## 发布与维护流程\n\n### 更新 Playwright 版本\n\n根据 CLAUDE.md，维护者需要运行 `roll.js` 脚本：\n\n1. 执行 `npm run roll` 更新 Playwright 版本\n2. 从主仓库复制 `config.d.ts`\n3. 刷新 README 文档\n4. 提交更新并创建 PR\n\n```javascript\nfunction doRoll(version) {\n  updatePlaywrightVersion(version);\n  copyConfig();\n  execSync('npm run lint', { cwd: __dirname, stdio: 'inherit' });\n}\n```\n\n资料来源：[roll.js:1-50]()\n\n### 测试配置\n\n项目使用 Playwright 自身进行测试：\n\n```typescript\nexport default defineConfig<TestOptions>({\n  testDir: './tests',\n  fullyParallel: true,\n  reporter: 'list',\n  projects: [\n    { name: 'chrome' },\n    // Docker 测试配置\n  ],\n});\n```\n\n资料来源：[playwright.config.ts:1-30]()\n\n---\n\n## 使用场景选择\n\n```mermaid\ngraph TD\n    A[开始] --> B{使用场景}\n    B -->|AI 模型集成| C[Playwright MCP]\n    B -->|开发者自动化| D[Playwright CLI]\n    B -->|脚本批处理| E[Playwright CLI]\n    B -->|测试执行| F[Playwright CLI / Test]\n```\n\n### 选择 Playwright MCP 的场景\n\n- AI 代理需要浏览器自动化能力\n- 通过标准化协议集成多个工具\n- 需要 MCP 生态系统兼容性\n\n### 选择 Playwright CLI 的场景\n\n- 终端直接操作浏览器\n- CI/CD 管道集成\n- 快速调试和原型开发\n- 安装和管理浏览器\n\n---\n\n## 总结\n\n| 特性 | Playwright MCP | Playwright CLI |\n|-----|----------------|----------------|\n| **设计目标** | AI 代理集成 | 开发者工具 |\n| **协议** | Model Context Protocol | 命令行参数 |\n| **传输** | STDIO | 标准输入/输出 |\n| **状态** | 持久化、可共享 | 临时会话 |\n| **配置复杂度** | 高（完整类型系统） | 低（命令行参数） |\n| **适用人群** | AI 开发者、系统集成商 | 开发者、测试工程师 |\n\n两者本质上是同一底层能力的不同封装形式，Playwright MCP 建立在 Playwright CLI 的基础之上，通过 MCP 协议提供更高级别的抽象，使 AI 模型能够以结构化的方式调用浏览器自动化功能。\n\n---\n\n<a id='page-quickstart'></a>\n\n## 快速入门\n\n### 相关页面\n\n相关主题：[客户端集成指南](#page-client-integration), [部署选项](#page-deployment)\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- [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# 快速入门\n\n## 概述\n\nPlaywright MCP（Model Context Protocol）是由微软开发的Playwright工具集，通过MCP协议为大型语言模型提供浏览器自动化能力。该项目允许AI代理通过标准化的工具接口执行网页导航、元素交互、截图捕获等浏览器操作。资料来源：[README.md](https://github.com/microsoft/playwright-mcp/blob/main/README.md)\n\n> [!IMPORTANT]\n> Playwright MCP的核心代码已迁移至 [Playwright 主仓库](https://github.com/microsoft/playwright)，源代码位于 `packages/playwright/src/mcp` 目录。资料来源：[CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n\n## 环境要求\n\n| 要求项 | 最低版本 | 说明 |\n|--------|----------|------|\n| Node.js | >= 18 | 运行时环境 |\n| npm | 最新稳定版 | 包管理器 |\n| 浏览器 | Chromium/Firefox/WebKit | 测试浏览器（按需安装） |\n\n## 安装步骤\n\n### 1. 克隆仓库\n\n由于核心代码已迁移至Playwright主仓库，推荐从主仓库克隆：\n\n```bash\ngit clone https://github.com/microsoft/playwright\ncd playwright\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n\n### 2. 安装依赖并构建\n\n```bash\n# 安装项目依赖\nnpm ci\n\n# 以监视模式运行构建\nnpm run watch\n\n# 安装浏览器（根据需要选择）\nnpx playwright install\n```\n\n### 3. 验证安装\n\n运行快速测试验证安装是否成功：\n\n```bash\n# 仅在Chromium中运行MCP测试（快速路径）\nnpm run mcp-ctest\n\n# 在三个浏览器中运行完整测试（慢速路径）\nnpm run mcp-test\n```\n\n## 项目结构\n\n```\nplaywright/\n├── packages/\n│   └── playwright/\n│       └── src/\n│           └── mcp/          # MCP核心源代码\n├── tests/\n│   └── mcp/                  # MCP测试套件\n├── config.d.ts               # 配置类型定义\n├── playwright.config.ts     # 测试配置\n└── package.json             # 项目配置\n```\n\n## 可用工具分类\n\nPlaywright MCP提供以下能力类别：\n\n| 能力类别 | 说明 |\n|----------|------|\n| `config` | 配置管理 |\n| `core` | 核心浏览器操作 |\n| `core-navigation` | 页面导航 |\n| `core-tabs` | 标签页管理 |\n| `core-input` | 输入操作 |\n| `core-install` | 浏览器安装 |\n| `network` | 网络请求监控 |\n| `pdf` | PDF生成 |\n| `storage` | 存储管理 |\n| `testing` | 测试相关功能 |\n| `vision` | 视觉相关（截图、可视化） |\n| `devtools` | 开发者工具 |\n\n资料来源：[config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## 配置选项\n\n### 浏览器配置\n\n```typescript\n{\n  browser: {\n    browserName?: 'chromium' | 'firefox' | 'webkit';\n    isolated?: boolean;        // 是否保持浏览器配置在内存中\n    userDataDir?: string;      // 用户数据目录路径\n  };\n}\n```\n\n### 超时配置\n\n```typescript\n{\n  timeouts: {\n    action?: number;      // 默认操作超时，默认5000ms\n    navigation?: number;  // 默认导航超时，默认60000ms\n    expect?: number;      // 默认expect超时，默认5000ms\n  };\n}\n```\n\n### 网络配置\n\n```typescript\n{\n  network: {\n    allowedOrigins?: string[];   // 允许的请求来源\n    blockedOrigins?: string[];   // 阻止的请求来源\n  };\n}\n```\n\n资料来源：[config.d.ts](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## 命令行工具\n\n项目提供以下npm脚本命令：\n\n| 命令 | 说明 |\n|------|------|\n| `npm run mcp-ctest` | 在Chromium中运行所有MCP测试 |\n| `npm run mcp-test` | 在三个浏览器中运行所有MCP测试 |\n| `npm run lint` | 运行代码检查和更新README |\n| `npm run watch` | 监视模式构建 |\n| `npm run flint` | 运行完整代码检查 |\n\n资料来源：[package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n\n### 直接使用CLI\n\n```bash\n# 启动MCP服务器\nnode index.js\n\n# 安装浏览器\nnode cli.js install-browser\n\n# 获取帮助\nnode cli.js --help\n```\n\n资料来源：[cli.js](https://github.com/microsoft/playwright-mcp/blob/main/cli.js)，[index.js](https://github.com/microsoft/playwright-mcp/blob/main/index.js)\n\n## 测试运行流程\n\n```mermaid\ngraph TD\n    A[开始测试] --> B{环境变量CI}\n    B -->|是| C[设置2个workers]\n    B -->|否| D[使用全部CPU核心]\n    C --> E[运行playwright test]\n    D --> E\n    E --> F{测试结果}\n    F -->|通过| G[测试完成]\n    F -->|失败| H[报告错误]\n```\n\n## 开发工作流\n\n### 提交规范\n\n项目使用语义化提交信息格式：\n\n```\nlabel(namespace): 标题\n\n描述\n\nfooter\n```\n\n可用标签：\n\n| 标签 | 用途 |\n|------|------|\n| `fix` | 错误修复 |\n| `feat` | 新功能 |\n| `docs` | 文档更改 |\n| `test` | 测试相关 |\n| `devops` | CI或构建相关 |\n| `chore` | 其他杂项 |\n\n资料来源：[CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n\n### 分支命名\n\n- 错误修复：`fix-<issue-number>`\n- Playwright版本滚动：`roll-pw-<version-suffix>`\n\n### 代码规范\n\n- 代码风格定义在 `eslint.config.mjs`\n- 提交前运行代码检查：`npm run flint`\n- 注释应有明确目的，避免冗余\n- 代码应尽可能自解释\n\n资料来源：[CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n\n## 常见问题\n\n### Q: 测试无法通过怎么办？\n\n1. 确保所有依赖已正确安装：`npm ci`\n2. 确保浏览器已安装：`npx playwright install`\n3. 清除缓存后重试\n\n### Q: 如何仅测试特定浏览器？\n\n```bash\n# 仅Chrome\nnpm run ctest\n\n# 仅Firefox\nnpm run ftest\n\n# 仅WebKit\nnpm run wtest\n```\n\n### Q: 如何在Docker中运行测试？\n\n```bash\nMCP_IN_DOCKER=1 npm run dtest\n```\n\n## 下一步\n\n- 阅读完整 [README.md](https://github.com/microsoft/playwright-mcp/blob/main/README.md) 了解所有可用工具\n- 查看 [tests/mcp](https://github.com/microsoft/playwright/blob/main/tests/mcp) 目录中的测试示例\n- 参考 [Playwright 官方文档](https://playwright.dev/docs/api/class-page) 了解底层API\n\n---\n\n<a id='page-client-integration'></a>\n\n## 客户端集成指南\n\n### 相关页面\n\n相关主题：[快速入门](#page-quickstart), [部署选项](#page-deployment)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\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- [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- [server.json](https://github.com/microsoft/playwright-mcp/blob/main/server.json)\n- [CLAUDE.md](https://github.com/microsoft/playwright-mcp/blob/main/CLAUDE.md)\n- [playwright.config.ts](https://github.com/microsoft/playwright-mcp/blob/main/playwright.config.ts)\n</details>\n\n# 客户端集成指南\n\n## 概述\n\nPlaywright MCP (Model Context Protocol) 是微软提供的 Playwright 浏览器自动化工具的 MCP（Model Context Protocol）实现。它允许 AI 模型通过标准化协议与浏览器进行交互，执行网页自动化、测试和内容抓取等任务。\n\n核心代码已迁移至 [Playwright 主仓库](https://github.com/microsoft/playwright)，位于 `packages/playwright/src/mcp` 目录。资料来源：[CONTRIBUTING.md:43]()\n\n## 架构概览\n\n```mermaid\ngraph TD\n    A[AI Client / MCP Host] -->|MCP Protocol| B[Playwright MCP Server]\n    B -->|STDIO Transport| C[Browser Automation]\n    C -->|Playwright API| D[Chromium / Firefox / WebKit]\n    B --> E[Local Browser]\n    B --> F[Docker Container]\n    \n    G[Config File / CLI Args] --> B\n    H[Environment Variables] --> B\n```\n\n服务器通过 STDIO 传输协议与 MCP Host 进行通信，支持本地浏览器启动和 Docker 容器模式。资料来源：[server.json:12]()\n\n## 安装与依赖\n\n### 系统要求\n\n- **Node.js**: 需要版本 >= 18\n- **浏览器**: 支持 Chromium、Firefox、WebKit\n\n### 安装步骤\n\n```bash\nnpm install @playwright/mcp\n```\n\n或从源码构建：\n\n```bash\ngit clone https://github.com/microsoft/playwright\ncd playwright\nnpm ci\nnpm run watch\nnpx playwright install\n```\n\n资料来源：[CONTRIBUTING.md:51-60]()\n\n### Docker 部署\n\n```bash\n# 构建镜像\nnpm run docker-build\n\n# 运行容器\nnpm run docker-run\n```\n\n资料来源：[package.json:25-27]()\n\n## 配置选项\n\nPlaywright MCP 支持丰富的配置选项，定义在 `config.d.ts` 中。\n\n### 配置类型定义\n\n```typescript\nexport type Config = {\n  browser?: {\n    browserName?: 'chromium' | 'firefox' | 'webkit';\n    isolated?: boolean;\n    userDataDir?: string;\n    // 浏览器启动选项\n  };\n  allowedOrigins?: string[];      // 允许的请求来源\n  blockedOrigins?: string[];      // 阻止的请求来源\n  testIdAttribute?: string;       // 测试 ID 属性，默认 \"data-testid\"\n  timeouts?: {\n    action?: number;              // 操作超时，默认 5000ms\n    navigation?: number;         // 导航超时，默认 60000ms\n    expect?: number;              // 断言超时，默认 5000ms\n  };\n  imageResponses?: 'allow' | 'omit' | 'auto';\n};\n```\n\n资料来源：[config.d.ts:31-85]()\n\n### 工具能力列表\n\n| 能力分类 | 标识符 | 说明 | 启用方式 |\n|---------|--------|------|---------|\n| 核心能力 | `core` | 基础浏览器操作 | 默认启用 |\n| 导航能力 | `core-navigation` | 页面导航相关 | 默认启用 |\n| 标签页能力 | `core-tabs` | 多标签页管理 | 默认启用 |\n| 输入能力 | `core-input` | 表单输入操作 | 默认启用 |\n| 安装能力 | `core-install` | 浏览器安装 | 默认启用 |\n| 网络能力 | `network` | 网络请求拦截 | `--caps=network` |\n| PDF 能力 | `pdf` | PDF 生成 | `--caps=pdf` |\n| 存储能力 | `storage` | 本地存储管理 | `--caps=storage` |\n| 测试能力 | `testing` | 测试断言 | `--caps=testing` |\n| 视觉能力 | `vision` | 视觉对比 | `--caps=vision` |\n| 开发者工具 | `devtools` | DevTools 协议 | `--caps=devtools` |\n\n资料来源：[config.d.ts:12-25]()\n\n### 来源过滤配置\n\n#### 允许来源 (allowedOrigins)\n\n```typescript\nallowedOrigins?: string[];\n```\n\n支持的格式：\n\n| 格式 | 示例 | 匹配范围 |\n|------|------|---------|\n| 完整来源 | `https://example.com:8080` | 仅该来源 |\n| 通配符协议 | `*://example.com` | http 和 https |\n| 通配符子域 | `https://*.example.com` | 所有子域 |\n| 通配符端口 | `http://localhost:*` | localhost 所有端口 |\n\n资料来源：[config.d.ts:38-45]()\n\n#### 阻止来源 (blockedOrigins)\n\n```typescript\nblockedOrigins?: string[];\n```\n\n同时匹配 `allowedOrigins` 和 `blockedOrigins` 的来源将被阻止。\n\n## 命令行接口\n\n### CLI 入口点\n\n服务器通过 `cli.js` 启动，使用 `playwright-core` 的命令行框架：\n\n```bash\nnode cli.js [options]\n```\n\n资料来源：[cli.js:1-32]()\n\n### 可用命令\n\n| 命令 | 说明 |\n|------|------|\n| `node cli.js --help` | 显示帮助信息 |\n| `node cli.js --version` | 显示版本信息 |\n| `node cli.js install-browser` | 安装浏览器 |\n\n### 主要选项\n\n| 选项 | 说明 | 环境变量 |\n|------|------|---------|\n| `--caps` | 启用的能力列表 | `PLAYWRIGHT_MCP_CAPS` |\n| `--secrets` | 密钥文件路径 | `PLAYWRIGHT_MCP_SECRETS_FILE` |\n| `--browser` | 指定浏览器类型 | `PLAYWRIGHT_MCP_BROWSER` |\n| `--headless` | 无头模式运行 | `PLAYWRIGHT_MCP_HEADLESS` |\n\n环境变量格式为 `PLAYWRIGHT_MCP_` 前缀加上选项名称的大写形式，中划线替换为下划线。\n\n资料来源：[update-readme.js:1-60]()\n\n### 特殊命令\n\n#### install-browser\n\n```bash\nnode cli.js install-browser\n```\n\n该命令实际上是 `playwright install` 的别名，用于安装必要的浏览器二进制文件。\n\n## 工具能力详解\n\n### 核心能力 (core)\n\n默认启用的核心工具集，提供基础的浏览器操作能力：\n\n| 工具 | 说明 | 只读 |\n|------|------|------|\n| 导航工具 | 页面跳转、前进后退 | ✓ |\n| 点击工具 | 元素点击交互 | ✗ |\n| 填充工具 | 表单填充 | ✗ |\n| 截图工具 | 页面截图 | ✓ |\n\n### 网络能力 (network)\n\n通过 `--caps=network` 启用，提供网络请求拦截和管理功能：\n\n```mermaid\ngraph LR\n    A[Browser Request] --> B{MCP Network Filter}\n    B -->|Allowed| C[Network]\n    B -->|Blocked| D[Blocked Response]\n```\n\n### 测试能力 (testing)\n\n通过 `--caps=testing` 启用，提供测试断言功能：\n\n- `expect`: 断言验证\n- `toHaveTitle`: 标题验证\n- `toContainText`: 文本内容验证\n- `toBeVisible`: 元素可见性验证\n\n资料来源：[update-readme.js:70-100]()\n\n## 环境变量\n\n| 环境变量 | 对应选项 | 说明 |\n|----------|---------|------|\n| `PLAYWRIGHT_MCP_CAPS` | `--caps` | 启用的能力列表 |\n| `PLAYWRIGHT_MCP_SECRETS_FILE` | `--secrets` | 密钥文件路径 |\n| `PLAYWRIGHT_MCP_BROWSER` | `--browser` | 默认浏览器类型 |\n| `MCP_IN_DOCKER` | - | Docker 模式标志 |\n\n## 测试指南\n\n### 运行测试\n\n```bash\n# 快速测试（仅 Chromium）\nnpm run ctest\n\n# 完整测试（三浏览器）\nnpm run test\n\n# Firefox 专项测试\nnpm run ftest\n\n# WebKit 专项测试\nnpm run wtest\n\n# Docker 模式测试\nnpm run dtest\n```\n\n资料来源：[package.json:20-24]()\n\n### 测试配置\n\n测试配置文件位于 `playwright.config.ts`：\n\n```typescript\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测试文件位于 `tests/mcp` 目录。资料来源：[playwright.config.ts:1-30]()\n\n### 测试要求\n\n- 测试必须是**自包含的**，不依赖外部服务\n- 测试必须在三个平台都能运行：macOS、Linux、Windows\n- 新功能必须包含对应的测试用例\n- 纯重构可以例外\n\n资料来源：[CONTRIBUTING.md:90-95]()\n\n## 集成示例\n\n### 基本集成配置\n\n```json\n{\n  \"mcpServers\": {\n    \"playwright\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@playwright/mcp\"],\n      \"env\": {\n        \"PLAYWRIGHT_MCP_CAPS\": \"core,network\",\n        \"PLAYWRIGHT_MCP_BROWSER\": \"chromium\"\n      }\n    }\n  }\n}\n```\n\n### 使用 Docker 模式\n\n```bash\nnpm run docker-build\nnpm run docker-run\n```\n\nDocker 模式会启动隔离的容器环境运行浏览器。\n\n## 版本管理\n\n### 版本信息\n\n当前版本：`0.0.75`\n\n资料来源：[package.json:3]()\n\n### 滚动更新\n\n使用 `roll.js` 脚本更新 Playwright 版本：\n\n```bash\nnpm run roll\n```\n\n该脚本会：\n1. 更新 `package.json` 中的 Playwright 依赖版本\n2. 从 Playwright 主仓库复制 `config.d.ts`\n3. 重新生成 README 文档\n\n更新后需要创建分支并提交 PR：\n\n```bash\ngit checkout -b roll-pw-<version-suffix>\nnpm test\ngit commit -m \"chore: roll Playwright to <version>\"\n```\n\n资料来源：[CLAUDE.md:14-23]()\n\n## 贡献指南\n\n### 提交流流程\n\n```mermaid\ngraph TD\n    A[创建 Issue] --> B{是否需要新功能?}\n    B -->|是| C[描述问题并申请处理]\n    B -->|否| D[找到已有 Issue]\n    C --> E{是否分配给你?}\n    D --> E\n    E -->|否| F[等待分配]\n    E -->|是| G[创建分支 fix-<issue-number>]\n    G --> H[开发并添加测试]\n    H --> I[提交 PR]\n    I --> J[代码审查]\n    J -->|通过| K[合并]\n    J -->|拒绝| L[修改后重新提交]\n```\n\n### 提交规范\n\n提交信息必须遵循 Semantic Commit Messages 格式：\n\n```\n<label>(<namespace>): <title>\n\n<description>\n\n<footer>\n```\n\n标签类型：\n- `fix`: Bug 修复\n- `feat`: 新功能\n- `docs`: 文档更改\n- `test`: 测试更改\n- `devops`: CI/构建更改\n- `chore`: 其他更改\n\n### PR 要求\n\n- PR 必须关联一个 Issue 或经过批准\n- PR 必须通过所有测试\n- 代码必须通过 lint 检查：`npm run lint`\n- PR 内容应保持小而可读\n\n资料来源：[CONTRIBUTING.md:1-40]()\n\n## 常见问题\n\n### 浏览器无法启动\n\n确保已安装浏览器：\n```bash\nnpx playwright install\n```\n\n### 测试超时\n\n调整配置中的超时设置：\n```typescript\ntimeouts: {\n  action: 10000,      // 增加操作超时\n  navigation: 120000 // 增加导航超时\n}\n```\n\n### 网络请求被阻止\n\n检查 `allowedOrigins` 和 `blockedOrigins` 配置，确保目标域名在允许列表中。\n\n---\n\n<a id='page-core-architecture'></a>\n\n## 核心架构\n\n### 相关页面\n\n相关主题：[MCP 工具与能力](#page-tools-capabilities), [浏览器配置文件管理](#page-browser-profiles)\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- [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- [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# 核心架构\n\n## 概述\n\nplaywright-mcp 是 Microsoft Playwright 的 MCP（Model Context Protocol）实现，为大语言模型提供浏览器自动化能力。该项目作为 Playwright 与 MCP 协议之间的桥梁，使 AI Agent 能够通过标准化的 MCP 接口控制浏览器执行自动化任务。\n\n核心架构采用模块化设计，核心功能依赖于 playwright-core 库，并通过 CLI 和 API 两种方式暴露能力。\n\n## 系统架构图\n\n```mermaid\ngraph TD\n    subgraph 客户端层\n        MCP_Client[MCP 客户端]\n    end\n    \n    subgraph 核心模块\n        Connection[createConnection]\n        Tools[工具集合]\n        CLI[CLI 入口]\n    end\n    \n    subgraph Playwright 核心\n        CoreBundle[coreBundle]\n        Browser[浏览器自动化]\n        Page[页面控制]\n    end\n    \n    subgraph 配置系统\n        Config[Config 类型定义]\n        EnvVars[环境变量映射]\n    end\n    \n    MCP_Client --> Connection\n    Connection --> Tools\n    Connection --> CoreBundle\n    Tools --> Browser\n    CoreBundle --> Browser\n    CLI --> CoreBundle\n    Config --> Connection\n```\n\n## 入口点设计\n\n### API 入口：index.js\n\n主入口文件负责导出 MCP 连接工厂函数，供外部系统集成使用。\n\n资料来源：[index.js:25-27]()\n\n```javascript\nconst { tools } = require('playwright-core/lib/coreBundle');\nmodule.exports = { createConnection: tools.createConnection };\n```\n\n**设计特点**：\n- 极简导出设计，仅暴露 `createConnection` 函数\n- 底层实现委托给 playwright-core 的 coreBundle\n- 支持 Node.js 和 ES Module 环境\n\n### CLI 入口：cli.js\n\n命令行入口点，支持多种操作模式。\n\n资料来源：[cli.js:1-34]()\n\n```javascript\nconst { program } = require('playwright-core/lib/utilsBundle');\nconst { tools, libCli } = require('playwright-core/lib/coreBundle');\n\nif (process.argv.includes('install-browser')) {\n  const argv = process.argv.map(arg => arg === 'install-browser' ? 'install' : arg);\n  libCli.decorateProgram(program);\n  void program.parseAsync(argv);\n  return;\n}\n\nconst packageJSON = require('./package.json');\nconst p = program.version('Version ' + packageJSON.version).name('Playwright MCP');\ntools.decorateMCPCommand(p, packageJSON.version);\n```\n\n**CLI 功能**：\n| 命令 | 说明 | 资料来源 |\n|------|------|----------|\n| `playwright-mcp install-browser` | 安装浏览器驱动 | cli.js:13 |\n| MCP 工具命令 | 通过 playwright-core 提供 | cli.js:28 |\n\n## 工具能力体系\n\n### 能力分类\n\n工具按照功能被组织为多个能力类别（ToolCapability）。\n\n资料来源：[config.d.ts:6-20]()\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### 能力详情表\n\n| 能力标识 | 功能描述 |\n|----------|----------|\n| config | 配置管理 |\n| core | 核心浏览器自动化 |\n| core-navigation | 页面导航控制 |\n| core-tabs | 多标签页管理 |\n| core-input | 输入交互处理 |\n| core-install | 浏览器安装 |\n| network | 网络请求拦截 |\n| pdf | PDF 生成操作 |\n| storage | 存储状态管理 |\n| testing | 测试相关功能 |\n| vision | 视觉坐标交互 |\n| devtools | 开发者工具 |\n\n## 配置系统\n\n### 配置类型定义\n\n配置系统采用 TypeScript 类型定义，提供完整的类型安全配置。\n\n资料来源：[config.d.ts:23-150]()\n\n**核心配置结构**：\n\n```typescript\nexport type Config = {\n  browser?: {\n    browserName?: 'chromium' | 'firefox' | 'webkit';\n    isolated?: boolean;\n    userDataDir?: string;\n    launchOptions?: Record<string, any>;\n    initPage?: string[];\n    initScript?: string[];\n  },\n  extension?: boolean;\n  server?: {\n    port?: number;\n    host?: string;\n    allowedHosts?: string[];\n  },\n  capabilities?: ToolCapability[];\n  saveSession?: boolean;\n  sharedBrowserContext?: boolean;\n  secrets?: Record<string, string>;\n  origins?: {\n    allowedOrigins?: string[];\n    blockedOrigins?: string[];\n  };\n  testIdAttribute?: string;\n  timeouts?: {\n    action?: number;\n    navigation?: number;\n    expect?: number;\n  };\n  imageResponses?: 'allow' | 'omit' | 'auto';\n  snapshot?: /* ... */;\n}\n```\n\n### 配置项分类表\n\n| 分类 | 配置项 | 默认值 | 说明 |\n|------|--------|--------|------|\n| **浏览器** | browserName | - | 浏览器类型：chromium/firefox/webkit |\n| | isolated | false | 是否保持浏览器隔离 |\n| | userDataDir | 临时目录 | 用户数据目录路径 |\n| **服务器** | port | - | SSE/MCP 传输监听端口 |\n| | host | localhost | 服务器绑定地址 |\n| | allowedHosts | 同 host | 允许服务的主机列表 |\n| **功能开关** | capabilities | - | 启用的工具能力列表 |\n| | saveSession | false | 是否保存 Playwright 会话 |\n| | sharedBrowserContext | false | 跨客户端共享浏览器上下文 |\n| **超时配置** | timeouts.action | 5000ms | 默认动作超时 |\n| | timeouts.navigation | 60000ms | 默认导航超时 |\n| | timeouts.expect | 5000ms | 默认断言超时 |\n| **安全** | secrets | - | 密钥配置映射 |\n| | origins.allowedOrigins | - | 允许的请求来源 |\n| | origins.blockedOrigins | - | 阻止的请求来源 |\n\n### 环境变量映射\n\nCLI 选项自动映射为环境变量，提供灵活的部署配置。\n\n资料来源：[update-readme.js:66-85]()\n\n| CLI 选项 | 环境变量 | 说明 |\n|----------|----------|------|\n| --secrets | PLAYWRIGHT_MCP_SECRETS_FILE | 密钥文件路径 |\n| --port | PLAYWRIGHT_MCP_PORT | 服务端口 |\n| --host | PLAYWRIGHT_MCP_HOST | 服务主机 |\n| 其他选项 | PLAYWRIGHT_MCP_<选项大写> | 标准前缀映射 |\n\n## 模块依赖关系\n\n```mermaid\ngraph LR\n    subgraph 依赖层\n        playwright-core\n        playwright\n        @playwright/test\n    end\n    \n    subgraph 本项目\n        index.js\n        cli.js\n        config.d.ts\n    end\n    \n    playwright --> playwright-core\n    @playwright/test --> playwright-core\n    \n    index.js --> playwright-core\n    cli.js --> playwright-core\n```\n\n资料来源：[package.json:17-40]()\n\n```json\n{\n  \"name\": \"@playwright/mcp\",\n  \"version\": \"0.0.75\",\n  \"mcpName\": \"io.github.microsoft/playwright-mcp\",\n  \"scripts\": {\n    \"build\": \"echo OK\",\n    \"test\": \"playwright test\"\n  },\n  \"dependencies\": {\n    \"playwright-core\": \"...\"\n  },\n  \"devDependencies\": {\n    \"@playwright/test\": \"...\",\n    \"playwright\": \"...\"\n  }\n}\n```\n\n## 构建与发布流程\n\n### 版本管理机制\n\n项目使用 roll.js 脚本同步 Playwright 依赖版本。\n\n资料来源：[roll.js:1-35]()\n\n```javascript\nfunction copyConfig() {\n  const src = path.join(__dirname, '..', 'playwright', 'packages', 'playwright-core', 'src', 'tools', 'mcp', 'config.d.ts');\n  const dst = path.join(__dirname, 'config.d.ts');\n  // 复制并替换导入路径\n  content = content.replace(\n    \"import type * as playwright from 'playwright-core';\",\n    \"import type * as playwright from 'playwright';\"\n  );\n}\n\nfunction updatePlaywrightVersion(version) {\n  // 更新 package.json 中的依赖版本\n}\n\nfunction doRoll(version) {\n  updatePlaywrightVersion(version);\n  copyConfig();\n  execSync('npm run lint', { cwd: __dirname });\n}\n```\n\n### 版本更新流程\n\n```mermaid\nflowchart TD\n    A[运行 npm run roll] --> B[updatePlaywrightVersion]\n    B --> C[copyConfig 同步 config.d.ts]\n    C --> D[npm install 安装依赖]\n    D --> E[npm run lint 更新 README]\n    E --> F[生成新版本提交]\n```\n\n### npm Scripts 说明\n\n| 脚本 | 命令 | 用途 |\n|------|------|------|\n| build | `echo OK` | 构建检查（无编译步骤） |\n| lint | `node update-readme.js` | 更新自动生成的 README |\n| test | `playwright test` | 运行完整测试套件 |\n| ctest | `playwright test --project=chrome` | 仅 Chrome 测试 |\n| ftest | `playwright test --project=firefox` | 仅 Firefox 测试 |\n| wtest | `playwright test --project=webkit` | 仅 WebKit 测试 |\n| roll | `node roll.js` | 同步 Playwright 版本 |\n\n## MCP 工具注册机制\n\n### 工具装饰器模式\n\n工具通过 playwright-core 提供的装饰器注册到 MCP 命令系统。\n\n资料来源：[cli.js:28]()\n\n```javascript\ntools.decorateMCPCommand(p, packageJSON.version);\n```\n\n### README 自动生成\n\nupdate-readme.js 脚本从编译后的模块自动提取工具信息并生成文档。\n\n资料来源：[update-readme.js:130-150]()\n\n```javascript\nasync function updateTools(content) {\n  const generatedLines = [];\n  for (const [capability, tools] of Object.entries(toolsByCapability)) {\n    generatedLines.push(`<details>`);\n    generatedLines.push(`<summary><b>${capability}</b></summary>`);\n    for (const tool of tools)\n      generatedLines.push(...formatToolForReadme(tool.schema));\n    generatedLines.push(`</details>`);\n  }\n  // 使用标记替换机制更新 README\n}\n```\n\n## 测试架构\n\n### 测试配置\n\n项目使用 @playwright/test 定义测试配置。\n\n资料来源：[playwright.config.ts:1-40]()\n\n```typescript\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    ...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\n### 测试项目矩阵\n\n| 项目名称 | 浏览器 | 环境 | 说明 |\n|----------|--------|------|------|\n| chrome | Chromium | 标准 | 主要测试环境 |\n| chromium-docker | Chromium | Docker | Docker 环境测试 |\n\n## 数据流向\n\n```mermaid\nsequenceDiagram\n    participant MCP as MCP 客户端\n    participant Server as MCP 服务器\n    participant Tools as 工具层\n    participant PW as Playwright Core\n    participant Browser as 浏览器实例\n    \n    MCP->>Server: MCP 请求\n    Server->>Tools: 调用工具\n    Tools->>PW: Playwright API\n    PW->>Browser: 浏览器控制\n    Browser-->>PW: 执行结果\n    PW-->>Tools: 返回结果\n    Tools-->>Server: 格式化响应\n    Server-->>MCP: MCP 响应\n```\n\n## 安全机制\n\n### 来源控制\n\n支持细粒度的请求来源控制。\n\n资料来源：[config.d.ts:88-100]()\n\n```typescript\norigins?: {\n  /**\n   * 允许浏览器请求的来源列表\n   * 支持格式：\n   * - 完整来源: `https://example.com:8080`\n   * - 通配符端口: `http://localhost:*`\n   */\n  allowedOrigins?: string[];\n\n  /**\n   * 阻止浏览器请求的来源列表\n   * 同时匹配 allowedOrigins 和 blockedOrigins 的请求将被阻止\n   */\n  blockedOrigins?: string[];\n};\n```\n\n### 密钥管理\n\n通过 secrets 配置支持敏感信息的安全传递。\n\n| 配置项 | 说明 |\n|--------|------|\n| secrets | 密钥名称到值的映射，用于环境变量注入 |\n\n## 与 Playwright 主仓库的关系\n\n根据 CLAUDE.md 和 CONTRIBUTING.md 的说明：\n\n> [!WARNING]\n> The core of the Playwright MCP was moved to the [Playwright monorepo](https://github.com/microsoft/playwright).\n\n当前仓库作为 Playwright 主仓库的 MCP 能力抽象层：\n\n| 职责 | 仓库位置 |\n|------|----------|\n| 核心实现 | [packages/playwright/src/mcp](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/mcp) |\n| 测试代码 | [tests/mcp](https://github.com/microsoft/playwright/blob/main/tests/mcp) |\n| 本仓库 | 独立打包和分发 |\n\n## 总结\n\nplaywright-mcp 的核心架构具有以下特点：\n\n1. **极简入口设计**：仅通过 `createConnection` 暴露核心功能\n2. **委托实现模式**：核心逻辑委托给 playwright-core\n3. **类型安全配置**：完整的 TypeScript 类型定义\n4. **自动化文档**：从源码自动生成 README\n5. **版本同步机制**：与 Playwright 主仓库保持同步\n6. **灵活部署**：支持环境变量、CLI 参数和编程式配置\n\n---\n\n<a id='page-tools-capabilities'></a>\n\n## MCP 工具与能力\n\n### 相关页面\n\n相关主题：[核心架构](#page-core-architecture), [初始状态配置](#page-initial-state)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/microsoft/playwright-mcp/blob/main/README.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- [index.js](https://github.com/microsoft/playwright-mcp/blob/main/index.js)\n</details>\n\n# MCP 工具与能力\n\n## 概述\n\nPlaywright MCP (Model Context Protocol) 是微软官方提供的 Playwright 工具集，为大语言模型 (LLM) 提供浏览器自动化能力。该项目通过 MCP 协议暴露一系列可调用的工具，使 AI Agent 能够执行网页导航、元素交互、网络监控、PDF 操作等浏览器自动化任务。\n\n根据 `config.d.ts` 中的定义，MCP 工具被组织为多个**能力域 (Capability)**，每个能力域包含一组相关的工具函数。资料来源：[config.d.ts:20-33]()\n\n## 架构概览\n\nPlaywright MCP 的源代码已迁移至 [Playwright 主仓库](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/mcp)，当前的 `playwright-mcp` 仓库作为依赖包装和分发层存在。资料来源：[CONTRIBUTING.md:1-10]()\n\n```mermaid\ngraph TD\n    A[LLM / AI Agent] -->|MCP Protocol| B[Playwright MCP Server]\n    B -->|工具调用| C[playwright-core]\n    C --> D[Browser Automation]\n    \n    E[CLI / Config] -->|配置| B\n    F[config.d.ts] -->|类型定义| E\n```\n\n## 能力域 (Tool Capabilities)\n\nPlaywright MCP 将工具划分为以下能力域，每个能力域对应不同的功能模块：\n\n| 能力域 | 说明 | 典型工具示例 |\n|--------|------|-------------|\n| `config` | 配置管理 | 服务端配置读取 |\n| `core` | 核心浏览器操作 | 导航、元素操作 |\n| `core-navigation` | 页面导航 | 打开 URL、前进/后退 |\n| `core-tabs` | 多标签页管理 | 创建/关闭标签页、切换 |\n| `core-input` | 输入处理 | 填写表单、键盘输入 |\n| `core-install` | 浏览器安装 | 安装浏览器驱动 |\n| `network` | 网络监控 | 请求拦截、响应捕获 |\n| `pdf` | PDF 生成 | 页面导出为 PDF |\n| `storage` | 存储管理 | Cookie、LocalStorage |\n| `testing` | 测试断言 | 元素存在性验证 |\n| `vision` | 视觉交互 | 坐标点击、截图 |\n| `devtools` | 开发者工具 | Chrome DevTools 协议 |\n\n资料来源：[config.d.ts:20-33]()\n\n## 配置选项详解\n\n### 基本配置结构\n\n```typescript\ntype Config = {\n  browser?: BrowserConfig;\n  capabilities?: ToolCapability[];\n  saveSession?: boolean;\n  sharedBrowserContext?: boolean;\n  secrets?: Record<string, string>;\n  outputDir?: string;\n  console?: ConsoleConfig;\n  network?: NetworkConfig;\n  testIdAttribute?: string;\n  timeouts?: TimeoutsConfig;\n  imageResponses?: 'allow' | 'omit' | 'auto';\n  snapshot?: SnapshotConfig;\n};\n```\n\n资料来源：[config.d.ts:36-120]()\n\n### 浏览器配置\n\n```typescript\nbrowser?: {\n  browserName?: 'chromium' | 'firefox' | 'webkit';\n  isolated?: boolean;\n  userDataDir?: string;\n  // ... launch options\n}\n```\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `browserName` | `chromium` \\| `firefox` \\| `webkit` | 指定使用的浏览器引擎 |\n| `isolated` | `boolean` | 是否保持浏览器配置文件在内存中，不写入磁盘 |\n| `userDataDir` | `string` | 浏览器用户数据目录路径，默认为临时目录 |\n\n### 超时配置\n\n```typescript\ntimeouts?: {\n  action?: number;      // 默认动作超时，默认 5000ms\n  navigation?: number;  // 默认导航超时，默认 60000ms\n  expect?: number;      // 默认断言超时，默认 5000ms\n}\n```\n\n资料来源：[config.d.ts:60-74]()\n\n### 网络安全配置\n\n```typescript\nnetwork?: {\n  allowedOrigins?: string[];   // 允许的请求来源\n  blockedOrigins?: string[];  // 阻止的请求来源\n}\n```\n\n**支持的格式：**\n\n| 格式 | 示例 | 匹配范围 |\n|------|------|----------|\n| 完整来源 | `https://example.com:8080` | 仅匹配该精确来源 |\n| 通配符端口 | `http://localhost:*` | localhost 上任意端口的 HTTP 请求 |\n\n资料来源：[config.d.ts:84-95]()\n\n### 控制台配置\n\n```typescript\nconsole?: {\n  level?: 'error' | 'warning' | 'info' | 'debug';\n}\n```\n\n| 级别 | 包含的消息 |\n|------|-----------|\n| `error` | 仅错误消息 |\n| `warning` | 错误 + 警告 |\n| `info` | 警告 + 信息（默认） |\n| `debug` | 所有消息 |\n\n### 图片响应配置\n\n```typescript\nimageResponses?: 'allow' | 'omit' | 'auto';\n```\n\n| 值 | 说明 |\n|----|------|\n| `allow` | 始终发送图片响应 |\n| `omit` | 从不发送图片响应 |\n| `auto` | 如果客户端能显示则发送（默认） |\n\n资料来源：[config.d.ts:76-79]()\n\n## MCP 工具生成机制\n\nREADME 文档中的工具列表通过 `update-readme.js` 脚本自动生成。脚本从编译后的模块加载工具信息，生成格式化的 Markdown 文档。资料来源：[update-readme.js:1-100]()\n\n```mermaid\ngraph LR\n    A[编译后的模块] -->|加载工具| B[update-readme.js]\n    B -->|生成 Markdown| C[README.md]\n    \n    D[cli.js --help] -->|CLI 选项| B\n    E[config.d.ts] -->|配置类型| B\n```\n\n### 工具描述格式\n\n每个工具在 README 中以折叠块形式展示：\n\n```markdown\n<details>\n<summary><b>能力域名称</b></summary>\n\n<!-- NOTE: This has been generated via update-readme.js -->\n\n- **tool_name**\n  - Title: 工具标题\n  - Description: 工具描述\n  - Parameters:\n    - `param_name` (type, optional): 参数描述\n  - Read-only: **true/false**\n```\n\n资料来源：[update-readme.js:170-190]()\n\n## 命令行接口\n\nMCP 服务通过 CLI 启动，支持以下操作模式：\n\n| 命令 | 说明 |\n|------|------|\n| `npm run ctest` | 仅在 Chromium 中运行测试 |\n| `npm run ftest` | 仅在 Firefox 中运行测试 |\n| `npm run wtest` | 仅在 WebKit 中运行测试 |\n| `npm run dtest` | 在 Docker 容器中运行 Chromium 测试 |\n| `npm run roll` | 更新 Playwright 版本 |\n\n资料来源：[package.json:14-24]()\n\n### CLI 入口点\n\nCLI 通过 `cli.js` 实现，集成了 `playwright-core` 的命令处理：\n\n```javascript\nconst { tools, libCli } = require('playwright-core/lib/coreBundle');\ntools.decorateMCPCommand(p, packageJSON.version);\n```\n\n特殊命令 `install-browser` 被映射为标准的 `playwright install`：\n\n```javascript\nif (process.argv.includes('install-browser')) {\n  const argv = process.argv.map(arg => arg === 'install-browser' ? 'install' : arg);\n  libCli.decorateProgram(program);\n}\n```\n\n资料来源：[cli.js:24-32]()\n\n## 核心入口点\n\nMCP 的主入口通过 `index.js` 导出 `createConnection` 函数：\n\n```javascript\nconst { tools } = require('playwright-core/lib/coreBundle');\nmodule.exports = { createConnection: tools.createConnection };\n```\n\n这使得其他 MCP 客户端能够通过标准的方式连接到 Playwright MCP 服务。资料来源：[index.js:26-27]()\n\n## 版本更新机制\n\n`roll.js` 脚本负责更新 Playwright 依赖版本：\n\n1. 从 Playwright 主仓库复制 `config.d.ts`\n2. 更新 `package.json` 中的 `playwright`、`playwright-core`、`@playwright/test` 版本\n3. 执行 `npm install` 安装新版本\n4. 运行 `npm run lint` 更新 README 文档\n\n```javascript\nfunction doRoll(version) {\n  updatePlaywrightVersion(version);\n  copyConfig();\n  execSync('npm run lint', { cwd: __dirname });\n}\n```\n\n资料来源：[roll.js:1-40]()\n\n## 会话管理\n\n| 配置项 | 说明 |\n|--------|------|\n| `saveSession` | 是否将会话保存到输出目录 |\n| `sharedBrowserContext` | 是否在所有 HTTP 客户端间共享浏览器上下文 |\n| `secrets` | 敏感信息替换映射，防止 LLM 意外暴露 |\n\n> **注意**：`secrets` 功能是便利性措施而非安全特性，客户端仍需自行审查传入和传出的数据。\n\n资料来源：[config.d.ts:96-107]()\n\n## 测试框架\n\n测试配置位于 `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资料来源：[playwright.config.ts:22-32]()\n\n## 总结\n\nPlaywright MCP 通过模块化的**能力域**设计，将浏览器自动化功能组织为可配置的逻辑单元。开发者可以通过 `config.d.ts` 中定义的类型精确配置所需功能，包括浏览器选择、超时策略、网络安全、存储管理等。这种设计使得 MCP 工具既保持了灵活性，又通过类型系统确保了配置的正确性。\n\n---\n\n<a id='page-browser-profiles'></a>\n\n## 浏览器配置文件管理\n\n### 相关页面\n\n相关主题：[初始状态配置](#page-initial-state), [核心架构](#page-core-architecture)\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- [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- [README.md](https://github.com/microsoft/playwright-mcp/blob/main/README.md)\n- [index.js](https://github.com/microsoft/playwright-mcp/blob/main/index.js)\n</details>\n\n# 浏览器配置文件管理\n\n## 概述\n\n浏览器配置文件管理是 Playwright MCP 的核心功能之一，允许用户通过配置对象自定义浏览器的启动行为、会话持久化方式以及浏览器上下文的安全策略。该模块通过 `config.d.ts` 中定义的 `Config` 类型提供类型安全的配置接口，支持多种浏览器引擎（Chromium、Firefox、WebKit）的灵活配置与管理。\n\nPlaywright MCP 的浏览器配置文件管理主要负责以下职责：\n\n| 职责 | 说明 |\n|------|------|\n| 浏览器选择 | 指定使用哪种浏览器引擎 |\n| 会话持久化 | 管理浏览器用户数据目录，支持会话恢复 |\n| 安全策略 | 控制浏览器请求的来源限制（允许/阻止的域名） |\n| 隔离模式 | 支持内存级浏览器配置文件，防止数据持久化 |\n| 启动参数 | 传递自定义浏览器启动选项 |\n\n资料来源：[config.d.ts:29-62]()\n\n## 配置结构\n\n### 顶级配置对象\n\nPlaywright MCP 的配置通过 `Config` 类型定义，核心结构如下：\n\n```typescript\nexport type Config = {\n  browser?: {\n    browserName?: 'chromium' | 'firefox' | 'webkit';\n    isolated?: boolean;\n    userDataDir?: string;\n    // 浏览器启动选项\n  };\n  // ... 其他配置项\n};\n```\n\n资料来源：[config.d.ts:35-45]()\n\n### 配置参数详解\n\n#### 浏览器配置（browser）\n\n浏览器配置对象包含以下可选参数：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `browserName` | `'chromium' \\| 'firefox' \\| 'webkit'` | `'chromium'` | 指定要使用的浏览器引擎 |\n| `isolated` | `boolean` | `undefined` | 是否在内存中运行浏览器，不保存配置文件到磁盘 |\n| `userDataDir` | `string` | `undefined` | 自定义浏览器用户数据目录路径 |\n\n```typescript\n// 浏览器配置示例\nconst config = {\n  browser: {\n    browserName: 'chromium',\n    isolated: true,\n    userDataDir: '/path/to/custom/profile'\n  }\n};\n```\n\n资料来源：[config.d.ts:35-62]()\n\n#### 起源安全策略（network）\n\n浏览器网络请求的安全策略通过 `network` 配置项管理：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `allowedOrigins` | `string[]` | 允许浏览器请求的来源列表，支持完整域名和通配符端口 |\n| `blockedOrigins` | `string[]` | 阻止浏览器请求的来源列表，同时匹配两个列表的请求将被阻止 |\n\n支持的来源格式：\n\n- **完整域名**：`https://example.com:8080` - 仅匹配该具体地址\n- **通配符端口**：`http://localhost:*` - 匹配 localhost 上任意端口的 HTTP 请求\n\n```typescript\nconst config = {\n  network: {\n    allowedOrigins: ['https://trusted-site.com'],\n    blockedOrigins: ['https://untrusted-site.com']\n  }\n};\n```\n\n资料来源：[config.d.ts:103-126]()\n\n#### 浏览器上下文配置（browserContext）\n\n用于配置浏览器的上下文级设置：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `screenSize` | `{ width: number, height: number }` | 浏览器视口尺寸 |\n| `timezoneId` | `string` | 浏览器的时区设置 |\n| `locale` | `string` | 浏览器的区域设置 |\n| `permissions` | `string[]` | 授予的浏览器权限列表 |\n| `viewport` | `{ width: number, height: number }` | 默认视口大小 |\n\n#### 测试标识属性（testIdAttribute）\n\n指定用于测试 ID 的 HTML 属性，默认值为 `\"data-testid\"`：\n\n```typescript\nconst config = {\n  testIdAttribute: 'data-testid'\n};\n```\n\n资料来源：[config.d.ts:71-77]()\n\n#### 超时配置（timeouts）\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `action` | `number` | `5000` | 操作超时时间（毫秒） |\n| `navigation` | `number` | `60000` | 导航超时时间（毫秒） |\n| `expect` | `number` | `5000` | 断言超时时间（毫秒） |\n\n```typescript\nconst config = {\n  timeouts: {\n    action: 5000,\n    navigation: 60000,\n    expect: 5000\n  }\n};\n```\n\n资料来源：[config.d.ts:79-94]()\n\n## 浏览器配置文件生命周期\n\n### 配置文件创建流程\n\n```mermaid\ngraph TD\n    A[配置对象创建] --> B{userDataDir 设置?}\n    B -->|是| C[使用指定目录]\n    B -->|否| D{isolated 为 true?}\n    D -->|是| E[创建临时内存目录]\n    D -->|否| F[创建临时持久化目录]\n    C --> G[浏览器启动]\n    E --> G\n    F --> G\n    G --> H[浏览器上下文创建]\n    H --> I[会话就绪]\n```\n\n### 会话持久化策略\n\nPlaywright MCP 支持三种会话持久化模式：\n\n| 模式 | `isolated` | `userDataDir` | 行为 |\n|------|------------|---------------|------|\n| 完全隔离 | `true` | 未设置 | 浏览器配置存储在内存中，进程结束后丢失 |\n| 临时持久化 | `false` | 未设置 | 临时目录存储配置，进程结束后自动清理 |\n| 自定义持久化 | 任意 | 已设置 | 使用指定目录存储配置，可跨会话复用 |\n\n```typescript\n// 完全隔离模式示例\nconst isolatedConfig = {\n  browser: {\n    browserName: 'chromium',\n    isolated: true\n  }\n};\n\n// 跨会话复用配置示例\nconst persistentConfig = {\n  browser: {\n    browserName: 'chromium',\n    userDataDir: '/path/to/persistent/profile'\n  }\n};\n```\n\n资料来源：[config.d.ts:35-56]()\n\n## 架构集成\n\n### 组件关系图\n\n```mermaid\ngraph TD\n    subgraph \"MCP 服务器层\"\n        A[index.js - createConnection]\n        B[cli.js - 命令行解析]\n    end\n    \n    subgraph \"配置管理层\"\n        C[config.d.ts - 类型定义]\n        D[Config 验证器]\n    end\n    \n    subgraph \"Playwright 核心\"\n        E[playwright-core]\n        F[浏览器引擎]\n    end\n    \n    A --> B\n    B --> D\n    C --> D\n    D --> E\n    E --> F\n    \n    style C fill:#e1f5fe\n    style F fill:#fff3e0\n```\n\n### 配置文件加载流程\n\n```mermaid\nsequenceDiagram\n    participant CLI as 命令行接口\n    participant Config as 配置加载器\n    participant Playwright as Playwright Core\n    participant Browser as 浏览器引擎\n\n    CLI->>Config: 解析用户配置\n    Config->>Config: 验证配置类型\n    Config->>Playwright: 传递配置参数\n    Playwright->>Browser: 初始化浏览器\n    Browser-->>Playwright: 浏览器实例\n    Playwright-->>Config: 会话就绪\n    Config-->>CLI: MCP 服务启动\n```\n\n资料来源：[index.js:1-28]()\n\n## 工具能力与浏览器配置\n\n浏览器配置文件管理与 MCP 工具能力紧密集成，支持通过 `capabilities` 配置启用或禁用特定功能：\n\n| 能力标识 | 说明 | 默认状态 |\n|----------|------|----------|\n| `core` | 核心浏览器操作 | 默认启用 |\n| `core-navigation` | 页面导航功能 | 默认启用 |\n| `core-tabs` | 多标签页管理 | 默认启用 |\n| `core-input` | 输入操作 | 默认启用 |\n| `core-install` | 浏览器安装 | 默认启用 |\n| `network` | 网络请求拦截 | 需显式启用 |\n| `pdf` | PDF 生成 | 需显式启用 |\n| `storage` | 存储管理 | 需显式启用 |\n| `testing` | 测试断言 | 需显式启用 |\n| `vision` | 视觉交互 | 需显式启用 |\n| `devtools` | 开发者工具 | 需显式启用 |\n\n```typescript\nconst config = {\n  browser: {\n    browserName: 'chromium'\n  },\n  capabilities: ['core', 'network', 'pdf']\n};\n```\n\n资料来源：[config.d.ts:28-32]()\n\n## 使用示例\n\n### 基础配置\n\n```typescript\nimport { createConnection } from '@playwright/mcp';\n\nconst server = createConnection({\n  browser: {\n    browserName: 'chromium'\n  }\n});\n```\n\n### 高级配置\n\n```typescript\nimport { createConnection } from '@playwright/mcp';\n\nconst server = createConnection({\n  browser: {\n    browserName: 'firefox',\n    isolated: false,\n    userDataDir: '/home/user/.playwright-profiles/firefox',\n  },\n  network: {\n    allowedOrigins: ['https://example.com'],\n    blockedOrigins: ['https://ads.example.com']\n  },\n  timeouts: {\n    action: 10000,\n    navigation: 120000\n  },\n  testIdAttribute: 'data-testid',\n  outputDir: '/tmp/playwright-output'\n});\n```\n\n资料来源：[config.d.ts:35-140]()\n\n### 命令行配置\n\nPlaywright MCP 通过 `cli.js` 提供命令行接口，支持通过命令行参数配置浏览器行为：\n\n```bash\n# 使用指定浏览器\nnpx playwright-mcp --browser=chromium\n\n# 安装浏览器\nnpx playwright-mcp install-browser\n\n# 查看帮助\nnpx playwright-mcp --help\n```\n\n资料来源：[cli.js:1-31]()\n\n## 相关源码文件索引\n\n| 文件路径 | 作用 |\n|----------|------|\n| `config.d.ts` | 配置类型定义，包含所有浏览器配置接口 |\n| `index.js` | MCP 连接入口，导出 `createConnection` |\n| `cli.js` | 命令行工具，处理用户输入和参数解析 |\n| `playwright.config.ts` | 测试框架配置，用于项目内部测试 |\n| `package.json` | 包元数据，定义 MCP 服务名称和版本 |\n\n## 配置验证\n\nPlaywright MCP 在启动时会验证配置对象的有效性。配置验证主要包括：\n\n1. **类型检查**：确保所有配置项符合 TypeScript 类型定义\n2. **值域验证**：检查枚举值（如浏览器类型）是否有效\n3. **路径验证**：验证 `userDataDir` 等路径是否存在或可创建\n\n配置验证失败时，MCP 服务器将抛出类型错误并拒绝启动，确保用户能够及时发现配置问题。\n\n资料来源：[config.d.ts:1-140]()\n\n---\n\n<a id='page-initial-state'></a>\n\n## 初始状态配置\n\n### 相关页面\n\n相关主题：[浏览器配置文件管理](#page-browser-profiles), [MCP 工具与能力](#page-tools-capabilities)\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- [package.json](https://github.com/microsoft/playwright-mcp/blob/main/package.json)\n- [update-readme.js](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)\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- [CONTRIBUTING.md](https://github.com/microsoft/playwright-mcp/blob/main/CONTRIBUTING.md)\n</details>\n\n# 初始状态配置\n\n## 概述\n\n初始状态配置（Initial State Configuration）是指 Playwright MCP Server 启动时的各项运行时参数与选项。这些配置项决定了浏览器的启动方式、会话管理策略、网络安全策略、超时行为等核心功能。配置文件采用 TypeScript 类型定义，统一存放在 `config.d.ts` 中，并通过 CLI 参数、环境变量或编程方式传递给服务端。\n\n## 配置架构\n\n```mermaid\ngraph TD\n    A[Playwright MCP Server] --> B[配置加载层]\n    B --> C[CLI 参数]\n    B --> D[环境变量]\n    B --> E[配置文件]\n    \n    C --> F[配置合并与验证]\n    D --> F\n    E --> F\n    \n    F --> G[Config 对象]\n    \n    G --> H[browser 配置]\n    G --> I[capabilities 配置]\n    G --> J[network 配置]\n    G --> K[timeouts 配置]\n    G --> L[其他选项]\n    \n    H --> M[Playwright Browser]\n    I --> N[可用工具集]\n    J --> O[网络请求过滤]\n    K --> P[超时策略]\n```\n\n## 核心配置项\n\n### 浏览器配置\n\n浏览器配置通过 `browser` 字段定义，控制浏览器实例的创建与生命周期管理。\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `browserName` | `'chromium' \\| 'firefox' \\| 'webkit'` | - | 指定使用的浏览器类型 |\n| `isolated` | `boolean` | `true` | 是否将浏览器配置文件保存在内存中，不写入磁盘 |\n| `userDataDir` | `string` | 临时目录 | 浏览器用户数据目录的路径，用于持久化浏览器状态 |\n\n**isolated 模式说明**：`isolated` 为 `true` 时，浏览器配置不会保存到磁盘，所有会话数据存储在内存中，浏览器关闭后自动清除。设置为 `false` 并配合 `userDataDir` 可实现浏览器状态的持久化保存。\n\n### 能力配置\n\n`capabilities` 数组定义了 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| 能力标识 | 说明 | 必需 |\n|----------|------|------|\n| `core` | 核心功能 | 默认启用 |\n| `core-navigation` | 页面导航功能 | 可选 |\n| `core-tabs` | 多标签页管理 | 可选 |\n| `core-input` | 输入处理功能 | 可选 |\n| `core-install` | 浏览器安装功能 | 可选 |\n| `network` | 网络请求拦截与修改 | 可选 |\n| `pdf` | PDF 生成功能 | 可选 |\n| `storage` | 存储管理功能 | 可选 |\n| `testing` | 测试断言功能 | 可选 |\n| `vision` | 视觉识别功能 | 可选 |\n| `devtools` | 开发者工具集成 | 可选 |\n\n## 网络安全配置\n\n`network` 字段用于控制浏览器可访问的网络来源，实现请求来源的白名单与黑名单管理。\n\n```typescript\nnetwork?: {\n  allowedOrigins?: string[];\n  blockedOrigins?: string[];\n};\n```\n\n### 支持的格式\n\n| 格式类型 | 示例 | 匹配范围 |\n|----------|------|----------|\n| 完整 origin | `https://example.com:8080` | 仅匹配该特定地址 |\n| 协议通配符 | `http://localhost:*` | localhost 任意端口的 HTTP 请求 |\n\n**匹配优先级**：当某个 origin 同时匹配 `allowedOrigins` 和 `blockedOrigins` 时，该请求将被**阻止**。\n\n## 超时配置\n\n`timeouts` 对象定义了各类操作的默认超时时间。\n\n```typescript\ntimeouts?: {\n  action?: number;      // 默认: 5000ms\n  navigation?: number; // 默认: 60000ms\n  expect?: number;      // 默认: 5000ms\n};\n```\n\n| 配置项 | 默认值 | 说明 | 相关文档 |\n|--------|--------|------|----------|\n| `action` | 5000ms | 默认操作超时 | [page.setDefaultTimeout](https://playwright.dev/docs/api/class-page#page-set-default-timeout) |\n| `navigation` | 60000ms | 默认导航超时 | [page.setDefaultNavigationTimeout](https://playwright.dev/docs/api/class-page#page-set-default-navigation-timeout) |\n| `expect` | 5000ms | 默认断言超时 | [test timeouts](https://playwright.dev/docs/test-timeouts#expect-timeout) |\n\n## 会话与上下文管理\n\n### 会话保存\n\n| 配置项 | 类型 | 说明 |\n|--------|------|------|\n| `saveSession` | `boolean` | 是否将 Playwright 会话保存到输出目录 |\n\n### 浏览器上下文共享\n\n| 配置项 | 类型 | 说明 |\n|--------|------|------|\n| `sharedBrowserContext` | `boolean` | 是否在所有连接的 HTTP 客户端之间重用同一个浏览器上下文 |\n\n## 安全配置\n\n### 密钥管理\n\n```typescript\nsecrets?: Record<string, string>;\n```\n\n`secrets` 用于替换工具响应中的匹配明文文本，防止 LLM 意外获取敏感数据。\n\n> 注意：这是便利性功能而非安全特性，客户端仍需始终检查传入和来自工具的信息。\n\n### 图片响应控制\n\n```typescript\nimageResponses?: 'allow' | 'omit' | 'auto';\n```\n\n| 值 | 说明 |\n|----|------|\n| `allow` | 始终发送图片响应 |\n| `omit` | 始终省略图片响应 |\n| `auto` | 如果客户端能显示图片则发送（默认行为） |\n\n## 其他配置项\n\n### 测试 ID 属性\n\n```typescript\ntestIdAttribute?: string;\n```\n\n指定用于测试 ID 的属性，默认为 `data-testid`。\n\n### 输出目录\n\n```typescript\noutputDir?: string;\n```\n\n保存输出文件的目录路径。\n\n### 控制台日志级别\n\n```typescript\nconsole?: {\n  level?: 'error' | 'warning' | 'info' | 'debug';\n};\n```\n\n每种级别包含更严重级别的消息：`debug` < `info` < `warning` < `error`。\n\n## 配置传递方式\n\nPlaywright MCP 支持多种配置传递方式：\n\n### 1. CLI 参数\n\n通过命令行启动时传递参数：\n\n```bash\nnpx playwright-mcp --browser-name=chromium --output-dir=/tmp/pw-output\n```\n\n### 2. 环境变量\n\n每个 CLI 参数都有对应的环境变量：\n\n| CLI 参数前缀 | 环境变量前缀 |\n|--------------|--------------|\n| `--browser-name` | `PLAYWRIGHT_MCP_BROWSER_NAME` |\n| `--output-dir` | `PLAYWRIGHT_MCP_OUTPUT_DIR` |\n| `--secrets` | `PLAYWRIGHT_MCP_SECRETS_FILE` |\n\n环境变量通过 `update-readme.js` 脚本自动从 CLI 定义生成。资料来源：[update-readme.js:62-67](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)\n\n### 3. 编程配置\n\n通过 `Config` 类型定义配置对象：\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  timeouts: {\n    action: 10000,\n    navigation: 30000\n  }\n};\n```\n\n## 配置类型定义\n\n完整的 `Config` 类型定义如下：\n\n```typescript\nexport type Config = {\n  browser?: {\n    browserName?: 'chromium' | 'firefox' | 'webkit';\n    isolated?: boolean;\n    userDataDir?: string;\n    // ... 其他启动选项\n  };\n  capabilities?: ToolCapability[];\n  saveSession?: boolean;\n  sharedBrowserContext?: boolean;\n  secrets?: Record<string, string>;\n  outputDir?: string;\n  console?: {\n    level?: 'error' | 'warning' | 'info' | 'debug';\n  };\n  network?: {\n    allowedOrigins?: string[];\n    blockedOrigins?: string[];\n  };\n  testIdAttribute?: string;\n  timeouts?: {\n    action?: number;\n    navigation?: number;\n    expect?: number;\n  };\n  imageResponses?: 'allow' | 'omit' | 'auto';\n  snapshot?: /* Snapshot 配置 */;\n};\n```\n\n资料来源：[config.d.ts:1-100](https://github.com/microsoft/playwright-mcp/blob/main/config.d.ts)\n\n## 测试配置\n\n对于测试场景，Playwright MCP 使用独立的 `playwright.config.ts` 配置文件：\n\n```typescript\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:1-30](https://github.com/microsoft/playwright-mcp/blob/main/playwright.config.ts)\n\n## 配置验证流程\n\n```mermaid\ngraph LR\n    A[输入配置] --> B[类型检查]\n    B --> C{合法?}\n    C -->|是| D[应用配置]\n    C -->|否| E[抛出错误]\n    \n    D --> F[浏览器启动]\n    D --> G[工具注册]\n    D --> H[网络策略应用]\n    D --> I[超时设置]\n```\n\n## 最佳实践\n\n1. **隔离环境**：使用 `isolated: true` 避免浏览器状态污染\n2. **超时设置**：根据网络环境调整 `timeouts` 数值\n3. **网络安全**：生产环境应明确设置 `allowedOrigins` 白名单\n4. **密钥保护**：通过 `secrets` 配置敏感信息，避免硬编码\n5. **能力精简**：仅启用必需的 `capabilities`，减少攻击面\n\n---\n\n<a id='page-security-config'></a>\n\n## 安全与网络配置\n\n### 相关页面\n\n相关主题：[MCP 工具与能力](#page-tools-capabilities), [部署选项](#page-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- [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- [update-readme.js](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)\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</details>\n\n# 安全与网络配置\n\nPlaywright MCP 提供了全面的安全与网络配置功能，允许用户精细控制浏览器的网络请求、敏感信息处理以及浏览器实例的安全策略。本文档详细介绍这些配置选项的用途、使用方法和最佳实践。\n\n## 概述\n\nPlaywright MCP 是一个为 MCP（Model Context Protocol）协议提供 Playwright 工具的项目。它允许 AI 助手通过标准化的接口控制浏览器执行各种自动化任务，包括导航、点击、输入、网络请求拦截等操作。资料来源：[package.json:1-10]()\n\n为了确保在自动化浏览器操作过程中的安全性，项目提供了多层次的安全配置机制：\n\n- **网络请求控制**：通过 `allowedOrigins` 和 `blockedOrigins` 白名单/黑名单机制\n- **敏感信息保护**：通过 `secrets` 配置实现敏感数据的自动替换\n- **浏览器隔离**：通过 `browser.isolated` 等选项控制浏览器实例的生命周期\n\n资料来源：[config.d.ts:1-150]()\n\n## 网络配置\n\n### 源地址过滤\n\nPlaywright MCP 提供了精细的网络请求控制功能，允许管理员指定允许或阻止的请求源地址。\n\n#### allowedOrigins（允许的源地址）\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| 类型 | `string[]` | 允许浏览器请求的源地址列表 |\n| 默认值 | 全部允许 | 若未配置，默认允许所有源地址的请求 |\n\n支持的匹配格式：\n\n| 格式 | 示例 | 匹配范围 |\n|------|------|----------|\n| 完整源地址 | `https://example.com:8080` | 仅匹配指定协议、域名和端口的请求 |\n| 通配符端口 | `http://localhost:*` | 匹配 localhost 上任意端口的 HTTP 请求 |\n\n当请求同时匹配 `allowedOrigins` 和 `blockedOrigins` 时，该请求将被阻止。\n\n资料来源：[config.d.ts:50-75]()\n\n#### blockedOrigins（阻止的源地址）\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| 类型 | `string[]` | 阻止浏览器请求的源地址列表 |\n| 默认值 | 空数组 | 若未配置，默认不阻止任何源地址 |\n\n```mermaid\ngraph TD\n    A[浏览器发起请求] --> B{检查 blockedOrigins}\n    B -->|匹配黑名单| C[阻止请求]\n    B -->|未匹配黑名单| D{检查 allowedOrigins}\n    D -->|已配置且匹配| E[允许请求]\n    D -->|已配置但未匹配| C\n    D -->|未配置| E\n```\n\n**配置示例**：\n\n```typescript\n{\n  network: {\n    // 允许所有本地开发服务器\n    allowedOrigins: [\n      'http://localhost:3000',\n      'http://localhost:8080',\n      'http://127.0.0.1:*'\n    ],\n    // 阻止所有外部 API 请求\n    blockedOrigins: [\n      'https://api.external-service.com'\n    ]\n  }\n}\n```\n\n资料来源：[config.d.ts:60-90]()\n\n### 网络配置结构\n\n完整的网络配置类型定义如下：\n\n```typescript\nnetwork?: {\n  allowedOrigins?: string[];\n  blockedOrigins?: string[];\n};\n```\n\n## 浏览器配置与安全隔离\n\n### 浏览器实例选项\n\nPlaywright MCP 支持配置浏览器实例的各项参数，以满足不同的安全需求。\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `browser.browserName` | `'chromium' \\| 'firefox' \\| 'webkit'` | `'chromium'` | 指定使用的浏览器类型 |\n| `browser.isolated` | `boolean` | `true` | 浏览器配置文件是否仅保留在内存中，不写入磁盘 |\n| `browser.userDataDir` | `string` | 系统临时目录 | 浏览器配置文件的存储路径 |\n\n#### 隔离模式（isolated）\n\n启用隔离模式后，浏览器不会将任何持久化数据（如 Cookie、缓存、本地存储）写入磁盘。这对于安全性要求较高的自动化场景特别有用。\n\n```typescript\n{\n  browser: {\n    browserName: 'chromium',\n    isolated: true  // 启用内存隔离模式\n  }\n}\n```\n\n资料来源：[config.d.ts:30-55]()\n\n### 用户数据目录管理\n\n通过 `userDataDir` 可以自定义浏览器配置文件的存储位置。默认情况下，系统会创建临时目录存储浏览器数据。\n\n| 模式 | userDataDir | 行为 |\n|------|-------------|------|\n| 临时模式 | 未指定 | 创建临时目录，测试结束后自动清理 |\n| 持久模式 | 指定路径 | 使用指定目录，可在多次运行间保持浏览器状态 |\n\n资料来源：[config.d.ts:35-45]()\n\n## 敏感信息安全\n\n### Secrets 配置\n\nPlaywright MCP 提供了 `secrets` 配置选项，用于在工具响应中自动替换敏感信息，防止大语言模型意外获取敏感数据。\n\n> **重要提示**：secrets 功能是便利性功能而非安全特性。它主要用于防止 LLM 意外泄露敏感数据，但不应将其视为真正的安全加密手段。请确保始终对客户端传入的信息进行仔细检查。\n\n资料来源：[config.d.ts:110-120]()\n\n#### Secrets 配置结构\n\n```typescript\nsecrets?: Record<string, string>;\n```\n\n#### 使用方式\n\n```typescript\n{\n  secrets: {\n    // key: 要替换的敏感值\n    // value: 替换后的显示值\n    'my-api-key-12345': '[REDACTED]',\n    'Bearer token_xyz': '[REDACTED]'\n  }\n}\n```\n\n#### 替换机制\n\n当工具响应中包含匹配 `secrets` 中定义的键值时，对应的敏感信息会被替换为预设的显示值：\n\n```mermaid\ngraph LR\n    A[工具响应生成] --> B{检查 secrets 配置}\n    B -->|发现敏感信息| C[替换为预设值]\n    B -->|无敏感信息| D[保持原样]\n    C --> E[返回处理后的响应]\n    D --> E\n```\n\n资料来源：[update-readme.js:80-95]()\n\n### Console 日志级别控制\n\n通过 `console.level` 配置可以控制返回给客户端的日志消息级别：\n\n| 级别 | 包含消息 | 使用场景 |\n|------|----------|----------|\n| `error` | 仅错误信息 | 生产环境，减少数据量 |\n| `warning` | 错误 + 警告 | 标准生产环境 |\n| `info` | 警告 + 信息 | 开发调试 |\n| `debug` | 所有消息 | 详细调试 |\n\n```typescript\n{\n  console: {\n    level: 'info'  // 默认值\n  }\n}\n```\n\n资料来源：[config.d.ts:125-135]()\n\n## 配置选项参考\n\n### 完整配置类型定义\n\n```typescript\nexport type Config = {\n  browser?: {\n    browserName?: 'chromium' | 'firefox' | 'webkit';\n    isolated?: boolean;\n    userDataDir?: string;\n    launchOptions?: Record<string, any>;\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' | 'auto';\n  snapshot?: Record<string, any>;\n};\n```\n\n资料来源：[config.d.ts:95-145]()\n\n### CLI 环境变量映射\n\nCLI 选项与环境变量的映射关系：\n\n| CLI 选项 | 环境变量 | 说明 |\n|----------|----------|------|\n| `--secrets` | `PLAYWRIGHT_MCP_SECRETS_FILE` | secrets 文件路径 |\n| `--browser` | `PLAYWRIGHT_MCP_BROWSER` | 浏览器类型 |\n| `--output-dir` | `PLAYWRIGHT_MCP_OUTPUT_DIR` | 输出目录 |\n| 其他选项 | `PLAYWRIGHT_MCP_<OPTION>` | 通用前缀映射 |\n\n资料来源：[update-readme.js:60-80]()\n\n## 安全最佳实践\n\n### 开发环境配置\n\n```typescript\n// 开发环境配置示例\n{\n  browser: {\n    browserName: 'chromium',\n    isolated: false  // 开发环境可复用浏览器状态\n  },\n  network: {\n    allowedOrigins: ['http://localhost:*'],\n    blockedOrigins: ['https://production-api.example.com']\n  },\n  console: {\n    level: 'debug'\n  }\n}\n```\n\n### 生产环境配置\n\n```typescript\n// 生产环境配置示例\n{\n  browser: {\n    browserName: 'chromium',\n    isolated: true  // 生产环境启用隔离\n  },\n  network: {\n    allowedOrigins: [\n      'https://app.example.com',\n      'https://cdn.example.com'\n    ],\n    blockedOrigins: ['*']\n  },\n  secrets: {\n    'api-key-xxx': '[REDACTED]',\n    'session-token': '[REDACTED]'\n  },\n  console: {\n    level: 'error'  // 仅返回错误信息\n  }\n}\n```\n\n### 安全检查清单\n\n在部署 Playwright MCP 之前，建议检查以下安全配置：\n\n| 检查项 | 推荐配置 | 说明 |\n|--------|----------|------|\n| 浏览器隔离 | `isolated: true` | 防止数据持久化泄露 |\n| 网络白名单 | 配置明确的 allowedOrigins | 限制仅访问必要的域 |\n| 敏感信息 | 配置 secrets | 防止 LLM 意外获取敏感数据 |\n| Console 日志 | 生产环境使用 `error` 级别 | 减少敏感信息泄露风险 |\n| 临时文件 | 使用默认临时目录 | 避免在持久化存储中遗留数据 |\n\n## 安全漏洞报告\n\n微软对软件产品的安全性非常重视，包括所有通过 GitHub 组织管理的源代码仓库。\n\n### 报告流程\n\n**请勿通过公开的 GitHub Issues 报告安全漏洞。**\n\n应按照以下方式向 Microsoft Security Response Center (MSRC) 报告：\n\n1. 访问：[https://msrc.microsoft.com/create-report](https://aka.ms/security.md/msrc/create-report)\n2. 或发送邮件至：[secure@microsoft.com](mailto:secure@microsoft.com)\n3. 如可能，请使用 PGP 密钥加密消息（可从 Microsoft Security Response Center PGP Key 页面下载）\n\n通常情况下，您将在 24 小时内收到回复。\n\n资料来源：[SECURITY.md:1-30]()\n\n### 报告内容建议\n\n在报告时，请尽可能提供以下信息以帮助我们更好地理解和处理问题：\n\n- 问题类型\n- 完整的产品路径\n- 受影响的组件\n- 复现步骤\n- 建议的修复方案（可选）\n\n## 相关文档\n\n| 文档 | 说明 |\n|------|------|\n| [配置参考](./config.md) | 完整的配置选项详细说明 |\n| [工具列表](./tools.md) | 可用工具及其参数说明 |\n| [CLI 使用指南](./cli.md) | 命令行工具使用方法 |\n| [测试指南](../tests/mcp) | 测试用例编写规范 |\n\n## 贡献指南\n\n如果发现安全相关问题或希望为项目贡献代码，请注意以下事项：\n\n1. **问题优先**：在提交 PR 之前，请先提交或查找相关的问题（issue）\n2. **提交规范**：提交信息应遵循语义化提交规范（Semantic Commit Messages）\n3. **分支命名**：问题修复的分支命名格式为 `fix-<issue-number>`\n\n资料来源：[CONTRIBUTING.md:1-50]()\n\n```bash\n# 创建修复分支示例\ngit checkout -b fix-39562\n\n# 提交修复\ngit commit -m \"fix(proxy): handle SOCKS proxy authentication\"\n```\n\n资料来源：[CLAUDE.md:1-40]()\n\n---\n\n<a id='page-deployment'></a>\n\n## 部署选项\n\n### 相关页面\n\n相关主题：[快速入门](#page-quickstart)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\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- [Dockerfile](https://github.com/microsoft/playwright-mcp/blob/main/Dockerfile)\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- [update-readme.js](https://github.com/microsoft/playwright-mcp/blob/main/update-readme.js)\n</details>\n\n# 部署选项\n\nPlaywright MCP 提供了多种部署方式，以适应不同的使用场景和环境需求。本页面详细介绍如何通过 Node.js 环境、Docker 容器以及 CLI 命令行工具等方式部署和运行 Playwright MCP。\n\n## 概述\n\nPlaywright MCP 是一个基于 Model Context Protocol (MCP) 的浏览器自动化工具，它将 Playwright 的强大功能封装为一组 MCP 工具，供 AI 代理和自动化系统使用。部署选项的设计目标是为开发者提供灵活的选择，无论是本地开发、测试环境还是生产环境，都能找到合适的部署方式。\n\n根据 package.json 中的配置，Playwright MCP 需要 Node.js 18 或更高版本运行环境，并通过 npm 进行包管理 资料来源：[package.json:8]()\n\n## Node.js 环境部署\n\n### 环境要求\n\n| 组件 | 最低版本 | 说明 |\n|------|----------|------|\n| Node.js | >= 18 | JavaScript 运行时环境 |\n| npm | 内置 | Node.js 包管理器 |\n| Playwright 浏览器 | 自动安装 | 通过 `npx playwright install` 安装 |\n\n### 安装步骤\n\n在 Node.js 环境中部署 Playwright MCP 的标准流程如下：\n\n```bash\n# 克隆仓库\ngit clone https://github.com/microsoft/playwright-mcp\ncd playwright-mcp\n\n# 安装依赖\nnpm ci\n\n# 安装浏览器（Chromium、Firefox、WebKit）\nnpx playwright install\n```\n\n### 运行 MCP 服务器\n\nPlaywright MCP 提供了两种运行模式：通过 CLI 直接运行或作为模块导入使用。\n\n#### CLI 模式\n\n直接使用 CLI 运行 MCP 服务器：\n\n```bash\n# 查看可用选项\nnpm run lint\n\n# 运行测试\nnpm test\n\n# 仅运行 Chromium 测试\nnpm run ctest\n```\n\n#### 模块导入模式\n\n在 JavaScript 或 TypeScript 项目中作为模块使用：\n\n```javascript\nconst { createConnection } = require('@playwright/mcp');\n// 或 ESM\nimport { createConnection } from '@playwright/mcp';\n```\n\n资料来源：[index.js:25]()\n\n### MCP 测试配置\n\n在 playwright.config.ts 中，测试配置支持多种运行方式：\n\n```typescript\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:20-30]()\n\n## Docker 容器部署\n\nDocker 部署提供了一致的运行环境，特别适合 CI/CD 场景和需要隔离环境的开发团队。\n\n### Dockerfile 构建\n\nPlaywright MCP 提供了预配置的 Dockerfile 用于构建容器镜像：\n\n```bash\n# 构建镜像\nnpm run docker-build\n\n# 运行容器\nnpm run docker-run\n```\n\n手动构建命令：\n\n```bash\ndocker build --no-cache -t playwright-mcp-dev:latest .\n```\n\n### 容器运行参数\n\n| 参数 | 说明 |\n|------|------|\n| `-it` | 交互式终端模式 |\n| `-p 8080:8080` | 端口映射（主机:容器） |\n| `--name playwright-mcp-dev` | 容器命名 |\n| `playwright-mcp-dev:latest` | 镜像名称 |\n\n### Docker 测试模式\n\n在 Docker 环境中运行测试需要设置特定的环境变量：\n\n```bash\n# 在 Docker 中运行 Chromium 测试\nnpm run dtest\n```\n\n内部实现使用 `MCP_IN_DOCKER=1` 环境变量触发特殊配置：\n\n```bash\nMCP_IN_DOCKER=1 playwright test --project=chromium-docker\n```\n\nplaywright.config.ts 中 Docker 测试配置：\n\n```typescript\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资料来源：[playwright.config.ts:21-27]()\n\n### 容器生命周期管理\n\n```bash\n# 构建镜像\nnpm run docker-build\n\n# 运行容器\nnpm run docker-run\n\n# 停止并删除容器\nnpm run docker-rm\n```\n\n资料来源：[package.json:15-17]()\n\n## CLI 命令行工具\n\n### CLI 入口点\n\nCLI 通过 cli.js 实现，基于 commander.js 构建：\n\n```javascript\nconst { program } = require('playwright-core/lib/utilsBundle');\nconst { tools, libCli } = require('playwright-core/lib/coreBundle');\n```\n\n资料来源：[cli.js:15-16]()\n\n### install-browser 命令\n\nCLI 支持通过 `install-browser` 别名安装浏览器：\n\n```bash\nnpx playwright-mcp install-browser\n# 或\nnode cli.js install-browser\n```\n\n内部实现将 `install-browser` 转换为 `install` 命令：\n\n```javascript\nif (process.argv.includes('install-browser')) {\n  const argv = process.argv.map(arg => arg === 'install-browser' ? 'install' : arg);\n  libCli.decorateProgram(program);\n  void program.parseAsync(argv);\n  return;\n}\n```\n\n资料来源：[cli.js:12-18]()\n\n### MCP 命令装饰\n\nCLI 使用 Playwright Core 的 MCP 工具装饰功能：\n\n```javascript\nconst packageJSON = require('./package.json');\nconst p = program.version('Version ' + packageJSON.version).name('Playwright MCP');\ntools.decorateMCPCommand(p, packageJSON.version);\n```\n\n资料来源：[cli.js:21-24]()\n\n## 配置选项\n\n### 配置类型定义\n\nPlaywright MCP 的配置通过 TypeScript 类型定义在 config.d.ts 中，支持多种配置选项。\n\n资料来源：[config.d.ts:1-100]()\n\n### 浏览器配置\n\n| 选项 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `browser.browserName` | `chromium \\| firefox \\| webkit` | - | 指定浏览器类型 |\n| `browser.isolated` | `boolean` | - | 保持浏览器配置在内存中，不保存到磁盘 |\n| `browser.userDataDir` | `string` | - | 浏览器配置持久化目录 |\n\n### 超时配置\n\n```typescript\ntimeouts?: {\n  action?: number;      // 默认操作超时，默认 5000ms\n  navigation?: number; // 默认导航超时，默认 60000ms\n  expect?: number;     // 默认 expect 超时，默认 5000ms\n};\n```\n\n### 来源控制配置\n\nPlaywright MCP 支持细粒度的来源控制：\n\n| 选项 | 说明 |\n|------|------|\n| `allowedOrigins` | 允许浏览器请求的来源列表 |\n| `blockedOrigins` | 阻止浏览器请求的来源列表 |\n\n支持的格式：\n- 完整来源：`https://example.com:8080` - 仅匹配该来源\n- 通配符端口：`http://localhost:*` - 匹配 localhost 上任意端口的 HTTP 请求\n\n### 图像响应配置\n\n```typescript\nimageResponses?: 'allow' | 'omit' | 'auto';\n// 默认值为 \"auto\"，如果客户端可以显示则发送图像\n```\n\n### 测试 ID 属性\n\n```typescript\ntestIdAttribute?: string;\n// 指定用于测试 ID 的属性，默认为 \"data-testid\"\n```\n\n### 快照配置\n\n```typescript\nsnapshot?: {\n  // 快照相关配置选项\n};\n```\n\n## 功能模块与部署关系\n\n### 可用功能模块\n\nPlaywright MCP 将工具按功能模块组织，不同的模块可能需要不同的部署配置：\n\n| 模块标识 | 功能描述 | 部署要求 |\n|----------|----------|----------|\n| `config` | 配置管理 | 基础部署 |\n| `core` | 核心功能 | 基础部署 |\n| `core-navigation` | 导航操作 | 浏览器实例 |\n| `core-tabs` | 标签页管理 | 浏览器实例 |\n| `core-input` | 输入处理 | 浏览器实例 |\n| `core-install` | 安装功能 | 系统依赖 |\n| `network` | 网络请求 | 浏览器实例 |\n| `pdf` | PDF 生成 | 浏览器实例 |\n| `storage` | 存储管理 | 浏览器实例 |\n| `testing` | 测试断言 | Playwright Test |\n| `vision` | 视觉功能 | 浏览器实例 |\n| `devtools` | 开发者工具 | 浏览器实例 |\n\nOpt-in 模块可通过 `--caps` 参数启用：\n\n```bash\n--caps=network,pdf,storage\n```\n\n资料来源：[config.d.ts:13-28]()\n\n## 部署架构图\n\n```mermaid\ngraph TD\n    A[开发者环境] --> B[Node.js 部署]\n    A --> C[Docker 容器部署]\n    A --> D[CLI 工具部署]\n    \n    B --> B1[直接运行]\n    B --> B2[模块导入]\n    \n    C --> C1[容器构建]\n    C --> C2[容器运行]\n    C --> C3[测试模式]\n    \n    D --> D1[install-browser]\n    D --> D2[MCP 命令]\n    \n    B1 --> E[playwright-core]\n    B2 --> E\n    C2 --> E\n    E --> F[浏览器实例]\n    \n    F --> G[Chromium]\n    F --> H[Firefox]\n    F --> I[WebKit]\n```\n\n## 环境变量\n\n| 环境变量 | 说明 | 使用场景 |\n|----------|------|----------|\n| `MCP_IN_DOCKER` | 标记运行在 Docker 环境中 | Docker 测试 |\n| `CI` | 标记 CI 环境 | 持续集成 |\n| `PRINT_ENV` | 打印环境变量配置 | 调试 |\n\n## 最佳实践\n\n### 开发环境\n\n- 使用 `npm ci` 安装依赖确保构建一致性\n- 本地运行 `npx playwright install` 安装所需浏览器\n- 使用 `npm run ctest` 快速验证 Chromium 功能\n\n### CI/CD 环境\n\n- 优先使用 Docker 容器确保环境一致性\n- 设置 `CI=true` 以启用严格的测试模式\n- 使用 `npm test` 运行完整测试套件\n\n### 生产环境\n\n- 考虑使用 `browser.isolated` 选项提高安全性\n- 根据需求配置 `allowedOrigins` 和 `blockedOrigins`\n- 设置合适的 `timeouts` 值避免长时间等待\n\n## 故障排查\n\n### 常见问题\n\n| 问题 | 解决方案 |\n|------|----------|\n| 浏览器未安装 | 运行 `npx playwright install` |\n| 端口冲突 | 修改 `-p` 参数使用其他端口 |\n| 权限错误 | 确保 Docker 有足够的系统权限 |\n| 超时错误 | 调整 config 中的 `timeouts` 配置 |\n\n### 诊断命令\n\n```bash\n# 检查 Node.js 版本\nnode --version\n\n# 检查 Playwright 安装\nnpx playwright --version\n\n# 查看 CLI 帮助\nnode cli.js --help\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. page-introduction：Playwright MCP 简介。围绕“Playwright MCP 简介”模拟一次用户任务，不展示安装或运行结果。\n2. page-quickstart：快速入门。围绕“快速入门”模拟一次用户任务，不展示安装或运行结果。\n3. page-client-integration：客户端集成指南。围绕“客户端集成指南”模拟一次用户任务，不展示安装或运行结果。\n4. page-core-architecture：核心架构。围绕“核心架构”模拟一次用户任务，不展示安装或运行结果。\n5. page-tools-capabilities：MCP 工具与能力。围绕“MCP 工具与能力”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“Playwright MCP 简介”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-quickstart\n输入：用户提供的“快速入门”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-client-integration\n输入：用户提供的“客户端集成指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-core-architecture\n输入：用户提供的“核心架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-tools-capabilities\n输入：用户提供的“MCP 工具与能力”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“Playwright MCP 简介”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-quickstart：Step 2 必须围绕“快速入门”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-client-integration：Step 3 必须围绕“客户端集成指南”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-core-architecture：Step 4 必须围绕“核心架构”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-tools-capabilities：Step 5 必须围绕“MCP 工具与能力”形成一个小中间产物，并等待用户确认。\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.js\n- index.d.ts\n- cli.js\n- config.d.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"
}