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)

1. clasificar_error_http(status_code) - Clasifica códigos HTTP
2. evaluar_sla(p95_ms, limite_ms) - Evalúa cumplimiento de SLA
3. validar_respuesta_api(status_code, tiempo_ms, limite_ms, tiene_token) - Valida respuesta API
4. buscar_cliente(cip) - Busca cliente en datos_prueba.json

Instalación y Ejecución

1. Instalar Dependencias

# 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):

{
  "$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):

{
  "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

py test_tools.py

4. Ejecutar Pruebas Playwright

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 [email protected]"
• "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, [email protected]) ->

{"valido":true,"cip":"12345","telefono":"6677-8899","email":"[email protected]"}

• 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`:

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