⚡ Omni-Tester: Agente de Pruebas MCP con Cero Alucinaciones

Omni-Tester es un servidor de Model Context Protocol (MCP) que dota a los agentes de IA (Claude, Cursor, Windsurf y otros) de un motor de validación basado en pruebas y antialucinaciones. Deja de permitir que tu LLM «adivine» si un endpoint funciona — exige pruebas programáticas.

El agente se comunica directamente con los servidores backend, inspeccionando los códigos de estado HTTP, las cabeceras de respuesta y los payloads JSON para producir resultados deterministas y verificados por máquina.

✅ Implementado Actualmente (Prueba Determinista)

Estas capas se ejecutan hoy y devuelven evidencia verificada por máquina — sin que intervenga el juicio de un LLM:

• Capa 1 — Verificación de Protocolo y Estado: Envía la petición y verifica que el código de estado HTTP devuelto coincide con tu expectativa explícita (p. ej., 200 OK, 201 Created), marcando discrepancias y fallos 5xx.

• Capa 2 — Integridad del Esquema y del Payload: Comprueba que la cabecera Content-Type sea application/json, analiza el cuerpo como JSON y devuelve una instantánea del payload. Cuando pasas un expected_schema opcional, también aplica de forma determinista la presencia y el tipo de cada campo — campos de nivel superior ("id"), anidados mediante rutas punteadas ("address.geo.lat") e índices de lista ("items.0.id"). Tipos admitidos: int, float/number, str/string, bool, list/array, dict/object, null. (JSON true/false no se acepta como int.)

Ambas capas se ejecutan siempre — un fallo de código de estado no suprime los diagnósticos del payload, por lo que sigues viendo el cuerpo del error de una respuesta 4xx/5xx fallida.

Ejemplo con aplicación del esquema:

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"},
)

También hay una herramienta experimental run_ui_dom_checklist (Playwright) que carga una página en un navegador sin interfaz gráfica y reporta el número de formularios, las imágenes sin etiquetas alt y los errores de consola.

Related MCP server: QA Testing MCP Server

🗺️ Hoja de Ruta (Aún No Implementado)

Lo siguiente está planificado, pero no está actualmente en el código. Se documenta aquí por transparencia, no como funciones disponibles:

• Capa 3 — Lógica de Negocio Funcional: Usa el LLM para comprobar que los datos devueltos encajan lógicamente con el escenario. (Nota: esta capa se basa en el juicio del LLM, no en una prueba determinista.)

• Capa 4 — Pruebas de Seguridad y Límites: Inyecta payloads maliciosos (cadenas de inyección SQL, cabeceras malformadas, tokens de autenticación caducados) para verificar que la API falla de forma segura.

• Capa 2 ampliada (comprobaciones de tipos anidados): ✅ Hecho — se aplican los campos de nivel superior, las rutas anidadas punteadas y los índices de lista. Ideas restantes: validación elemento por elemento en un array completo (p. ej., «cada elemento tiene un id int») y restricciones de enum/formato.

• Agente API Soberano: Un ingeniero de pruebas autónomo que planifica escenarios, genera código de prueba Python y se autocorrige cuando los esquemas cambian.

• Agente Explorador de API: Realiza fuzzing y encadena acciones dinámicamente (p. ej., extrae un token de un GET y lo inyecta en un PUT).

• Registros de auditoría: Salida estructurada en specs/api_plan.md, tests/api/ y data/reports/api_report_*.html.

📦 Instalación

Usando uv (recomendado):

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

Para la herramienta de lista de verificación de UI, instala una vez el navegador de Playwright:

uv run playwright install chromium

Verifica que el servidor arranca (se comunica mediante MCP a través de stdio y esperará a un cliente):

uv run omni-tester

🔌 Conexión con Clientes MCP

El servidor se lanza con uv run omni-tester. Añádelo al cliente que elijas de la lista siguiente. Si uv no está en el PATH de tu cliente, usa la ruta absoluta al binario uv en el campo command.

Claude Code (CLI)

Añádelo con un comando:

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

O añádelo manualmente a un .mcp.json de ámbito de proyecto:

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

Claude Desktop

Edita claude_desktop_config.json (Configuración → Desarrollador → Editar configuración):

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

Reinicia Claude Desktop después de guardar.

Cursor

Edita .cursor/mcp.json (a nivel de proyecto) o ~/.cursor/mcp.json (global):

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

Windsurf (Cascade)

Edita mcp_config.json (Configuración → Gestionar servidores MCP → Ver configuración sin procesar):

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

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

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

Reinicia Windsurf después de guardar.

🛠️ Herramientas

Nota sobre el nombre: la herramienta se llama run_api_4_layer_validation por compatibilidad futura, pero hoy solo están implementadas las Capas 1–2 (consulta la Hoja de Ruta).

🧪 Ejemplo

Validando un endpoint en vivo, esperando un 200:

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

Produce:

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', ...}