OpenAPI Contract Tester - MCP Server

✅ Status: COMPLETE MVP - Fases 1-18 Implementadas

Servidor MCP (Model Context Protocol) para testing comprehensivo de APIs basado en especificaciones OpenAPI 3.x con soporte para contract testing usando Pact.

🎯 Características

Generación de Tests

• ✅ Happy Path Tests: Tests con datos válidos para casos exitosos
• ✅ Edge Case Tests: Boundary Value Analysis (valores límite, enums, campos opcionales)
• ✅ Error Case Tests: Tests de errores 400/401/404 (campos faltantes, formatos inválidos, constraints)

Ejecución de Tests

• ✅ HTTP Client con Playwright: Cliente robusto con soporte para todos los métodos HTTP
• ✅ Ejecución Paralela: Ejecuta múltiples tests en paralelo
• ✅ Validación de Schemas: Valida responses contra schemas OpenAPI usando ajv
• ✅ Soporte de Autenticación: Bearer, API Key, Basic, OAuth2

Contract Testing

• ✅ Generación de Contratos Pact: Convierte OpenAPI a contratos Pact
• ✅ Pact Matchers: Matching flexible basado en tipos
• ✅ Verificación de Provider: Verifica que el provider implementa el contrato
• ✅ Pact Broker: Publicación y descarga de contratos

Error Handling & Resilience

• ✅ Custom Error Classes: Errores semánticos con códigos (E001-E999) y mensajes user-friendly
• ✅ Retry Logic: Exponential backoff para errores transitorios (timeout, network)
• ✅ Circuit Breaker: Previene cascading failures con estados CLOSED/OPEN/HALF_OPEN
• ✅ Error Wrapping: Conversión automática de errores nativos a errores custom
• ✅ Structured Logging: Sistema de logs compatible con STDIO que escribe a archivo en modo MCP

MCP Tools (4 herramientas principales)

1. generate-tests: Genera tests inteligentes desde especificaciones OpenAPI

   • Happy path, edge cases, error cases
   • Auto-detección de dependencias entre tests
   • Generación de datos con IA contextual

2. run-tests: Ejecuta tests contra APIs con análisis avanzado

   • Ejecución paralela con control de dependencias
   • Auto-detección de tokens (24 campos conocidos)
   • Validación de schemas automática
   • AI-powered failure analysis

3. export-results: Exporta resultados con análisis profundo

   • Formatos: JSON, HTML profesional, Markdown
   • Auto-comparación: Si detecta specPath + codeEndpoints, ejecuta compare-sources automáticamente
   • Root Cause Analysis: Correlaciona fallos con discrepancias conocidas
   • Coverage analysis integrado
   • AI-powered insights y recomendaciones

4. compare-sources: Compara OpenAPI spec vs Código vs PRD

   • Priorización inteligente: Critical/High/Medium/Low según keywords
   • Reporte HTML visual: Matriz de endpoints, discrepancias color-coded
   • Detección semántica IA: Encuentra matches no obvios (POST /users ≈ POST /register)
   • Business rule mappings (PRD → código)
   • Sugerencias de remediación accionables

📊 Reportes Profesionales

• HTML: Diseño moderno con gradientes, cards interactivos, tablas responsivas y progress bars
• Markdown: Tablas con emojis, executive summary, métricas de performance y detalles de fallos
• Contenido: Summary dashboard, breakdown por categoría/endpoint, failed tests con errores detallados

📦 Instalación

Instalación para Desarrollo

npm install
npm run build

Instalación desde npm (Cuando esté publicado)

npm install -g openapi-contract-tester

🧪 Testing Local (Pre-Publicación)

Para probar el paquete como si estuviera instalado desde npm:

Opción 1: npm link (desarrollo activo)

npm run build
npm link

# Ahora puedes usar el comando globalmente
which openapi-contract-tester

Uso: Ideal para desarrollo cuando haces cambios frecuentes. Los cambios se reflejan inmediatamente.

Opción 2: npm pack (testing de publicación)

