Web检查器MCP🔍

赋予LLM查看、调试和测试任何网页的视觉超能力。

一种模型上下文协议（MCP）服务器，提供全面的web检查和调试功能。它基于Playwright构建，使AI助手能够深入了解网页结构，调试元素可见性问题，验证布局，并在真实的浏览器环境中检查DOM。

为什么选择Web检查器MCP？

现代web应用程序很复杂。元素被隐藏，布局中断，选择器失败，调试感觉就像侦探工作。 Web检查器MCP 为您的AI助手提供以下工具：

🔍 了解任何页面结构 -渐进式DOM检查，通过遍历包装器div来查找语义元素
🎯 调试可见性问题 -详细的诊断显示了点击失败的确切原因（剪切、覆盖、滚动到视图之外）
🔼 跟踪布局约束 -沿着DOM树向上走，找到意外的边距、宽度限制和溢出剪裁的来源
📐 验证布局 -比较元素位置以确保对齐和间距一致
🧪 测试选择器可靠性 -在编写测试之前查看所有匹配元素及其可见性状态
🎨 检查样式 -获取计算CSS以了解元素行为异常的原因
📝 查找没有ID的元素 -当测试ID不可用时，按文本内容查找元素

完美适合

QA工程师 -调试失败的自动化测试，了解选择器中断的原因
前端开发人员 -调查跨浏览器的布局问题和CSS问题
测试自动化 -在编写测试之前，构建健壮的选择器并验证页面结构
可访问性审计 -检查ARIA角色、语义HTML和元素可见性
网络爬虫 -了解页面结构并找到正确的数据提取选择器

安装

无需手动安装！ 您的AI编码助手将通过以下方式自动安装服务器 npx 当配置时。

如果您更喜欢全局安装以加快启动速度：

npm install -g mcp-web-inspector

______________________________________________________________________

AI工具设置

以下所有配置均使用 npx 其自动下载并运行最新版本。单击展开AI工具的安装说明：

🚀 Codex CLI

通过CLI安装

# Add the server globally
codex mcp add web-inspector -- npx -y mcp-web-inspector

# Verify it was registered
codex mcp list

手动配置

Codex将MCP服务器定义存储在 ~/.codex/config.toml.在下面添加（或创建）条目 [mcp.servers] 表：

[mcp.servers.web-inspector]
command = "npx"
args = ["-y", "mcp-web-inspector"]

重新启动Codex CLI以确保新服务器在未来的会话中可用。

🤖 Claude Code (CLI)

通过CLI安装

# Add MCP server using Claude Code CLI
claude mcp add web-inspector --scope user -- npx -y mcp-web-inspector

# Verify installation
claude mcp list

手动配置

编辑 ~/.config/claude/mcp.json （Linux/macOS）或 %APPDATA%\Claude\mcp.json （Windows）：

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

安装后，重新启动Claude Code以加载服务器。

💻 Claude Desktop

配置文件位置

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

添加到配置

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

保存配置后重新启动Claude Desktop。

🔷 VS Code with GitHub Copilot

先决条件

VS代码版本1.101或更高版本
已安装GitHub Copilot扩展

通过CLI安装

# VS Code Stable
code --add-mcp '{"name":"web-inspector","command":"npx","args":["-y","mcp-web-inspector"]}'

# VS Code Insiders
code-insiders --add-mcp '{"name":"web-inspector","command":"npx","args":["-y","mcp-web-inspector"]}'

手动配置

打开VS代码设置（JSON）
将MCP服务器配置添加到 mcp.json:

{
  "servers": {
    "web-inspector": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-web-inspector"]
    }
  }
}

在VS代码中启用MCP

打开VS代码设置（UI）
搜索“MCP”
启用 聊天>MCP 选项
MCP仅适用于 代理模式 -在聊天界面中切换到代理模式
打开 mcp.json 文件并单击 “开始” 服务器旁边的按钮

首次浏览器设置

当您首次使用服务器时 npx，Playwright浏览器将 自动安装 如果还没有，请在第一次使用工具时使用。安装一次，浏览器存储在您的主目录中，在所有项目中共享。

如果自动安装不起作用（防火墙、权限等），您将看到清晰的运行说明：

npx playwright install chromium firefox webkit

然后重新启动VS Code以使用服务器。

关于嵌入式浏览器的说明

GitHub Copilot和VS Code可能具有嵌入式浏览器功能。如果您遇到冲突或更喜欢对所有Web检查任务使用Web Inspector MCP，您可能需要禁用内置浏览器：

打开VS代码设置
搜索“浏览器预览”或“简单浏览器”
如果需要，禁用相关的浏览器相关扩展

Web Inspector MCP提供了比嵌入式浏览器更强大的检查功能。

🎯 Cursor

配置文件位置

MacOS/Linux: ~/.cursor/mcp.json 或检查Cursor的设置目录
视窗: %APPDATA%\Cursor\mcp.json

添加到配置

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

步骤

打开光标设置（Cmd/Ctrl+，）
搜索“MCP”设置
编辑MCP配置文件
添加web检查器服务器配置
重新启动游标
验证MCP面板中的服务器是否可用

🌊 Windsurf

配置

Windsurf使用与Claude Desktop相同的配置格式。您可以直接复制您的Claude Desktop配置！

配置文件：检查Windsurf的设置以获取确切的路径（通常在应用程序数据目录中）

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

步骤

打开Windsurf设置
导航到MCP配置
添加web检查器服务器
重新启动Windsurf
在工具面板中验证服务器可用性

Windsurf很好地处理了MCP工具——配置很简单！

🔧 Cline (VS Code Extension)

先决条件

安装了Cline扩展的VS代码
系统上已安装Node.js

配置

在VS Code中打开Cline的设置
找到MCP配置部分
添加服务器配置：

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

重新启动VS Code或重新加载Cline扩展
Web检查器MCP工具将在Cline的工具面板中提供

⚙️ Other MCP-Compatible Tools

大多数MCP兼容工具使用类似的配置格式。寻找：

MCP设置或配置文件
服务器/工具配置部分
添加标准配置：

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

CLI优先助手，如GitHub Copilot CLI、Copylot CLI、Continue CLI和其他新兴的AI程序员遵循相同的模式——要么运行 mcp add 命令与 npx -y mcp-web-inspector 或者将上面的代码段放入他们的MCP配置文件中。

如果您的工具支持MCP，但未在此处列出，请参阅其文档以获取确切的配置文件位置。

______________________________________________________________________

命令行选项

使用命令行标志自定义服务器行为：

--no-save-session -禁用自动会话持久性（每次从新的浏览器状态开始）
**`--user-data-dir

** -会话数据的自定义目录（默认： ./.mcp-web-inspector`)

--headless -默认情况下以无头模式运行浏览器（无可见窗口）
--expose-sensitive-network-data -放宽对敏感网络标头的编辑（例如，显示截断的auth/cookie值）。出于安全考虑，默认禁用。

示例用法：

