CyberEdu MCP Server

Este es el servidor oficial del Protocolo de Contexto de Modelo (MCP) para la plataforma CyberEdu CTF (cyber-edu.co / cyberedu.ro)

GitHub
8
Prueba este MCPPatrocinado

Documentación

Servidor MCP de CyberEdu

Este es el servidor oficial del Protocolo de Contexto de Modelos (MCP) para la plataforma CTF de CyberEdu (https://cyber-edu.co / https://cyberedu.ro). Este servidor descubre y expone automáticamente todos los métodos de CyberEduClient como herramientas MCP, lo que facilita la interacción con la plataforma CyberEdu a través de clientes compatibles con MCP.

Características

  • Descubrimiento Dinámico de Herramientas: Descubre automáticamente todos los métodos públicos de CyberEduClient y los expone como herramientas MCP
  • Configuración Cero para Nuevos Métodos: Cuando se añaden nuevos métodos a CyberEduClient, automáticamente están disponibles como herramientas MCP sin necesidad de cambios en el código
  • Seguridad de Tipos: Genera automáticamente esquemas JSON a partir de las firmas de los métodos y las sugerencias de tipo
  • Manejo de Errores: Manejo integral de errores con mensajes de error detallados

Descripción General de la Plataforma CyberEDU

CyberEDU es una plataforma de formación en ciberseguridad que ofrece laboratorios prácticos, simulaciones realistas y entornos competitivos. Está diseñada para equipos de seguridad empresarial, instituciones académicas, agencias gubernamentales y estudiantes individuales.

Descripción Principal

CyberEDU es una plataforma integral de formación en ciberseguridad que ofrece laboratorios prácticos, simulaciones realistas y entornos competitivos. Está diseñada para equipos de seguridad empresarial, instituciones académicas, agencias gubernamentales y estudiantes individuales que desean desarrollar habilidades prácticas en ciberseguridad a través de escenarios del mundo real.

Diferenciadores Clave

  • Enfoque práctico: Cyber ranges interactivos donde los usuarios atacan y defienden infraestructura real (no solo videos o teoría)
  • Mapeo MITRE ATT&CK: Escenarios mapeados a MITRE ATT&CK, utilizando muestras reales de malware (contenidas de forma segura)
  • Mejor retención: Retención de habilidades 3.5 veces mejor en comparación con el aprendizaje pasivo
  • Escenarios del mundo real: Simula técnicas reales de adversarios y patrones de ataque

Componentes de la Plataforma

  1. Cyber Range — Simulación de guerra cibernética a escala empresarial con topologías de red complejas
  2. Cyber Labs — Más de 650 laboratorios prácticos mapeados a MITRE ATT&CK, basados en navegador y con calificación automática
  3. Tournament Suite — Competencias gamificadas (CTFs, Red vs Blue, juegos de guerra)

Estadísticas Clave

  • Más de 30,000 usuarios activos en todo el mundo
  • Más de 650 laboratorios prácticos
  • Más de 1,400 perfiles de simulación
  • Más de 500 eventos organizados
  • Más de 45 países atendidos
  • Más de 250 horas de contenido de formación

Audiencias Objetivo

  • Estudiantes: Formación enfocada en la carrera profesional con desafíos CTF y tablas de clasificación
  • Academia: Plan de estudios con integración LMS y calificación automática
  • Empresas: Evaluaciones técnicas de contratación, formación de equipos, mapeo de cumplimiento
  • Gobierno: Implementaciones aisladas, simulación OT/SCADA, defensa de infraestructura crítica

Opciones de Implementación

  • SaaS alojado en la nube (basado en navegador, sin instalación)
  • On-premise (VMware, Proxmox, bare-metal)
  • Implementaciones aisladas para entornos clasificados

Instalación

Clonar el Repositorio

El cyberedu-client está incluido como submódulo de git. Clona con --recursive para obtener todo:

git clone --recursive https://github.com/CyberEDU-Cyber-Range/cyberedu-mcp.git
cd cyberedu-mcp

Si ya clonaste sin --recursive, inicializa el submódulo:

git submodule update --init --recursive

Instalar Paquetes

Instala ambos paquetes (cliente y servidor MCP):

macOS/Linux:

python3 -m venv venv  
source venv/bin/activate
pip install -e ".[local]"      # Installs with local cyberedu-client submodule
# Or for development:
# pip install -e ".[local,dev]"

Windows (PowerShell):

python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -e ".[local]"      # Installs with local cyberedu-client submodule

Windows (Símbolo del sistema):

python -m venv venv
venv\Scripts\activate.bat
pip install -e ".[local]"

Alternativa: Instala los paquetes por separado:

pip install -e ./cyberedu-client
pip install -e .

Configuración

Persistencia de Sesión (Recomendado)

El servidor MCP persiste automáticamente las credenciales de sesión en disco. Esto significa:

  • Establece tu cookie una vez usando la herramienta cyberedu_set_session_cookie, y se recordará en todas las sesiones MCP
  • No se necesitan variables de entorno después de la primera autenticación
  • La selección de tenant se conserva cuando cambias de tenant

Ubicación del archivo de sesión:

  • macOS/Linux: ~/.cyberedu-mcp/session.json
  • Windows: %USERPROFILE%\.cyberedu-mcp\session.json (por ejemplo, C:\Users\YourName\.cyberedu-mcp\session.json)

El archivo tiene permisos restringidos (solo lectura/escritura del propietario) por seguridad en sistemas Unix.

Variables de Entorno (Alternativa)

También puedes usar variables de entorno. El servidor carga las credenciales en este orden de prioridad:

  1. Credenciales persistidas en disco (mayor prioridad)
  2. Variables de entorno
  3. Valores predeterminados

Variables de entorno:

  • CYBEREDU_SESSION_COOKIE: Tu cookie de sesión de CyberEdu
    • Obtén esto desde las herramientas de desarrollador de tu navegador después de iniciar sesión en https://app.cyber-edu.co
    • Busca el valor de la cookie cyberedu_session
  • CYBEREDU_TENANT: Tu identificador de tenant (opcional, el valor predeterminado es "cyberedu")

Cómo Obtener tu Cookie de Sesión

Chrome/Edge:

  1. Abre las Herramientas de Desarrollador (F12)
  2. Ve a la pestaña Aplicación/Almacenamiento
  3. Navega a Cookies → https://app.cyber-edu.co
  4. Encuentra cyberedu_session y copia su valor

Firefox:

  1. Abre las Herramientas de Desarrollador (F12)
  2. Ve a la pestaña Almacenamiento
  3. Navega a Cookies → https://app.cyber-edu.co
  4. Encuentra cyberedu_session y copia su valor

Uso

Ejecutar el Servidor MCP

El servidor se puede ejecutar directamente (para pruebas):

macOS/Linux:

python3 -m venv venv

source venv/bin/activate
python -m cyberedu_mcp

Windows:

python -m venv venv
.\venv\Scripts\Activate.ps1
python -m cyberedu_mcp

Configuración del Cliente MCP

Para usar este servidor con un cliente MCP (Cursor IDE o Claude Desktop), agrégalo a tu configuración MCP.

Importante: Usa la ruta completa al ejecutable de Python en tu venv. Los clientes MCP ejecutan servidores externamente y no tendrán acceso a un entorno virtual activado.

Ejemplos para macOS/Linux

Cursor IDE (~/.cursor/mcp.json):

{
  "mcpServers": {
    "cyberedu": {
      "command": "/path/to/cyberedu-mcp/venv/bin/python3",
      "args": ["-m", "cyberedu_mcp"]
    }
  }
}

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "cyberedu": {
      "command": "/path/to/cyberedu-mcp/venv/bin/python3",
      "args": ["-m", "cyberedu_mcp"]
    }
  }
}

