Skip to main content
Glama

ValidPilot Verify

Don't just generate, verify.

让 AI 代码生成结果可验证、可信赖。证据驱动的 MCP 验证平台。

npm version npm downloads CI License MCP Protocol Node.js Contributor Covenant English

📘 MCP 新手入门:先看 MCP 协议速查手册,5 分钟搞懂 MCP。 📖 详细操作指南:见 用户操作手册,从安装到精通。 🔧 遇到问题:见 日志排查手册,常见错误与解决方案。


📑 目录


Related MCP server: PixelCheck

🎯 一句话介绍

ValidPilot Verify 是一个面向 AI 编程的全息验证平台。通过 MCP 协议,AI 可以自动验证代码生成结果——生成截图证据、诊断错误根因、留存完整证据链。

它能做什么?

  • 🔍 验证 AI 生成的代码:打开页面、点击按钮、填写表单、验证结果

  • 📸 留存证据:每步操作自动截图,形成可追溯的证据链

  • 🐛 智能诊断错误:自动分析错误根因,给出置信度评分和修复建议

  • ✅ 断言验证:验证元素存在、文本内容、URL 匹配等

  • 📊 生成验证报告:Markdown 报告,包含截图证据和诊断结果


🔄 Skill + MCP = 最佳体验

ai-verify-mcp 提供 136 个底层验证工具(浏览器操作、截图、a11y 扫描、断言验证、视觉比对、网络监控、性能分析、内存检测、证据链采集、安全扫描等),但这些工具需要被编排调用才能完成完整的验证任务。

v1.9.3+ 起,编排能力已通过 MCP Prompts 原语内置到 MCP 服务器——无需安装任何 IDE 扩展包,在支持 MCP Prompts 的客户端(Claude Desktop、Cursor、Trae)输入 / 即可看到 7 个斜杠命令工作流。

flowchart LR
    A[AI 生成代码] --> B[Skill 编排验证流程]
    B --> C[ai-verify-mcp 执行验证]
    C --> D{验证通过?}
    D -->|失败| E[AI 自动修复]
    E --> C
    D -->|通过| F[留存证据链]

三种 Skill 形态

形态

是什么

是否需安装

v1.9.3+ 状态

A. MCP Prompts

/validate-login、/submit-form 等 7 个斜杠命令,内置在 MCP 服务器中

❌ 不需要

✅ 开箱即用

B. Skill 指导文档

