# 🚀 Enterprise-Grade QA MCP Server

Una implementación profesional del **Model Context Protocol (MCP)** para **Quality Assurance**, integrando las mejores prácticas de testing, reportería y gestión de defectos.

## 📋 Tabla de Contenidos

1. [Características](#características)
2. [Arquitectura](#arquitectura)
3. [Instalación](#instalación)
4. [Uso](#uso)
5. [API Reference](#api-reference)
6. [Casos de Uso](#casos-de-uso)
7. [Integraciones](#integraciones)

---

## ✨ Características

### 1. **Gestión de Casos de Prueba** 📝
- Crear, actualizar y eliminar test cases
- Organización por prioridad, etiquetas y estado
- Trazabilidad con requisitos
- Estimación de duración de pruebas

### 2. **Ejecución de Tests** 🧪
- Registro detallado de resultados
- Tracking por environment
- Captura de errores y stack traces
- Métricas de tiempo de ejecución
- Estadísticas de pass/fail rate

### 3. **Gestión de Defectos** 🐛
- Reportería integral de bugs
- Clasificación por severidad (critical, high, medium, low)
- Priorización (P0-P3)
- Workflow de estados
- Asignación a desarrolladores
- Trazabilidad con test cases

### 4. **Análisis de Cobertura** 📊
- Reporte de cobertura de código por línea
- Análisis por archivo
- Identificación de áreas no cubiertas
- Histórico de tendencias
- Visualización de gaps

### 5. **Planificación de Tests** 📅
- Creación de test plans
- Definición de objetivos y scope
- Hitos y cronograma
- Gestión de recursos
- Análisis de riesgos

### 6. **Matriz de Trazabilidad (RTM)** 🔗
- Mapeo requisitos → test cases
- Análisis de cobertura de requisitos
- Identificación de requisitos sin pruebas
- Reporte de gaps

### 7. **Reportería Comprehensiva** 📈
- Dashboards en tiempo real
- Reportes ejecutivos
- Métricas de calidad
- Análisis de tendencias
- Exportación multi-formato

---

## 🏗️ Arquitectura

```
┌─────────────────────────────────────────────────────┐
│          Claude AI (via MCP Protocol)               │
└────────────────┬────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────────┐
│         QA MCP Server (TypeScript/Node.js)          │
├─────────────────────────────────────────────────────┤
│  Test Case Management      │  Defect Management     │
│  Test Execution Tracking   │  Coverage Analysis     │
│  Test Planning             │  RTM & Traceability    │
│  Reporting Engine          │  Statistics & Analytics│
└─────────────────────────────────────────────────────┘
                 │
    ┌────────────┼────────────┐
    ▼            ▼            ▼
[Database]  [File System]  [External Tools]
- Test Cases   - Reports    - Jenkins
- Results      - Logs       - GitHub
- Defects      - Artifacts  - JIRA
```

---

## 🔧 Instalación

### Requisitos
- Node.js 16+
- TypeScript 4.5+
- Claude API Key

### Setup

```bash
# 1. Clonar o descargar el servidor
git clone <repo-url>
cd qa-mcp-server

# 2. Instalar dependencias
npm install

# 3. Compilar TypeScript
npm run build

# 4. Configurar en .claude/settings.json
cat > ~/.claude/settings.json << 'EOF'
{
  "mcpServers": {
    "qa": {
      "command": "node",
      "args": ["qa-mcp-server.js"],
      "env": {
        "API_KEY": "your-key-here"
      }
    }
  }
}
EOF

# 5. Iniciar el servidor
npm start
```

---

## 💡 Uso

### Ejemplo 1: Crear un Test Case

```
User: "Crea un test case para validar el login de usuarios"

Claude:
Voy a crear un test case bien estructurado para validar el login...

Usando: create_test_case
{
  "title": "Validar login de usuario con credenciales correctas",
  "description": "Verifica que un usuario pueda hacer login exitosamente",
  "steps": [
    "1. Navegar a la página de login",
    "2. Ingresar email válido",
    "3. Ingresar contraseña correcta",
    "4. Hacer click en el botón Login",
    "5. Esperar redirección"
  ],
  "expected_result": "Usuario redirigido a dashboard, sesión activa",
  "priority": "critical",
  "tags": ["authentication", "core-feature", "login"]
}

✅ Creado: TC-1718527500 "Validar login de usuario con credenciales correctas"
```

### Ejemplo 2: Registrar Resultado de Test

```
User: "Ejecuté el test TC-1718527500 y falló. El mensaje de error dice que no 
       se puede conectar a la base de datos de usuarios."

Usando: record_test_result
{
  "test_case_id": "TC-1718527500",
  "status": "failed",
  "actual_result": "Error al conectar a base de datos de usuarios",
  "executed_by": "qa_engineer_01",
  "environment": "staging",
  "duration": 12,
  "error_message": "Connection timeout: unable to reach auth_service on port 5432"
}

❌ Registrado: Test TC-1718527500 falló en staging
```

### Ejemplo 3: Reportar Defecto

```
User: "El test falló porque el servicio de autenticación no responde. 
       Este es un bug crítico que encontramos en staging."

Usando: report_defect
{
  "title": "Auth service timeout - database connection issue",
  "description": "El servicio de autenticación no puede conectarse a la BD de usuarios.
                 Timeout después de 30 segundos. Afecta login de todos los usuarios.",
  "severity": "critical",
  "priority": "p0",
  "found_in": "staging",
  "detected_by": "qa_engineer_01",
  "related_test_case_ids": ["TC-1718527500"]
}

🐛 Reportado: DEF-1718527501
   Severidad: CRITICAL
   Prioridad: P0
   Estado: OPEN
```

### Ejemplo 4: Generar Reporte QA

```
User: "Dame un reporte completo del estado actual del testing"

Usando: generate_qa_report

╔════════════════════════════════════════════════════════════════╗
║                  COMPREHENSIVE QA REPORT                      ║
║           Generated: 2026-06-16T10:30:00.000Z                 ║
╚════════════════════════════════════════════════════════════════╝

📊 TEST EXECUTION SUMMARY
────────────────────────────────────────────────────────────────
  Total Tests Executed:     145
  ✅ Passed:                128 (88%)
  ❌ Failed:                12
  🔒 Blocked:               3
  ⏭️  Skipped:               2

🐛 DEFECT SUMMARY
────────────────────────────────────────────────────────────────
  Total Defects:            15
  🟠 Open:                  7
  🟡 In Progress:           5
  ✅ Resolved:              3

  By Priority:
    P0: 2
    P1: 3
    P2: 6
    P3: 4

📋 REQUIREMENTS TRACEABILITY
────────────────────────────────────────────────────────────────
  Total Requirements:       32
  ✅ Fully Traced:          28
  🟡 Partially Traced:      3
  🔴 Untraced:              1
  Coverage:                 87%

📈 CODE COVERAGE
────────────────────────────────────────────────────────────────
  Overall Coverage:         78%
  Lines Covered:            3425/4390
  Uncovered Areas:          965
```

---

## 📚 API Reference

### Test Case Management

#### `create_test_case`
Crea un nuevo caso de prueba.

```typescript
create_test_case({
  title: string,                 // Título descriptivo del test
  description: string,           // Descripción detallada
  steps: string[],              // Pasos a seguir
  expected_result: string,      // Resultado esperado
  priority: "critical" | "high" | "medium" | "low",
  tags?: string[]               // Etiquetas opcionales
})
→ TestCase
```

#### `list_test_cases`
Lista test cases con filtros opcionales.

```typescript
list_test_cases({
  priority?: string,
  tag?: string,
  status?: string
})
→ TestCase[]
```

#### `get_test_case`
Obtiene detalles de un test case específico.

```typescript
get_test_case({
  test_case_id: string
})
→ TestCase | null
```

### Test Execution

#### `record_test_result`
Registra el resultado de una ejecución de test.

```typescript
record_test_result({
  test_case_id: string,
  status: "passed" | "failed" | "blocked" | "skipped",
  actual_result: string,
  executed_by: string,
  environment: string,
  duration: number,              // en segundos
  error_message?: string
})
→ TestResult
```

#### `get_execution_stats`
Obtiene estadísticas de ejecución de tests.

```typescript
get_execution_stats()
→ {
  total: number,
  passed: number,
  failed: number,
  blocked: number,
  skipped: number,
  passRate: number
}
```

### Defect Management

#### `report_defect`
Reporta un nuevo defecto/bug.

```typescript
report_defect({
  title: string,
  description: string,
  severity: "critical" | "high" | "medium" | "low",
  priority: "p0" | "p1" | "p2" | "p3",
  found_in: string,             // environment donde se encontró
  detected_by: string,          // quien lo detectó
  related_test_case_ids?: string[]
})
→ Defect
```

#### `list_defects`
Lista defectos con filtros.

```typescript
list_defects({
  severity?: string,
  status?: string,
  priority?: string
})
→ Defect[]
```

#### `update_defect`
Actualiza estado, asignación o resolución de un defecto.

```typescript
update_defect({
  defect_id: string,
  status?: "open" | "in-progress" | "in-review" | "resolved" | "closed" | "reopened",
  assigned_to?: string,
  resolution?: string
})
→ Defect | null
```

#### `get_defect_stats`
Obtiene estadísticas de defectos.

```typescript
get_defect_stats()
→ {
  total: number,
  open: number,
  inProgress: number,
  resolved: number,
  byPriority: Record<string, number>,
  bySeverity: Record<string, number>
}
```

### Coverage Analysis

#### `get_coverage_report`
Genera o recupera reporte de cobertura.

```typescript
get_coverage_report({
  generate?: boolean,
  total_lines?: number,
  covered_lines?: number,
  by_file?: Record<string, { covered: number, total: number }>
})
→ CoverageReport
```

### Test Planning

#### `create_test_plan`
Crea un nuevo test plan.

```typescript
create_test_plan({
  name: string,
  description: string,
  scope: string,
  objectives: string[],
  test_case_ids?: string[],
  start_date: string,           // ISO 8601
  end_date: string
})
→ TestPlan
```

### Requirements Traceability

#### `add_requirement_to_rtm`
Añade un requisito a la matriz de trazabilidad.

```typescript
add_requirement_to_rtm({
  requirement_id: string,
  description: string,
  test_case_ids?: string[],
  priority: string
})
→ RTMEntry
```

#### `get_rtm_report`
Obtiene reporte de trazabilidad de requisitos.

```typescript
get_rtm_report()
→ {
  total: number,
  fullyTraced: number,
  partiallyTraced: number,
  untraced: number,
  coveragePercentage: number,
  entries: RTMEntry[]
}
```

### Reporting

#### `generate_qa_report`
Genera reporte comprehensivo de QA.

```typescript
generate_qa_report()
→ string (formatted report)
```

---

## 🎯 Casos de Uso

### 1. **Ciclo de Testing Completo**
```
Crear test plan → Crear test cases → Ejecutar tests → 
Registrar resultados → Reportar defectos → 
Actualizar defectos → Generar reportes
```

### 2. **Gestión de Defectos Post-Release**
```
Test ejecutado por usuario
    ↓
Defecto reportado → P0 asignado
    ↓
Desarrollador lo arregla → Status: in-review
    ↓
QA verifica fix → Status: resolved
    ↓
Incluido en retrospectiva
```

### 3. **Análisis de Cobertura de Requisitos**
```
RTM: REQ-123 mapeado a TC-456, TC-789
    ↓
Si todos los tests pasan → Requisito satisfecho
    ↓
Si algún test falla → Defecto vinculado a requisito
    ↓
Reporte de trazabilidad muestra gaps
```

### 4. **Decisiones de Go/No-Go Release**
```
Métricas observadas:
  - Pass Rate: 95% ✅
  - Critical Defects Open: 0 ✅
  - Requirement Coverage: 100% ✅
  - Code Coverage: 85% ✅
    
Decisión: ✅ READY FOR RELEASE
```

---

## 🔌 Integraciones

### Integración con JIRA
```typescript
// Cuando un defecto se reporta:
// 1. Se crea automáticamente en JIRA
// 2. Se sincroniza status bidireccionalmente
// 3. Se vinculan test cases relacionados

report_defect({...})
→ [DEF-123 creado en QA MCP]
→ [JIRA-456 creado automáticamente]
→ [Bidirectional sync habilitado]
```

### Integración con GitHub
```typescript
// Los test results se pueden postear como:
// 1. PR comments
// 2. Status checks
// 3. Commit statuses
// 4. Release notes

record_test_result({...})
→ [GitHub Check created]
→ [PR status actualizado]
```

### Integración con CI/CD (Jenkins, GitHub Actions)
```typescript
// Los tests se ejecutan en pipeline
// Los resultados se sincronizan automáticamente:

pipeline {
  post {
    always {
      // Post test results to QA MCP
      sh '''
        curl -X POST http://qa-mcp:3000/api/results \
          -H "Content-Type: application/json" \
          -d @test-results.json
      '''
    }
  }
}
```

### Integración con Confluence
```typescript
// Genera documentación automática:
// - Test Plans → Confluence pages
// - RTM Reports → Wiki
// - Execution reports → Living documentation

generate_qa_report()
→ [Confluence page creada]
→ [Automáticamente actualizada cada ejecución]
```

---

## 🚀 Mejores Prácticas

### 1. **Test Case Design**
✅ Cada test case debe probar UNA cosa
✅ Usar nombres descriptivos y claros
✅ Incluir precondiciones explícitas
✅ Especificar datos de entrada específicos
✅ Definir claramente el resultado esperado

### 2. **Defect Reporting**
✅ Describir en qué condiciones ocurre el bug
✅ Incluir pasos para reproducir
✅ Adjuntar evidencia (screenshots, logs)
✅ Vincular test cases relacionados
✅ Proporcionar stack traces cuando sea posible

### 3. **Cobertura de Requisitos**
✅ Mapear cada requisito a al menos un test
✅ Rastrear cambios de requisitos
✅ Mantener RTM actualizado
✅ Reportar gaps regularmente
✅ Revisar antes de cada release

### 4. **Métricas Importante**
```
📊 Métricas a Monitorear:
   - Pass Rate (objetivo > 95%)
   - Defect Density (máx 2 por 1000 LOC)
   - Code Coverage (objetivo > 80%)
   - Requirement Traceability (100%)
   - Mean Time to Resolution (MTTR)
   - Test Cycle Time
```

### 5. **Comunicación**
✅ Generar reportes diarios/semanales
✅ Usar dashboards en tiempo real
✅ Escalación automática de P0/Critical
✅ Retrospectivas post-release
✅ Sharing de lecciones aprendidas

---

## 📊 Ejemplo de Flujo Completo

```
Día 1: Planning
├─ create_test_plan
├─ add_requirement_to_rtm (REQ-1 → REQ-50)
└─ create_test_case (TC-1 → TC-200)

Día 2-5: Execution
├─ record_test_result (run batch 1)
├─ record_test_result (run batch 2)
└─ report_defect (encontrados: DEF-1 → DEF-15)

Día 6: Analysis
├─ get_execution_stats → 88% pass rate
├─ list_defects (severity: critical) → 2 defectos P0
├─ get_coverage_report → 78% coverage
└─ get_rtm_report → 95% requirement coverage

Día 7: Report
└─ generate_qa_report → ejecutivos, stakeholders

Decisión: GO/NO-GO basada en métricas

Si NO-GO:
├─ Developers arreglan defectos críticos
├─ Smoke test suite (TC subset)
└─ Re-evaluación

Si GO:
├─ Release pushed
├─ Post-release monitoring
└─ Retrospectiva
```

---

## 🛠️ Troubleshooting

### Error: "Test case not found"
Verifica que el ID del test case sea correcto
```bash
list_test_cases() # para ver todos los IDs
```

### Error: "Connection timeout"
Asegúrate que el MCP server esté corriendo
```bash
npm start
```

### High False Positive Rate
Revisa la especificación del test case
- ¿Está bien definido el expected result?
- ¿Hay flakiness por timing?
- ¿Los datos de test son correctos?

---

## 📞 Soporte y Contribuciones

Para reportar issues o contribuir:
1. Abre un GitHub issue con detalles
2. Incluye logs y pasos para reproducir
3. Proporciona contexto del ambiente
4. Submit PR con fix propuesto

---

**Made with ❤️ for Quality Assurance Engineering**