Ejemplos para Windows

Cursor IDE (%APPDATA%\Cursor\User\mcp.json o C:\Users\YourName\.cursor\mcp.json):

{
  "mcpServers": {
    "cyberedu": {
      "command": "C:\\path\\to\\cyberedu-mcp\\venv\\Scripts\\python.exe",
      "args": ["-m", "cyberedu_mcp"]
    }
  }
}

Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "cyberedu": {
      "command": "C:\\path\\to\\cyberedu-mcp\\venv\\Scripts\\python.exe",
      "args": ["-m", "cyberedu_mcp"]
    }
  }
}

Ejemplos Multiplataforma

VS Code (.vscode/mcp.json en tu espacio de trabajo):

{
  "servers": {
    "cyberedu": {
      "type": "stdio",
      "command": "/path/to/cyberedu-mcp/venv/bin/python3",
      "args": ["-m", "cyberedu_mcp"]
    }
  }
}

Windows: Usa C:\\path\\to\\cyberedu-mcp\\venv\\Scripts\\python.exe

Antigravity / Windsurf (mcp_config.json - acceso a través de la tienda MCP → Administrar servidores MCP → Ver configuración sin procesar):

{
  "mcpServers": {
    "cyberedu": {
      "command": "/path/to/cyberedu-mcp/venv/bin/python3",
      "args": ["-m", "cyberedu_mcp"],
      "env": {}
    }
  }
}

