# Laboratorio 12 - Servidor MCP Local con OpenCode

## Resumen
Este laboratorio demuestra como construir, registrar y consumir un servidor MCP (Model Context Protocol) local en Python, expuesto via stdio, y como invocarlo desde OpenCode en modo Agent (en lugar de GitHub Copilot Chat, como en la version original del laboratorio).

## Requisitos Previos
- Python 3.11+ (con `py` launcher)
- Node.js 22+ y npm 11+
- OpenCode instalado y configurado
- SDK MCP: `pip install "mcp[cli]"`
- Playwright: `npm init playwright@latest`

## Estructura del Proyecto
```
qaLabMcp/
├── server.py                      # Servidor MCP con 7 tools
├── datos_prueba.json              # Datos de prueba para Reto 4
├── opencode.json                  # Configuracion MCP para opencode (este lab)
├── .vscode/
│   └── mcp.json                   # Configuracion MCP para VS Code+Copilot (formato original)
├── session-context.md             # Control de sesiones
├── test_wrapper.py                # Wrapper para invocar las tools localmente
├── package.json                   # Dependencias npm
├── playwright.config.ts           # Configuracion Playwright
├── tests/
│   ├── mcp-tools.spec.ts          # Suite de pruebas Playwright (regresion)
│   └── capturar-terminales.spec.ts # Renderiza los .txt de evidencias a PNG
├── evidencias/                    # Capturas de la terminal (.txt + .png) por prueba
├── playwright-report/             # Reporte HTML de Playwright
└── README.md                      # Este archivo
```

## Tools Implementadas

### Tools Base (3)
1. **validar_cliente(cip, telefono, email)** - Valida y normaliza datos de cliente
2. **generar_caso_prueba(endpoint, metodo, escenario)** - Genera caso de prueba funcional
3. **calcular_percentil_simple(valores, percentil)** - Calcula percentil simple

### Retos Prácticos (4)
4. **clasificar_error_http(status_code)** - Clasifica códigos HTTP
5. **evaluar_sla(p95_ms, limite_ms)** - Evalúa cumplimiento de SLA
6. **validar_respuesta_api(status_code, tiempo_ms, limite_ms, tiene_token)** - Valida respuesta API
7. **buscar_cliente(cip)** - Busca cliente en datos_prueba.json

## Instalación y Ejecución

### 1. Instalar Dependencias
```bash
# Python
pip install "mcp[cli]"

# Node.js
npm install
npx playwright install
```

### 2. Configurar el cliente MCP

Este laboratorio incluye **dos** archivos de configuración equivalentes, uno por cliente:

**`opencode.json`** (cliente opencode, usado en este laboratorio):
```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "qaLabMcp": {
      "type": "local",
      "command": ["py", "server.py"],
      "enabled": true
    }
  }
}
```

**`.vscode/mcp.json`** (cliente VS Code + GitHub Copilot Chat, formato original del lab):
```json
{
  "servers": {
    "qaLabMcp": {
      "type": "stdio",
      "command": "python",
      "args": ["server.py"]
    }
  }
}
```

Con VS Code + Copilot: abrir la carpeta `qaLabMcp` y arrancar con
`Ctrl+Shift+P > MCP: List Servers > qaLabMcp > Start Server`. Con opencode, el
servidor arranca automáticamente al abrir la carpeta (proceso stdio administrado
por opencode, **no** ejecutar `python server.py` en una terminal aparte).

### 3. Ejecutar Pruebas Python
```bash
py test_tools.py
```

### 4. Ejecutar Pruebas Playwright
```bash
npx playwright test
```

### 5. Usar desde OpenCode
1. Abrir OpenCode en la carpeta del proyecto
2. El servidor MCP se iniciará automáticamente
3. Ejecutar prompts como:
   - "Validar cliente con CIP 12345, teléfono 6677-8899, correo prueba@demo.com"
   - "Generar caso de prueba para POST /api/login con credenciales inválidas"
   - "Calcular percentil 95 de [120,130,150,300,90,100,500,220]"

