npm.io
1.6.2 • Published 17h agoCLI

@validpilot/ai-verify-mcp

Licence
MIT
Version
1.6.2
Deps
7
Size
1.5 MB
Vulns
0
Weekly
0
SummaryDependencyVersions

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。 详细操作指南：见 用户操作手册，从安装到精通。 遇到问题：见 日志排查手册，常见错误与解决方案。

目录

一句话介绍

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

它能做什么？
  • 验证 AI 生成的代码：打开页面、点击按钮、填写表单、验证结果
  • 留存证据：每步操作自动截图，形成可追溯的证据链
  • 智能诊断错误：自动分析错误根因，给出置信度评分和修复建议
  • 断言验证：验证元素存在、文本内容、URL 匹配等
  • 生成验证报告：Markdown 报告，包含截图证据和诊断结果

Skill + MCP = 最佳体验

ai-verify-mcp 提供 78 个底层验证工具（浏览器操作、截图、a11y 扫描、断言验证等），但这些工具需要被编排调用才能完成完整的验证任务。

Skill 系统（如 Trae 的 browser-dev-full-validation-skill）正是这个编排层——它定义了一套标准验证流程：

flowchart LR
    A[AI 生成代码] --> B[Skill 编排验证流程]
    B --> C[ai-verify-mcp 执行验证]
    C --> D{验证通过?}
    D -->|失败| E[AI 自动修复]
    E --> C
    D -->|通过| F[留存证据链]
Skill 负责
职责 说明
流程编排 定义验证步骤顺序：打开页面 → 截图 → 检查 a11y → 断言结果
证据管理 统一存放截图、日志、HAR 文件到各阶段产物目录
生成验证报告 将多轮验证结果汇总为一份完整报告（成功率、故障清单、修复建议）
对比基准 对比当前验证结果与上一轮（或原始版本），计算回归情况
ai-verify-mcp 负责
职责 说明
84 个原子验证工具 browser_open / browser_overlay_detect / browser_smoke_test / browser_counterfactual_analyze / browser_assert / browser_a11y_check 等
证据链采集 每步操作自动截图，记录 Console 日志和网络请求
对比与 CSS 变量扫描 axe-core 集成、CSS 变量追踪
报告输出 结构化 JSON + Markdown 报告

最佳实践：在 Trae 中同时启用 browser-dev-full-validation-skill + ai-verify-mcp MCP Server。Skill 自动编排 7 阶段验证流程，ai-verify-mcp 提供底层执行能力。两者缺一不可——只有 MCP 缺乏编排，只有 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

配置 MCP Server

在 Cursor 中使用
  1. 打开 Cursor → 设置 → MCP Servers → Add
  2. 填写配置

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

{
  "ai-verify-mcp": {
    "command": "npx",
    "args": ["-y", "ai-verify-mcp"],
    "env": {
      "MCP_MODE": "http",
      "MCP_HTTP_PORT": "3456"
    }
  }
}
在 Claude Code 中使用

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

{
  "mcpServers": {
    "ai-verify-mcp": {
      "command": "npx",
      "args": ["-y", "ai-verify-mcp"],
      "env": {
        "MCP_MODE": "http",
        "MCP_HTTP_PORT": "3456"
      }
    }
  }
}
在 Windsurf 中使用

Settings → MCP Servers → Add：

{
  "ai-verify-mcp": {
    "command": "npx",
    "args": ["-y", "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 友好 78 个专用工具 通用 API 通用 API
证据链留存 自动截图 + 时间戳 手动实现 手动实现
智能诊断 错误根因 + 置信度 仅日志 仅日志
验证报告 Markdown + 截图 需自己写 需自己写
快速验证 一键检查 需编写测试 需编写测试

核心差异：Playwright/Puppeteer 是"手"（负责操作），ValidPilot Verify 是"眼+脑"（负责检查和验证）。

Skill + MCP 协同优势
单独用 MCP 单独用 Skill Skill + MCP 组合
78 个工具但需手动编排 有流程但缺执行能力 自动编排 + 自动执行
验证结果零散 流程模板固定 完整证据链 + 灵活配置
需手动对比差异 无法直接操控浏览器 全自动闭环

推荐配置：在 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   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

完整工具列表

验证框架（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 页面类型识别

证据链概念

证据链是 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: 启动失败，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", "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", "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", "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", "ai-verify-mcp"],
      "env": {
        "MCP_HTTP_PORT": "3456"
      }
    }
  }
}
在 Claude Code（本地安装）

项目根目录的 .mcp.json：

{
  "mcpServers": {
    "ai-verify-mcp": {
      "command": "npx",
      "args": ["-y", "ai-verify-mcp"]
    }
  }
}
在 Cline / Continue / 其他 stdio MCP 客户端
{
  "name": "ai-verify-mcp",
  "command": "npx",
  "args": ["-y", "ai-verify-mcp"]
}
在 Trae IDE

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

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

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

{
  "mcpServers": {
    "ai-verify-mcp": {
      "command": "npx",
      "args": ["-y", "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", "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", "ai-verify-mcp"]

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

或使用 CLI 一次性添加：

codex mcp add ai-verify-mcp -- npx -y 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", "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", "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", "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", "ai-verify-mcp"],
      "env": {
        "MCP_HTTP_PORT": "3456"
      }
    }
  }
}

方式 B：Settings.json 集成

设置 → "Add MCP" → 自动打开 settings.json，追加：

{
  "mcpServers": {
    "ai-verify-mcp": {
      "command": "npx",
      "args": ["-y", "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
> ai-verify-mcp@1.0.0 prepublishOnly
> node bin/validpilot.js health && npm pack --dry-run

{ "ok": true, "name": "ai-verify-mcp", "version": "1.0.0", ... }
npm notice package size: 102.4 kB
npm notice total files: 101
+ npm publish → 上传 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 编程可信赖。

Keywords

aiverifymcpvalidationproofevidenceagentbrowser-automationplaywrightweb-testingvisual-regressionscreenshotdebuggingmcp-servercursorclaudewindsurfcopilotai-codingcode-verification