AI Verify MCP README

ValidPilot Verify

Don't just generate, verify.

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

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

📑 目录

🎯 一句话介绍
🔄 Skill + MCP = 最佳体验
🚀 快速开始
🔧 配置 MCP Server
🎬 实际使用示例
🏆 为什么选择 ValidPilot Verify？
📦 完整工具列表
🔬 证据链概念
⚙️ 环境变量
❓ 常见问题
🔌 MCP Client 配置速查
🎬 演示：✅ vs ❌ 对比
📦 发布自动化
🙏 致谢
💬 社区与联系
❤️ 支持捐赠

🎯 一句话介绍

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 个斜杠命令工作流。

mermaid

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 分钟快速体验

bash

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

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

# 3. 在 AI 助手中配置 MCP（以 Cursor 为例）

方式二：直接验证（无需 MCP）

bash

# 快速验证一个网站
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

📦 更新到最新版本

查看当前版本：

bash

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

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

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

场景 A：MCP 配置中使用 `npx`（推荐，多数用户）

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

json

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

更新方法：将版本号改为最新版本（当前为 1.6.9），或使用 @latest 自动跟随最新：

json

// 方式 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 配置是这种形式：

json

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

更新方法：

bash

# 更新到最新版本
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 安装的：

bash

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

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

🔧 配置 MCP Server

在 Cursor 中使用

打开 Cursor → 设置 → MCP Servers → Add
填写配置

或在 IDE 的 MCP 配置文件中添加（项目级 .cursor/mcp.json 或用户级配置）：

config.json

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

在 Claude Code 中使用

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

config.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：

config.json

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

🎬 实际使用示例

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

你告诉 AI：

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

AI 调用的工具链：

Code

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（生成证据报告）

结果：完整证据链

Code

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 负责"怎么验"。

🎨 验证流程可视化

Code

┌─────────────────────────────────────────────────────────────┐
│                    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 参数区分子模式。例如：

javascript

// 旧方式（仍然可用）：调用 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`

迁移建议

v1.10.0 已移除别名：自 v1.10.0 起，TOOL_ALIASES 正式移除，旧工具名不再可用，必须使用主工具 + mode 参数
升级前必做：从 v1.9.5 升级到 v1.10.0 前，请按上方映射表将代码中所有旧工具名调用替换为主工具 + mode 参数
推荐使用新主工具：新代码直接使用主工具 + mode 参数，工具列表更简洁
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 的核心概念：

每步操作自动截图：时间戳 + 操作类型 + 结果状态
错误自动诊断：错误类型 + 根因分析 + 置信度评分
修复建议生成：基于规则的修复建议 + 验证闭环
报告自动生成：Markdown 报告 + 截图引用 + 诊断结果

示例证据链报告：

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（项目根目录）：

config.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）：

config.json

{
  "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：

config.json

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

在 Claude Code（本地安装）

项目根目录的 .mcp.json：

config.json

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

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

config.json

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

在 Trae IDE

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

方式 A：项目级（推荐，多人共享）

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

config.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）：

config.json

{
  "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 区别）：

toml

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

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

或使用 CLI 一次性添加：

bash

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：

config.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 路径不同）：

yaml

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

或使用 CLI 交互式添加：

bash

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：

config.json

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

或在 IDE 命令面板执行：

Ctrl+Shift+P → "CodeArts: Add MCP Server"
选 stdio → 填 npx → 填 -y,ai-verify-mcp
配置自动写入 mcp_settings.json

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

在 Tencent CodeBuddy

方式 A（推荐）：~/.codebuddy/.mcp.json（推荐）

~/.codebuddy/.mcp.json（全局）或项目级 .mcp.json（项目级）：

config.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，追加：

config.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 编程）

Code

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

✅ 使用 ValidPilot Verify

Code

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

完整证据链文件结构：

Code

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 时会自动执行健康校验。

config.json

{
  "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"
  }
}

执行流程：

bash

$ 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 → 打包预览（不实际打包）

🙏 致谢

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

Playwright 浏览器自动化引擎
@modelcontextprotocol/sdk MCP 协议 SDK
axe-core 无障碍检查

💬 社区与联系

钉钉交流群

扫码加入 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

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

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 获取编码指南和项目约定。

📜 许可证

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

ValidPilot Verify

📑 目录

🎯 一句话介绍

它能做什么？

🔄 Skill + MCP = 最佳体验

三种 Skill 形态

Skill 负责

ai-verify-mcp 负责

🚀 快速开始

方式一：1 分钟快速体验

方式二：直接验证（无需 MCP）

📦 更新到最新版本

场景 A：MCP 配置中使用 npx（推荐，多数用户）

场景 B：全局安装方式

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

🔧 配置 MCP Server

在 Cursor 中使用

在 Claude Code 中使用

在 Windsurf 中使用

🎬 实际使用示例

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

🏆 为什么选择 ValidPilot Verify？

Skill + MCP 协同优势

🎨 验证流程可视化

🔄 v1.9.5 工具体系重构

重构动机与收益

mode 参数使用指南

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

迁移建议

📦 完整工具列表

✅ 验证框架（8个）

🔍 智能诊断（9个）

📸 证据收集（6个）

🌐 浏览器操作（21个）

🎯 智能定位（4个）

🔒 安全扫描（6个）

🔬 证据链概念

⚙️ 环境变量

❓ 常见问题

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

Q: 支持哪些 AI 助手？

Q: 证据存放在哪里？

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

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

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

Q: 端口 3456 已被占用

Q: 截图没生成到 ./artifacts

🔌 MCP Client 配置速查

在 Cursor（项目级推荐）

在 Claude Desktop

在 Windsurf

在 Claude Code（本地安装）

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

在 Trae IDE

方式 A：项目级（推荐，多人共享）

方式 B：用户级（全局生效）

⚠️ Trae MCP 限制提醒

在 Codex CLI（OpenAI）

在 OpenClaw（开源 Claude Code 替代品）

在 Hermes Agent（Nous Research）

在华为云 CodeArts（码云 IDE）

在 Tencent CodeBuddy

🎬 演示：✅ vs ❌ 对比

❌ 没有验证（普通 AI 编程）

✅ 使用 ValidPilot Verify

📦 发布自动化

🙏 致谢

💬 社区与联系

钉钉交流群

联系邮箱

❤️ 支持捐赠 / Donations

捐赠方式 / Donation Methods

📜 许可证

场景 A：MCP 配置中使用 `npx`（推荐，多数用户）

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

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