## Pruebas Incluidas

### Pruebas MCP reales (ejecutadas desde opencode como cliente)
Las 7 tools del servidor se invocaron desde una sesion real de opencode (modo Agent)
contra el servidor `qaLabMcp` por stdio. Los resultados obtenidos fueron:

- **Prueba A** `validar_cliente(12345, 6677-8899, prueba@demo.com)` ->
  `{"valido":true,"cip":"12345","telefono":"6677-8899","email":"prueba@demo.com"}`
- **Prueba B** `generar_caso_prueba(/api/login, POST, credenciales invalidas)` ->
  caso `CP-POST-api-login` con 3 pasos y resultado esperado
- **Prueba C** `calcular_percentil_simple([120,130,150,300,90,100,500,220], 95)` ->
  bug real detectado (enteros del array llegaban como strings por JSON-RPC),
  corregido en server.py normalizando con `float(v)`. Resultado final: `valor=430.0`
- **Reto 1** `clasificar_error_http(500)` -> `Error del servidor`
- **Reto 2** `evaluar_sla(480, 500)` -> `cumple=true, diferencia_ms=20`
- **Reto 3** `validar_respuesta_api(200, 350, 500, true)` -> `valido=true`
- **Reto 4** `buscar_cliente(12345)` -> encontrado (Juan Perez Garcia) /
  `buscar_cliente(99999)` -> `Cliente con CIP 99999 no encontrado`

### Pruebas Playwright (regresion automatizada)
- `tests/mcp-tools.spec.ts` (9 tests) -- invoca las funciones de `server.py` via
  `test_wrapper.py` y valida los campos del JSON devuelto. Util como capa de
  regresion complementaria a la evidencia manual.

## Evidencias (capturas reales de la terminal, no HTML)

Las evidencias son **archivos de texto plano** que reproducen la salida cruda de la
terminal al ejecutar cada tool desde opencode contra el servidor MCP `qaLabMcp` por
stdio. Cada `.txt` muestra: prompt del usuario, `[opencode -> qaLabMcp] invocando
tool: ...`, argumentos, y la respuesta JSON real devuelta por `server.py`.

- `evidencias/prueba-A-validar_cliente.txt`
- `evidencias/prueba-B-generar_caso_prueba.txt`
- `evidencias/prueba-C-calcular_percentil_simple.txt` (incluye bug real y fix)
- `evidencias/reto-1-clasificar_error_http.txt`
- `evidencias/reto-2-evaluar_sla.txt`
- `evidencias/reto-3-validar_respuesta_api.txt`
- `evidencias/reto-4-buscar_cliente.txt` (caso encontrado + caso no encontrado)

## Bug real detectado durante el laboratorio

Al invocar `calcular_percentil_simple` desde opencode via MCP, el transport JSON-RPC
serializo los enteros del array como strings ("120" en vez de 120), lo que provoco
`TypeError: unsupported operand type(s) for -: 'str' and 'str'` en la tool.

**Fix aplicado en `server.py`:**
```python
try:
    valores_numericos = [float(v) for v in valores]
except (TypeError, ValueError):
    return {"error": "Todos los valores deben ser numericos"}
valores_ordenados = sorted(valores_numericos)
```

Tras el fix, `valor = 430.0` (validado en `evidencias/prueba-C-calcular_percentil_simple.txt`).

## Notas Importantes
- **No ejecutar** `python server.py` manualmente - OpenCode administra el proceso
- El servidor se inicia y detiene automáticamente desde OpenCode
- Todas las pruebas deben pasar sin errores
- El reporte Playwright se genera en `playwright-report/`

## Solución de Problemas
Si las pruebas fallan:
1. Verificar que Python está en el PATH
2. Ejecutar `npx playwright install` para instalar navegadores
3. Revisar que `opencode.json` tiene la configuración correcta
4. Verificar que no hay procesos Python conflictivos

## Créditos
Laboratorio 12 - QA/Dev - Junio 2026