关键词

网页调试AI辅助测试DOM检查浏览器自动化Playwright

项目简介

Web Inspector MCP 赋予大语言模型（LLM）“视觉超能力”，使其能够“看到”、调试和测试任何网页。该服务器利用强大的 Playwright 库，为 AI 助手提供深度理解网页结构、调试元素可见性、验证布局、检查 DOM 以及执行各种浏览器操作的工具，从而简化 AI 辅助的网页开发、测试和内容抓取任务。

主要功能点

  • 深度 DOM 检查: 逐步检查 DOM 结构，发现父子关系、居中问题、间距等，并跳过非语义的包裹层，优先展示语义化元素和带有测试 ID 的元素。
  • 布局调试与约束追踪: 上溯 DOM 树，分析宽度限制、边距、边框和溢出裁剪的来源。
  • 元素对齐比较: 精确比较两个元素的对齐和尺寸，快速发现布局不一致问题。
  • 详细可见性诊断: 检查元素是否对用户可见，并提供详细原因（如视口内外、被覆盖、需要滚动、CSS 属性导致隐藏等）。
  • CSS 样式检查: 获取元素的计算 CSS 属性，理解样式行为。
  • 选择器测试与发现: 测试 CSS 选择器有效性，获取匹配元素的信息；通过文本内容查找元素，或发现页面上所有可用的测试 ID。
  • 浏览器交互: 支持页面导航、点击、填充表单、拖拽、键盘操作、文件上传等多种用户交互。
  • 网络请求与控制台日志: 列表并查看 HTTP 请求详情，获取并过滤浏览器控制台日志，辅助 API 和前端错误调试。
  • 会话持久化: 自动保存浏览器会话数据（如 Cookies、LocalStorage），无需重复登录即可进行多步操作或测试认证功能。
  • 屏幕截图: 捕获页面或元素的视觉截图，用于人工审查或视觉回归测试。

安装步骤

Web Inspector MCP 服务器通常由 AI 编码助手自动安装。您无需手动执行复杂操作，只需在 AI 工具中进行配置。

如果您需要手动安装以实现更快的启动速度，可以通过 npm 全局安装：

npm install -g mcp-web-inspector

服务器配置 (MCP 客户端使用)

MCP 客户端需要配置服务器的启动命令及其参数。以下是 MCP 客户端配置 Web Inspector MCP 服务器的通用信息，请根据您使用的 AI 工具在其配置中添加相应条目。

常用配置格式：

{
  "mcpServers": {
    "web-inspector": {
      "command": "npx",
      "args": ["-y", "mcp-web-inspector"]
    }
  }
}
  • 'server name' (名称): 'web-inspector' (您在 AI 助手中使用该服务器时调用的名称)
  • 'command' (命令): 'npx' (一个 Node.js 包执行器，用于运行本地或远程包)
  • 'args' (参数): '["-y", "mcp-web-inspector"]' (运行 'mcp-web-inspector' 包，'-y' 表示自动确认安装 Playwright 浏览器等依赖)

可用参数：

  • '--no-save-session': 禁用自动会话持久化，每次启动浏览器都是全新状态，不会保留 Cookies 或 LocalStorage。
  • '--user-data-dir <path>': 指定浏览器会话数据的存储目录，默认在当前工作目录的 './.mcp-web-inspector' 文件夹下。
  • '--headless': 默认以无头模式运行浏览器（无可见的浏览器窗口），适用于自动化和 CI/CD 环境。

例如，配置为无头模式并禁用会话持久化：

{
  "mcpServers": {
    "web-inspector": {
      "command": "npx",
      "args": ["-y", "mcp-web-inspector", "--headless", "--no-save-session"]
    }
  }
}

请将上述 JSON 片段添加到您的 AI 工具对应的 MCP 配置文件中。 具体配置文件的位置请参考您 AI 工具的文档（例如，对于 'Claude Code (CLI)'，修改 '~/.config/claude/mcp.json'；对于 'VS Code with GitHub Copilot'，通过 VS Code Settings (JSON) 编辑 'mcp.json'）。

基本使用方法

安装并配置完成后，您的 AI 助手将能够识别并调用 "web-inspector" 服务器提供的工具。您可以在与 AI 助手的对话中直接提及或使用这些工具来完成网页相关的任务。

例如：

  1. 导航到指定网页:
    • AI 提示: "Navigate to 'https://example.com'"
    • AI 助手将自动调用 'navigate({ url: "https://example.com" })' 工具。
  2. 检查主内容区的 DOM 结构:
    • AI 提示: "Inspect the DOM of the main content area."
    • AI 助手可能会调用 'inspect_dom({ selector: 'main' })'。
  3. 点击页面上的按钮:
    • AI 提示: "Click the 'Submit' button."
    • AI 助手可能会调用 'click({ selector: 'testid:submit-button' })' 或通过 'find_by_text({ text: 'Submit' })' 定位后再调用 'click'。
  4. 填写表单字段:
    • AI 提示: "Fill the username field with 'testuser'."
    • AI 助手可能会调用 'fill({ selector: 'testid:username-input', value: 'testuser' })'。
  5. 调试元素不可见问题:
    • AI 提示: "Why isn't the 'Add to Cart' button visible?"
    • AI 助手可能会调用 'check_visibility({ selector: 'text=Add to Cart' })' 来获取诊断信息。

在使用过程中，请根据 AI 助手的提示，提供必要的参数和上下文信息。AI 助手会根据您的请求智能选择并执行最合适的工具。

信息

分类

开发者工具

访问项目