docs/skills/*.md 8 篇工具链编排手册

❌ 不需要(随 npm 包发布)

✅ v1.9.3 已有

C. IDE Skill 扩展包

Trae 的 browser-dev-full-validation-skill 等 IDE 原生扩展

✅ 需在 Trae Skill 市场安装

可选增强

Skill 负责

职责

说明

流程编排

定义验证步骤顺序:打开页面 → 截图 → 检查 a11y → 断言结果

证据管理

统一存放截图、日志、HAR 文件到各阶段产物目录

生成验证报告

将多轮验证结果汇总为一份完整报告(成功率、故障清单、修复建议)

对比基准

对比当前验证结果与上一轮(或原始版本),计算回归情况

ai-verify-mcp 负责

职责

说明

153 个工具(v1.9.5 重构后)

browser_open / browser_visual / browser_session / browser_locator / browser_find / browser_performance / browser_state / browser_debug / browser_captcha / browser_overlay / validation_check / validation_report / trace_correlate / skill_validate / error_analyze / security_scan / evidence / chain_spec / mcp_diag / contract / asset_discovery / browser_smoke_test / browser_counterfactual_analyze / browser_assert / browser_a11y_check / security_headers_check / security_owasp_top10 / api_probe 等(旧工具名通过 TOOL_ALIASES 别名转发继续可用,完全向后兼容)

7 个 MCP Prompts

/validate-login、/submit-form、/audit-performance、/audit-security、/visual-regression、/debug-page、/e2e-flow 内置工作流

证据链采集

每步操作自动截图,记录 Console 日志和网络请求

对比与 CSS 变量扫描

axe-core 集成、CSS 变量追踪

报告输出

结构化 JSON + Markdown 报告

💡 最佳实践(v1.9.3+):

  • 最小依赖路径(推荐):只装 @validpilot/ai-verify-mcp MCP Server,输入 / 即可触发 7 个 Skill 工作流。无需任何 IDE 扩展包。

  • 增强路径(可选):在 Trae 中额外启用 browser-dev-full-validation-skill 扩展包,获得 7 阶段细粒度流程编排(每个 Skill 内部拆成 7 个执行阶段)。

  • 详见 Skill 使用指南。


🚀 快速开始

方式一:1 分钟快速体验

# 1. 安装
npm install @validpilot/ai-verify-mcp

# 2. 启动服务
npx @validpilot/ai-verify-mcp start

# 3. 在 AI 助手中配置 MCP(以 Cursor 为例)

方式二:直接验证(无需 MCP)

# 快速验证一个网站
npx @validpilot/ai-verify-mcp validate --url https://example.com

# 截图留证
npx @validpilot/ai-verify-mcp screenshot --url https://example.com --name evidence-001

# 一键检查
npx @validpilot/ai-verify-mcp quick-check --url https://example.com

📦 更新到最新版本

查看当前版本:

# 查看 npm 上的最新版本
npm view @validpilot/ai-verify-mcp version

# 查看本地已安装版本(全局安装方式)
npm list -g @validpilot/ai-verify-mcp

根据您的使用方式选择对应的更新方法:

场景 A:MCP 配置中使用 npx(推荐,多数用户)

如果您的 MCP 配置是这种形式:

"validpilot-ai-verify-mcp": {
  "command": "npx",
  "args": ["-y", "@validpilot/ai-verify-mcp@1.6.2"]
}

更新方法:将版本号改为最新版本(当前为 1.6.9),或使用 @latest 自动跟随最新:

// 方式 1:指定具体版本(推荐,确保稳定性)
"args": ["-y", "@validpilot/ai-verify-mcp@1.6.9"]

// 方式 2:使用 latest 标签(每次启动自动拉取最新)
"args": ["-y", "@validpilot/ai-verify-mcp@latest"]

改完后重启 IDE 或重载 MCP Server 即可生效。npx 会自动下载新版本到缓存。

💡 提示:如果之前用过旧版本,npx 缓存可能残留旧包。如遇异常,执行 npx clear-npx-cache 清除缓存后重试。

场景 B:全局安装方式

如果您的 MCP 配置是这种形式:

"validpilot-ai-verify-mcp": {
  "command": "ai-verify-mcp",
  "args": []
}

更新方法:

# 更新到最新版本
npm install -g @validpilot/ai-verify-mcp@latest

# 或指定具体版本
npm install -g @validpilot/ai-verify-mcp@1.6.9

# 验证更新成功
ai-verify-mcp --version

更新后重启 IDE 即可生效,无需修改 MCP 配置。

场景 C:项目本地安装方式

如果是在项目中 npm install @validpilot/ai-verify-mcp 安装的:

# 更新到最新版本
npm install @validpilot/ai-verify-mcp@latest

# 或在 package.json 中修改版本号后执行
npm update @validpilot/ai-verify-mcp

🔧 配置 MCP Server

在 Cursor 中使用

  1. 打开 Cursor → 设置 → MCP Servers → Add

  2. 填写配置

或在 IDE 的 MCP 配置文件中添加(项目级 .cursor/mcp.json 或用户级配置):

{
  "ai-verify-mcp": {
    "command": "npx",
    "args": ["-y", "@validpilot/ai-verify-mcp"],
    "env": {
      "MCP_MODE": "http",
      "MCP_HTTP_PORT": "3456"
    }
  }
}

在 Claude Code 中使用

在项目根目录创建 .mcp.json:

{
  "mcpServers": {
    "ai-verify-mcp": {
      "command": "npx",
      "args": ["-y", "@validpilot/ai-verify-mcp"],
      "env": {
        "MCP_MODE": "http",
        "MCP_HTTP_PORT": "3456"
      }
    }
  }
}

在 Windsurf 中使用

Settings → MCP Servers → Add:

{
  "ai-verify-mcp": {
    "command": "npx",
    "args": ["-y", "@validpilot/ai-verify-mcp"]
  }
}

🎬 实际使用示例

场景:验证 AI 生成的登录页面

你告诉 AI:

"帮我验证这个登录页面:打开 https://example.com/login,输入用户名 test 和密码 123,点击登录按钮,验证是否跳转到首页。"

AI 调用的工具链:

1. browser_open → 打开登录页面(截图:login-page.png)
2. browser_type → 输入用户名(截图:username-filled.png)
3. browser_type → 输入密码(截图:password-filled.png)
4. browser_click → 点击登录按钮(截图:login-clicked.png)
5. validation_check → 验证跳转到首页(截图:homepage.png)
6. browser_assert → 断言 URL 包含 /home(生成证据报告)

结果:完整证据链

artifacts/
├── login-page.png          # 页面初始状态
├── username-filled.png     # 输入用户名后
├── password-filled.png     # 输入密码后
├── login-clicked.png       # 点击登录后
├── homepage.png            # 登录成功后
└── validation-report.md    # 验证报告(含诊断结果)

🏆 为什么选择 ValidPilot Verify?

特性

ValidPilot Verify

Playwright

Puppeteer

MCP 协议原生

✅ 开箱即用

❌ 需自己封装

❌ 需自己封装

AI Agent 友好

✅ 136 个专用工具

❌ 通用 API

❌ 通用 API

证据链留存

✅ 自动截图 + 时间戳

❌ 手动实现

❌ 手动实现

智能诊断

✅ 错误根因 + 置信度

❌ 仅日志

❌ 仅日志

验证报告

✅ Markdown + 截图

❌ 需自己写

❌ 需自己写

快速验证

✅ 一键检查

❌ 需编写测试

❌ 需编写测试

核心差异:Playwright/Puppeteer 是"手"(负责操作),ValidPilot Verify 是"眼+脑"(负责检查和验证)。

Skill + MCP 协同优势

单独用 MCP

单独用 Skill

Skill + MCP 组合

✅ 136 个工具但需手动编排

✅ 有流程但缺执行能力

✅ 自动编排 + 自动执行

❌ 验证结果零散

❌ 流程模板固定

✅ 完整证据链 + 灵活配置

❌ 需手动对比差异

❌ 无法直接操控浏览器

✅ 全自动闭环

✅ 推荐配置:在 Trae 中启用 browser-dev-full-validation-skill,同时配置 ai-verify-mcp 作为 MCP Server。Skill 负责"什么时候验、验什么",MCP 负责"怎么验"。

🎨 验证流程可视化

┌─────────────────────────────────────────────────────────────┐
│                    AI 生成代码 → 验证流程                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌────────┐ │
│  │ 1. 打开   │ -> │ 2. 操作   │ -> │ 3. 断言   │ -> │ 4. 报告 │ │
│  │ browser_  │    │ browser_  │    │ browser_  │    │ evidence│ │
│  │ open      │    │ type/click│    │ assert    │    │ _pack  │ │
│  └──────────┘    └──────────┘    └──────────┘    └────────┘ │
│       │               │               │               │      │
│       ▼               ▼               ▼               ▼      │
│  📸 screenshot    📸 screenshot    📸 screenshot    📄 .md   │
│  login.png        input.png       result.png       report   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

🔄 v1.9.5 工具体系重构

重构动机与收益

v1.9.5 之前,ai-verify-mcp 注册了 137 个工具,IDE 工具列表过长,AI 模型在工具选择时容易混淆。v1.9.5 通过 mode 参数统一 + TOOL_ALIASES 别名转发机制,将功能相近的工具合并为主工具 + 子模式:

  • 工具数:137 → 154(含 59 个别名转发规则,实际主工具约 95 个)

  • 视觉噪音:IDE 工具列表大幅精简,AI 模型工具选择更准确

  • 完全向后兼容:所有旧工具名通过 TOOL_ALIASES 继续可用,不破坏任何现有调用

mode 参数使用指南

v1.9.5 起,主工具通过 mode 参数区分子模式。例如:

// 旧方式(仍然可用):调用 3 个独立工具
browser_captcha_detect({})
browser_captcha_read({})
browser_captcha_screenshot({})

// 新方式(推荐):调用 1 个主工具 + mode 参数
browser_captcha({ mode: 'detect' })
browser_captcha({ mode: 'read' })
browser_captcha({ mode: 'screenshot' })

旧工具名 → 新工具名映射表

旧工具名

新主工具

mode 值

browser_captcha_detect

browser_captcha

detect

browser_captcha_read

browser_captcha

read

browser_captcha_screenshot

browser_captcha

screenshot

browser_overlay_detect

browser_overlay

detect

browser_overlay_dismiss

browser_overlay

dismiss

browser_session_create

browser_session

create

browser_session_switch

browser_session

switch

browser_session_close

browser_session

close

browser_sessions

browser_session

list

browser_visual_baseline

browser_visual

baseline

browser_visual_compare

browser_visual

compare

browser_visual_report

browser_visual

report

browser_visual_check

browser_visual

check

browser_visual_snapshot

browser_visual

snapshot

screenshot_diff

browser_visual

diff

browser_screenshot_element

browser_screenshot

element

browser_locator_suggest

browser_locator

suggest

browser_locator_validate

browser_locator

validate

browser_find_element

browser_find

element

browser_find_page

browser_find

page

browser_performance_check

browser_performance

check

browser_performance_trace

browser_performance

trace

browser_cookies

browser_state

cookies

browser_storage

browser_state

storage

browser_debug_report

browser_debug

report

browser_diagnose

browser_debug

diagnose

debug_investigate

browser_debug

investigate

validation_quick_run

validation_check

quick

validation_report_export

validation_report

export

trace_correlation_check

trace_correlate

check

browser_trace_chain

trace_correlate

chain

browser_chain

browser_flow

chain

browser_batch

browser_flow

batch

validation_chain

validation_flow

chain

browser_errors_aggregate

browser_errors

aggregate

browser_errors_clear

browser_errors

clear

browser_events_clear

browser_events

clear

browser_smart_fill

browser_form_fill

smart

browser_network_detail

browser_network

detail

skill_mcp_validate

skill_validate

mcp_validate

skill_consistency_check

skill_validate

consistency

skill_tools_map

skill_validate

tools_map

error_fix_suggestion

error_analyze

fix

error_summary_md

error_analyze

summary

security_headers_check

security_scan

headers

security_csp_analyze

security_scan

csp

security_sql_injection_scan

security_scan

sqli

security_xss_scan

security_scan

xss

security_owasp_top10

security_scan

owasp

evidence_pack

evidence

pack

evidence_index

evidence

index

chain_list_templates

chain_spec

list

chain_spec_run

chain_spec

run

chain_score_report

chain_spec

score

mcp_health_check

mcp_diag

health

mcp_self_test

mcp_diag

self_test

contract_baseline

contract

baseline

contract_guard

contract

guard

asset_endpoint_enum

asset_discovery

enum

asset_endpoint_probe

asset_discovery

probe

asset_routes_discover

asset_discovery

routes

迁移建议

  1. v1.10.0 已移除别名:自 v1.10.0 起,TOOL_ALIASES 正式移除,旧工具名不再可用,必须使用主工具 + mode 参数

  2. 升级前必做:从 v1.9.5 升级到 v1.10.0 前,请按上方映射表将代码中所有旧工具名调用替换为主工具 + mode 参数

  3. 推荐使用新主工具:新代码直接使用主工具 + mode 参数,工具列表更简洁

  4. IDE 工具列表缓存:升级后需重启 IDE 才能在自动补全中显示新的 93 个主工具列表


📦 完整工具列表

✅ 验证框架(8个)

工具

说明

validation_check

检查点验证(负载时间、JS错误、HTTP错误等)

validation_element

元素状态验证(存在、可见、文本包含等)

validation_flow

流程验证(多步骤验证流程)

validation_quick_run

一键快速验证(7项检查)

validation_report

生成验证报告

validation_report_export

导出验证报告

browser_assert

断言验证(URL、标题、元素等)

screenshot_diff

视觉回归对比

🔍 智能诊断(9个)

工具

说明

browser_diagnose

错误自动诊断(根因分析 + 置信度)

browser_element_status

元素状态检查(可见性、可交互性、遮挡)

browser_quick_fix

快速修复(8种策略自动尝试)

browser_verify_fix

修复验证闭环

browser_debug_report

调试报告生成

browser_errors_aggregate

错误聚合统计

error_fix_suggestion

修复建议(基于规则)

error_summary_md

错误摘要(Markdown)

debug_investigate

深度调查

📸 证据收集(6个)

工具

说明

browser_screenshot

全屏截图

browser_screenshot_element

元素截图

browser_artifacts

工件管理

browser_artifacts_clear

清理工件

browser_har_export

导出 HAR 文件

browser_snapshot

页面快照

🌐 浏览器操作(21个)

完整浏览器操作能力:打开、点击、输入、滚动、等待、Cookie、存储、网络、控制台等。

🎯 智能定位(4个)

工具

说明

browser_find_element

按文本智能查找元素

browser_locator_suggest

选择器建议

browser_locator_validate

选择器验证

browser_find_page

页面类型识别

🔒 安全扫描(6个)

工具

说明

security_headers_check

HTTP 安全头部检查(CSP、HSTS、XFO 等 7 项 + 信息泄露检测)

security_csp_analyze

CSP 策略深度分析(unsafe-inline/eval 检测、评分)

security_sql_injection_scan

SQL 注入扫描(20 个 payload,多数据库错误检测)

security_xss_scan

XSS 漏洞扫描(26 个 payload,未转义检测)

security_owasp_top10

OWASP Top 10 快速检查(A1-A10 全覆盖)

api_probe

API 端点探测(多 HTTP 方法 + CORS 分析)


🔬 证据链概念

证据链是 ValidPilot Verify 的核心概念:

  1. 每步操作自动截图:时间戳 + 操作类型 + 结果状态

  2. 错误自动诊断:错误类型 + 根因分析 + 置信度评分

  3. 修复建议生成:基于规则的修复建议 + 验证闭环

  4. 报告自动生成:Markdown 报告 + 截图引用 + 诊断结果

示例证据链报告:

# 验证报告 - 登录流程

## ✅ 通过的步骤

| 步骤 | 操作 | 截图 | 时间戳 |
|------|------|------|--------|
| 1 | 打开登录页 | login-page.png | 2026-06-28T10:00:00Z |
| 2 | 输入用户名 | username-filled.png | 2026-06-28T10:00:05Z |
| 3 | 点击登录 | login-clicked.png | 2026-06-28T10:00:10Z |

## ❌ 失败的步骤

| 步骤 | 操作 | 错误 | 截图 | 诊断 |
|------|------|------|------|------|
| 4 | 验证首页 | URL不匹配 | homepage.png | 置信度 85% - 登录可能失败 |

**错误类型**: 验证失败
**置信度**: 85%
**建议**: 检查登录是否成功,查看是否有错误提示。

⚙️ 环境变量

变量

说明

默认值

MCP_MODE

MCP 运行模式(stdio/http)

stdio

MCP_HTTP_PORT

HTTP 端口

3456

VALIDPILOT_ARTIFACTS_DIR

证据存放目录

./artifacts

SCREENSHOT_QUALITY

截图质量

80


❓ 常见问题

Q: 和 browser-mcp 有什么区别?

browser-mcp 是"手"——负责操作浏览器(打开、点击、输入)。 ai-verify-mcp 是"眼+脑"——负责验证和诊断(检查结果、留存证据、诊断错误)。

两者可以配合使用:browser-mcp 操作,ai-verify-mcp 验证。

Q: 支持哪些 AI 助手?

支持所有 MCP 协议兼容的 AI 助手:Cursor、Claude Code、Windsurf、Cline 等。

Q: 证据存放在哪里?

默认存放在 ./artifacts 目录,包含截图、HAR 文件、验证报告等。

Q: 如何更新到最新版本?

详见上方 📦 更新到最新版本 章节。简要说明:

  • npx 方式:将 MCP 配置中的版本号改为 @latest 或具体新版本号(如 @1.6.9),重启 IDE

  • 全局安装:执行 npm install -g @validpilot/ai-verify-mcp@latest

  • 查看最新版本:执行 npm view @validpilot/ai-verify-mcp version

Q: 启动失败,Error: Playwright browser failed to launch

  • 原因 A: Playwright 浏览器二进制未安装

  • 解决: 运行 npx playwright install chromium

  • 原因 B: Linux 系统缺少系统依赖

  • 解决: Debian/Ubuntu 执行 apt-get install libnspr4 libnss3 libatk1.0-0 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1 libasound2

Q: MCP 连接失败,MCP error -32000: Connection closed

  • 原因: node 可执行文件路径在 MCP Host 里找不到

  • 解决: 在 MCP config 中使用 command: "npx" args: ["-y", "@validpilot/ai-verify-mcp"] 而非 node .../start-http.js

Q: 端口 3456 已被占用

  • 解决: 在 MCP config 中指定自定义端口: "env": { "MCP_HTTP_PORT": "3557" }

Q: 截图没生成到 ./artifacts

  • 检查1: 进程对当前目录有写权限

  • 检查2: 通过环境变量覆盖: "env": { "VALIDPILOT_ARTIFACTS_DIR": "C:/temp/evidence" }

  • 检查3: AI 是否真的调用了 browser_screenshot 工具(在 MCP 调试模式下看 ListTools 调用日志)


🔌 MCP Client 配置速查

所有客户端的 stdio/HTTP shape 一致,下面列出可直接复制粘贴的配置块。

在 Cursor(项目级推荐)

.cursor/mcp.json(项目根目录):

{
  "mcpServers": {
    "ai-verify-mcp": {
      "command": "npx",
      "args": ["-y", "@validpilot/ai-verify-mcp"],
      "env": {
        "MCP_HTTP_PORT": "3456"
      }
    }
  }
}

在 Claude Desktop

编辑 %APPDATA%/Claude/claude_desktop_config.json(Windows)或 ~/Library/Application Support/Claude/claude_desktop_config.json(macOS):

{
  "mcpServers": {
    "ai-verify-mcp": {
      "command": "npx",
      "args": ["-y", "@validpilot/ai-verify-mcp"],
      "env": {
        "MCP_HTTP_PORT": "3456"
      }
    }
  }
}

⚠️ Claude Desktop 只会加载用户级 config 文件,重启 Claude Desktop 才能看到新工具。

在 Windsurf

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "ai-verify-mcp": {
      "command": "npx",
      "args": ["-y", "@validpilot/ai-verify-mcp"],
      "env": {
        "MCP_HTTP_PORT": "3456"
      }
    }
  }
}

在 Claude Code(本地安装)

项目根目录的 .mcp.json:

{
  "mcpServers": {
    "ai-verify-mcp": {
      "command": "npx",
      "args": ["-y", "@validpilot/ai-verify-mcp"]
    }
  }
}

在 Cline / Continue / 其他 stdio MCP 客户端

{
  "name": "ai-verify-mcp",
  "command": "npx",
  "args": ["-y", "@validpilot/ai-verify-mcp"]
}

在 Trae IDE

两种入口二选一,推荐项目级。

方式 A:项目级(推荐,多人共享)

在项目根目录创建 .trae/mcp.json:

{
  "mcpServers": {
    "ai-verify-mcp": {
      "command": "npx",
      "args": ["-y", "@validpilot/ai-verify-mcp"],
      "env": {
        "MCP_HTTP_PORT": "3456"
      }
    }
  }
}

方式 B:用户级(全局生效)

%APPDATA%\Trae\User\mcp.json(Windows)或 ~/.config/Trae/User/mcp.json(macOS/Linux):

{
  "mcpServers": {
    "ai-verify-mcp": {
      "command": "npx",
      "args": ["-y", "@validpilot/ai-verify-mcp"],
      "env": {
        "MCP_HTTP_PORT": "3456"
      }
    }
  }
}

💡 Trae 在 settings → MCP → "+ Add" → "Raw Config (JSON)" 按钮可直接弹出对应路径;保存后重启 Trae 会话加载新工具。

⚠️ Trae MCP 限制提醒

Trae 因模型上下文窗口有限,对 MCP 引入的两道硬性上限:

限制项

上限值

触达后果

所有 MCP Server 工具描述总字符数

≈ 8000 字符

超出后按工具粒度丢弃多余的工具描述

所有 MCP Server 工具总数

≈ 40 个工具

超出后按工具粒度丢弃装不下的工具

📌 数据来源:Trae 官方 FAQ|MCP 工具 · 2026-02

大量堆叠 MCP 后,可能出现"list tools failed"或工具显示不全的现象——并非 ai-verify-mcp 自身问题,而是触达 Trae 上限后按工具粒度丢失描述。具体规避措施请参考 Trae 官方文档。

在 Codex CLI(OpenAI)

~/.codex/config.toml(TOML 格式,注意与 JSON 区别):

[mcp_servers.ai-verify-mcp]
command = "npx"
args = ["-y", "@validpilot/ai-verify-mcp"]

[mcp_servers.ai-verify-mcp.env]
MCP_HTTP_PORT = "3456"

或使用 CLI 一次性添加:

codex mcp add ai-verify-mcp -- npx -y @validpilot/ai-verify-mcp

💡 Codex CLI 默认用 stdio,HTTP 端口仅在 MCP_MODE=http 时使用;如需用 HTTP 暴露给浏览器调试,需用 start-http.js 启动后让 Codex 通过 SSE/HTTP 连接(Codex 0.40+ 支持)。

在 OpenClaw(开源 Claude Code 替代品)

~/.openclaw/openclaw.json:

{
  "mcp": {
    "servers": {
      "ai-verify-mcp": {
        "command": "npx",
        "args": ["-y", "@validpilot/ai-verify-mcp"],
        "env": {
          "MCP_HTTP_PORT": "3456"
        }
      }
    }
  }
}

💡 OpenClaw 使用 mcp.servers.<name> 嵌套结构(不是 servers 后缀是另一种风格),与 Claude Code 同源协议,可平滑迁移。

在 Hermes Agent(Nous Research)

~/.hermes/config.yaml(YAML 格式,与 JSON 路径不同):

mcp_servers:
  ai-verify-mcp:
    command: "npx"
    args: ["-y", "@validpilot/ai-verify-mcp"]
    env:
      MCP_HTTP_PORT: "3456"

或使用 CLI 交互式添加:

hermes mcp add ai-verify-mcp \
  --command "npx" \
  --args "-y,ai-verify-mcp"

💡 Hermes 会自动 discover 工具列表,启动后用 hermes tools list 可看到 browser_*、validation_* 等工具已注册。

在华为云 CodeArts(码云 IDE)

设置 → MCP工具 → "配置MCP" → 编辑 mcp_settings.json:

{
  "mcpServers": {
    "ai-verify-mcp": {
      "command": "npx",
      "args": ["-y", "@validpilot/ai-verify-mcp"],
      "env": {
        "MCP_HTTP_PORT": "3456"
      }
    }
  }
}

或在 IDE 命令面板执行:

  1. Ctrl+Shift+P → "CodeArts: Add MCP Server"

  2. 选 stdio → 填 npx → 填 -y,ai-verify-mcp

  3. 配置自动写入 mcp_settings.json

⚠️ 华为云码云建议开启 MCP 不超过 8 个,启用 3 个最佳,本工具是验证类,建议与 Playwright、Context7 等共用并设置 defer_loading 避免冲突。

在 Tencent CodeBuddy

方式 A(推荐):~/.codebuddy/.mcp.json(推荐)

~/.codebuddy/.mcp.json(全局)或项目级 .mcp.json(项目级):

{
  "mcpServers": {
    "ai-verify-mcp": {
      "command": "npx",
      "args": ["-y", "@validpilot/ai-verify-mcp"],
      "env": {
        "MCP_HTTP_PORT": "3456"
      }
    }
  }
}

方式 B:Settings.json 集成

设置 → "Add MCP" → 自动打开 settings.json,追加:

{
  "mcpServers": {
    "ai-verify-mcp": {
      "command": "npx",
      "args": ["-y", "@validpilot/ai-verify-mcp"]
    }
  }
}

💡 CodeBuddy 支持 STDIO / SSE / HTTP 三种 transports,本节配置均用 STDIO(最常用);如需用 HTTP 模式,把 command/args 替换为 url: "http://localhost:3456/sse" 即可。


🎬 演示:✅ vs ❌ 对比

❌ 没有验证(普通 AI 编程)

👤 "帮我写一个登录页"
🤖 "已生成 login.html / login.js ..."
👤 "能跑吗?"
🤖 "应该没问题"
👤 "......"   ❌ 没有证据

✅ 使用 ValidPilot Verify

👤 "帮我写一个登录页,跑完之后验证一下"
🤖 "好的,我边写边验证:
    1. 打开页面 → validation_quick_run ✅
    2. 输入用户名 → screenshot 已留存
    3. 输入密码 → screenshot 已留存
    4. 点击登录 → screenshot + URL断言 ✅
    5. 验证首页 → evidence/report.md ✅
👤 *(点击 evidence/login-flow-report.md 查看截图证据)*

完整证据链文件结构:

artifacts/
├── step-1-login-page.png
├── step-2-username-typed.png
├── step-3-password-typed.png
├── step-4-login-clicked.png
├── step-5-home-verified.png
└── login-flow-report.md

📦 发布自动化

发布到 npm 时会自动执行健康校验。

{
  "scripts": {
    "start": "node server.js",
    "http": "node start-http.js",
    "cli": "node bin/validpilot.js",
    "validate": "node bin/validpilot.js health",
    "pack:dry": "npm pack --dry-run",
    "prepublishOnly": "node bin/validpilot.js health && npm pack --dry-run"
  }
}

执行流程:

$ npm publish
> @validpilot/ai-verify-mcp@1.6.9 prepublishOnly
> node bin/validpilot.js health && npm pack --dry-run

{ "ok": true, "name": "@validpilot/ai-verify-mcp", "version": "1.6.9", ... }
npm notice package size: 649.9 kB
npm notice total files: 220
+ @validpilot/ai-verify-mcp@1.6.9 → 上传 npm registry

发布前可手动验证:

  • npm run validate → Playwright 健康检查

  • npm run pack:dry → 打包预览(不实际打包)


🙏 致谢

感谢以下项目和技术的启发:


💬 社区与联系

钉钉交流群

扫码加入 ai-verify-mcp 官方交流群,提问、反馈、交流最佳实践:

钉钉交流群

此二维码永久有效

联系邮箱

📧 validpilot@outlook.com

  • 商务合作

  • 安全漏洞报告(请优先使用 SECURITY.md 流程)

  • 其他问题


❤️ 支持捐赠 / Donations

感谢您对本项目的关注与支持!如果您觉得这个项目对您有帮助,欢迎通过捐赠的方式给予鼓励。

Thank you for your interest and support! If you find this project helpful, consider buying me a coffee.

捐赠将用于项目维护、功能开发、服务器开销等,所有资金将透明公开,专款专用。

Donations will be used for project maintenance, feature development, and server costs. All funds will be transparent and project-dedicated.

捐赠方式 / Donation Methods

支付宝 (Alipay)

微信支付 (WeChat)

PayPal

支付宝

微信支付

PayPal

无论金额大小,都是对我莫大的鼓励。再次感谢您的支持!

No matter the amount, every bit of support means a lot. Thank you!

GitHub Sponsors:暂未开通,敬请期待。Not yet available, stay tuned.


Contributing:欢迎贡献!阅读 CONTRIBUTING.md 了解如何参与。请遵守 Code of Conduct。

Security:发现漏洞?查看 SECURITY.md 了解安全策略。

AI Agents:你是 AI Agent?查看 AGENTS.md 获取编码指南和项目约定。

License:MIT © 2026 ValidPilot

📜 许可证

MIT © 2026 ValidPilot Team


Don't just generate, verify. 让 AI 编程可信赖。

Available Tools

142 tools
api_probeA

API endpoint prober: sends multiple HTTP methods (GET/POST/PUT/DELETE/PATCH/OPTIONS) to the target URL, analyzes response status, content-type, and CORS configuration. Supports custom headers and body, suitable for API security testing and endpoint discovery.

中文详情:

  • 用途:API 端点探测工具,向目标 URL 发送多种 HTTP 方法,分析响应状态、内容类型和 CORS 配置,支持自定义请求头和请求体

  • 何时使用:API 安全测试时探测允许的方法;CORS 配置验证时;端点发现/枚举时;OPTIONS 预检请求行为验证时

  • 输出:{ ok: boolean, url: string, results: array, corsAnalysis: object } — results 每项含 { method, status, contentType, contentLength, allowed }; corsAnalysis 含 { enabled, allowedOrigins, allowCredentials }

  • 参数:

    • url (string, 必填):目标 API URL

    • methods (array, 可选):要测试的 HTTP 方法列表,默认 ["GET","POST","PUT","DELETE","PATCH","OPTIONS"]

    • headers (object, 可选):自定义请求头,如 {"Authorization":"Bearer token","Content-Type":"application/json"}

    • body (string, 可选):请求体(POST/PUT/PATCH 方法使用)

    • checkCors (boolean, 可选):是否分析 CORS 配置,默认 true

  • 错误:URL 不可达抛出 'Request failed';methods 为空数组使用默认方法列表

  • 示例:{"url":"https://api.example.com/users","methods":["GET","POST","OPTIONS"],"headers":{"Authorization":"Bearer token"},"checkCors":true}

Inputs: url (required), body, headers, methods, +1 more.

asset_discoveryA

v1.9.5 起合并 asset_routes_discover / asset_endpoint_enum / asset_endpoint_probe 三大资产发现工具。通过 mode 参数切换:routes=前端路由发现;enum=API 端点枚举;probe=端点主动探测。需要先 browser_open 打开页面。

Inputs: mode, method, timeout, basePath, +5 more.

asset_routes_discoverA

开源版浅层路由发现:从 DOM 链接、hash 路由、内联脚本、已加载 JS bundle 以及 network 日志中静态提取前端路由(SPA / hash / REST 路径)。仅做被动分析,不发起主动探测或越权访问。需要先 browser_open 打开页面。

Inputs: maxScripts.

browser_a11y_checkA

Run an axe-core accessibility check on the current page, supporting scan-scope restriction, exclude regions, and rule-tag filtering, returning a violations summary.

中文详情:

  • 用途:使用 axe-core 对当前页面执行可访问性检查,支持限定扫描范围、排除区域和规则标签过滤,返回 violations 摘要

  • 何时使用:上线前 WCAG 合规检查时;可访问性自动化回归时;排查元素缺少 aria-label/alt 时;针对特定组件做 a11y 局部扫描时

  • 输出:{ ok: boolean, url: string, total: number, violations: array, passes: number, incomplete: number, summary: string } — 每项含 { id, impact, tags, description, help, nodes: array }

  • 参数:

    • selector (string, 可选):CSS 选择器;指定后只扫描该区域

    • excludeSelectors (array, 可选):排除扫描的 CSS 选择器列表

    • tags (array, 可选):axe runOnly 标签,如 wcag2a/wcag2aa/best-practice

    • sessionName (string, 可选):浏览器会话名称,默认当前活跃会话

  • 错误:浏览器未启动抛出 'Browser not launched';selector 无匹配抛出 'element not found'

  • 示例:{"selector":"main","excludeSelectors":[".ad-banner"],"tags":["wcag2a","wcag2aa"]}

Inputs: tags, selector, sessionName, excludeSelectors.

browser_aria_typeA

通过可访问性树的 ref 稳定标识符定位元素并输入文本。与 browser_aria_snapshot 配合使用:先用 snapshot 获取元素的 ref,再用此工具输入文本。自动清空元素已有内容后再输入。不依赖 CSS 选择器,CSS 重构后定位仍然稳定有效。

Inputs: ref (required), text (required).

browser_artifactsA

列出当前 MCP 浏览器验证产生的证据产物:截图、trace.zip、HAR、HTML reports、visual 视觉产物、日志文件和当前 checkpoint。

Inputs: no named parameters.

browser_captchaB

验证码处理工具(v1.9.5 起合并 browser_captcha_detect/read/screenshot)。通过 mode 参数区分子模式:detect(默认,检测验证码类型和复杂度)/ read(OCR 识别验证码文本)/ screenshot(精准截取验证码区域保存 PNG)。

Inputs: url, mode, minSize, padding, +5 more.

browser_captcha_readA

读取页面中的验证码图片,支持从图片URL直接提取文字(适用于简单验证码服务),以及使用OCR识别复杂验证码。当识别失败或置信度较低时,会返回验证码图片供人工识别。

Inputs: url, captchaIndex, captchaSelector.

browser_captcha_screenshotA

精准截取验证码图片区域,保存为PNG文件。支持自动检测验证码位置或手动指定选择器。截图文件可用于后续OCR分析或人工识别。

Inputs: url, minSize, padding, savePath, +2 more.

browser_chainA

链式执行多个浏览器操作,每步操作后自动检查控制台错误和网络错误。发现错误可立即终止并返回失败步骤。支持强制执行模式,开启时强制进行错误检查且不可关闭。step.type 与 step.action 互为别名,二者至少传一个。

Inputs: actions (required), stopOnError, includeConsole, includeNetwork, +1 more.

browser_clickA

Click a DOM element matched by CSS selector in a real browser. Returns multi-element hint (not timeout) when selector matches multiple elements; use index to pick which one.

中文详情:

  • 用途:在真实浏览器中模拟鼠标点击指定 CSS 选择器元素(按钮、链接、tab、复选框等)

  • 何时使用:触发导航或表单提交时;激活 UI 控件(展开菜单、切换 tab)时;验证按钮可点击性时;在 browser_snapshot 获取元素 ref 后进行交互时

  • 输出:{ ok: boolean, clickedSelector: string, beforeHash: string, afterHash: string, index: number } — afterHash 与 beforeHash 不同表示触发了页面变更

  • 参数:

    • selector (string, 必填):CSS 选择器,支持 Playwright 语法如 'button:has-text("Log In")' 或 '#submit-btn'

    • index (number, 可选):当选择器匹配多个元素时,指定点击第几个(从 0 开始),默认点击第一个

  • 错误:选择器无匹配抛出 'element not found';元素被遮挡抛出 'element not clickable'

  • 示例:{"selector":"#submit-btn","index":0}

Inputs: selector (required), index.

browser_click_auditA

Audit a single click: screenshot before→click→wait→screenshot after→image diff→error collection→return. One call replaces 6+ individual tool calls for click-through validation loops. Returns navigation status, visual diff ratio, console/network errors, silentFail errors (HTTP 2xx with error body), and screenshot paths.

Inputs: text, label, waitMs, selector, +1 more.

browser_consoleA

查看浏览器控制台日志,支持按类型过滤(level: log/warning/error/debug/info)。

覆盖范围:所有 console.error/warn/log/debug、window.onerror 同步异常、unhandledrejection 未处理 Promise 拒绝。

边界说明:

  • 跨域脚本(Script error.):当 标签指向第三方域名且缺少 crossorigin="anonymous" 属性时,只能显示 'Script error.' 而无法获取详情。已自动检测并标记 crossOrigin:true。

  • 极端早期错误:在 addInitScript 执行前发生的 inline 内联同步错误可能遗漏。CDP 层 page.on('console') 可捕获大部分,但 document.write() 中的错误可能被页面渲染流程吞没。

Inputs: level, limit, since, urlContains.

browser_cookiesA

查看和管理浏览器Cookie。支持获取所有Cookie、按域名筛选、设置Cookie、清除Cookie。返回Cookie总数、每个Cookie的详细信息(名称、值、域名、路径、过期时间、安全标志等)。调试时可快速查看登录态、Token等认证信息。

Inputs: name, action, cookie, domain.

browser_counterfactual_analyzeA

反事实根因分析 - 当测试失败时,分析"如果消除因素X(遮挡物/JS错误/HTTP错误/加载问题),测试是否还会失败",自动生成根因假设并按置信度排序,给出验证工具建议

Inputs: format, failureContext.

browser_data_compareB

数据一致性比对:提取页面表格、卡片、列表数据,与期望数据或基准数据进行比对,识别数据缺失、格式错误、内容差异。支持多种数据源:DOM表格、JSON响应、localStorage、API返回数据。

Inputs: apiBody, session, selector, apiMethod, +9 more.

browser_debugA

浏览器调试诊断工具(v1.9.5 起合并 browser_debug_report/browser_diagnose/debug_investigate)。通过 mode 参数区分子模式:report(默认,生成调试报告汇总页面状态、错误日志、网络错误)/ diagnose(自动诊断浏览器错误根因,返回 rootCause/confidence/suggestedFixes)/ investigate(输入问题症状,自动汇总 errors/events/network/DOM/storage/artifacts 并输出假设和证据链)。

Inputs: mode, focus, limit, symptom, +9 more.

browser_debug_reportA

生成当前浏览器调试报告,汇总页面状态、错误日志、网络错误、可选 DOM 与存储信息

Inputs: includeDom, includeStorage.

browser_diagnoseA

自动诊断浏览器错误根因。分析控制台错误、页面错误、网络错误、元素状态、JS执行状态,定位问题根源(如元素未加载、JS未执行、网络超时、权限不足等)。返回诊断报告含 rootCause、confidence、suggestedFixes、affectedElements。

Inputs: selector, errorType, includeStackTrace.

browser_domA

Query detailed DOM state of a single element matched by CSS selector: visibility, text, attributes, computed style, and bounding box position.

中文详情:

  • 用途:查询指定 CSS 选择器元素的完整 DOM 状态,包括可见性、文本、属性、计算样式和位置坐标

  • 何时使用:点击/输入前确认元素存在且可见时;调试元素被遮挡问题时;验证元素属性(disabled/readonly/checked)时;获取元素位置坐标用于截图时

  • 输出:{ ok: boolean, selector: string, exists: boolean, visible: boolean, text: string, attributes: object, computedStyle: object, boundingBox: { x, y, width, height } }

  • 参数:

    • selector (string, 必填):要查询的 CSS 选择器

  • 错误:选择器无匹配返回 exists=false 但不抛出;选择器语法错误抛出 'Invalid selector'

  • 示例:{"selector":"#submit-btn"}

Inputs: selector (required).

browser_element_statusA

诊断元素状态(可见性、可交互性、加载状态、遮挡情况、事件绑定)。快速判断元素为何无法点击/输入,返回具体原因(如被遮挡、不可见、disabled、未加载、动画中、z-index问题等)和修复建议。

Inputs: selector (required), checkEvents, checkVisibility, checkInteractability.

browser_emulate_deviceB

模拟指定设备(iPhone/Android/平板)的完整特性,包括 User-Agent、视口尺寸、触摸事件、像素密度等。支持预设设备列表和自定义设备配置。

Inputs: touch, device, locale, timezone, +6 more.

browser_errorsA

统一错误管理工具(v1.9.5 起合并 browser_errors_aggregate 和 browser_errors_clear)。通过 mode 参数区分子模式:view(默认,查看本轮 Console/PageError/HTTP 4xx 5xx/静默失败错误)/ aggregate(去重聚合并返回 Top errors)/ clear(清空错误日志并创建新 checkpoint)。

Inputs: mode, limit, since, method, +5 more.

browser_errors_aggregateA

收集或接收浏览器 Console/Network/PageError/DOM 摘要,去重聚合并返回 Top errors;默认不返回完整日志。

Inputs: limit, evidence, includeCurrentPage.

browser_errors_clearA

清空当前浏览器运行时 Console/PageError/Network 错误日志并创建新的验证 checkpoint,用于隔离本轮验证错误。

Inputs: no named parameters.

browser_evalA

在当前浏览器页面执行调试 JavaScript 表达式并返回可序列化结果。返回值会自动脱敏 token、password、apiKey、Authorization 等敏感字段。

Inputs: expression (required).

browser_eventsA

运行时事件管理工具(v1.9.5 起合并 browser_events_clear)。通过 mode 参数区分子模式:view(默认,查看 browser_instrument 捕获的事件流,支持按类型/URL/方法/状态码过滤)/ clear(清空运行时事件并创建新的事件 checkpoint)。

Inputs: mode, type, limit, since, +3 more.

browser_events_clearA

清空 browser_instrument 捕获的运行时事件并创建新的事件 checkpoint。

Inputs: no named parameters.

browser_findA

智能查找工具(v1.9.5 起合并 browser_find_element/find_page)。通过 mode 参数区分子模式:element(默认,按文本描述或 ARIA 角色智能定位页面元素)/ page(按目标页面关键词定位页面,支持 SPA 按钮导航发现)。

Inputs: mode, role, text, limit, +5 more.

browser_find_elementA

Smart element locator: find visible DOM elements by text description or ARIA role using multi-strategy matching (exact text > contains text > placeholder > aria-label > title/alt > fuzzy), returning CSS selectors and confidence scores sorted by score desc.

中文详情:

  • 用途:按自然语言文本描述或角色智能定位页面元素,返回 CSS 选择器、置信度和元素信息

  • 何时使用:不知道选择器但知道按钮文案时;UI 文案变化后定位元素时;批量自动化脚本根据文案定位时;测试无 id/name 属性的元素时

  • 输出:{ ok: boolean, results: array, total: number } — 每项含 { selector, text, role, tagName, confidence, visible }

  • 参数:

    • text (string, 必填):要查找的元素文本

    • role (string, 可选):元素角色,如 button/link/input/textbox/checkbox/radio/combobox

    • tagName (string, 可选):标签名过滤,如 button/a/input/div

    • onlyVisible (boolean, 可选):只返回可见元素,默认 true

    • limit (number, 可选):返回数量,默认 5

  • 错误:无匹配元素返回空数组但 ok=true;text 为空抛出 'Text is required'

  • 示例:{"text":"提交","role":"button","limit":3}

Inputs: text (required), role, limit, tagName, +1 more.

browser_find_pageA

Smart page discovery: locate target page (login/signup/home/dashboard/admin/settings/profile/etc.) by priority chain (URL path > title > CSS selector > SPA button text > nav region > visible text), returns matched links and suggested navigation URL; optionally auto-navigate.

中文详情:

  • 用途:根据目标页面关键词(login/signup/home/dashboard/admin/settings/profile 等)快速定位页面,支持 SPA 应用的按钮导航发现

  • 何时使用:测试入口页(登录/注册/后台)未直接知晓 URL 时;SPA 应用通过按钮导航时;导航回归测试时;权限切换后定位目标页时

  • 输出:{ ok: boolean, target: string, matched: boolean, matchMethod: string, score: number, links: array, buttons: array, suggestedUrl: string, navigated: boolean }

  • 参数:

    • target (string, 必填):目标页面类型,可选 login/signup/home/dashboard/admin/settings/profile/search/cart/checkout/forgot-password/reset-password/logout/all

    • navigate (boolean, 可选):是否自动导航到发现的页面,默认 false

    • baseUrl (string, 可选):基础 URL,用于尝试常见路径,不指定时从当前 URL 推导

  • 错误:target 值非法抛出 'Invalid target';未匹配且 navigate=true 时返回 matched=false

  • 示例:{"target":"login","navigate":true,"baseUrl":"https://example.com"}

Inputs: target (required), baseUrl, navigate.

browser_flowA

多步浏览器流程编排工具(v1.9.5 起合并 browser_chain 和 browser_batch),按步骤依次执行 open/click/type/wait/assert/eval/screenshot/snapshot/scroll/hover/select/navigate/har/step/clearErrors 等操作,每步自动捕获证据(截图+快照)。step.type 与 step.action 互为别名,二者至少传一个。通过 mode 参数区分子模式:flow(默认,标准编排)/ chain(链式,每步检查 console+network 错误,等价于 browser_chain)/ batch(批量,受 maxSteps 限制,等价于 browser_batch)。与 validation_flow 的区别:browser_flow 侧重浏览器操作编排,支持更多浏览器原生操作(open/har/snapshot/scroll/hover/select 等);validation_flow 侧重验证语义,仅支持 navigate/click/type/wait/eval/screenshot 6 种操作。

Inputs: steps (required), mode, actions, maxSteps, +5 more.

browser_form_fillA

表单填充工具(v1.9.5 起合并 browser_smart_fill)。通过 mode 参数区分子模式:basic(默认,批量填充表单字段并可选提交检测,支持 CSS 选择器模式和字段名模式)/ smart(智能填充单个字段,按 fieldType 自动生成符合格式的测试数据,等价于已废弃的 browser_smart_fill)。

中文详情:

  • 用途:批量或智能填充表单字段并可选提交检测

  • 何时使用:登录/注册表单批量填写时;多字段表单快速测试时;表单提交流程端到端验证时;需要 mock 数据填充表单时

  • 输出:basic 模式返回 { ok, url, filledFields, submitResult, timestamp };smart 模式返回 { success, selector, fieldType, value }

  • 参数:

    • mode (string, 可选):basic(默认)/ smart

    • url (string, basic 模式必填):目标页面 URL

    • selector (string, 可选):表单选择器(basic 模式)或字段选择器(smart 模式必填)

    • fields (object, basic 模式可选):手动指定的字段值

    • fieldType (string, smart 模式必填):字段类型(email/phone/name/address/idCard/number/text/url/date/password)

    • options (object, smart 模式可选):数据生成选项

    • submit (boolean, 可选):basic 模式填充后是否自动提交,默认 true

    • submitSelector (string, 可选):提交按钮选择器

Inputs: url (required), mode, fields, submit, +4 more.

browser_form_validateA

Auto-detect form field validation rules (required, pattern, length, etc.) and run a complete validation flow. Detects HTML5 validation attributes and outputs a detailed report per field.

中文详情:

  • 用途:自动检测表单字段验证规则(必填、格式、长度等),执行完整表单验证流程并输出详细验证报告

  • 何时使用:测试表单校验规则实现是否正确时;提交空表单验证必填提示时;测试 email/url 格式校验时;验证最小/最大长度限制时

  • 输出:{ ok: boolean, url: string, formSelector: string, totalFields: number, fields: array, validationPassed: boolean } — 每项含 { selector, name, type, required, pattern, minLength, maxLength, valid, message }

  • 参数:

    • url (string, 可选):要检测表单的目标 URL,不提供则使用当前页面

    • formSelector (string, 可选):表单选择器,不提供则自动检测页面第一个表单

    • validateSubmit (boolean, 可选):是否尝试提交表单检测验证,默认 true

    • checkRequired (boolean, 可选):是否检测必填字段,默认 true

    • checkPattern (boolean, 可选):是否检测格式模式(email、url 等),默认 true

    • checkLength (boolean, 可选):是否检测长度限制,默认 true

  • 错误:页面无表单抛出 'No form found';URL 不可达抛出 'Navigation failed'

  • 示例:{"url":"https://example.com/register","formSelector":"#signup-form","checkRequired":true}

Inputs: url, checkLength, checkPattern, formSelector, +2 more.

browser_full_auditA

对当前页面执行全量错误审计,聚合所有错误来源(CDP console + 注入脚本 + 网络 4xx/5xx + 响应体静默失败 + 资源加载错误 + 未处理的 Promise 拒绝 + 跨域脚本错误)。

返回分层报告:

  • summary: 各类别错误计数

  • consoleErrors: CDP 控制台错误列表

  • injectedErrors: 注入脚本捕获的错误列表(含堆栈)

  • networkErrors: HTTP 4xx/5xx 请求列表

  • silentFailures: HTTP 200 但响应体含 SQL 错误/异常信息的请求

  • resourceErrors: 资源加载失败(img/script/link 加载错误)

  • unhandledRejections: 未处理的 Promise 拒绝

  • crossOriginErrors: 跨域脚本错误(Script error.)

  • runtimeErrors: 运行时 JS 异常(含堆栈)

  • diagnostics: 诊断建议

使用场景:在页面加载完成后或交互操作后,调用此工具进行全面健康检查。

Inputs: since, includeWarnings.

browser_full_regressionA

强制执行的浏览器全功能闭环回归验证。自动发现页面上所有可交互功能(链接和按钮),逐个点击验证功能正常工作,检查 Console/Network 错误,验证每个功能的闭环完整性(可进入、可返回)。默认目标 URL: http://localhost:5173

Inputs: url, timeout, visible, maxDepth, +2 more.

browser_har_exportA

将当前采集的网络记录导出为简化 HAR JSON 文件,包含请求/响应头、请求/响应体摘要、状态码和耗时。输出自动脱敏。

Inputs: name, since, method, contains, +4 more.

browser_highlightA

Highlight a specific element on the page with a colored border and shadow for human observation and debugging. Effect persists until page refresh.

中文详情:

  • 用途:在页面上高亮显示指定元素(默认红色边框和阴影),便于人工观察和调试

  • 何时使用:调试元素定位问题时;演示/评审时强调某个元素;视觉走查时标记可疑元素;自动化失败后人工复核时

  • 输出:{ ok: boolean, selector: string, color: string, timestamp: string }

  • 参数:

    • selector (string, 必填):要高亮的元素选择器

    • color (string, 可选):高亮颜色,支持 CSS 颜色值,默认 red

  • 错误:selector 无匹配抛出 'element not found';color 值非法会使用默认红色

  • 示例:{"selector":".error-message","color":"#ff6600"}

Inputs: selector (required), color.

browser_hoverA

Hover the mouse over a DOM element matched by CSS selector to trigger hover effects, tooltips, and dropdown menus.

中文详情:

  • 用途:将鼠标悬浮到指定 CSS 选择器元素上,触发 hover 效果、tooltip、下拉菜单等交互

  • 何时使用:测试二级菜单展开时;验证 tooltip 显示内容时;触发 hover 状态样式变化时;测试 hover 触发的异步加载时

  • 输出:{ ok: boolean, hoveredSelector: string, timestamp: string }

  • 参数:

    • selector (string, 必填):目标元素的 CSS 选择器

  • 错误:选择器无匹配抛出 'element not found';元素不可见抛出 'element not visible'

  • 示例:{"selector":".user-menu-trigger"}

Inputs: selector (required).

browser_instrumentB

向当前页面注入运行时调试探针,捕获 fetch/XHR、console error/warn、全局错误、点击、输入、路由和 storage 变化。

Inputs: headless.

browser_lighthouse_auditA

Run a Google Lighthouse audit on the current page, returning Performance, Accessibility, Best Practices, and SEO scores plus key diagnostic advice. Each audit spins up an isolated headless Chrome instance (no interference with the active session) and shuts down afterwards.

中文详情:

  • 用途:对当前页面执行 Google Lighthouse 审计,返回性能、可访问性、最佳实践、SEO 评分及关键诊断建议,每次审计启动独立 Headless Chrome 实例并自动关闭

  • 何时使用:上线前综合质量评估时;性能/可访问性/SEO 多维度评分时;Lighthouse 评分回归监控时;Core Web Vitals 与 SEO 优化建议获取时

  • 输出:{ ok: boolean, url: string, scores: { performance, accessibility, bestPractices, seo }, metrics: object, diagnostics: array, reportPath: string } — metrics 含 lcp/fid/cls/tbt/si

  • 参数:

    • url (string, 可选):要审计的 URL,默认为当前浏览器页面的 URL

    • categories (array, 可选):要审计的类别,可选 performance/accessibility/best_practices/seo,默认全部

    • formFactor (string, 可选):模拟设备类型,可选 mobile/desktop,默认 desktop

    • throttling (boolean, 可选):是否模拟网络节流(3G 模拟),仅 mobile 模式下推荐启用,默认 false

  • 错误:URL 不可达抛出 'Audit failed';Lighthouse 启动失败抛出 'Lighthouse launch failed'

  • 示例:{"url":"https://example.com","categories":["performance","accessibility"],"formFactor":"mobile","throttling":true}

Inputs: url, categories, formFactor, throttling.

browser_locatorA

选择器定位工具(v1.9.5 起合并 browser_locator_suggest/validate)。通过 mode 参数区分子模式:suggest(默认,基于已有 selector 命中元素或 target 文本生成稳定推荐选择器)/ validate(验证选择器稳定性,统计匹配数量并输出评分和风险)。

Inputs: mode, target, selector, sessionName.

browser_locator_suggestA

基于已有 selector 命中的元素或 target 文本查找可见元素,按可访问属性生成更稳定的推荐选择器、评分、风险和 fallback 列表。

Inputs: target, selector, sessionName.

browser_locator_validateA

验证选择器稳定性,统计匹配数量、可见数量,并按 role/label/placeholder/data-testid/text/id/css/xpath 等规则输出分数、风险、警告和建议。

Inputs: selector (required), sessionName.

browser_matrix_testA

跨浏览器矩阵测试。在指定的多个浏览器引擎上依次执行相同的操作序列,返回各浏览器的执行结果对比。支持 chromium / firefox / webkit 任意组合。自动管理浏览器的创建和关闭,每个浏览器独立隔离。符合产品定位 v2.0 能力补齐方案 §P0-6。step.action 与 step.type 互为别名,二者至少传一个。

Inputs: steps (required), timeout, browsers, headless.

browser_memory_checkA

Memory leak detection: via Performance API, measures detached DOM node count, event-listener leak risk, JS heap size, and total DOM node count, returning a leak-risk assessment and optimization suggestions.

中文详情:

  • 用途:内存泄漏检测,通过 Performance API 检测 detached DOM 节点数量、事件监听器泄漏风险、JS 堆大小和 DOM 节点总数,返回泄漏风险评估和优化建议

  • 何时使用:SPA 长时间运行内存增长排查时;路由切换后 DOM 节点未释放验证时;事件监听器泄漏排查时;上线前内存基线评估时

  • 输出:{ ok: boolean, heapSize: number, heapUsed: number, domNodeCount: number, detachedDomCount: number, listenerLeakRisk: boolean, riskLevel: string, recommendations: array }

  • 参数:

    • sessionName (string, 可选):浏览器会话名称,默认当前活跃会话

  • 错误:浏览器未启动抛出 'Browser not launched';Performance API 不可用抛出 'Performance API not available'

  • 示例:{"sessionName":"long-running-session"}

Inputs: sessionName.

browser_navigateA

Navigate the browser: go forward, back, refresh, or reload the current page with configurable wait conditions.

中文详情:

  • 用途:控制浏览器导航操作(前进/后退/刷新/重新加载当前页面)

  • 何时使用:在 browser_open 打开页面后需要控制加载状态时;表单提交后需要 reload 重置状态时;测试浏览器后退/前进按钮行为时;页面资源加载不完整需要 refresh 时

  • 输出:{ ok: boolean, url: string, action: string, timestamp: string }

  • 参数:

    • action (string, 必填):导航操作,可选 forward / back / refresh / reload,默认 refresh

    • waitUntil (string, 可选):等待条件,可选 domcontentloaded / load / networkidle,默认 domcontentloaded

    • timeout (number, 可选):超时毫秒数,默认 30000

  • 错误:超时抛出 'Timeout XXXXms exceeded';无效 action 值抛出 'Invalid action'

  • 示例:{"action":"refresh","waitUntil":"networkidle","timeout":10000}

Inputs: action (required), timeout, waitUntil.

browser_networkA

网络请求管理工具(v1.9.5 起合并 browser_network_detail)。通过 mode 参数区分子模式:list(默认,获取网络请求记录列表,支持按 URL/方法/状态码/checkpoint 过滤)/ detail(查看网络请求详情,包括请求头、响应头、请求体、响应体摘要、耗时和失败原因,等价于已废弃的 browser_network_detail)。

Inputs: mode, since, method, contains, +4 more.

browser_network_detailA

查看本轮网络请求详情,包括请求头、响应头、请求体、响应体摘要、耗时和失败原因。输出自动脱敏。

Inputs: limit, since, method, contains, +4 more.

browser_openA

Launch a real (visible by default) browser instance and navigate to the target URL. Supports chromium, firefox, and webkit engines.

中文详情:

  • 用途:启动真实可视化浏览器并导航到指定 URL,是所有浏览器交互测试的入口

  • 何时使用:开始一个新的浏览器测试会话时;需要可视化观察页面行为时;切换浏览器引擎做兼容性验证时;调试需要看到真实渲染时

  • 输出:{ ok: boolean, url: string, browserType: string, headless: boolean, sessionId: string, title: string, timestamp: string }

  • 参数:

    • url (string, 必填):要打开的页面 URL

    • browserType (string, 可选):浏览器引擎,可选 chromium / firefox / webkit,默认 chromium

    • headless (boolean, 可选):是否无头模式,默认 false(可视化验证建议 false)

  • 错误:URL 缺失或格式非法抛出 'Invalid url';浏览器启动失败抛出 'Browser launch failed'

  • 示例:{"url":"https://example.com/login","browserType":"chromium","headless":false}

Inputs: url (required), headless, browserType.

browser_overlayA

遮挡物处理工具(v1.9.5 起合并 browser_overlay_detect/dismiss)。通过 mode 参数区分子模式:detect(默认,检测页面遮挡元素如弹窗/Cookie 横幅/浮层)/ dismiss(自动识别并点击关闭常见遮挡物)。

Inputs: mode, format.

browser_overlay_detectA

遮挡物检测 - 在 DOM 层面自动检测页面上的遮挡元素(弹窗、Cookie横幅、浮层、色块遮挡等),分析 z-index、position、覆盖面积等属性,返回遮挡物列表和建议

Inputs: format.

browser_overlay_dismissB

遮挡物自动关闭 - 自动识别并点击关闭常见遮挡物(Cookie横幅、弹窗、浮层、遮罩等),支持多种关闭按钮选择器模式

Inputs: format.

browser_performanceA

性能分析工具(v1.9.5 起合并 browser_performance_check/trace)。通过 mode 参数区分子模式:check(默认,采集当前页面性能指标并按预算评估)/ trace(记录完整性能轨迹并输出 HAR 和结构化数据)。

Inputs: url, mode, budgets, duration, +5 more.

browser_performance_checkA

Collect current page performance metrics (navigation, paint, resource, long task, CLS/LCP) and evaluate against budgets. Enhanced with Core Web Vitals deep analysis (LCP/FCP/TTFB/CLS scoring).

中文详情:

  • 用途:采集当前页面 navigation/paint/resource/long task/CLS/LCP 等性能指标,按 budgets 输出性能预算结果,并集成 Core Web Vitals 深度分析

  • 何时使用:上线前性能基线评估时;Core Web Vitals 达标验证时;慢请求/长任务定位时;性能预算(budgets)门禁检查时

  • 输出:{ ok: boolean, metrics: object, budgets: object, passed: boolean, violations: array, coreWebVitals: { lcp, fcp, cls, ttfb, score } } — metrics 含 domContentLoaded/load/fcp/lcp/cls/longTaskCount/resourceCount

  • 参数:

    • budgets (object, 可选):预算阈值,支持 domContentLoaded/load/fcp/lcp/cls/longTaskCount/resourceCount/slowRequestMs

    • slowRequestMs (number, 可选):慢请求阈值毫秒,默认 1000;可覆盖 budgets.slowRequestMs

    • sessionName (string, 可选):浏览器会话名称,默认当前活跃会话

  • 错误:浏览器未启动抛出 'Browser not launched';budgets 字段类型错误抛出 'Invalid budget'

  • 示例:{"budgets":{"lcp":2500,"cls":0.1,"longTaskCount":5},"slowRequestMs":800}

Inputs: budgets, sessionName, slowRequestMs.

browser_performance_traceA

Record a complete performance trace (paint/timing/resource) and output HAR plus structured performance data. Supports W3C Performance Timeline API to capture FP/FCP/LCP/CLS core metrics.

中文详情:

  • 用途:记录完整的性能轨迹(Paint/Timing/Resource),输出 HAR 格式和结构化性能数据,支持 W3C Performance Timeline API 获取 FP/FCP/LCP/CLS 等核心指标

  • 何时使用:性能瓶颈深度分析时;HAR 文件取证时;前端渲染瀑布图分析时;FCP/LCP 异常排查时

  • 输出:{ ok: boolean, tracePath: string, harPath: string, metrics: object, entries: array, duration: number } — metrics 含 fp/fcp/lcp/cls/tbt;entries 为 PerformanceEntry 列表

  • 参数:

    • url (string, 可选):要追踪性能的目标 URL,不提供则使用当前页面

    • categories (array, 可选):要记录的性能类别,默认 ["navigation","resource","paint","longtask"]

    • duration (number, 可选):追踪持续时间(毫秒),默认 5000

    • enableScreenshots (boolean, 可选):是否在追踪期间定期截图,默认 false

    • exportHar (boolean, 可选):是否导出 HAR 格式数据,默认 true

  • 错误:浏览器未启动抛出 'Browser not launched';duration 过大可能影响响应时间

  • 示例:{"url":"https://example.com","categories":["navigation","paint","longtask"],"duration":10000,"exportHar":true}

Inputs: url, duration, exportHar, categories, +1 more.

browser_press_keyA

Press a keyboard key or combo on the current page or focused element. Supports single keys (Enter, Escape, Tab, ArrowDown) and combos (Control+c, Shift+Tab).

中文详情:

  • 用途:在当前页面或指定元素上按下键盘按键,支持单个按键或组合键(如 Control+c)

  • 何时使用:表单输入后按 Enter 提交时;模态框按 Escape 关闭时;下拉菜单用 ArrowDown 导航时;快捷键组合测试时

  • 输出:{ ok: boolean, key: string, selector: string|null, timestamp: string }

  • 参数:

    • key (string, 必填):按键名称,如 Enter/Escape/Tab/ArrowDown/Backspace/a/Control+c

    • selector (string, 可选):在指定元素上按键(先聚焦再按键)

  • 错误:key 为空抛出 'Key is required';selector 无匹配抛出 'element not found'

  • 示例:{"key":"Enter","selector":"#search-input"}

Inputs: key (required), selector.

browser_quick_fixA

快速修复验证闭环。自动尝试常见修复策略(等待加载、滚动到元素、强制可见、移除遮挡、注入JS等),每步验证是否修复成功。返回修复尝试记录、最终状态、建议的下一步操作。支持批量传入多个 problem。

Inputs: selector (required), problem, problems, maxAttempts, +1 more.

browser_responsive_testA

模拟多视口(mobile/tablet/desktop)截图对比,检测响应式布局问题。打开指定URL,分别以三个标准视口截图,返回各视口截图和布局差异分析。

Inputs: url (required), waitMs, fullPage, viewports.

browser_screenshotA

Take a screenshot of the current page and save it to the MCP artifacts directory. Sensitive inputs (password, token, apiKey) are auto-redacted by default.

中文详情:

  • 用途:对真实浏览器当前页面截图并保存为 PNG 文件到 screenshots 目录

  • 何时使用:验证页面渲染结果时;记录 bug 证据时;视觉对比前截取基线/实际图时;流程关键节点留证时

  • 输出:{ ok: boolean, path: string, name: string, timestamp: string } — path 为截图绝对路径

  • 参数:

    • name (string, 可选):截图文件名(不含扩展名),默认使用时间戳

    • redactSelectors (array, 可选):需要额外遮挡的 CSS 选择器列表,默认已遮挡 [type=password]、[name*=token]、[name*=apiKey]

  • 错误:浏览器未启动抛出 'Browser not launched';截图失败抛出 'Screenshot failed'

  • 示例:{"name":"login-page","redactSelectors":[".credit-card"]}

Inputs: mode, name, padding, selector, +1 more.

browser_screenshot_elementA

Screenshot a specific page element located by CSS selector, returning the artifact path and dimensions. Supports padding to expand the captured area.

中文详情:

  • 用途:对指定 CSS 选择器元素截图,截取该元素的可见区域,返回截图路径和尺寸信息

  • 何时使用:组件级截图取证时;视觉对比前截取元素图时;bug 报告附带局部截图时;多元素单独留档时

  • 输出:{ ok: boolean, path: string, name: string, selector: string, width: number, height: number, timestamp: string }

  • 参数:

    • selector (string, 必填):目标元素的 CSS 选择器

    • padding (number, 可选):截图区域周围的 padding,单位像素,默认 0

    • name (string, 可选):截图文件名(不含扩展名),默认自动生成

  • 错误:selector 无匹配抛出 'element not found';元素不可见抛出 'element not visible'

  • 示例:{"selector":".user-avatar","padding":10,"name":"avatar-component"}

Inputs: selector (required), name, padding.

browser_scrollA

Scroll the page or to a specific element. Supports scrollIntoView for targeting an element and pixel-based x/y scrolling with auto/smooth behavior.

中文详情:

  • 用途:滚动页面到指定位置,支持滚动到指定元素(scrollIntoView)或按像素值(x/y)滚动

  • 何时使用:需要触发懒加载内容时;将目标元素滚动到可视区域时;测试无限滚动分页时;截图前确保元素可见时

  • 输出:{ ok: boolean, scrollX: number, scrollY: number, scrolledTo: string, timestamp: string }

  • 参数:

    • selector (string, 可选):要滚动到的目标元素选择器,与 scrollIntoView 配合使用

    • scrollIntoView (boolean, 可选):是否滚动到 selector 指定的元素,默认 true(指定 selector 时)

    • x (number, 可选):横向滚动像素值(不指定 selector 时使用)

    • y (number, 可选):纵向滚动像素值(不指定 selector 时使用)

    • behavior (string, 可选):滚动行为,可选 auto/smooth,默认 auto

  • 错误:selector 无匹配抛出 'element not found';selector 与 x/y 同时提供时以 selector 为优先

  • 示例:{"selector":"#footer","behavior":"smooth"}

Inputs: x, y, behavior, selector, +1 more.

browser_selectA

Select an option in a dropdown by value, label text, or index.

中文详情:

  • 用途:在下拉框(select 元素)中选择指定选项,支持按 value 值、按 label 文本、按索引三种方式

  • 何时使用:表单下拉选项选择时;测试 select 联动效果时;筛选条件选择时;下拉框默认值验证时

  • 输出:{ ok: boolean, selector: string, selectedValue: string, selectedLabel: string, selectedIndex: number, timestamp: string }

  • 参数:

    • selector (string, 必填):select 元素的 CSS 选择器

    • value (string, 可选):要选择的 option 的 value 值

    • label (string, 可选):要选择的 option 的显示文本

    • index (number, 可选):要选择的 option 的索引(从 0 开始)

  • 错误:selector 无匹配或非 select 元素抛出 'Not a select element';value/label/index 都未提供抛出 'No selection criteria provided';选项不存在抛出 'Option not found'

  • 示例:{"selector":"#country","value":"cn"}

Inputs: selector (required), index, label, value.

browser_sessionA

浏览器会话管理工具(v1.9.5 起合并 browser_session_create/switch/close + browser_sessions)。通过 mode 参数区分子模式:list(默认,列出所有会话)/ create(创建命名会话,独立上下文/cookie/storage)/ switch(切换活跃会话)/ close(关闭并删除会话)。

Inputs: url, mode, name, timeout, +4 more.

browser_session_closeC

关闭并删除指定浏览器会话。

Inputs: name (required), sessionName.

browser_session_createA

Create or reuse a named browser session with isolated context, cookies, localStorage, console, network, errors, and events. Supports Chrome extension loading via persistent context.

中文详情:

  • 用途:创建或复用一个命名浏览器会话,每个会话拥有独立的浏览器上下文、cookie、localStorage、console、network、errors 和 events

  • 何时使用:需要多账号/多角色并行测试时;测试需要不同浏览器上下文隔离时;加载 Chrome 扩展验证扩展行为时;验证不同会话状态(登录/未登录)时

  • 输出:{ ok: boolean, name: string, sessionId: string, url: string, created: boolean, headless: boolean, extensionLoaded: boolean }

  • 参数:

    • name (string, 必填):会话名称,如 free-user、pro-user

    • sessionName (string, 可选):会话名称别名

    • url (string, 可选):创建后打开的 URL

    • headless (boolean, 可选):是否无头模式,默认 false

    • extensionPath (string, 可选):要加载的 Chrome 扩展目录路径,提供后使用持久化上下文并强制 headless=false

    • loadExtensionPath (string, 可选):extensionPath 的别名

    • timeout (number, 可选):导航超时时间,默认 30000ms

  • 错误:name 为空抛出 'Session name is required';扩展路径不存在抛出 'Extension path not found';导航超时抛出 'Timeout XXXXms exceeded'

  • 示例:{"name":"pro-user","url":"https://example.com/dashboard","headless":false}

Inputs: name (required), url, timeout, headless, +3 more.

browser_sessionsA

List all current browser sessions with their active state, current URL, creation time, last-used time, and trace status.

中文详情:

  • 用途:列出当前所有浏览器会话,显示活跃状态、URL、创建时间、最后使用时间和 trace 录制状态

  • 何时使用:多会话测试前查看会话清单时;确认会话是否仍活跃时;排查 trace 录制状态时;调试并发会话问题时

  • 输出:{ ok: boolean, sessions: array, total: number } — 每项含 { name, active, url, createdAt, lastUsedAt, traceEnabled }

  • 参数:无

  • 错误:无活跃会话时返回空数组但 ok=true

  • 示例:{}

Inputs: no named parameters.

browser_session_switchA

切换当前活跃浏览器会话。后续未指定 sessionName 的浏览器工具会作用于该会话。

Inputs: name (required), sessionName.

browser_smart_fillA

Smart form filler: auto-generate format-valid realistic test data by field type and fill the target input. Supports 10+ types (email, phone, name, address, idCard, number, text, url, date, password); each call produces random data to cover edge cases.

中文详情:

  • 用途:智能表单填充工具,根据字段类型自动生成符合格式的真实测试数据并填入指定输入框

  • 何时使用:注册表单需要合法邮箱/手机号时;地址表单需要格式正确数据时;密码字段需要符合复杂度要求时;批量生成测试数据覆盖边界场景时

  • 输出:{ ok: boolean, selector: string, fieldType: string, generatedValue: string, timestamp: string }

  • 参数:

    • selector (string, 必填):目标输入框的 CSS 选择器

    • fieldType (string, 必填):字段类型,可选 email/phone/name/address/idCard/number/text/url/date/password

    • options (object, 可选):生成选项,各字段类型有不同选项

      • domain (string, 可选):email 类型的域名

      • min (number, 可选):number 类型的最小值

      • max (number, 可选):number 类型的最大值

      • minLen (number, 可选):text 类型的最小长度

      • maxLen (number, 可选):text 类型的最大长度

      • start (string, 可选):date 类型的起始日期

      • end (string, 可选):date 类型的结束日期

  • 错误:selector 无匹配抛出 'element not found';fieldType 非法抛出 'Invalid fieldType';元素不可编辑抛出 'element not editable'

  • 示例:{"selector":"#email","fieldType":"email","options":{"domain":"test.com"}}

Inputs: selector (required), fieldType (required), options.

browser_smoke_testA

一键冒烟测试 - 自动执行页面加载、JS错误、HTTP错误、无障碍、控制台警告等5项快速检查,返回综合评分和详细结果

Inputs: url, format.

browser_snapshotA

Capture a structured snapshot of the current page: URL, title, visible text, form fields, and actionable buttons for AI-driven element targeting.

中文详情:

  • 用途:获取当前页面的结构化快照,包含 URL、标题、可见文本、表单元素和按钮清单

  • 何时使用:交互前需要了解页面当前结构时;定位元素前获取可点击清单时;表单填写前查看字段时;流程断点处记录页面状态时

  • 输出:{ ok: boolean, url: string, title: string, visibleText: string, forms: array, buttons: array, inputs: array, timestamp: string } — forms/buttons/inputs 各项含 selector、text、attributes 等定位信息

  • 参数:无

  • 错误:浏览器未启动抛出 'Browser not launched';页面未加载完成可能返回不完整快照

  • 示例:{}

Inputs: no named parameters.

browser_stateA

查看和管理浏览器状态(Cookie 与 Web Storage)。v1.9.5 起合并 browser_cookies 与 browser_storage。mode=cookies 时支持获取/设置/清除 Cookie;mode=storage 时查看 localStorage、sessionStorage、cookies 快照。调试登录态、Token、状态持久化问题的首选工具。

Inputs: mode, name, scope, action, +2 more.

browser_stepA

记录当前验证步骤证据:截图、DOM 简要快照、本轮统一错误摘要。用于形成可追溯证据链。

Inputs: label, snapshot, screenshot, includeWarnings, +1 more.

browser_storageA

查看当前页面 localStorage、sessionStorage 或 cookie,辅助定位登录态和状态问题

Inputs: scope.

browser_trace_chainA

全链路调用链追溯:从 trace_id 或时间点追溯前端→API→后端的完整请求链路,聚合每个 trace 的请求/响应体和关联的 console 错误

Inputs: url, since, traceId, statusMin, +1 more.

browser_trace_startB

开始浏览器追踪会话,记录页面加载和交互过程中的性能数据

Inputs: no named parameters.

browser_trace_stopA

停止浏览器追踪会话,返回收集到的追踪数据

Inputs: no named parameters.

browser_traverse_menuA

Auto-traverse page navigation menus level by level (1/2/3 tier), clicking each item while checking console errors, page errors, and network errors per step. Auto-detects standard nav containers, sidebars, and UI framework menus (Ant Design/Element UI); falls back to full-page link scan if not found.

中文详情:

  • 用途:自动遍历页面导航菜单,逐级点击一级/二级/三级菜单项,每步检查控制台/页面/网络错误,验证功能链路是否正常

  • 何时使用:站点功能回归测试时;页面健康检查时;新版本上线前菜单遍历验证时;UI 框架迁移后菜单稳定性测试时

  • 输出:{ ok: boolean, totalItems: number, clickedItems: number, results: array, errors: array } — 每项含 { text, url, urlChanged, pageTitle, consoleErrors, networkErrors, success }

  • 参数:

    • maxDepth (number, 可选):最大遍历深度(1=仅一级,2=含二级,3=含三级),默认 3

    • maxItems (number, 可选):最大点击次数,防止无限遍历,默认 30

    • waitMs (number, 可选):每次点击后的等待时间(毫秒),默认 500

    • includeSubMenus (boolean, 可选):是否自动展开并点击子菜单,默认 true

  • 错误:未找到菜单容器时降级扫描全页面链接;遍历超时会在 results 中标记 timeout

  • 示例:{"maxDepth":2,"maxItems":20,"waitMs":800,"includeSubMenus":true}

Inputs: waitMs, maxDepth, maxItems, includeSubMenus.

browser_typeA

Type text into a DOM element matched by CSS selector in a real browser, simulating real keyboard input.

中文详情:

  • 用途:在真实浏览器中向指定 CSS 选择器元素输入文本(输入框、文本域、搜索框等)

  • 何时使用:填写登录表单用户名/密码时;搜索框输入查询词时;textarea 输入长文本时;测试输入框字符限制时

  • 输出:{ ok: boolean, typedSelector: string, textLength: number, timestamp: string }

  • 参数:

    • selector (string, 必填):CSS 选择器,支持 Playwright 语法

    • text (string, 必填):要输入的文本内容

  • 错误:选择器无匹配抛出 'element not found';元素不可编辑抛出 'element not editable'

  • 示例:{"selector":"#username","text":"testuser@example.com"}

Inputs: text (required), selector (required).

browser_verify_fixA

修复验证闭环工具。记录修复前状态(错误数、元素状态),执行修复操作(browser_click/type/wait等),验证修复后状态,对比前后差异,确认修复是否生效。返回 before/after 对比、fixStatus、verificationResult、nextAction。

Inputs: selector (required), timeout, fixValue, fixAction, +1 more.

browser_visualA

视觉回归与 UI 检查工具(v1.9.5 起合并 browser_visual_baseline/compare/report/check/snapshot + screenshot_diff)。通过 mode 参数区分子模式:baseline(默认,建立视觉基线 PNG)/ compare(截取实际图与基线对比,生成 diff)/ report(列出所有视觉产物)/ check(无基线 UI 问题扫描)/ snapshot(三级快照:截图+DOM+CSS)/ diff(手动指定两张截图对比,等价于已废弃的 screenshot_diff)。

Inputs: mode, name, fullPage, selector, +16 more.

browser_visual_baselineA

Create a visual regression baseline PNG for the current page or a specific element. Defaults to full-page screenshot and auto-masks sensitive inputs (password, token, apiKey).

中文详情:

  • 用途:为当前页面或指定元素创建视觉回归基线 PNG,作为后续 visual_compare 的对比基准

  • 何时使用:首次建立视觉回归基线时;UI 升级后重置基线时;多 viewport 视觉测试前建立基准时;组件级视觉对比前创建基线时

  • 输出:{ ok: boolean, name: string, path: string, selector: string|null, fullPage: boolean, timestamp: string }

  • 参数:

    • name (string, 必填):基线名称,不含扩展名

    • selector (string, 可选):CSS 选择器;指定后只截取该元素

    • fullPage (boolean, 可选):是否全页截图,默认 true;selector 存在时忽略

    • maskSelectors (array, 可选):截图前额外遮挡/脱敏的 CSS 选择器列表

    • sessionName (string, 可选):浏览器会话名称,默认当前活跃会话

  • 错误:name 为空抛出 'Name is required';selector 无匹配抛出 'element not found';浏览器未启动抛出 'Browser not launched'

  • 示例:{"name":"login-page-baseline","fullPage":true,"maskSelectors":[".ad-banner"]}

Inputs: name (required), fullPage, selector, sessionName, +1 more.

browser_visual_checkA

No-baseline automated UI issue scan: scans the current page for common UI problems (invisible text, overlapping elements, z-index occlusion, small click targets, blank regions, overflow, missing image alt, contrast issues, responsive breakpoints) and returns a natural-language issue list.

中文详情:

  • 用途:无需基线直接扫描当前页面常见 UI 问题(文字不可见、元素重叠、z-index 遮挡、点击区域过小、空白区域、溢出、图片 alt 缺失、对比度不足、响应式断点等),输出自然语言描述的问题清单

  • 何时使用:UI 走查时快速发现问题;上线前 UI 健康检查;多 viewport 响应式验证;可访问性基础扫描(对比度/alt 缺失)时

  • 输出:{ ok: boolean, totalIssues: number, issues: array, summary: string } — 每项含 { severity, category, description, selector, recommendation }

  • 参数:

    • includeAccessibility (boolean, 可选):是否包含可访问性检查(图片 alt 缺失、对比度检测),默认 true

    • includeResponsive (boolean, 可选):是否包含响应式检查,默认 false

    • viewports (array, 可选):响应式检查的 viewport 列表,可选 mobile/tablet/desktop,仅当 includeResponsive=true 时生效,默认 ["mobile","tablet"]

    • severity (string, 可选):最低报告级别,可选 blocking/major/minor,默认 major

  • 错误:浏览器未启动抛出 'Browser not launched';viewport 无效抛出 'Invalid viewport'

  • 示例:{"includeAccessibility":true,"includeResponsive":true,"viewports":["mobile","desktop"],"severity":"major"}

Inputs: severity, viewports, includeResponsive, includeAccessibility.

browser_visual_compareA

Capture an actual PNG of the current page, compare against the same-named visual baseline, generate a diff PNG, and return diffPixels, diffRatio, passed flag, and artifact paths.

中文详情:

  • 用途:截取当前页面 actual PNG 与同名视觉基线对比,生成 diff PNG 并返回差异指标和产物路径

  • 何时使用:UI 改动后回归对比时;多环境(dev/staging/prod)视觉一致性验证时;组件样式调整后差异检测时;CI 中视觉回归门禁时

  • 输出:{ ok: boolean, name: string, baselinePath: string, actualPath: string, diffPath: string, diffPixels: number, diffRatio: number, passed: boolean, threshold: number }

  • 参数:

    • name (string, 必填):要对比的基线名称,不含扩展名

    • selector (string, 可选):CSS 选择器;需与基线截图范围一致

    • fullPage (boolean, 可选):是否全页截图,默认 true;selector 存在时忽略

    • maskSelectors (array, 可选):截图前额外遮挡/脱敏的 CSS 选择器列表,用于忽略动态区域

    • maxDiffPixelRatio (number, 可选):允许的最大差异像素比例,默认 0.01

    • sessionName (string, 可选):浏览器会话名称,默认当前活跃会话

  • 错误:基线不存在抛出 'Baseline not found, run browser_visual_baseline first';selector 无匹配抛出 'element not found'

  • 示例:{"name":"login-page-baseline","maxDiffPixelRatio":0.005,"maskSelectors":[".timestamp"]}

Inputs: name (required), fullPage, selector, sessionName, +2 more.

browser_visual_componentA

Component-level visual diff in one call: capture a screenshot of the CSS-selected component, compare against same-named baseline, return diffPixels/diffRatio/passed. Auto-creates the baseline if missing and returns baseline_created flag.

中文详情:

  • 用途:组件级视觉对比,一次调用完成组件截图 → 与同名基线对比 → 返回差异指标;基线不存在时自动创建并返回 baseline_created 标记

  • 何时使用:组件库视觉回归时;卡片/弹窗/表格等独立组件 UI 验证时;多主题(light/dark)组件对比时;增量 UI 改动只对比受影响组件时

  • 输出:{ ok: boolean, name: string, selector: string, baselinePath: string, actualPath: string, diffPath: string, diffPixels: number, diffRatio: number, passed: boolean, baseline_created: boolean }

  • 参数:

    • name (string, 必填):组件基线名称,不含扩展名

    • selector (string, 必填):CSS 选择器,精确选择要对比的组件

    • maxDiffPixelRatio (number, 可选):允许的最大差异像素比例,默认 0.01

    • sessionName (string, 可选):浏览器会话名称,默认当前活跃会话

  • 错误:selector 无匹配抛出 'element not found';选择器匹配多个元素抛出 'Selector matches multiple elements, refine it'

  • 示例:{"name":"product-card","selector":".product-card","maxDiffPixelRatio":0.005}

Inputs: name (required), selector (required), sessionName, maxDiffPixelRatio.

browser_visual_reportA

List all visual regression artifacts (baselines, actuals, diffs) and recent comparison results in the project.

中文详情:

  • 用途:列出视觉回归基线、actual、diff 产物文件和最近比较结果,便于人工审查

  • 何时使用:视觉回归测试后查看历史对比时;清理旧基线前盘点时;调试 visual_compare 结果时;报告汇总时

  • 输出:{ ok: boolean, baselines: array, actuals: array, diffs: array, recentResults: array, total: number } — 每项含 { name, path, size, createdAt }

  • 参数:无

  • 错误:无产物时返回空数组但 ok=true

  • 示例:{}

Inputs: no named parameters.

browser_visual_snapshotA

Three-level snapshot: capture screenshot + DOM state snapshot + CSS computed properties in one call, with automatic L1+L2 UI issue detection (invisible text, overlapping elements, large blank regions, z-index occlusion, small click targets, overflow).

中文详情:

  • 用途:三级快照工具,一次性获取截图 + DOM 状态快照 + CSS 计算属性,并自动检测 L1+L2 级别 UI 问题

  • 何时使用:UI 缺陷排查时需要同时查看图/结构/样式时;调试元素不可见原因时;自动化发现问题后人工定位时;回归测试前留档页面状态时

  • 输出:{ ok: boolean, screenshotPath: string, dom: object, computedStyles: object, issues: array, viewport: { width, height }, timestamp: string }

  • 参数:

    • selector (string, 可选):CSS 选择器;不传则全页

    • fullPage (boolean, 可选):是否全页截图,默认 true

    • includeMetadata (boolean, 可选):是否包含完整元数据,默认 true

    • detectIssues (boolean, 可选):是否自动检测 UI 问题,默认 true

    • viewportWidth (integer, 可选):自定义 viewport 宽度

    • viewportHeight (integer, 可选):自定义 viewport 高度

    • sessionName (string, 可选):浏览器会话名称,默认当前活跃会话

  • 错误:selector 无匹配抛出 'element not found';浏览器未启动抛出 'Browser not launched'

  • 示例:{"selector":".header","fullPage":false,"detectIssues":true,"viewportWidth":375,"viewportHeight":812}

Inputs: fullPage, selector, sessionName, detectIssues, +3 more.

browser_waitA

Wait for the browser to reach a specified condition: element visible/hidden/detached, text appears, URL contains substring, load state, or a fixed duration. Used to stabilize asynchronous flows.

中文详情:

  • 用途:等待真实浏览器达到指定状态(元素出现/隐藏、文本出现、URL 包含、加载状态、固定时间),稳定异步流程

  • 何时使用:点击后等待 loading 消失时;异步请求后等待元素出现时;SPA 路由跳转后等待 URL 变化时;轮询前固定延迟时;动画完成后继续操作时

  • 输出:{ ok: boolean, condition: string, elapsed: number, timeout: number, timedOut: boolean }

  • 参数:

    • selector (string, 可选):要等待的 CSS 选择器,配合 state 使用

    • state (string, 可选):选择器状态,可选 attached/detached/visible/hidden,默认 visible

    • text (string, 可选):等待出现的页面文本

    • exact (boolean, 可选):文本是否精确匹配,默认 false

    • nth (number, 可选):当文本匹配多个元素时选择第几个,默认 0

    • urlContains (string, 可选):等待当前 URL 包含该字符串

    • loadState (string, 可选):等待加载状态,可选 load/domcontentloaded/networkidle

    • ms (number, 可选):固定等待毫秒数

    • timeout (number, 可选):超时时间,默认 10000ms

  • 错误:超时抛出 'Timeout XXXXms exceeded';未提供任何等待条件抛出 'No wait condition provided'

  • 示例:{"selector":".loading-spinner","state":"hidden","timeout":15000}

Inputs: ms, nth, text, exact, +5 more.

business_loop_validateA

开源版业务闭环验证:自动��别页面上的业务关键节点(留资/下单/结算),并验证各节点的可达性、表单完整性和流程连贯性。识别 6 类业务节点:lead_capture(留资)、product_browse(商品浏览)、cart(购物车)、checkout(下单结算)、payment(支付)、account(账户)。每类节点检查:可达性、表单字段、按钮、网络请求、状态转换。

Inputs: target (required), loop, depth, maxSteps, +2 more.

bypass_loginA

开源版认证绕过检测:通过多种方式测试是否可以绕过登录验证直接访问受保护页面/API。包括:无 Cookie 请求、修改用户 ID、移除 Authorization 头、测试常见后门路径等。

Inputs: targetUrl (required), testCases, authApiPath, maxTestCount, +2 more.

chain_list_templatesA

列出所有内置链路规格模板,包括 marketplace-purchase、login-basic、credits-balance 等。每个模板包含名称、描述、步骤数、是否有状态源、目标 URL。

Inputs: no named parameters.

chain_score_reportA

对 chain_spec_run 结果输出 5 维评分报告:功能链路(步骤通过率)、技术链路(API/网络成功率)、一致性(状态 diff 通过率)、契约(API schema 校验)、可观测性(错误采集质量)。输出加权总分和等级。先做进现有 MCP,后续再剥离。

Inputs: runId, result, chainResult.

chain_specA

链路规格工具(v1.9.5 起合并 chain_list_templates/chain_spec_run/chain_score_report)。通过 mode 参数区分子模式:list(默认,列出所有内置链路模板)/ run(按链路规格执行业务链路验证)/ score(对 chain_spec_run 结果输出 5 维评分报告)。

Inputs: mode, name, runId, steps, +16 more.

chain_spec_runC

按链路规格执行简化版业务链路验证:支持打开页面、点击、输入、等待、断言、状态采集/对比,并汇总每步 Console、PageError、Network、状态 diff 和证据。先做进现有 MCP,后续再剥离为独立链路验证引擎。

Inputs: steps (required), name, runId, timeout, +13 more.

contractA

API 契约工具。v1.9.5 起合并 contract_guard / contract_baseline。mode=guard 从前端实际消费的 API 响应中自动提取字段结构,生成 consumer contract(消费者契约),防止后端 API 漂移;mode=baseline 进行契约基线管理(保存/加载/对比/列出/删除)。

Inputs: mode, name, since, action, +8 more.

contract_baselineA

消费者契约基线管理:保存当前 schema 为基线、加载基线、对比当前 schema 与基线检测漂移、列出所有基线、删除基线。配合 contract_guard 使用,可实现 API 变更版本化守护。

Inputs: name, action, contracts.

contract_guardC

从前端实际消费的 API 响应中自动提取字段结构,生成 consumer contract(消费者契约),防止后端 API 漂移。支持两种来源:直接调用指定端点,或从已捕获的 network 日志中提取。先做进现有 MCP,后续再剥离。

Inputs: since, endpoints, fromNetwork, urlContains, +4 more.

correlate_triple_checkA

开源版 UI-API 三方比对:从页面 DOM 提取数据,调用对应 API 获取数据,对比两者是否一致。支持列表页和详情页两种模式。检测数据不一致、字段遗漏、格式差异等问题。

Inputs: mode (required), maxRows, apiMethod, apiPayload, +6 more.

css_var_checkA

分析 CSS 文件中缺失的变量定义,并提供修复建议。扫描 CSS 内容,检测在 :root 或其他选择器中引用但未定义的 CSS 自定义属性(变量),为每个缺失变量生成 suggestedFix(建议值和插入位置)。

Inputs: css (required), filePath.

debug_investigateA

输入问题症状,自动汇总本轮 errors、events、network_detail、DOM 可见错误、storage、artifacts,并输出假设、证据链和下一步修复/复测建议。

Inputs: focus, limit, symptom, expected, +4 more.

dual_chain_exploreA

双链路并行探索:链路① Browser Agent 在真实浏览器中做黑客式功能探索(发现→正向→对抗→闭环),链路② Trace Agent 追踪全栈数据流(前端→API→后端→数据库),交叉验证后输出多维判定(真通过/假通过/渲染问题/数据问题)并自动修复。两条链路独立并行,结果交叉对比,打破 AI 代码「自己验证自己」的闭环。

Inputs: target (required), chains, phases, autoFix, +5 more.

error_analyzeA

错误分析工具(v1.9.5 起合并 error_fix_suggestion/error_summary_md)。通过 mode 参数区分子模式:fix(默认,根据错误日志生成修复建议)/ summary(生成错误摘要 Markdown 报告)。

Inputs: mode, limit, errors, format, +1 more.

error_fix_suggestionA

基于 errorSummary 和 contextFiles 返回最多 3 个最小修复建议;不自动改码。

Inputs: errorSummary (required), file, contextFiles, maxSuggestions.

error_summary_mdA

将错误聚合结果输出为 500 字以内 Markdown 摘要,不包含完整日志、重复堆栈或完整响应体。

Inputs: limit, evidence.

evidenceA

证据管理工具(v1.9.5 起合并 evidence_pack/evidence_index)。通过 mode 参数区分子模式:pack(默认,生成单步证据包,把截图、DOM 摘要、错误、网络请求、API 响应摘要、数据 diff、traceId、Console、PageError、HAR 汇总成一个 JSON 文件)/ index(证据包索引,扫描 reports 目录所有 evidence.json 文件,按 runId 串联生成完整验证时间线)。

Inputs: har, mode, label, runId, +17 more.

evidence_indexA

证据包索引:扫描 reports 目录所有 evidence.json 文件,按 runId 串联多个证据包生成完整验证时间线。支持跨步骤、跨 runId 检索,汇总 traceId、错误数、API 响应数、数据 diff 数等关键指标。

Inputs: runId, includeTraceIds.

evidence_packB

生成单步证据包(v2.0),把截图、DOM 摘要、错误、网络请求、API 响应摘要、数据 diff、traceId 汇总、Console、PageError、HAR 和现有产物汇总成一个 JSON 文件,用于后续双链路验证复盘。

Inputs: har, label, runId, stepId, +15 more.

exploration_quickA
Read-only

【探索模式】对目标 URL 执行 6 阶段前端浅层自动探索:导航快照→端点提取→技术栈指纹→路由发现→表单检测→报告聚合。纯浏览器沙箱内完成,无需后端权限。发现高价值线索时自动提示 Pro/Team 升级路径。

Inputs: url, mode, depth, target.

mcp_diagA

MCP 自诊断工具。v1.9.5 起合并 mcp_health_check / mcp_self_test。mode=health 检查 MCP 健康状态(工具注册完整性、schema 合法性、目录可写性、checkpoint);mode=self_test 执行 MCP 自测(创建会话、验证 flow/assert/type/click/wait 等基础能力)。

Inputs: mode, trace, headless, sessionName.

mcp_health_checkA

检查 MCP 自身健康状态:工具注册完整性、schema 合法性、证据目录可写性、当前会话和 checkpoint 状态。

Inputs: no named parameters.

mcp_self_testB

执行 MCP 自测:创建自测会话,打开 data URL,验证 flow/assert/type/click/wait/step/events/errors/trace/artifacts 基础能力。

Inputs: trace, headless, sessionName.

memory_recallB

跨会话记忆系统:检索/固化/列出/遗忘历史验证发现与修复模式。基于 .validpilot/memory/ 目录持久化情景记忆、模式记忆、程序记忆三类知识,支持文本相似度+标签+主机多维度召回,实现同类 Bug 第二次自动识别。

Inputs: operation (required), id, host, tags, +10 more.

project_auditB

扫描项目目录,检测常见的代码质量问题:硬编码密码/密钥、硬编码绝对路径、SQL语法错误、CSS变量异常(循环引用、引用未定义变量、非:root区域引用未定义变量)等。运行后返回带有严重级别的问题列表。

Inputs: projectPath (required), severity.

screenshot_diffA

Compare two screenshots (baseline vs actual) or capture a current screenshot and return a diff summary and artifact path. Supports element-scoped capture via selector; does not emit long screenshot descriptions.

中文详情:

  • 用途:比较两张截图(baseline/actual)或捕获当前截图并返回差异摘要与产物路径,不输出长截图描述

  • 何时使用:手动指定 baseline/actual 路径做差异对比时;测试前后页面状态对比时;元素级截图差异分析时;调试 visual_compare 流程时

  • 输出:{ ok: boolean, diffPath: string, baselinePath: string, actualPath: string, diffPixels: number, diffRatio: number, passed: boolean, threshold: number }

  • 参数:

    • baselinePath (string, 可选):基线截图路径

    • actualPath (string, 可选):实际截图路径,与 baselinePath 同时提供时直接对比

    • beforePath (string, 可选):baselinePath 的别名

    • afterPath (string, 可选):actualPath 的别名

    • selector (string, 可选):捕获时仅截取该元素区域

    • threshold (number, 可选):差异阈值,默认 0.01

    • name (string, 可选):产物名称,用于命名 diff 文件

  • 错误:baselinePath 与 actualPath 都缺失且浏览器未启动抛出 'No screenshots to compare';文件不存在抛出 'File not found'

  • 示例:{"baselinePath":"screenshots/login.png","actualPath":"screenshots/login-v2.png","threshold":0.005,"name":"login-diff"}

Inputs: name, selector, afterPath, threshold, +3 more.

security_csp_analyzeA

Deep analysis of Content-Security-Policy: parse CSP directives, detect unsafe-inline/unsafe-eval/wildcard * and other unsafe configurations, and produce a CSP security score.

中文详情:

  • 用途:深度分析 Content-Security-Policy 策略,解析 CSP 指令,检测不安全配置(unsafe-inline/unsafe-eval/通配符 * 等)并评估 CSP 安全评分

  • 何时使用:CSP 策略上线前评估时;XSS 防护层验证时;第三方脚本加载白名单审查时;CSP 报告异常排查时

  • 输出:{ ok: boolean, url: string, csp: string, directives: object, unsafeDirectives: array, score: number, recommendations: array }

  • 参数:

    • url (string, 必填):目标 URL

  • 错误:URL 不可达抛出 'Request failed';响应无 CSP 头返回 score=0 但 ok=true

  • 示例:{"url":"https://example.com"}

Inputs: url (required).

security_headers_checkA

Check HTTP security response headers: analyze presence and correctness of CSP, X-Content-Type-Options, X-Frame-Options, HSTS, Referrer-Policy, and detect information leakage via X-Powered-By/Server.

中文详情:

  • 用途:检查 HTTP 安全响应头部,分析 CSP、X-Content-Type-Options、X-Frame-Options、HSTS、Referrer-Policy 等头部的存在性和配置正确性,检测 X-Powered-By/Server 等信息泄露

  • 何时使用:上线前安全头部合规检查时;HTTPS/HSTS 配置验证时;点击劫持防护(X-Frame-Options)验证时;信息泄露排查时

  • 输出:{ ok: boolean, url: string, headers: object, missing: array, misconfigured: array, infoLeakage: array, score: number, recommendations: array }

  • 参数:

    • url (string, 必填):目标 URL

  • 错误:URL 不可达抛出 'Request failed';非 HTTP(S) URL 抛出 'Invalid url'

  • 示例:{"url":"https://example.com"}

Inputs: url (required).

security_owasp_top10A

OWASP Top 10 security check: quickly scans for risks like A01 access control, A02 cryptographic failures, A05 security misconfiguration, etc., and returns pass/warn/fail status per category.

中文详情:

  • 用途:OWASP Top 10 安全检查,快速检查 A1 访问控制、A2 加密失败、A5 安全配置错误等安全风险,返回通过/警告/失败状态

  • 何时使用:上线前整体安全风险评估时;合规审计 OWASP 检查清单时;安全门禁快速过检时;定期安全巡检时

  • 输出:{ ok: boolean, url: string, totalChecks: number, categories: array, score: number } — 每项含 { id, name, status: pass/warn/fail, findings: array, recommendation }

  • 参数:

    • url (string, 必填):目标 URL

  • 错误:URL 不可达抛出 'Request failed';部分检查依赖其他工具(如 headers/csp),缺失时该类别标记 warn

  • 示例:{"url":"https://example.com"}

Inputs: url (required).

security_scanA

安全扫描工具(v1.9.5 起合并 security_headers_check/security_owasp_top10/security_sql_injection_scan/security_xss_scan/security_csp_analyze)。通过 mode 参数区分子模式:headers(默认,HTTP 安全头检查,等价于已废弃的 security_headers_check)/ owasp(OWASP Top 10 安全检查,等价于 security_owasp_top10)/ sqli(SQL 注入漏洞扫描,等价于 security_sql_injection_scan)/ xss(XSS 漏洞扫描,等价于 security_xss_scan)/ csp(Content-Security-Policy 深度分析,等价于 security_csp_analyze)。

Inputs: url (required), mode.

security_sql_injection_scanA

SQL injection vulnerability scanner: injects 20 SQLi payloads into the target URL's query parameters and detects SQL error leakage (MySQL, Oracle, PostgreSQL, SQL Server, SQLite) in responses.

中文详情:

  • 用途:SQL 注入漏洞扫描,向目标 URL 的查询参数注入 20 种 SQL 注入 payload,检测响应中是否泄露 SQL 错误信息

  • 何时使用:上线前 SQL 注入漏洞扫描时;查询参数(如 ?id=1)可疑时;接口输入校验回归时;OWASP A03 注入类风险验证时

  • 输出:{ ok: boolean, url: string, totalPayloads: number, vulnerable: boolean, findings: array, dbms: string } — 每项含 { payload, response, evidence }

  • 参数:

  • 错误:URL 无查询参数抛出 'No injectable parameters found';URL 不可达抛出 'Request failed'

  • 示例:{"url":"https://example.com/product?id=1"}

Inputs: url (required).

security_xss_scanA

XSS vulnerability scanner: injects 26 XSS payloads (script tags, event handlers, SVG, template injection, etc.) into the target URL and detects unescaped payload reflection in the response body.

中文详情:

  • 用途:XSS 漏洞扫描,向目标 URL 注入 26 种 XSS payload(script 标签、事件处理器、SVG、模板注入等),检测响应体中是否未转义地包含 payload

  • 何时使用:搜索/评论/反馈等输入点上线前扫描时;URL 参数反射型 XSS 验证时;模板引擎转义回归时;OWASP A03 注入类风险验证时

  • 输出:{ ok: boolean, url: string, totalPayloads: number, vulnerable: boolean, findings: array } — 每项含 { payload, reflected: boolean, context: string, evidence }

  • 参数:

  • 错误:URL 无查询参数抛出 'No injectable parameters found';URL 不可达抛出 'Request failed'

  • 示例:{"url":"https://example.com/search?q=test"}

Inputs: url (required).

skill_consistency_checkA

批量校验所有开源 Skill 引用的工具是否与 tools/ 目录实际注册一致,不依赖 .trae/skills/SKILL.tools.json 外部文件。同时检测 SKILL_TOOLS_MAP 与 handlers/prompts.js 的 buildMessages 输出之间是否存在漂移(mapDrift 仅 warning)。

Inputs: mode, skillName.

skill_mcp_validateB

自动校验 Skill 定义的工具依赖是否与 MCP 服务器实际可用工具一致

Inputs: skillName (required), mode.

skill_tools_mapA

查询 Skill 与 MCP 工具的双向映射:传入 skillName 返回该 Skill 的工具链;传入 toolName 返回引用该工具的所有 Skill。数据源 handlers/skill_map.js,与 handlers/prompts.js 交叉校验。

Inputs: toolName, skillName, includeDetails.

skill_validateA

Skill 与 MCP 工具一致性校验与映射查询。v1.9.5 起合并 skill_consistency_check / skill_mcp_validate / skill_tools_map。mode=consistency 批量校验所有 Skill 引用的工具是否与 tools/ 目录一致;mode=mcp_validate 校验单个 Skill 定义的工具依赖是否与 MCP 服务器一致;mode=tools_map 查询 Skill↔Tool 双向映射。

Inputs: mode, toolName, skillName, strictMode, +1 more.

state_diff_assertB

捕获并对比操作前后的页面/API/存储状态,用于验证 UI、API、数据状态是否真的发生预期变化。先做进现有 MCP,后续可剥离为独立双链路验证模块。

Inputs: sources (required), after, label, action, +10 more.

trace_correlateA

traceId 深度关联工具(v1.9.5 起合并 browser_trace_chain 和 trace_correlation_check)。通过 mode 参数区分子模式:view(默认,根据 traceIds 反查前端证据包和后端日志,实现前后端联调闭环)/ check(校验浏览器请求和后端日志是否共享同一 traceId/runId,输出 trace 覆盖率和关联性评分,等价于已废弃的 trace_correlation_check)/ chain(全链路调用链追溯,从 traceId 或时间点追溯前端→API→后端的完整请求链路,等价于已废弃的 browser_trace_chain)。

Inputs: url, mode, since, traceId, +7 more.

trace_correlation_checkB

校验浏览器请求和后端日志是否共享同一 traceId/runId。读取 MCP 采集的 network 日志中的 traceparent/traceId,可选读取后端日志文件或通过 SSH 抓取后端容器日志,输出 trace 覆盖率和前后端关联性评分。先做进现有 MCP,后续再剥离。

Inputs: since, urlContains, useSshBackend, backendLogPath.

validation_chainA

完整功能链路闭环验证工具,按步骤依次执行 navigate/click/type/wait/validate 操作,每步自动检查控制台错误和网络错误,发现错误立即终止并返回详细的失败信息,输出完整的链路验证报告。支持强制执行5步链路验证,缺少关键步骤时拒绝执行。step.type 与 step.action 互为别名,二者至少传一个。

Inputs: steps (required), timeout, failOnError, networkFilter, +2 more.

validation_checkA

单项验证检查工具(v1.9.5 起合并 validation_quick_run)。通过 mode 参数区分子模式:basic(默认,执行完整浏览器健康检查:打开 URL、等待条件、执行断言、截图留证、统计错误)/ quick(低 Token 快速验证,等价于已废弃的 validation_quick_run)。仍支持 check_type=deploy_verify 执行部署验证。

Inputs: url, mode, name, wait, +10 more.

validation_complianceB

验证当前会话中各功能的链路验证合规性,检查是否完成了完整的5步链路验证(入口可达→操作可行→请求正确→响应正常→状态更新),未完成的功能标记为 NON-COMPLIANT。

Inputs: functions (required), strictMode, sessionLogs.

validation_data_integrityB

验证 CRUD 全链路数据一致性。通过 browser_eval 调用 API 并拦截响应,对比 Create/Read/Update/Delete 各阶段的数据是否一致。支持三种验证模式:check_create_read、check_update_read、check_delete_read

Inputs: action (required), entity (required), name, timeout, +11 more.

validation_decisionA

快速止损决策系统 - 基于页面初始错误状态,1 秒内判断是否值得继续验证,避免浪费 Token。返回决策建议(STOP/WARN/CONTINUE)、置信度、预计节省 Token 比例和估算的浪费 Token 数量。

Inputs: format, browserErrors.

validation_elementA

验证特定DOM元素的状态:存在性、可见性、可用性、文本内容、属性、值、数量等。支持多条断言组合,返回每条断言的通过/失败详情和证据截图。

Inputs: selector (required), url, name, exists, +11 more.

validation_flowA

多步流程验证工具(v1.9.5 起合并 validation_chain),按步骤依次执行 navigate/click/type/wait/eval/screenshot 等操作,支持失败可配置继续执行。step.action 与 step.type 互为别名,二者至少传一个;navigate 也支持别名 goto。通过 mode 参数区分子模式:flow(默认,标准流程验证)/ chain(链式验证,等价于已废弃的 validation_chain,失败即停止并返回失败步骤详情)。

Inputs: steps (required), mode, timeout, stopOnError, +1 more.

validation_matrixB

执行多维度验证矩阵(功能/视觉/性能/a11y),输出综合评分报告。支持角色×功能权限矩阵验证,每个角色使用独立 session。

Inputs: url (required), roles (required), features (required), har, +11 more.

validation_permissionA

权限越权检测工具。支持三种模式:horizontal_privilege=水平越权检测(替换API路径中的ID);vertical_privilege=垂直越权检测(普通用户访问管理API);role_menu=基于角色的菜单可见性验证

Inputs: action (required), name, entity, timeout, +8 more.

validation_quick_runA

对单页执行低 Token 快速验证:Console、Network、PageError、DOM/ARIA/文本摘要和稳定选择器可达性,返回 pass/fail、Top errors、artifact 路径。

Inputs: url (required), timeout, headless.

validation_reportA

验证报告工具(v1.9.5 起合并 validation_report_export)。通过 mode 参数区分子模式:view(默认,根据最近一次 validation_check/run/matrix 生成 Markdown/JSON 结构化验证报告,含六段式结构)/ export(导出 HTML 报告到文件,等价于已废弃的 validation_report_export)。

Inputs: mode, format, strictSchema.

validation_report_exportA

将最近一次验证结果导出为本地静态 HTML 报告,包含六段式结构:摘要、工具链、发现问题、网络证据、证据产物、待分类项。HTML 报告和 JSON 数据统一输出到 .trae/validations/runs// 目录下;若无活跃 run-id,则输出到 ai-verify-mcp/reports/ 目录。

Inputs: no named parameters.

validation_runA

Execute a complete browser acceptance plan: auto-clear errors, inject probes, record trace, run browser_flow per case, assert, investigate failures, export HAR, and persist evidence artifacts.

中文详情:

  • 用途:执行完整的浏览器端到端验收测试计划,自动完成错误清空、探针注入、trace 录制、按用例执行 browser_flow、断言、失败调查、HAR 导出和证据保存

  • 何时使用:需要一次性运行多个测试用例并产出完整证据链时;CI/CD 流水线中需要 gate 检查时;版本发布前回归验证时;复杂业务流程端到端验证时

  • 输出:{ ok: boolean, planName: string, totalCases: number, passedCases: number, failedCases: number, artifacts: { screenshots: [], traces: [], har: string, report: string }, summary: string }

  • 参数:

    • name (string, 可选):验证计划名称,用于报告标识

    • cases (array, 必填):测试用例列表,每项含 name/sessionName/steps/assertions/focus/symptom/expected/continueOnError

    • clearArtifacts (boolean, 可选):执行前是否清理旧截图/trace/har,默认 false

    • clearErrors (boolean, 可选):执行前是否清空错误 checkpoint,默认 true

    • instrument (boolean, 可选):是否注入运行时探针,默认 true

    • trace (boolean, 可选):是否录制 trace,默认 true

    • har (boolean, 可选):是否导出 HAR JSON,默认 true

    • investigateOnFailure (boolean, 可选):失败时是否自动调用 debug_investigate,默认 true

    • continueOnFailure (boolean, 可选):用例失败后是否继续执行后续用例,默认 false

  • 错误:cases 为空抛出 'No test cases provided';浏览器未启动抛出 'Browser not launched';单个用例断言失败会在 result 中标记 failed 但不抛出

  • 示例:{"name":"login-regression","cases":[{"name":"valid-login","steps":[{"action":"navigate","url":"https://example.com/login"}],"assertions":{"urlContains":"dashboard"}}],"clearArtifacts":true}

Inputs: cases (required), har, name, trace, +5 more.

validation_startB

Start an end-to-end validation flow. 启动端到端验证流程,按给定场景列表对目标 URL 执行多步验证。

Inputs: targetUrl (required), testScenarios (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 142 tools

    Disambiguation1/5

    Many tools are exact or near-exact duplicates because v1.9.5 consolidated older tools into mode-based umbrella tools but left the old standalone tools registered (e.g., browser_errors vs browser_errors_aggregate, browser_flow mode=chain vs browser_chain, browser_visual vs browser_visual_compare, security_scan vs security_headers_check). Audit and check tools also heavily overlap (browser_full_audit, browser_smoke_test, browser_visual_check, browser_a11y_check, lighthouse_audit, validation_check). An agent cannot reliably select between deprecated and current variants.

    Naming Consistency3/5

    The dominant pattern is readable snake_case with domain prefixes and verb_action names (browser_*, validation_*, security_*, skill_*), and mode-based umbrella tools mostly follow that convention. However, the pattern is diluted by bare noun tools (browser_artifacts, browser_state, evidence, contract), unprefixed outliers (api_probe, screenshot_diff, css_var_check, bypass_login), and deprecated standalone names that no longer match the consolidated naming scheme.

    Tool Count1/5

    142 tools is an extreme count for any MCP server, and the list is inflated by deprecated aliases, standalone versions of merged tools, and multiple overlapping audit/check capabilities. This imposes a heavy selection and context burden on agents and should be reduced to a focused set of roughly 30-40 unique capabilities organized via mode parameters.

    Completeness4/5

    The server covers the verification domain remarkably broadly: browser lifecycle, interaction, assertion, error/network diagnostics, visual regression, performance, accessibility, security scanning, API contracts, evidence, trace correlation, session management, and MCP self-checks are all present. Minor gaps or workarounds exist (e.g., no standalone browser_assert tool, no direct storage clearing without browser_eval), but no major workflow dead end is apparent.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers