ai-verify-mcp: Instructions file for Codex

AI 代理指南

本文档为在 ai-verify-mcp 项目上工作的 AI 编程代理（Claude、Cursor、Trae、Copilot 等）提供指导。

项目概述

ai-verify-mcp 是一个 MCP（模型上下文协议）服务器，为 AI 代理提供 136 个浏览器验证工具（v1.9.3）。它使 AI 代理能够通过标准化的 MCP 接口执行端到端的 Web 验证、调试和自动化修复。

核心技术栈：Node.js + Playwright + @modelcontextprotocol/sdk

架构

server.js                    # 主 MCP 服务器（所有工具处理器位于 switch 语句中）
tools/                       # 136 个 JSON schema 文件（每个工具一个）
handlers/                    # 工具处理器实现（browser/security/validation/exploration 等）
engines/                     # Playwright / Chrome 适配器引擎
core/                        # 核心工具（产物、配置、安全、脱敏、报告）
hands/                       # 高级操作器（browser_operator、evidence_collector、verification_runner）
brain/                       # AI 逻辑（error_aggregator）
rules/                       # 验证规则（suggested-rules.json）
docs/                        # 用户文档
examples/                    # 演示示例
bin/                         # CLI 入口点
test/                        # 单元测试（npm test 运行）
test-reports/                # 测试报告（含 v1.8.0 全量测试报告）

核心约定

1. 工具 schema 与实现必须完全匹配 — tools/*.json 中的每个工具在 server.js 的 switch 语句中都必须有对应的处理器。参数、类型和描述必须保持一致。

2. 安全第一 — 切勿在工具输出中暴露 API 密钥、令牌、密码或 Cookie。使用 core/redaction.js 中的脱敏工具。browser_eval 工具存在已知安全风险，需要仔细进行输入验证。

3. 敏感数据脱敏 — 所有可能包含敏感数据的工具输出（Cookie、存储、带认证头的网络响应）在返回给 MCP 客户端之前必须经过脱敏处理。

4. 错误处理 — 禁止空 catch 块。始终记录错误。HTTP 服务器未经认证不得暴露于公共网络。

5. 会话管理 — 浏览器会话必须能够完全关闭，以防止资源泄漏。池操作必须处理竞态条件以确保线程安全。

6. 日志数组边界控制 — 日志数组必须有大小限制，以防止内存泄漏。

7. Schema 命名 — 使用 inputSchema（驼峰命名），而非 input_schema（下划线命名），以与 MCP SDK 约定保持一致。

8. CLI 参数 — 对于敏感配置，优先使用环境变量而非命令行参数。

代码风格

• 所有 JS 文件顶部使用 'use strict';
• 2 空格缩进
• 字符串使用单引号
• 行尾不使用分号？ — 不，使用分号（参见现有代码）
• 优先使用 const > let > var
• 所有异步操作使用 async/await

添加新工具

1. 创建 tools/<tool_name>.json，包含完整的 JSON schema（name、description、inputSchema）
2. 将工具对象添加到 server.js 的 tools 数组中
3. 在工具处理器 switch 语句中添加 case '<tool_name>': 代码块
4. 更新 README.md 和 docs/USER-MANUAL.md 中的工具数量
5. 如适用，添加测试或验证脚本
6. 更新 CHANGELOG.md