Windows: Usa C:\\path\\to\\cyberedu-mcp\\venv\\Scripts\\python.exe

Nota: Las credenciales de sesión se persisten en ~/.cyberedu-mcp/session.json, por lo que no se necesitan variables de entorno después de la primera autenticación a través de la herramienta cyberedu_set_session_cookie.

Herramientas Disponibles

El servidor expone automáticamente todos los métodos públicos de CyberEduClient como herramientas MCP. Las herramientas tienen el prefijo cyberedu_ para evitar conflictos de nombres.

Herramientas de Gestión de Sesión

Estas herramientas te permiten gestionar la autenticación y el cambio de tenant sin reiniciar el servidor MCP. Las credenciales se persisten automáticamente en ~/.cyberedu-mcp/session.json:

  • cyberedu_get_session_status - Verifica si estás autenticado, qué tenant está seleccionado y si las credenciales están persistidas
  • cyberedu_set_session_cookie - Establece/actualiza la cookie de sesión para autenticación (se persiste en disco)
  • cyberedu_switch_tenant - Cambia a un tenant/organización diferente (se persiste en disco)
  • cyberedu_clear_session - Borra las credenciales almacenadas del disco y la memoria

Ejemplo de uso:

  1. Verificar estado: "¿Cuál es el estado de mi sesión de CyberEdu?"
  2. Establecer cookie: "Establece mi cookie de sesión de CyberEdu a eyJ..." (solo se necesita una vez, ¡se persiste!)
  3. Cambiar tenant: "Cambia al tenant myorg"
  4. Borrar credenciales: "Borra mi sesión de CyberEdu"

Herramientas de Autenticación y Usuario

  • cyberedu_check_auth - Verifica la autenticación y obtén información del usuario
  • cyberedu_get_user_info - Obtén información completa del usuario
  • cyberedu_list_tenants - Lista todos los tenants disponibles
  • cyberedu_get_current_tenant_info - Obtén información del tenant actual
  • cyberedu_get_user - Obtén información del usuario por ID

Herramientas de Desafíos (Archivo)

  • cyberedu_list_challenges - Lista todos los desafíos (con filtros opcionales)
  • cyberedu_get_challenge - Obtén detalles del desafío
  • cyberedu_get_challenge_difficulties - Obtén los niveles de dificultad disponibles
  • cyberedu_get_challenge_tags - Obtén las etiquetas de desafíos disponibles
  • cyberedu_subscribe_to_challenge - Suscríbete a un desafío

Herramientas de Banderas y Envíos (Archivo)

  • cyberedu_get_flag - Obtén información de bandera/pregunta
  • cyberedu_submit_flag - Envía una bandera/respuesta

Herramientas de Archivos (Archivo)

  • cyberedu_download_file - Descarga un archivo de desafío (usa el parámetro opcional save_path para guardar directamente en disco)

Herramientas de Servicios (Archivo)

  • cyberedu_start_service - Inicia un servicio de desafío
  • cyberedu_get_service_status - Obtén el estado del servicio
  • cyberedu_extend_service - Extiende el tiempo del servicio
  • cyberedu_restart_service - Reinicia el servicio

Herramientas de Concursos

  • cyberedu_list_contests - Lista todos los concursos disponibles
  • cyberedu_get_contest - Obtén detalles del concurso
  • cyberedu_get_contest_ranks - Obtén la tabla de clasificación del concurso
  • cyberedu_get_contest_challenge - Obtén detalles del desafío dentro de un concurso
  • cyberedu_subscribe_to_contest_challenge - Suscríbete a un desafío de concurso

Herramientas de Banderas y Envíos de Concursos

  • cyberedu_get_contest_flag - Obtén información de bandera dentro de un concurso
  • cyberedu_submit_contest_flag - Envía una bandera dentro de un concurso

