⚡ Omni-Tester: 零幻觉 MCP 测试智能体

Omni-Tester 是一个 Model Context Protocol (MCP) 服务器，为 AI 智能体（Claude、Cursor、Windsurf 等）提供基于证明的防幻觉验证引擎。别再让您的 LLM “猜测”端点是否可用——要求程序化证明。

该智能体直接与后端服务器通信，检查 HTTP 状态码、响应头和 JSON 负载，以产生确定性的、机器可验证的结果。

✅ 目前已实现（确定性证明）

这些层目前即可运行，并返回机器可验证的证据——不涉及任何 LLM 判断：

• 第 1 层 — 协议与状态验证： 发送请求并验证返回的 HTTP 状态码是否与您的明确预期匹配（例如 200 OK、201 Created），标记不匹配项和 5xx 崩溃。

• 第 2 层 — 模式与负载完整性： 检查 Content-Type 头是否为 application/json，将响应体解析为 JSON，并返回负载快照。当您传入可选的 expected_schema 时，它还会以确定性方式强制每个字段的存在性和类型——顶层（"id"）、通过点分路径嵌套（"address.geo.lat"）以及列表索引（"items.0.id"）。支持的类型：int、float/number、str/string、bool、list/array、dict/object、null。（JSON true/false 不被接受为 int。）

这两层始终运行——状态码失败不会抑制负载诊断，因此您仍然可以看到失败的 4xx/5xx 响应的错误正文。

带模式强制的示例：

run_api_4_layer_validation(
    endpoint_url="https://jsonplaceholder.typicode.com/users/1",
    expected_status=200,
    method="GET",
    expected_schema={"id": "int", "email": "str", "address.geo.lat": "str"},
)

还有一个实验性的 run_ui_dom_checklist 工具（Playwright），它会在无头浏览器中加载页面，并报告表单数量、缺少 alt 标签的图片以及控制台错误。

Related MCP server: agentseed

🗺️ 路线图（尚未实现）

以下功能已规划，但目前尚未在代码中实现。此处列出它们是为了透明起见，并非作为可用功能：

• 第 3 层 — 功能业务逻辑： 使用 LLM 检查返回的数据在逻辑上是否符合场景。（注意：该层基于 LLM 判断，而非确定性证明。）

• 第 4 层 — 安全与边界压力测试： 注入恶意负载（SQL 注入字符串、格式错误的标头、过期的身份验证令牌），以验证 API 能否安全地失败。

• 更深入的第 2 层（嵌套类型检查）： ✅ 已完成 — 顶层、点分嵌套路径和列表索引均已强制校验。剩余想法：对整个数组中的每个元素进行验证（例如“每个项目都有一个 int id”）以及枚举/格式约束。

• 自主 API 智能体： 一个自主的测试工程师，负责规划场景、生成 Python 测试代码，并在模式发生变化时自我修复。

• API 探索器智能体： 动态执行模糊测试并串联操作（例如从 GET 中提取令牌，并将其注入到 PUT 中）。

• 审计追踪： 将结构化输出写入 specs/api_plan.md、tests/api/ 和 data/reports/api_report_*.html。

📦 安装

使用 uv（推荐）：

uv venv
source .venv/bin/activate        # On Windows: .venv\Scripts\activate
uv sync                          # Install dependencies from pyproject.toml

对于 UI 检查清单工具，请安装 Playwright 浏览器一次：

uv run playwright install chromium

验证服务器能够启动（它通过 stdio 使用 MCP 进行通信，并将等待客户端连接）：

uv run omni-tester

🔌 连接 MCP 客户端

服务器通过 uv run omni-tester 启动。请将其添加到下方您选择的客户端中。如果客户端的环境变量 PATH 中没有 uv，请在 command 字段中使用 uv 二进制的绝对路径。

Claude Code (CLI)

使用一条命令添加：

claude mcp add --transport stdio omni-tester -- uv run omni-tester

或者手动将其添加到项目作用域的 .mcp.json 文件中：

{
  "mcpServers": {
    "omni-tester": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "omni-tester"],
      "env": {}
    }
  }
}

Claude Desktop

编辑 claude_desktop_config.json（设置 → 开发者 → 编辑配置）：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "omni-tester": {
      "command": "uv",
      "args": ["run", "omni-tester"],
      "env": {}
    }
  }
}

保存后重启 Claude Desktop。

Cursor

编辑 .cursor/mcp.json（项目作用域）或 ~/.cursor/mcp.json（全局）：

{
  "mcpServers": {
    "omni-tester": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "omni-tester"],
      "env": {}
    }
  }
}

Windsurf (Cascade)

编辑 mcp_config.json（设置 → 管理 MCP 服务器 → 查看原始配置）：

• macOS/Linux： ~/.codeium/windsurf/mcp_config.json

• Windows： %APPDATA%\Codeium\Windsurf\mcp_config.json

{
  "mcpServers": {
    "omni-tester": {
      "command": "uv",
      "args": ["run", "omni-tester"],
      "env": {}
    }
  }
}

保存后重启 Windsurf。

🛠️ 工具

命名说明： 该工具之所以命名为 run_api_4_layer_validation，是为了向前兼容，但目前仅实现了第 1–2 层（请参阅路线图）。

🧪 示例

验证一个在线端点，预期返回 200：

run_api_4_layer_validation(
    endpoint_url="https://jsonplaceholder.typicode.com/users/1",
    expected_status=200,
    method="GET",
)

输出结果：

Backend 4-Layer Validation Complete:
✅ Layer 1 PASS: Expected 200, received 200.
✅ Layer 2 PASS: Valid JSON payload returned.
Payload Snapshot: {'id': 1, 'name': 'Leanne Graham', ...}