MCP-QA: Analizador de Contratos Swagger/OpenAPI

MCP Server para análisis completo de contratos Swagger/OpenAPI con exportación a JSON y generación automática de documentación.

🎯 Características

• ✅ Soporta Swagger 2.0 y OpenAPI 3.x
• ✅ Análisis completo de endpoints (paths, métodos HTTP)
• ✅ Extracción de parámetros (path, query, header, cookie)
• ✅ Análisis de request bodies con schemas
• ✅ Análisis de responses (códigos HTTP, schemas, headers)
• ✅ Extracción de schemas con propiedades, tipos y formatos
• ✅ Validaciones (obligatoriedad, tipos, formatos UUID/fecha/etc)
• ✅ Información de servidores y seguridad
• ✅ Tags y documentación
• ✅ Exportación a JSON con toda la información estructurada
• ✅ Generación de README con documentación estilo Swagger UI

🏗️ Arquitectura

El proyecto sigue arquitectura limpia y principios SOLID con estructura modular donde cada herramienta es completamente autónoma:

mcp-qa/
├── tools/                           # Herramientas de QA (una por subdirectorio)
│   └── swagger_analyzer/            # Analizador de contratos Swagger/OpenAPI
│       ├── src/                     # Código fuente de la herramienta
│       │   ├── domain/              # Capa de dominio
│       │   │   ├── models.py        # Entidades del dominio
│       │   │   ├── interfaces.py    # Abstracciones (Fetcher, Parser, Analyzer)
│       │   │   └── exporters.py     # Interfaces de exportación
│       │   ├── application/         # Capa de aplicación (casos de uso)
│       │   │   ├── swagger_analyzer.py            # Analizador de contratos
│       │   │   ├── complete_analysis_use_case.py  # Orquestador principal
│       │   │   └── export_use_cases.py            # Casos de uso de exportación
│       │   └── infrastructure/      # Capa de infraestructura
│       │       ├── http_fetcher.py           # Obtención HTTP
│       │       ├── contract_parser.py        # Parser YAML/JSON
│       │       ├── json_exporter.py          # Exportador JSON
│       │       └── markdown_generator.py     # Generador de Markdown
│       ├── __init__.py
│       ├── config.py                # Configuración de la herramienta
│       └── tool.py                  # Facade de la herramienta
├── output/                          # Salidas generadas (por herramienta)
│   └── swagger_analyzer/            # Salidas del analizador Swagger
│       ├── swagger-analysis.json
│       └── API-README.md
└── main.py                          # Punto de entrada MCP

Principios SOLID aplicados:

• S (Single Responsibility): Cada clase tiene una única responsabilidad bien definida
• O (Open/Closed): Fácil agregar nuevas herramientas sin modificar las existentes
• L (Liskov Substitution): Las implementaciones son intercambiables vía interfaces
• I (Interface Segregation): Interfaces específicas y focalizadas
• D (Dependency Inversion): Dependencias de abstracciones mediante inyección

Estructura modular y escalable:

• Cada herramienta es autónoma: Tiene su propio src/ con arquitectura limpia completa
• Alta cohesión, bajo acoplamiento: No hay dependencias entre herramientas
• Estructura homóloga: Todas las herramientas siguen el mismo patrón arquitectónico
• Salidas organizadas: Por herramienta en output/
• Fácil de mantener: Cambios en una herramienta NO afectan a otras
• Fácil de escalar: Agregar nuevas herramientas es simplemente duplicar la estructura

📦 Instalación

# Instalar dependencias
pip install -e .

🚀 Uso principal:

Análisis completo de contrato Swagger (una herramienta, todo incluido)

# Análisis completo: texto + JSON + README
analizar_contrato_swagger("http://localhost:8080/v3/api-docs")

# Con URL de Swagger UI para incluir en README
analizar_contrato_swagger(
    "http://localhost:8080/v3/api-docs",
    swagger_ui_url="http://localhost:8080/swagger-ui/index.html"
)

# Solo texto, sin generar archivos
analizar_contrato_swagger(
    "https://petstore.swagger.io/v2/swagger.json",
    generar_json=False,
    generar_readme=False
)

# Solo JSON
analizar_contrato_swagger(
    "http://localhost:8080/v3/api-docs",
    generar_readme=False
)

Salidas generadas:

Todos los archivos se guardan automáticamente en output/swagger_analyzer/:

• swagger-analysis.json: Análisis completo en JSON estructurado
• API-README.md: Documentación estilo Swagger UI Esto genera un README.md profesional con:
• Tabla de contenidos
• Resumen y estadísticas
• Links a Swagger UI
• Documentación completa de endpoints
• Tablas de schemas y propiedades
• Códigos de estado HTTP

🔍 Información extraída

El analizador extrae:

• Información general: título, versión, descripción
• Servidores: URLs y configuraciones
• Endpoints:
  • Path y método HTTP
  • Parámetros (ubicación, tipo, obligatoriedad)
  • Request body (content types, schemas)
  • Responses (códigos, schemas, headers)
• Schemas:
  • Propiedades con tipos y formatos
  • Validaciones (min/max length, pattern, enum)
  • Obligatoriedad de campos
  • Formatos especiales (UUID, date, email, etc)
• Seguridad: esquemas de autenticación
• Estadísticas: resumen de métodos, códigos HTTP, content types

📄 Licencia

MIT