Qa 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
2. Arquitectura
3. Instalación
4. Uso
5. API Reference
6. Casos de Uso
7. 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

# 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.

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.

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

get_test_case

Obtiene detalles de un test case específico.

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

Test Execution

record_test_result

Registra el resultado de una ejecución de test.

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.

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

Defect Management

report_defect

Reporta un nuevo defecto/bug.

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.

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

update_defect

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

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.

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.

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.

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.

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.

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

Reporting

generate_qa_report

Genera reporte comprehensivo de QA.

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

// 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

// 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)

// 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

// 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

list_test_cases() # para ver todos los IDs

Error: "Connection timeout"

Asegúrate que el MCP server esté corriendo

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