Herramientas de Archivos de Concursos

  • cyberedu_download_contest_file - Descarga un archivo de un desafío de concurso (usa el parámetro opcional save_path para guardar directamente en disco)

Herramientas de Servicios de Concursos

  • cyberedu_start_contest_service - Inicia un servicio dentro de un concurso
  • cyberedu_get_contest_service_status - Obtén el estado del servicio dentro de un concurso
  • cyberedu_extend_contest_service - Extiende el tiempo del servicio dentro de un concurso
  • cyberedu_restart_contest_service - Reinicia el servicio dentro de un concurso

Ejemplos de Uso y Prompts

Ejemplos de prompts para interactuar con el servidor MCP de CyberEdu:

Sesión y Autenticación

"Check my CyberEdu session status"
"Set my CyberEdu session cookie to eyJpdiI6Ik..."
"Switch to tenant 'mycompany'"

Desafíos (Archivo)

"List all web security challenges"
"Show me the easiest challenges from tenant unbreakable/rocsc"
"Show me hard difficulty forensics challenges"
"Get details for challenge abc123"
"Subscribe me to this challenge and start the service"
"Download challenge files to ./downloads/"
"Submit flag 'CTF{i-like-web-security-ctf-challenges}' for this challenge"

Concursos

"List available CTF contests"
"Show leaderboard for contest 'defcamp ctf quals 2025'"
"Get challenge abc123 from contest 'rocsc26-quals'"
"Start service for this contest challenge"
"Submit flag 'FLAG{solved}' for contest challenge"

Ejemplo de Flujo de Trabajo

1. "List easy web challenges from tenant rocsc"
2. "Subscribe to 'why-xor' and start the service"
3. "Download the challenge files"
4. [Solve...]
5. "Submit flag 'CTF{xor-is-not-safe}'"

Arquitectura

Descubrimiento Dinámico de Herramientas

El servidor utiliza el módulo inspect de Python para descubrir automáticamente todos los métodos públicos de la clase CyberEduClient. Para cada método:

  1. Descubrimiento de Métodos: Escanea la clase en busca de métodos públicos (excluyendo métodos privados y ayudantes)
  2. Generación de Esquemas: Genera automáticamente esquemas JSON a partir de las firmas de los métodos y las sugerencias de tipo
  3. Registro de Herramientas: Registra cada método como una herramienta MCP con metadatos apropiados

Registro de Herramientas

La clase ToolRegistry proporciona un sistema flexible para gestionar herramientas:

  • Descubrimiento Automático: Descubre métodos de clases mediante introspección
  • Registro Manual: Permite el registro manual de métodos personalizados
  • Organización por Categorías: Categoriza automáticamente los métodos (auth, desafíos, concursos, servicios, etc.)

Extensibilidad

Para añadir nueva funcionalidad:

  1. Añade métodos a CyberEduClient: Simplemente añade nuevos métodos públicos a la clase CyberEduClient
  2. Exposición Automática: El servidor MCP descubrirá y expondrá automáticamente los nuevos métodos
  3. Sin Cambios en el Código MCP: No se necesitan cambios en el código del servidor MCP

Para herramientas personalizadas que no se asignan directamente a métodos del cliente:

from cyberedu_mcp.tool_registry import ToolRegistry

registry = ToolRegistry()

def custom_tool(param1: str, param2: int) -> dict:
    """Custom tool description."""
    return {"result": f"{param1}: {param2}"}

registry.register_method(
    name="custom_tool",
    method=custom_tool,
    description="A custom tool",
    category="custom"
)

Manejo de Errores

El servidor proporciona un manejo integral de errores:

  • Errores HTTP: Devuelve información detallada de errores HTTP, incluidos códigos de estado y cuerpos de respuesta
  • Errores de Validación: Devuelve mensajes de error claros para parámetros faltantes o inválidos
  • Errores del Cliente: Devuelve información estructurada de errores para todas las excepciones

Documentación

Documentación adicional está disponible en la carpeta docs/:

  • docs/index.md - Resumen de documentación y referencia rápida
  • docs/architecture.md - Diseño del servidor, descubrimiento de herramientas y gestión de sesiones
  • docs/extending.md - Cómo añadir herramientas personalizadas y modificar el comportamiento

Licencia

MIT