Playwright MCP 使用归档：让 AI IDE 看懂 API 文档与流程图

面向所有带 AI 对话 / Agent 能力的代码编辑器（Copilot、Cursor‌等VS Code + 各类插件、自研 Agent IDE 等）。

用本地 Playwright MCP 驱动真实浏览器，让 AI“代劳”访问内部系统、外部 API 文档、动态页面、登录受限资源。

---

我们到底在做什么？

你将：

1. 在本地启动一个 Playwright MCP 服务（Model Context Protocol）。
2. 在支持 MCP / 自定义工具的 AI 代码编辑器里注册这个服务。
3. 用一句提示词，调起真实浏览器：打开链接 →（如需）登录 → 抓取页面 → 结构化返回。
4. 将 API 文档、错误码、参数表、动态加载内容迅速沉淀。

自然语言驱动浏览器，就像让一个“可编程爬虫”实时听你指挥，但不写一行脚本。

---

TL;DR（超短跑通版）

# 1. 安装
npm install -g @playwright/mcp
npx playwright install# 2. 启动本地 MCP（每次使用前都要重新开）
npx @playwright/mcp@latest --port 8931# 3. 查本机局域网 IP(本地IDE不用执行该步骤)
ipconfig     # Windows
ifconfig     # macOS/Linux 或：ip addr# 4. 在你的 AI 编辑器里添加配置（示例 JSON, 如果本地IDE配置 http://127.0.0.1:8931/mcp 即可）
{"mcpServers": {"playwright": {"type": "streamableHttp","url": "http://<你的局域网IP>:8931/mcp"}}
}# 5. 对话区输入（示例提示词）
使用playwright工具，获取这个页面的API文档信息，<https://example.com/api/docs>

保持浏览器开启直到 AI 说“完成”。

如果页面需要登录：先暂停自动执行 → 手动登录 → 再继续指令。

---

背后理念

需求	传统方式	现在方式
抓内部 API 文档	手写脚本 / 复制粘贴	对话一句触发 Playwright 会话
动态 Tab / 懒加载	复杂选择器 & 等待	自然语言“滚动到底/点击错误码 Tab”
登录态页面	爬虫经常被拦	浏览器里人机协作
输出结构化	解析 HTML	让 AI 自行拆字段、补描述
扩展新动作	改脚本	增加提示词策略

---

环境准备

项	要求
Node.js	18+
操作系统	Windows / macOS / Linux
网络	能被你的编辑器访问到本机端口（某些内网区域可能受限；如你的组织限制特定区域网络，需先确认）
浏览器依赖	npx playwright install 会自动装 Chromium/Firefox/WebKit

---

安装与启动

1. 全局安装 MCP 包

   npm install -g @playwright/mcp

2. 安装浏览器运行时

   npx playwright install

3. 启动服务（建议前台运行以观察日志）

   npx @playwright/mcp@latest --port 8931

4. 记录本机 IP（例如 10.23.45.67）。

5. 在 AI 编辑器（支持 MCP / 自定义工具 / 插桩）中，添加配置：
   每次重连网络可能换 IP → 需更新 url。

   {"mcpServers": {"playwright": {"type": "streamableHttp","url": "<http://10.23.45.67:8931/mcp>"}}
   }

---

首次使用流程（详细心智模型）

1. 启动 MCP 服务。

2. 配置编辑器侧工具（成功后能看到工具列表中出现“playwright”或你设定的名字）。

3. 在 AI 对话输入：

   使用playwright工具，获取这个页面的API文档信息，<https://internal.portal/api/docs>

4. 弹出浏览器 → 如出现登录页：

   • 暂停自动执行（如果编辑器有“AUTO”开关）。
   • 手动完成 4A / SSO / MFA。
   • 回到对话输入：已登录，继续。

5. AI 给出初步抓取（可能是原始文本）。

6. 补一句：

   请将刚才抓取的接口转成 JSON，字段：name, method, path, authRequired, requestParams[{name,type,required,description}], responseFields[{name,type,description}], errors[{code,message,httpStatus,solution}]

7. 得到结构化结果 → 保存 / 比对 / 入库。

---

高质量提示词攻略

目的	提示词样例
基础抓取	使用playwright工具，获取这个页面的API文档信息，{url}
精准结构化	使用playwright工具，提取所有接口：接口名、方法、路径、请求参数（含类型/是否必填/描述）、响应字段、错误码列表，页面：{url}
多 Tab 遍历	使用playwright工具，依次点击页面所有可见Tab，抓取每个Tab内的API列表，并按Tab标题分组返回
懒加载滚动	使用playwright工具，向下滚动直到不再出现新接口项，再抓取完整列表
错误码专抓	使用playwright工具，只抓取并返回本页错误码表，含：错误码、HTTP状态、说明、可能原因、处理建议，页面：{url}
版本差异	使用playwright工具，分别抓取 {url_old} 与 {url_new} 的API列表，并比较新增/删除/修改的接口路径与字段变化
指定 Tab	使用playwright工具，点击“错误码”Tab，再抓取其表格内容并结构化输出

