ValidPilot Verify

Don't just generate, verify.

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

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

📑 目录

• 🎯 一句话介绍

• 🔄 Skill + MCP = 最佳体验

• ⚡ 快速开始

• 🔧 配置 MCP Server

• 🎬 实际使用示例

• 🏆 为什么选择 ValidPilot Verify？

• 📦 完整工具列表

• 🔬 证据链概念

• ⚙️ 环境变量

• ❓ 常见问题

• 🔌 MCP Client 配置速查

• 🎬 演示：✅ vs ❌ 对比

• 📦 发布自动化

• 🙏 致谢

• 💬 社区与联系

• ❤️ 支持捐赠

Related MCP server: PixelCheck

🎯 一句话介绍

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

💡 最佳使用方式：配合 AI IDE（如 Trae）的 Skill 系统 使用，形成「生成 → 验证 → 修复 → 复验」的完整内循环。Skill 负责协调验证流程，ai-verify-mcp 提供 77 个底层验证工具，两者组合效果远优于单独使用。

它能做什么？

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

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

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

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

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

🔄 Skill + MCP = 最佳体验

ai-verify-mcp 提供 77 个底层验证工具（浏览器操作、截图、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 负责

ai-verify-mcp 负责

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

⚡ 快速开始

方式一：5 分钟快速体验

# 1. 安装
npm install ai-verify-mcp

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

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

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

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

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

# 一键检查
npx 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？

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

Skill + MCP 协同优势

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

📦 完整工具列表

✅ 验证框架（14个）

🔍 智能诊断（12个）

📸 证据收集（6个）

🌐 浏览器操作（21个）

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

🎯 智能定位（4个）

🔬 证据链概念

证据链是 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%
**建议**: 检查登录是否成功，查看是否有错误提示

⚙️ 环境变量

❓ 常见问题

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 引入了两道硬性上限：

📌 数据来源：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 — 打包预览（不实际打包）

🙏 致谢

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

• Playwright — 浏览器自动化引擎

• @modelcontextprotocol/sdk — MCP 协议 SDK

• axe-core — 无障碍检查

💬 社区与联系

钉钉交流群

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

此二维码永久有效

联系邮箱

📧 validpilot@outlook.com

• 商务合作

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

• 其他问题

❤️ 支持捐赠

感谢您对本项目的关注与支持！

如果您觉得这个项目对您有帮助，或者希望支持我持续开发和维护，欢迎通过捐赠的方式给予鼓励。您的每一份支持，都是我继续前行的动力！

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

捐赠方式

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

PayPal / GitHub Sponsors：暂未开通，敬请期待。

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 编程可信赖。