{
  "mcpServers": {
    "web-inspector": {
      "command": "npx",
      "args": ["-y", "mcp-web-inspector", "--user-data-dir", "./my-sessions"]
    }
  }
}

在无头模式下运行以实现自动化/CI：

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

组合多个标志：

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

______________________________________________________________________

会话持久性和数据存储

默认情况下，浏览器会话数据和屏幕截图会自动保存并组织在 ./.mcp-web-inspector/:

.mcp-web-inspector/
  ├── user-data/       # Browser sessions (cookies, localStorage, sessionStorage)
  └── screenshots/     # Screenshot files

运作原理

会话数据在浏览器重新启动后仍然存在
截图保存到截图目录
浏览器在会话之间保持登录状态
开箱即用-只需导航即可保存数据

好处

✅ 无需每次重新登录即可测试经过身份验证的功能
✅ 跨会话维护购物车状态
✅ 保留用户偏好和设置
✅ 高效调试登录用户工作流

禁用会话持久性

如果您希望浏览器每次都重新启动（没有持久状态），请使用 --no-save-session 标志：

克劳德代码CLI：

claude mcp add web-inspector --scope user -- npx -y mcp-web-inspector --no-save-session

克劳德桌面/风帆/克莱恩：

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

光标：

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

清除数据

要清除所有已保存的数据（会话和屏幕截图）：

rm -rf ./.mcp-web-inspector

要仅清除会话或屏幕截图，请执行以下操作：

rm -rf ./.mcp-web-inspector/user-data      # Clear sessions only
rm -rf ./.mcp-web-inspector/screenshots    # Clear screenshots only

安全最佳实践

⚠️ 重要：添加 .mcp-web-inspector/ 给你的 .gitignore 文件以防止提交：

浏览器会话数据（Cookie、本地存储、会话存储）
保存的屏幕截图（可能包含敏感信息）
身份验证令牌和凭据

添加到您的 .gitignore:

# MCP Web Inspector data
.mcp-web-inspector/

为什么这很重要：

会话数据包含Cookie和身份验证令牌
屏幕截图可能会捕获敏感的用户数据
提交此数据可能会将凭据泄漏到您的存储库
会话文件可能很大，会使您的git历史记录膨胀

最佳实践：

默认为可见浏览器 (headless: false)用于交互式调试
使用 headless: true 专门用于自动化和CI/CD环境
测试敏感应用程序后清除会话数据
使用 --no-save-session 在共享/公共站点上测试时标记

______________________________________________________________________

核心工具

检查

`inspect_dom`

🔍 主要检查工具-从这里开始布局调试：渐进式DOM检查，显示父子关系、居中问题、间距间隙和可滚动容器。跳过包装器div，只显示语义元素（header、nav、main、form、button、具有测试ID的元素、ARIA角色等）。

工作流：在没有选择器的情况下调用页面概览，然后通过使用孩子的选择器进行调用来深入查看。

检测：可滚动容器（显示“可滚动”↕️ 当scrollHeight>clientHeight时为36px），父级相对位置，垂直/水平居中，兄弟间距间隙，布局模式。

输出格式：

[0] 
    @ (16,8) 40×40px                         ← Absolute viewport position (x,y) and size
    from edges: ←16px →1144px ↑8px ↓8px      ← Distance from parent edges (↑8px = ↓8px means vertically centered)
    "Menu"
    ✓ visible, ⚡ interactive

[1] 

    @ (260,2) 131×28px
    from edges: ←244px →244px ↑2px ↓42px     ← Equal left/right (244px) = horizontally centered, unequal top/bottom = NOT vertically centered
    gap from [0]: →16px                      ← Spacing between siblings
    "Title"
    ✓ visible, 2 children

符号：✓=可见，✗=隐藏，⚡=交互式，←→=水平边缘，↑↓=垂直边缘，↕️=垂直滚动，↔️=横向滚动居中：相等的左/右距离=水平居中，相等的上/下距离=垂直居中滚动检测：自动检测可滚动容器并显示溢出量（例如，“可滚动”↕️ 397px”表示397px的隐藏内容）。不需要使用evaluate（）来比较scrollHeight/clientHeight。

相关工具：要比较两个元素的对齐（不是父子对齐），请使用compare.element_aligent（）。对于框模型（填充/边距），使用measure_element（）。

⚠️ 在结构分析方面比get_html（）或evaluate（）更有效。使用BEFORE可视化工具（截图）或evaluate（）。支持testid快捷方式。

注意：下拉菜单、列表框、对话框和弹出窗口（尤其是在react-aria/headless UI/Radix中）通常被移植到document.body中——当组合框或菜单打开时，在根级别进行查询（例如。 [role="listbox"], [role="dialog"])而不是在触发器的子树内。

参数：

- 选择器（字符串，可选）：CSS选择器、文本选择器或用于检查的testid简写。省略页面概述（默认为正文）。使用“testid:登录表单”、“#main”等。 - includeHidden（布尔值，可选）：在结果中包含隐藏元素（默认值：false） - maxChildren（数字，可选）：要显示的最大儿童数（默认值：20） - maxDepth（number，可选）：查找语义子元素时钻取非语义包装器元素的最大深度（默认值：5）。对于嵌套极深的组件，增加，减少到1，只看到直接的子组件，而不进行钻孔。

输出格式：

- 当有多个匹配项（与所选索引）时，可选的选择标头。 - 对于每个列出的元素： - 带有最佳标识符的索引标签（testid/ID/classes）。 - 位置线：@（x，y）宽×高px。 - 从边缘：左/右/上/下距离；中心提示。 - 与\[prev\]的差距：适用时兄弟姐妹之间的间距。 - 引号内的文本片段（已修剪）。 - 状态：✓ 可见/✗ 隐藏，⚡ 互动，N个孩子。 - 可滚动标记↕️/↔️ 检测到溢出量时。

示例：

inspect_dom（｛｝）

inspect_dom（{选择器：'testid:menu'}）

inspect_dom（{选择器：'#content'，最大子项：10}）

示例输出（inspect_dom（｛｝））：

[0] 
    @ (0,0) 1280×64px
    from edges: ←0px →0px ↑0px ↓1216px
    "My App"
    ✓ visible, 3 children

[1] 
    @ (0,64) 1280×640px
    from edges: ←0px →0px ↑64px ↓512px
    "Welcome back"
    ✓ visible, 5 children, scrollable ↕️ 320px

示例输出（inspect_dom（{选择器：“testid:menu”}）：

[0] 
    @ (16,8) 40×40px
    from edges: ←16px →1224px ↑8px ↓16px
    "Menu"
    ✓ visible, ⚡ interactive

`inspect_ancestors`

