# 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

```bash
# Instalar dependencias
pip install -e .
```

## 🚀 Uso principal:

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

```python
# 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