npm run build
npm pack
# Crea: openapi-contract-tester-1.0.0.tgz

# Instalar globalmente desde el tarball
npm install -g ./openapi-contract-tester-1.0.0.tgz

# Verificar instalación
which openapi-contract-tester
# Output: /usr/local/lib/node_modules/openapi-contract-tester/dist/index.js

Uso: Prueba exacta de cómo funcionará cuando se publique en npm. Útil para validación final antes de npm publish.

Configuración en cell-cli (después de instalar con cualquier opción):

{
  "mcpServers": {
    "openapi-contract-tester": {
      "command": "openapi-contract-tester",
      "env": {
        "MCP_ROOT": "~/.openapi-contract-tester",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Nota: Por defecto usa gemini-3-flash-preview. Puedes cambiar el modelo con AI_MODEL en env.

Limpiar instalación de prueba:

# Si usaste npm link
npm unlink -g openapi-contract-tester

# Si usaste npm install -g
npm uninstall -g openapi-contract-tester

# Limpiar tarball
rm openapi-contract-tester-*.tgz

⚙️ Configuración

Variables de Entorno

Todas las configuraciones pueden ser controladas vía variables de entorno:

Directorios y Logging

MCP_ROOT=~/.openapi-contract-tester     # Directorio raíz (default: ~/.openapi-contract-tester)
LOG_LEVEL=info                           # Nivel de log: debug, info, warn, error (default: info)
LOG_DIR=/custom/path/logs                # Override del directorio de logs
MAX_LOG_FILE_SIZE=10485760               # Tamaño máximo antes de rotación en bytes (default: 10MB)
MAX_LOG_FILES=5                          # Número de archivos rotados a mantener (default: 5)

AI/LLM Configuration

# Opción 1: Solo cambiar el modelo (recomendado)
AI_MODEL=gemini-3-flash-preview          # Nombre del modelo (default: gemini-3-flash-preview)

# Opción 2: Cambiar modelo a versión anterior
AI_MODEL=gemini-2.5-flash                # Usa gemini-2.5-flash en lugar del default

# Opción 3: URL completa personalizada (override total)
AI_API_URL=https://custom-api.com/v1/generate

# Opción 4: Configuración avanzada
AI_BASE_URL=http://localhost:13800/cell_apps/v1.1/gemini/v1beta/models  # Base URL (default)
AI_MODEL=gemini-3-flash-preview          # Modelo específico
AI_ENDPOINT=generateContent              # Endpoint de generación (default: generateContent)

Prioridad de configuración:

1. AI_API_URL - URL completa (ignora otras variables)
2. AI_MODEL + AI_BASE_URL + AI_ENDPOINT - Construcción dinámica
3. Valores por defecto (gemini-3-flash-preview)

HTTP y Performance

HTTP_TIMEOUT=5000                        # Timeout para requests HTTP en ms (default: 5000)
MAX_PARALLEL_REQUESTS=5                  # Requests HTTP paralelos (default: 5)
MAX_PARALLEL_TESTS=5                     # Tests paralelos (default: 5)
TEST_TIMEOUT=30000                       # Timeout de test execution en ms (default: 30000)

Retry Logic

RETRY_MAX_ATTEMPTS=3                     # Máximo de reintentos (default: 3)
RETRY_INITIAL_DELAY=1000                 # Delay inicial en ms (default: 1000)
RETRY_MAX_DELAY=10000                    # Delay máximo en ms (default: 10000)
RETRY_BACKOFF_MULTIPLIER=2               # Multiplicador para backoff (default: 2)

Circuit Breaker

CIRCUIT_BREAKER_THRESHOLD=5              # Failures antes de abrir (default: 5)
CIRCUIT_BREAKER_TIMEOUT=60000            # Tiempo antes de HALF_OPEN en ms (default: 60000)
CIRCUIT_BREAKER_SUCCESS_THRESHOLD=2      # Éxitos para cerrar en HALF_OPEN (default: 2)

Estructura de Directorios

Cuando se configura MCP_ROOT, se crea la siguiente estructura:

~/.openapi-contract-tester/
└── logs/
    ├── mcp-server-2025-01-19.log
    └── mcp-server-2025-01-19-2025-01-19T10-30-00-123Z.log (rotados)

🚀 Uso

Como MCP Server para cell-cli

1. Configura cell-cli para usar este servidor MCP:

{
  "mcpServers": {
    "openapi-contract-tester": {
      "command": "node",
      "args": ["/ruta/absoluta/a/mcp_testing/dist/index.js"],
      "env": {
        "MCP_ROOT": "~/.openapi-contract-tester",
        "LOG_LEVEL": "info",
        "AI_MODEL": "gemini-3-flash-preview",
        "HTTP_TIMEOUT": "10000",
        "MAX_PARALLEL_TESTS": "10",
        "RETRY_MAX_ATTEMPTS": "3",
        "CIRCUIT_BREAKER_THRESHOLD": "5"
      }
    }
  }
}

Configuración Mínima:

{
  "mcpServers": {
    "openapi-contract-tester": {
      "command": "node",
      "args": ["/ruta/absoluta/a/mcp_testing/dist/index.js"],
      "env": {
        "MCP_ROOT": "~/.openapi-contract-tester",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Nota: Si no especificas AI_MODEL, usa gemini-3-flash-preview por defecto.

2. Usa los tools desde cell-cli:

> Genera tests para mi API usando el archivo ./api.yml
> Ejecuta los tests contra http://localhost:8080
> Crea un contrato Pact entre mi-app y user-api

Uso Directo (sin cell-cli)

1. Generar Tests

import { parseOpenAPISpec, extractEndpoints } from './dist/parsers/openapi-parser.js';
import { generateHappyPathTests } from './dist/generators/happy-path-generator.js';
import { generateEdgeCaseTests } from './dist/generators/edge-case-generator.js';
import { generateErrorCaseTests } from './dist/generators/error-case-generator.js';

// Parsear especificación
const spec = await parseOpenAPISpec('./api.yml');
const endpoints = extractEndpoints(spec);

// Generar tests
const happyTests = generateHappyPathTests(endpoints, { seed: 42 });
const edgeTests = generateEdgeCaseTests(endpoints, { seed: 42 });
const errorTests = generateErrorCaseTests(endpoints, spec, { seed: 42 });

console.log(`Generated ${happyTests.length + edgeTests.length + errorTests.length} tests`);

2. Ejecutar Tests

import { TestRunner } from './dist/executor/test-runner.js';

const environment = {
  name: 'local',
  baseUrl: 'http://localhost:8080',
  timeout: 5000,
  auth: {
    type: 'bearer',
    token: 'your-token-here'
  }
};

const runner = new TestRunner(environment);
const { results, summary } = await runner.runTests(allTests, endpoints, {
  parallel: 5,
  validateSchemas: true,
  onProgress: (completed, total, current) => {
    console.log(`Progress: ${completed}/${total} - ${current.name}`);
  }
});

console.log(`Passed: ${summary.passed}/${summary.total}`);
console.log(`Failed: ${summary.failed}/${summary.total}`);
console.log(`Avg Response Time: ${summary.avgResponseTime}ms`);

3. Contract Testing con Pact

import { generatePactContract, pactContractToJSON } from './dist/pact/pact-generator.js';
import { verifyPactProvider } from './dist/pact/pact-executor.js';
import fs from 'fs/promises';

// Generar contrato
const contract = generatePactContract(endpoints, {
  consumer: 'my-app',
  provider: 'user-api',
  useMatchers: true
});

// Guardar contrato
await fs.writeFile(
  './pacts/my-app-user-api.json',
  pactContractToJSON(contract, true)
);

// Verificar provider
const result = await verifyPactProvider({
  provider: 'user-api',
  providerBaseUrl: 'http://localhost:8080',
  pactUrls: ['./pacts/my-app-user-api.json']
});

console.log(`Verification: ${result.success ? 'PASSED' : 'FAILED'}`);

📊 Ejemplo de Salida

Generación de Tests

Desde una API de 5 endpoints + 3 archivos de documentación:

✅ Happy Path Tests: 4
✅ Edge Case Tests: 24
✅ Error Case Tests: 34
✅ Business Rules Tests: 48 (desde docs/)
📈 Total: 110 tests

Ejecución de Tests

Summary:
  Total: 62
  Passed: 58 (93.55%)
  Failed: 4 (6.45%)
  Duration: 2,345ms
  Avg Response Time: 156ms

By Category:
  happy-path: 4 passed, 0 failed
  edge-case: 22 passed, 2 failed
  error-case: 32 passed, 2 failed

By Endpoint:
  GET /users: 7 tests (7 passed)
  POST /users: 28 tests (26 passed, 2 failed)
  GET /users/{id}: 4 tests (4 passed)
  PUT /users/{id}: 24 tests (22 passed, 2 failed)
  DELETE /users/{id}: 3 tests (3 passed)

📁 Estructura del Proyecto

mcp_testing/
├── src/
│   ├── types/
│   │   └── index.ts (800+ líneas de tipos con JSDoc)
│   ├── parsers/
│   │   └── openapi-parser.ts (400+ líneas)
│   ├── generators/
│   │   ├── data-generator.ts (500+ líneas)
│   │   ├── happy-path-generator.ts (300+ líneas)
│   │   ├── edge-case-generator.ts (450+ líneas)
│   │   └── error-case-generator.ts (450+ líneas)
│   ├── validators/
│   │   ├── schema-validator.ts (400+ líneas)
│   │   └── openapi-validator.ts (400+ líneas)
│   ├── executor/
│   │   ├── http-client.ts (400+ líneas)
│   │   └── test-runner.ts (500+ líneas)
│   ├── pact/
│   │   ├── pact-generator.ts (450+ líneas)
│   │   └── pact-executor.ts (500+ líneas)
│   ├── utils/
│   │   ├── logger.ts (400+ líneas)
│   │   ├── errors.ts (450+ líneas)
│   │   └── resilience.ts (350+ líneas)
│   ├── mcp/
│   │   └── server.ts (650+ líneas)
│   └── index.ts (Entry point)
├── examples/
│   └── user-service.yml
├── LOGGING.md (Logging documentation)
├── ERROR-HANDLING.md (Error handling documentation)
├── package.json
├── tsconfig.json
└── README.md

Total: ~7,700+ líneas de código TypeScript con 100% JSDoc

🧪 Testing

# Ejecutar tests de validación
node quick-test.js
node test-all-generators.js
node test-schema-validator.js
node test-openapi-validator.js
node test-business-rules.js
node test-logger.js
node test-error-handling.js
node test-config.js

# Test con variables de entorno personalizadas
HTTP_TIMEOUT=10000 MAX_PARALLEL_TESTS=10 LOG_LEVEL=debug node test-config.js

🔧 Tecnologías

• TypeScript: Strict mode con tipos completos
• Playwright: HTTP client robusto
• Pact: Contract testing consumer-driven
• ajv: Validación de JSON Schemas
• Faker.js: Generación de datos realistas
• MCP SDK: Integración con CLI conversacional con MCP
• Node.js 18+: ES Modules, async/await

📖 Mejores Prácticas Aplicadas

• ✅ TypeScript strict mode
• ✅ 100% JSDoc coverage
• ✅ ESLint + Prettier
• ✅ Node.js 2025 best practices
• ✅ Error handling comprehensivo con retry & circuit breaker
• ✅ Async/await patterns
• ✅ ES Modules (type: "module")
• ✅ Reproducible test generation (seeds)
• ✅ STDIO-safe logging para protocolo MCP
• ✅ Structured error codes (E001-E999)

📚 Documentación

• LOGGING.md - Sistema de logging compatible con MCP
• ERROR-HANDLING.md - Error handling, retry logic y circuit breaker

📝 Licencia

MIT

Servidor MCP completo para testing de APIs con OpenAPI 3.x, Playwright, y Pact.