调试布局约束：沿DOM树向上走，找到宽度约束、边距、边框和溢出剪裁的来源。为每个祖先显示：位置/大小、宽度约束（w、max-w、min-w）、带方向箭头的边距（↑↓←→格式）、填充、显示类型、边框（如果不均匀，则为方向）、溢出(🔒=隐藏，↕️=滚动）、flexbox上下文（flex方向对齐项目间隙）、网格上下文（cols行间隙）、设置时的位置/z-index/变换。通过自动边距和标记剪切点自动检测水平居中(🎯). 对于调试意外的居中、受限宽度或剪切内容至关重要。默认值：10个祖先（到达在大多数React应用程序中），最大值：15。使用after inspect_dom（）来理解父布局约束。

参数：

- 选择器（字符串，必填）：CSS选择器或元素起始的testid简写（例如，'testid:header'，'#main'） - limit（number，可选）：要遍历的最大祖先数（默认值：10，最大值：15）。增加深度嵌套组件框架。

输出格式：

- 当选择器匹配多个元素时，显示所选元素索引的标题。 - 对于每个祖先（从目标开始）： - \[i\] |testid：。..或课程 - @（x，y）宽×高px - 内联摘要：w，显示（如果不是块），m/p，最大w，最小w - Flexbox/Grid上下文（方向、间隙、网格模板） - 带箭头的边距细分（↑↓←→）和居中诊断 - 设置时的边框细节（如果不均匀，则为方向性） - 溢出状态：🔒 隐藏，↕️/↔️ 滚动+溢出量 - 额外：非默认时的位置/z-index/变换 - 诊断：🎯 剪裁点/可滚动容器/宽度约束

示例：

inspect_ancestors（{选择器：'testid:提交按钮'）

inspect_ancestors（{选择器：'#content'，限制：15}）

示例输出（inspect_ancestors（{选择器：'testid:提交按钮'}）：

Selected: testid:submit-button (1 of 2 matches)

Ancestor Chain:

[0]  | testid:submit-button
    @ (860,540) 120x40px | w:120px display:inline-block
    margin: ↑0px →0px ↓0px ←0px
    border: 1px solid rgb(0, 122, 255)
    ⚠ none

[1] 
 | form-actions
    @ (800,520) 240x80px | w:240px display:flex m:0px p:16px gap:8px
    flex: row, justify:center, align:center, gap:8px
    margin: →auto ←auto ← Horizontally centered (likely margin:0 auto)
    border: none
    overflow: 🔒 hidden
    🎯 CLIPPING POINT - May clip overflowing children

[2]  | #login-form
    @ (640,200) 560x480px | w:560px max-w:600px
    position:relative
    🎯 WIDTH CONSTRAINT

`compare_element_alignment`

比较两个元素：在一次通话中获得全面的对齐和维度比较。显示边缘对齐（顶部、左侧、右侧、底部）、中心对齐（水平、垂直）和尺寸（宽度、高度）。非常适合调试“这些标头对齐了吗？或者这些面板匹配吗？'.返回所有对齐信息✓/✗ 符号和像素差异。对于父子居中，请改用inspect_dom（）（自动显示子对象是否居中于父对象）。比使用手动getBoundingClientRect（）计算evaluate（）更有效。

参数：

- selector1（字符串，必填）：CSS选择器、文本选择器或第一个元素的testid简写（例如，'testid:main-header'、'#header'） - selector2（字符串，必填）：CSS选择器、文本选择器或第二个元素的testid简写（例如，'testid:chatheader'、'#secondary header'）

输出格式：

- 选择器匹配多个元素时的可选警告（使用第一个可见；建议添加唯一的数据testid）。 - 标题：对齐方式：对比 - 两行显示每个元素的位置和大小：@（x，y）w×h px - 边缘块：顶部/左侧/右侧/底部✓/✗ 和差异 - 中心块：水平/垂直中心对齐✓/✗ 和差异 - 尺寸块：宽度/高度与✓/✗ 和差异 - 检测到大偏差时运行inspect_ancestors（…）的可选提示

示例：

compare.element_aligation（{选择器1:“testid:标题”，选择器2:“testid:subtitle”}）

compare.element_aligation（{选择器1:“#左面板”，选择器2:“#右面板”}）

示例输出（compare.element_aligation（{选择器1:“#左面板”，选择器2:“#右面板”}）：

Alignment: 
 vs 

  #left-panel: @ (80,120) 320×600px
  #right-panel: @ (440,120) 320×600px

Edges:
  Top:    ✓ aligned (both @ 120px)
  Left:   ✗ not aligned (80px vs 440px, diff: 360px)
  Right:  ✗ not aligned (400px vs 760px, diff: 360px)
  Bottom: ✓ aligned (both @ 720px)

Centers:
  Horizontal: ✗ not aligned (240px vs 600px, diff: 360px)
  Vertical:   ✓ aligned (both @ 420px)

Dimensions:
  Width:  ✓ same (320px)
  Height: ✓ same (600px)

`get_computed_styles`

检查CSS属性：获取特定属性（显示、位置、宽度等）的计算CSS值。当您需要原始CSS值或measure_element（）未显示的特定属性时使用。返回按类别（布局、可见性、间距、排版）分组的样式。对于长方体模型可视化（填充/边距），请改用measure_element（）。

参数：

- 选择器（字符串，必填）：CSS选择器、文本选择器或testid简写（例如，'testid:submit button'、'#main'） - properties（字符串，可选）：以逗号分隔的要检索的CSS属性列表（例如，“display，width，color”）。如果未指定，则返回常见的布局属性：显示、位置、宽度、高度、不透明度、可见性、z-index、溢出、边距、填充、字体大小、字体粗细、颜色、背景色

输出格式：

- 当多个元素匹配时，可选的选择标题。 - 标题：“计算样式：\” - 一个或多个部分：布局、可见性、间距、排版、其他 - 每个部分都列出了所请求属性的“属性：值”行

示例：

get_computed_styles（{选择器：'testid:登录表单'}）

get_computed_styles（{选择器：“#hero”，属性：“display，width，color”}）

示例输出（get_computed_styles（{选择器：'testid:login form'}））：

⚠ Found 2 elements matching "testid:login-form", using element 1 (first visible)
💡 Tip: Consider adding a unique data-testid attribute for more reliable selection.
   Primary fix: add data-testid and target it (e.g., testid:submit).
   Workaround: use '>> nth=' only when you can't add test IDs.

Computed Styles: 

Layout:
  display: block
  position: static
  width: 560px
  height: 480px

Visibility:
  opacity: 1
  visibility: visible
  z-index: auto
  overflow: visible

Spacing:
  margin: 0px
  padding: 24px

Typography:
  font-size: 16px
  font-weight: 400
  color: rgb(33, 37, 41)

`check_visibility`

检查元素是否对用户可见。对于调试点击/交互失败至关重要。返回详细的可见性信息，包括视口交点、溢出剪切：隐藏以及元素是否需要滚动。支持testid快捷方式（例如“testid:提交按钮”）。

参数：

- 选择器（字符串，必填）：CSS选择器、文本选择器或testid简写（例如，“testid:登录按钮”、“#submit”、“text=Click here”）

输出格式：

- 标题：可见性：\ - 状态行：✓ 可见/✗ 隐藏，✓/✗ 在视口中，%可见 - CSS：不透明度、显示、可见性 - 可选交互问题：禁用、只读、aria禁用、指针事件：无 - 可选问题块：被父溢出剪切，被元素覆盖（带描述符和~coverage%），需要滚动 - 可选建议：scroll_to_element、模态/叠加提示、交互状态注释 - 检测到剪切时运行inspect_ancestors的可选提示

示例：

check_visibility（{选择器：'testid:submit'}）

check_visibility（{选择器：“#登录按钮”}）

示例输出（check_visibility（{选择器：'testid:submit'}））：

Visibility: 

✓ visible, ✓ in viewport
opacity: 1, display: inline-block, visibility: visible

示例输出（check_visibility（{选择器：'#hero-cta'}））：

Visibility: 

✗ hidden, ✗ not in viewport (45% visible)
opacity: 1, display: block, visibility: visible

Issues:
  ✗ covered by another element (~60% covered)
    Covering: 
 (z-index: 9999)
  ⚠ needs scroll to bring into view

→ Call scroll_to_element before clicking
→ Element may be behind modal, overlay, or fixed header

`query_selector`

测试选择器并返回所有匹配元素的详细信息。对于选择器调试和找到正确的元素进行交互至关重要。返回包含元素标记、位置、文本内容、可见性状态和交互功能的紧凑文本格式。显示隐藏元素的原因（显示：无，不透明度：0，大小为零）。支持testid快捷方式（例如“testid:提交按钮”）。使用limit参数控制要显示的匹配项数量（默认值：10）。新增：使用only visible参数过滤结果（true=仅可见，false=仅隐藏，undefined=全部）。

参数：

- 选择器（字符串，必填）：CSS选择器、文本选择器或用于测试的testid简写（例如，“button.submit”、“testid:登录表单”、“text=Sign-In”） - limit（number，可选）：返回详细信息的最大元素数（默认值：10，建议最大值：50） - only visible（布尔值，可选）：按可见性筛选结果：true=仅显示可见元素，false=仅显示隐藏元素，undefined/not specified=显示所有元素（默认值：undefined） - showAttributes（字符串，可选）：以逗号分隔的HTML属性列表，用于显示每个元素（例如，'id、name、aria-label、href、type'）。如果未指定，则不显示属性。

输出格式：

- 显示总匹配项的标题（以及过滤后的可见/隐藏计数（如果需要））。 - 每场比赛（上限）： - 带有元素标签和标识符（testid/id/class）的索引。 - 位置线：@（x，y）宽x高px。 - 引号中可选的修剪文本内容。 - 可选列出的属性（如果需要）。 - 状态行：✓ 可见或✗ 隐藏原因（显示：无，不透明度：0，大小为零）； ⚡ 在适用的情况下进行互动。 - 脚注中显示了多少与省略了多少，以及增加限制的提示。

示例：

query_selector（{选择器：'a'，限制：3}）

query_selector（{选择器：“testid:提交”，only可见：true，showAttributes：“href，aria-label”}）

示例输出（query_selector（{选择器：'a'，限制：2}）：

Found 5 elements matching "a":

[0] 
    @ (16,12) 80x20px
    "Home"
    href: "/"
    ✓ visible, ⚡ interactive

[1] 
    @ (104,12) 120x20px
    "Products"
    ✓ visible, ⚡ interactive

Showing 2 of 5 matches (3 omitted)
Use limit parameter to show more: { selector: "a", limit: 5 }

`get_test_ids`

发现页面上的所有测试标识符（数据testid、数据测试、数据cy等）。返回按属性类型分组的紧凑文本列表。对于测试驱动的工作流程和了解可以可靠地选择哪些元素至关重要。使用返回的测试ID和选择器快捷键，如“testid:submit按钮”。

参数：

- attributes（字符串，可选）：以逗号分隔的要搜索的测试ID属性列表（默认值：“data-testid，data-test，data-cy”） - showAll（布尔值，可选）：如果为true，则显示所有测试ID，不截断。如果为false（默认），则显示每个属性的前8个测试ID，并为较长的列表提供摘要。

输出格式：

- “找到N个测试ID”标头或带有提示的“找到0个测试ID - 对于每个属性组：属性名称，带计数和一个紧凑的逗号分隔列表（或用“…和X更多”截断） - 可选重复警告：属性：值出现N次 - 带有选择器快捷方式最佳实践和使用提示的建议块

示例：

get_test_ids（{}）

get_test_ids（{showAll:true}）

get_test_ids（{属性：'datatestid，data-cy'}）

示例输出（get_test_ids（{}））：

Found 5 test IDs:

data-testid (3):
  submit, email-input, password-input

data-cy (2):
  navbar, footer

💡 Tip: Use these test IDs with selector shortcuts:
   testid:submit → [data-testid="submit"]

示例输出（get_test_ids（{showAll:false}）：

Found 14 test IDs:

data-testid (12):
  submit, email-input, password-input, remember-me, login-form, link-register, link-forgot, header-title,
  ... and 4 more
  💡 Use showAll: true to see all 12 test IDs

data-cy (2):
  navbar, footer

`measure_element`

📏 测量工具-调试间距问题：请参阅视觉框模型格式中的填充、边距、边框和尺寸测量。当元素具有意外的间距或大小时使用。返回显示内容的紧凑视觉表示→ 填充→ 边界→ 带方向箭头的边距（↑24px表示上边距等）。还提供了对滚动检测有用的原始尺寸（客户端高度与内容高度）。对于父子居中问题，请先使用inspect_dom（）（显示子对象是否居中于父对象）。要比较两个元素之间的对齐情况，请使用compare_element_aligent（）。为了快速检测滚动，请改用inspect_dom（）（显示“可滚动”↕️'). 比get_computerd_styles（）或evaluate（）更具可读性，适用于盒子模型调试。

参数：

- 选择器（字符串，必填）：CSS选择器或testid简写（例如，“testid:submit”、“#登录按钮”）

输出格式：

- 标题：元素：\ - 位置/尺寸线：@（x，y）宽x高px - 框模型部分：内容大小、填充（带方向箭头）、边框（带箭头或简写）、边距（带箭头） - 总空格线：总宽x总高px（带边距） - 检测到异常间距时运行inspect_ancestors的可选建议

示例：

measure_element（{选择器：'testid:card'}）

measure_element（{选择器：'#hero'}）

示例输出（measure_element（{选择器：'testid:card'}））：

Element: 

@ (240,320) 360x240px

Box Model:
  Content: 328x208px
  Padding: ↑16px ↓16px ←8px →8px
  Border:  none
  Margin:  ↑0px ↓24px ←0px →0px

Total Space: 360x264px (with margin)

`find_by_text`

根据文本内容查找元素。对于查找没有良好选择器的元素至关重要，特别是在结构不佳的DOM中。返回具有位置、可见性和交互状态的元素。支持精确匹配、区分大小写的搜索和NEW:regex模式匹配，用于高级文本搜索（例如，使用“/\\d+items？/”查找带数字的元素）。

参数：

- text（字符串，必填）：在元素中搜索的文本。如果regex=true，这可以是/patter/flags格式的正则表达式模式（例如，'/\\d+/i'表示不区分大小写的数字）或原始模式字符串。 - exact（布尔值，可选）：是否完全匹配文本（默认值：false，允许部分匹配）。如果regex=true，则忽略。 - caseSensitive（布尔值，可选）：搜索是否应区分大小写（默认值：false）。如果regex=true，则忽略（改用正则表达式标志）。 - regex（布尔值，可选）：是否将“text”视为正则表达式模式（默认值：false）。如果为true，则支持/patter/flags格式或原始模式。示例：'/sign.\*/i'（不区分大小写），'/\\d+项目？/'（数字+可选的's'）。 - limit（number，可选）：要返回的最大元素数（默认值：10）

输出格式：

- 标题显示“未找到元素”。..'或'找到N个元素。..' - 上限结果，每个结果： - \带有关键属性的行 - 位置线：@（x，y）宽x高px - 修剪的文本内容（如有） - 可见性和可交互性状态 - 页脚显示了显示与省略的数量以及如何增加限制

示例：

find_by_text（{text:“登录”}）

find_by_text（{文本：“/^下一个\\d+$/”，正则表达式：true}）

find_by_text（{文本：“删除”，精确：true，大小写敏感：true}）

示例输出（find_by_text（{text:“登录”}）：

Found 3 elements containing "Sign in":

[0] 
    @ (640,420) 120x40px
    "Sign in"
    ✓ visible

[1] 
    @ (600,480) 68x20px
    "Sign in"
    ✓ visible, ⚡ interactive

[2] 

    @ (40,360) 200x24px
    "Sign in"
    ✗ hidden

Showing all 3 matches

`element_exists`

快速检查页面上是否存在元素。当您只需要确认存在时，query_selector_all的超轻量级替代品。返回简单存在/未找到状态。尝试交互前最常见的检查。支持testid快捷方式。

参数：

- 选择器（字符串，必填）：CSS选择器、文本选择器或testid简写（例如，'testid:submit button'、'#main'）

输出格式：

- 返回一行： - ✓ 存在：找到时\（N个匹配项）（N个可选项） - ✗ 未找到：当没有

示例：

element_exists（{选择器：'testid:submit'}）

element_exists（{选择器：“#不存在”}）

示例输出（element_exists（{选择器：“testid:submit”}）：

✓ exists:

示例输出（element_exists（{选择器：'.card'}））：

✓ exists: 
 (3 matches)

示例输出（element_exists（{选择器：“#不存在”}）：

✗ not found: #does-not-exist

浏览浏览器历史记录（后退/前进）。返回：'导航在浏览器历史记录中，如果可用，会显示一个快速的网络空闲提示，URL： ”和“标题： ”当设置。如果导航后出现控制台错误，则返回类似“历史导航后的控制台错误： “包括标题（如果可用）。

参数：

- direction（字符串，必填）：要导航的历史方向

`navigate`

导航到一个URL。浏览器会话（Cookie、localStorage、sessionStorage）会自动保存在中。/.mcp web检查器/用户数据目录，并在重新启动时保持不变。要清除已保存的会话，请删除该目录。

参数：

- url（字符串，必填）：导航到指定网站的url - browserType（字符串，可选）：要使用的浏览器类型（chromium、firefox、webkit）。默认为铬 - 设备（字符串，可选）：预设要模拟的设备。使用视口、用户代理和设备比例因子的设备配置。指定后，将替代宽度/高度参数。手机：iphone se、iphone-14、iphone-14-pro、像素-5、ipad、三星s21。台式机：台式机-1080p（1920x1080），台式机-2k（2560x1440），笔记本电脑高清（1366x768）。 - width（数字，可选）：视口宽度（像素）。如果未指定，则自动匹配屏幕宽度。如果指定了设备，则忽略。 - height（数字，可选）：视口高度（像素）。如果未指定，则自动匹配屏幕高度。如果指定了设备，则忽略。 - timeout（数字，可选）：导航超时（毫秒） - waitUntil（字符串，可选）：导航等待条件 - headless（布尔值，可选）：在无头模式下运行浏览器（无可见窗口）。默认情况下，在桌面上可见，在没有显示器的Linux上无头，或者当传递--headless时。

`scroll_by`

按特定像素数滚动容器（或页面）。当只有一个可用时，自动检测滚动方向。必备功能：测试粘性页眉/页脚、触发无限滚动、转盘导航、精确滚动位置测试。使用“html”或“body”进行页面滚动。正像素=向下/向右，负像素=向上/向左。输出：✓ 带有轴位置和最大滚动百分比的成功总结； ⚠️ 移动受限时的边界通知； ⚠️ 两轴滚动时方向引导模糊； ⚠️ 带有祖先建议的不可滚动报告； 💡 与检测到的场景匹配的后续提示。

参数：

- 选择器（字符串，必填）：可滚动容器的CSS选择器（使用“html”或“body”进行页面滚动，例如“testid:chat container”、“.srollable list”、“html”） - pixels（number，必填）：要滚动的像素数。正=向下/向右，负=向上/向左。示例：500、-200 - direction（字符串，可选）：滚动方向：“垂直”（默认）、“水平”或“自动”（检测可用方向）。使用“自动”进行智能检测。

`scroll_to_element`

将元素滚动到视图中。自动处理最近的可滚动祖先（页面或可滚动容器）内的滚动。关键在于：在交互之前使元素可见，触发延迟加载内容，测试滚动行为。位置：开始（视口顶部）、中心（中间）、结束（底部）。默认值：开始。

参数：

- 选择器（字符串，必填）：CSS选择器、文本选择器或测试ID（例如，“testid:submit btn”、“#登录按钮”、“text=Load More”） - position（字符串，可选）：在视口中对齐元素的位置：“start”（顶部）、“center”（中间）、“end”（底部）。默认值：“start”

交互

`click`

单击页面上的元素

参数：

- 选择器（string，必填）：用于单击元素的CSS选择器

`drag`

将元素拖动到目标位置

参数：

- sourceSelector（字符串，必填）：用于拖动元素的CSS选择器 - targetSelector（字符串，必填）：目标位置的CSS选择器

`fill`

填写可编辑的输入/文本区域/内容；如果选择器与包装器匹配，则最多会下降4级到一个唯一的可填充后代（如果为零或多个，则会出错）

参数：

- 选择器（字符串，必填）：输入字段或其包装器的CSS选择器 - value（字符串，必填）：要填充的值

`hover`

将元素悬停在页面上

参数：

- 选择器（字符串，必填）：用于悬停元素的CSS选择器

`press_key`

按键盘键

参数：

- key（字符串，必填）：要按的键（例如“Enter”、“ArrowDown”、“a”） - 选择器（字符串，可选）：可选的CSS选择器，用于在按键前聚焦

`select`

使用Select标签在页面上选择一个元素

参数：

- 选择器（string，必填）：用于选择元素的CSS选择器 - value（字符串，必填）：要选择的值

`upload_file`

将文件上传到页面上的input\[type='file'\]元素

参数：

- 选择器（string，必填）：文件输入元素的CSS选择器 - filePath（字符串，必填）：要上传的文件的绝对路径

内容

`get_html`

\[可以返回预览+令牌\]⚠️ 很少需要：从页面获取原始HTML标记（无需渲染，只需源代码）。大多数任务都需要结构化检查。只将get_html用于：（1）检查特定的html属性或元素嵌套，（2）分析标记结构，（3）调试SSR/html问题。对于结构化任务，使用：inspect_dom（）来理解带有位置的页面结构，使用query_selector（）来查找和检查元素，使用get_computed_styles（）来获取CSS值。如果\ @（x，y）宽x高'（四舍五入整数） - NodeList/HTMLCollection摘要：“NodeList（n）\[\，\，\…\]” - 当结果较大（≥~2000个字符）时预览保护： - '预览（前500个字符）：'后面是摘录 - 计数：'总长度：N，显示长度：M，截断：true' - 用于获取完整输出的一次性令牌字符串 - 建议块（有条件）：基于脚本模式的专用工具的简洁提示

网络

`get_request_details`

\[可能返回预览+令牌\]通过索引（从list_network_requests）获取特定网络请求的详细信息。返回请求/响应标头、正文（截断为500个字符）、时间和大小。带有密码的请求体会自动屏蔽。如果请求或响应正文超过500个字符，则包含一个预览和一个一次性confirm_output令牌，当调用该令牌时，会将全文保存到下的磁盘。/.mcp web inspector/networkbodies/并返回文件路径。对于调试API响应和调查失败的请求至关重要。

参数：

- index（number，必填）：来自list_network_requests输出的请求索引（例如\[0\]、\[1\]等）

`list_network_requests`

列出浏览器最近捕获的网络请求。返回包含方法、URL、状态、资源类型、时间和大小的紧凑文本格式。对于调试API调用和性能问题至关重要。使用get_request_details（）检查特定请求的完整标头和正文。

参数：

- type（字符串，可选）：按资源类型筛选：“xhr”、“fetch”、“script”、“stylesheet”、“image”、“font”、“document”等。省略显示所有类型。 - limit（number，可选）：要返回的最大请求数，最近的请求数在前（默认值：50）

等待

`wait_for_element`

等待元素达到特定状态（可见、隐藏、附着、分离）。等待动态内容比sleep（）更好。返回持续时间和当前元素状态。支持testid快捷方式（例如“testid:提交按钮”）。

参数：

- 选择器（字符串，必填）：CSS选择器、文本选择器或testid简写（例如，“testid:submit按钮”、“#loading微调器”） - state（字符串，可选）：要等待的状态：“可见”（默认）、“隐藏”、“附着”、“分离” - timeout（数字，可选）：等待的最长时间（毫秒）（默认值：10000）

`wait_for_network_idle`

等待网络活动稳定。等待至少500毫秒，直到没有网络连接。在等待AJAX调用或动态内容加载时，比固定延迟要好。返回实际等待时间和空闲状态的确认。

参数：

- timeout（数字，可选）：等待的最长时间（毫秒）（默认值：10000）

生命周期

`close`

关闭浏览器并释放所有资源

`set_color_scheme`

设置控制CSS首选配色方案的浏览器配色方案。默认为系统外观。在检查颜色或截图之前使用。选项：系统（清除覆盖以遵循OS/浏览器设置）、暗、亮、无偏好（模拟没有声明偏好的代理）。返回活动方案的确认。

参数：

- scheme（字符串，必填）：要模拟的配色方案：“系统”、“暗”、“亮”或“无偏好”。示例：｛方案：“dark”｝

其他

`confirm_output`

使用一次性令牌返回先前预览的大型结果的完整输出。当工具以预览+标记响应时使用。比重新发送原始参数更安全。

参数：

- token（字符串，必填）：从工具的预览响应中获得的一次性令牌 - reason（string，必填）：解释为什么需要完整的输出以及如何使用它。这有助于用户了解该操作是否合理和必要。

输出格式：

- 如果令牌有效，则完整的原始有效载荷（一次性） - 错误：“令牌无效或过期”

选择器快捷方式⭐ 节省时间

所有浏览器工具支持 方便的测试ID快捷方式 节省打字时间并提高可读性：

速记	扩展为	保存的字符
`testid:submit-button`	`[data-testid="submit-button"]`	17个字符
`data-test:login-form`	`[data-test="login-form"]`	11个字符
`data-cy:username`	`[data-cy="username"]`	9个字符

之前（详细）：

click({ selector: '[data-testid="submit-button"]' })
fill({ selector: '[data-testid="email-input"]', value: 'user@example.com' })
check_visibility({ selector: '[data-testid="loading-spinner"]' })

之后（使用快捷方式）：

click({ selector: 'testid:submit-button' })
fill({ selector: 'testid:email-input', value: 'user@example.com' })
check_visibility({ selector: 'testid:loading-spinner' })

为什么这很重要：

✅ 更简洁、更易读的工具调用 -无需转义引号或记住括号语法
✅ 适用于所有浏览器工具 -click、fill、inspect_dom等语法一致。
✅ 与其他选择器混合 -常规CSS选择器仍然有效： #login, .button, nav > a

所有支持的快捷方式：

testid:* → [data-testid="*"]
data-test:* → [data-test="*"]
data-cy:* → [data-cy="*"] （塞浦路斯公约）

常规CSS选择器、文本选择器(text=Login)，剧作家选择器工作不变。

示例用例

调试失败的测试

1. navigate({ url: "https://example.com" })
2. query_selector({ selector: ".submit-button", limit: 5 })
   → Found 3 matches, 2 are hidden (display:none)
3. check_visibility({ selector: ".submit-button:nth-child(1)" })
   → Element is clipped by parent overflow:hidden
4. measure_element({ selector: ".submit-button:nth-child(1)" })
   → @ (1500,300) 100x40px (outside viewport)

了解页面结构

1. navigate({ url: "https://app.example.com" })
2. inspect_dom({})
   → Shows: header, nav, main, aside, footer
3. inspect_dom({ selector: "main" })
   → Shows: form[role=search], section.results, section.filters
4. get_test_ids({})
   → Discovers: search-input, filter-dropdown, result-card

验证布局一致性

1. navigate({ url: "https://dashboard.example.com" })
2. compare_positions({
     selector1: "testid:main-header",
     selector2: "testid:chat-header",
     checkAlignment: "top"
   })
   → ✓ Aligned (difference: 0px)
3. compare_positions({
     selector1: ".card:nth-child(1)",
     selector2: ".card:nth-child(2)",
     checkAlignment: "width"
   })
   → ✗ Not aligned (difference: 15px)

查找没有测试ID的元素

1. find_by_text({ text: "Add to Cart", exact: false })
   → Found 1 element: button.primary-action
2. get_computed_styles({
     selector: "button.primary-action",
     properties: "background-color,padding,font-size"
   })
   → Shows: background-color: rgb(0,123,255), padding: 12px 24px

食谱：常见工作流程

这些循序渐进的食谱展示了如何将工具链接在一起，用于常见的测试和调试场景。

诀窍1：测试登录流

1. navigate({ url: "https://app.example.com/login" })
2. fill({ selector: "testid:email-input", value: "user@example.com" })
3. fill({ selector: "testid:password-input", value: "password123" })
4. click({ selector: "testid:login-button" })
5. wait_for_network_idle()
6. get_console_logs({ type: "error" })
   → Verify no JavaScript errors occurred
7. get_text()
   → Verify success message or dashboard content

为什么这有效：会话持久性意味着您保持登录状态以进行后续测试。

秘诀2：调试布局问题

1. navigate({ url: "https://dashboard.example.com" })
2. inspect_dom({ selector: "testid:sidebar" })
   → Understand the structure of the problematic area
3. measure_element({ selector: "testid:logo" })
   → @ (20,10) 150x40px
4. measure_element({ selector: "testid:menu" })
   → @ (20,60) 200x300px
5. compare_positions({
     selector1: "testid:logo",
     selector2: "testid:menu",
     checkAlignment: "left"
   })
   → ✓ aligned (both at x=20)
6. get_computed_styles({
     selector: "testid:sidebar",
     properties: "margin,padding,display,flex-direction"
   })
   → Shows: display: flex, flex-direction: column, padding: 20px

导航（{url:“https://dashboard.example.com" })
inspect_dom（{选择器：“testid:soard”}）

→ 了解问题区域的结构

measure_element（{选择器：“testid:logo”}）

→ @ （20,10）150x40px

measure_element（{选择器：“testid:menu”}）

→ @ （20,60）200x300px

比较位置({

selector1:“testid:logo”，选择器2：“testid:menu”， check对齐：“左” }) → ✓ 对齐（均在x=20处）

get_computerd_styles({

选择器：“testid：侧边栏”，属性：“边距、填充、显示、弯曲方向” }) → 显示：显示：柔性，柔性方向：列，填充：20px

为什么这有效：渐进式检查+精确测量揭示了布局问题。

秘诀2a：找出意外利润的来源

1. navigate({ url: "https://app.example.com" })
2. inspect_dom({ selector: "main" })
   → Shows header element with test ID
3. measure_element({ selector: "testid:event-mode-header" })
   → @ (160,0) 896x56px
   → Margin: ←160px →160px (unexpected!)
   💡 Unexpected spacing detected. Check parent constraints
4. inspect_ancestors({ selector: "testid:event-mode-header" })
   → [0] 
       @ (160,0) 896x56px | w:896px max-w:896px m:0 160px
       border-bottom: 1px solid #e5e7eb
       ⚠ Auto margins centering (160px each side)
   → [1] 

       @ (0,0) 1216x56px | w:1216px
   → [2] 
 flex max-w-[1600px]
       @ (352,60) 1216x900px
       max-width: 1600px
       🎯 WIDTH CONSTRAINT
5. Solution: Remove mx-auto from header (centering already handled by parent)

为什么这有效: inspect_ancestors 追踪布局约束链，以找出深层嵌套React组件中意外间距的根本原因。

配方3：API响应测试

1. navigate({ url: "https://app.example.com/dashboard" })
2. click({ selector: "testid:refresh-button" })
3. wait_for_network_idle()
4. list_network_requests({ type: "fetch", limit: 10 })
   → [5] GET /api/users 200 OK | 45ms
5. get_request_details({ index: 5 })
   → Check headers, status, response body
6. get_console_logs({ type: "error" })
   → Verify no network errors

为什么这有效：网络工具在交互后捕获所有检查请求。

诀窍4：在没有测试ID的页面上查找元素

1. navigate({ url: "https://legacy-app.example.com" })
2. inspect_dom()
   → Get overall page structure
3. get_test_ids()
   → Check if any test IDs exist (spoiler: none)
4. find_by_text({ text: "submit", caseSensitive: false })
   → Found 2 buttons containing "submit"
5. query_selector({ selector: "button", onlyVisible: true, limit: 10 })
   → Shows all visible buttons with positions and text
6. element_exists({ selector: "button:has-text('Submit Form')" })
   → ✓ exists
7. click({ selector: "button:has-text('Submit Form')" })

为什么这有效：多种发现工具（文本搜索、查询选择器）有助于定位元素。

配方5：调试“元素不可见”错误

1. navigate({ url: "https://app.example.com" })
2. element_exists({ selector: "testid:submit" })
   → ✓ exists
3. check_visibility({ selector: "testid:submit" })
   → ✗ not visible: clipped by parent overflow:hidden
4. inspect_dom({ selector: "form" })
   → See parent container structure
5. get_computed_styles({
     selector: "form",
     properties: "overflow,height,max-height"
   })
   → overflow: hidden, height: 300px, max-height: 300px
6. evaluate({ script: "document.querySelector('[data-testid=submit]').scrollIntoView()" })
   → Scroll element into view
7. check_visibility({ selector: "testid:submit" })
   → ✓ visible
8. click({ selector: "testid:submit" })

为什么这有效：可见性诊断揭示了确切的原因，从而实现了有针对性的修复。

秘诀6：视觉回归测试

1. navigate({ url: "https://dashboard.example.com" })
2. compare_positions({
     selector1: "testid:header",
     selector2: "testid:footer",
     checkAlignment: "width"
   })
   → ✓ aligned (both 1280px)
3. compare_positions({
     selector1: ".card:nth-child(1)",
     selector2: ".card:nth-child(2)",
     checkAlignment: "height"
   })
   → ✗ not aligned (difference: 20px)
4. measure_element({ selector: ".card:nth-child(1)" })
   → @ (20,100) 400x300px
5. measure_element({ selector: ".card:nth-child(2)" })
   → @ (440,100) 400x320px  ← 20px taller!

为什么这有效：位置比较工具验证组件之间的一致间距。

配方7：表单验证测试

1. navigate({ url: "https://app.example.com/signup" })
2. fill({ selector: "testid:email", value: "invalid-email" })
3. fill({ selector: "testid:password", value: "short" })
4. click({ selector: "testid:submit" })
5. wait_for_element({ selector: ".error-message", state: "visible", timeout: 5000 })
6. find_by_text({ text: "invalid", caseSensitive: false })
   → Found 2 elements: .error-message spans
7. get_text({ selector: ".error-message" })
   → "Please enter a valid email address"
8. get_text({ selector: ".error-message" })
   → Capture validation text for assertions

为什么这有效：等待元素确保在检查之前出现验证消息。

秘诀8：移动响应式测试

1. navigate({
     url: "https://app.example.com",
     width: 375,
     height: 667
   })
   → iPhone SE viewport
2. inspect_dom({ selector: "nav" })
   → Check if mobile menu is used
4. element_exists({ selector: "testid:hamburger-menu" })
   → ✓ exists (mobile menu visible)
5. element_exists({ selector: "testid:desktop-menu" })
   → ✗ not found (desktop menu hidden on mobile)
6. click({ selector: "testid:hamburger-menu" })
7. wait_for_element({ selector: "testid:mobile-nav", state: "visible" })
8. get_text({ selector: "testid:mobile-nav" })
   → Snapshot of opened mobile menu content

为什么这有效：navigation中的视口配置支持移动测试。

诀窍9：调试悬停状态

1. navigate({ url: "https://app.example.com" })
2. hover({ selector: "testid:tooltip-trigger" })
3. wait_for_element({ selector: "testid:tooltip", state: "visible", timeout: 2000 })
4. check_visibility({ selector: "testid:tooltip" })
   → ✓ visible
5. measure_element({ selector: "testid:tooltip" })
   → @ (300,150) 200x50px
6. get_computed_styles({
     selector: "testid:tooltip",
     properties: "display,opacity,visibility,z-index"
   })
   → display: block, opacity: 1, visibility: visible, z-index: 1000
7. check_visibility({ selector: "testid:tooltip" })
   → Double-check that tooltip remains visible

为什么这有效：悬停工具+可见性检查验证工具提示行为。

秘诀10：可访问性审计

1. navigate({ url: "https://app.example.com" })
2. inspect_dom()
   → Check for semantic HTML (header, nav, main, footer)
3. query_selector({
     selector: "[role]",
     showAttributes: "role,aria-label,aria-labelledby"
   })
   → Shows all ARIA roles on page
4. find_by_text({ text: "button", regex: true })
   → Find buttons by text (should have accessible labels)
5. query_selector({
     selector: "button",
     showAttributes: "aria-label,title"
   })
   → Check if buttons have accessible labels
6. get_test_ids()
   → Verify no duplicate test IDs (accessibility issue)

为什么这有效：DOM检查+属性查询揭示了可访问性问题。

故障排除

浏览器安装问题

症状：有关Playwright浏览器未安装或浏览器无法启动的错误消息。

运作原理：浏览器是 首次使用时自动安装 当你运行任何导航工具时。安装一次（下载约1GB），浏览器存储在您的主目录中，在所有项目中共享。

第一次使用时你会看到什么:

🎭 Playwright browsers not found. Installing automatically...
⏳ This will download ~1GB of browser binaries. Please wait...
[Installation progress...]
✅ Browsers installed successfully! Starting browser...

如果自动安装失败 （防火墙、权限等）：

# Manual installation - run this command:
npx playwright install chromium firefox webkit

# With system dependencies (requires admin/sudo):
npx playwright install --with-deps chromium firefox webkit

适用于GitHub Copilot/VS Code用户:

首次使用工具将自动安装浏览器（等待1-2分钟）
后续使用是即时的
安装在后台进行，并显示进度消息
如果需要手动安装，请在运行命令后重新启动IDE

服务器未加载

症状：您的AI助手中没有web检查器的工具。

解决方案:

验证配置文件是否正确（请参阅上面的AI工具设置部分）
完全重新启动AI工具（而不仅仅是重新加载窗口）
检查服务器日志（位置取决于您的AI工具）
尝试删除并重新添加服务器配置

权限问题

症状：安装浏览器时出现拒绝权限错误。

解决方案:

# If using global installation, you may need sudo (Linux/macOS)
sudo npm install -g mcp-web-inspector

# Or use npx without global installation (recommended)
# Just configure with "npx -y mcp-web-inspector" as shown in setup

浏览器崩溃或断开连接

症状：浏览器在使用过程中变得无响应或断开连接。

MCP服务器自动处理此问题:

检测断开连接的浏览器
重置状态并提供清晰的错误消息
指示您重试导航/操作
无需手动干预-只需重试您的命令

发展

测试

npm test              # Run tests
npm run test:coverage # Run with coverage

建筑

npm run build  # Compile TypeScript
npm run watch  # Watch mode for development

技术细节

协议：模型上下文协议（MCP）
浏览器引擎：剧作家（Chromium、Firefox、WebKit）
语言：TypeScript
节点版本: 20+

贡献

欢迎投稿！添加新工具时：

保持工具名称简短（某些客户端限制 server_name:tool_name 至60个字符）
遵循原子操作原理（一个工具，一个目的）
使用具有基本类型的平面参数结构
在中添加测试 src/__tests__/

许可证

麻省理工学院

链接

GitHub: https://github.com/antonzherdev/mcp-web-inspector
npm: https://www.npmjs.com/package/mcp-web-inspector
问题: https://github.com/antonzherdev/mcp-web-inspector/issues

学分

这个项目是一个专注的分支执行自动化/mcp剧作家，专门从事web检测和调试能力。我们感谢ExecuteAutomation团队为这个项目奠定了坚实的基础。

主要区别：

Web检查器MCP：专注于使用干净的工具名称进行检查、调试和布局验证
原mcp剧作家：全功能浏览器自动化，包括代码生成、API测试和全面的交互工具

如果您需要完整的Playwright自动化功能（代码生成、高级交互、API测试），请查看 mcp原创剧作家服务器.

______________________________________________________________________

专为人工智能辅助的web开发和测试而设计 🤖

Web Inspector MCP

快速接入

详细介绍

Web检查器MCP🔍

为什么选择Web检查器MCP？

完美适合

安装

AI工具设置

通过CLI安装

手动配置

通过CLI安装

手动配置

配置文件位置

添加到配置

先决条件

通过CLI安装

手动配置

在VS代码中启用MCP

首次浏览器设置

关于嵌入式浏览器的说明

配置文件位置

添加到配置

步骤

配置

步骤

先决条件

配置

命令行选项

会话持久性和数据存储

运作原理

好处

禁用会话持久性

清除数据

安全最佳实践

核心工具

检查

inspect_dom

inspect_ancestors

compare_element_alignment

get_computed_styles

check_visibility

query_selector

get_test_ids

measure_element

find_by_text

element_exists

导航

go_history

navigate

scroll_by

scroll_to_element

交互

click

drag

fill

hover

press_key

select

upload_file

内容

get_html

网络

get_request_details

list_network_requests

等待

wait_for_element

wait_for_network_idle

生命周期

close

set_color_scheme

其他

confirm_output

选择器快捷方式⭐ 节省时间

示例用例

调试失败的测试

了解页面结构

验证布局一致性

查找没有测试ID的元素

食谱：常见工作流程

诀窍1：测试登录流

`inspect_dom`

`inspect_ancestors`

`compare_element_alignment`

`get_computed_styles`

`check_visibility`

`query_selector`

`get_test_ids`

`measure_element`

`find_by_text`

`element_exists`

`go_history`

`navigate`

`scroll_by`

`scroll_to_element`

`click`

`drag`

`fill`

`hover`

`press_key`

`select`

`upload_file`

`get_html`

`get_request_details`

`list_network_requests`

`wait_for_element`

`wait_for_network_idle`

`close`

`set_color_scheme`

`confirm_output`