---

连续对话范式（示例）

你：使用playwright工具，获取这个页面的API文档信息，<https://example.com/api/docs>
AI：已打开页面，需要登录
你：（浏览器完成登录后）已登录，继续
AI：返回原始接口块
你：请结构化为JSON，字段：name, method, path, requestParams[…], responseFields[…], errors[…]
AI：返回 JSON
你：再抓取“错误码”Tab
AI：返回错误码表
你：将接口与错误码整合成一个最终 JSON
AI：输出完成

---

结构化输出模板参考

{"apis": [{"name": "获取用户详情","method": "GET","path": "/v1/users/{id}","authRequired": true,"requestParams": [{"name": "id", "type": "string", "required": true, "description": "用户ID"}],"responseFields": [{"name": "id", "type": "string", "description": "用户ID"},{"name": "nickname", "type": "string", "description": "昵称"}],"errors": [{"code": "USER_NOT_FOUND", "message": "用户不存在", "httpStatus": 404, "solution": "确认ID正确"}]}],"errorCodes": [{"code": "INVALID_TOKEN", "httpStatus": 401, "message": "认证失败", "solution": "刷新令牌"}]
}

---

进阶玩法

场景	技巧
多链接批处理	按顺序逐条提示，或让 AI 在一次对话里循环访问（若工具支持批任务）。
差异监控	每周定时跑新旧链接 → 让 AI 输出 diff。
错误码守护	单独抓错误码区块 → 存历史文件 → 自动对比新增异常。
文档再发布	让 AI 输出 Markdown/API 手册+目录。
模型训练集	结构化 JSON → 转 QA 对话对。
混合源	外部开源 API + 内部私有 API 整合归档。

---

安全与合规

风险点	说明	建议
未授权抓取	内部系统可能有合规边界	先获批再执行
登录敏感信息	Cookie / Token 存本地浏览器	不分享截图；抓完退出登录
输出含隐私字段	用户数据/密钥	让 AI 匿名化 / 脱敏
地域网络限制	某些内网分区不通	换可达网络 / VPN
浏览器误关	会话丢失	完成前别关；需要重启再发指令

---

故障排查矩阵

症状	可能原因	处理
工具调用失败	IP 变更 / 端口占用	重新查 IP，确认端口空闲
无返回	浏览器被关闭	重启服务重新调用
登录循环	会话未完成/MFA	浏览器里全流程点完再继续
内容缺失	懒加载未触发	增补指令：滚动到底
Tab 数据空	没点击 Tab	明确提示“点击 XXX Tab”
错误码缺字段	表格多列折叠	放大窗口/提示展开列
中文乱码	编码渲染问题	让 AI 重新基于 UTF-8 解析文本

---

终端自检脚本（快速确认服务可用）

PORT=8931
npx @playwright/mcp@latest --port $PORT & \\
echo "Launching MCP on $PORT"; sleep 2; \\
curl -s "<http://127.0.0.1>:$PORT/mcp" >/dev/null \\
&& echo "✅ MCP endpoint reachable" \\
|| echo "❌ MCP endpoint unreachable"

---

快速产出资产（执行清单）

目标	行动
初次验证	抓一个外部公开 API 文档
内部接入	登录内网 4A 后抓主要接口页
结构化	让 AI 输出统一 JSON 模板
归档	写入 apis/<date>.json
差异化	对比上一版本 JSON
自动化	固定提示词清单放入团队知识库

---

提示词收藏（复制即用）

使用playwright工具，向下滚动直到接口列表不再新增，然后抓取所有接口信息并结构化输出（字段：name, method, path, requestParams, responseFields, errors），页面：{url}

使用playwright工具，依次点击页面所有Tab，抓取每个Tab内的API文档，并按Tab名称分组返回JSON，页面：{url}

使用playwright工具，分别抓取 {url_old} 与 {url_new} 的API参数定义，生成 diff：新增/删除/修改，标注字段级变化。

---

总结

你已经拥有：

• 一个无需手写爬虫的动态文档采集通道
• 支持登录态、多 Tab、懒加载、差异分析
• 可随意塑形的结构化输出（JSON / Markdown / 报告）
• 人机协同（AI 负责抓 + 解析，你负责策略 + 审核）
• 产品文档中html格式（非图片）的流程图逻辑它也可以采集，然后剩下的就交给AI来读懂😎