Files
admin-edu-space/backend/mcp_server.py
T

258 lines
11 KiB
Python

"""
mcp_server.py - Servidor Model Context Protocol (MCP) para Admin Edu-Space (UniCABA)
Expone herramientas canónicas y de inspección de la aplicación para que agentes de IA
puedan guiar a los usuarios interactivamente en el uso del sistema.
"""
from typing import Dict, Any, List, Optional
CANONICAL_ROUTES = [
{"name": "Dashboard Principal", "path": "/dashboard", "roles": ["ADMIN", "DOCENTE", "ALUMNO", "BEDELIA"]},
{"name": "Paso 1: Sedes y Edificios", "path": "/buildings", "roles": ["ADMIN", "BEDELIA"]},
{"name": "Paso 2: Aulas Físicas y Virtuales", "path": "/classrooms/list_classrooms", "roles": ["ADMIN", "BEDELIA", "DOCENTE"]},
{"name": "Paso 3: Ciclos Lectivos", "path": "/admin/academic_periods", "roles": ["ADMIN", "BEDELIA"]},
{"name": "Paso 4: Carreras", "path": "/admin/careers", "roles": ["ADMIN", "BEDELIA"]},
{"name": "Paso 5: Asignaturas", "path": "/admin/subjects", "roles": ["ADMIN", "BEDELIA"]},
{"name": "Paso 6: Comisiones", "path": "/admin/commissions", "roles": ["ADMIN", "BEDELIA"]},
{"name": "Paso 7: Profesores y Docentes", "path": "/admin/professors", "roles": ["ADMIN", "BEDELIA"]},
{"name": "Paso 8: Alumnos y Matrícula", "path": "/admin/students", "roles": ["ADMIN", "BEDELIA"]},
{"name": "Paso 9: Reserva de Espacios Áulicos", "path": "/schedule", "roles": ["ADMIN", "BEDELIA", "DOCENTE"]},
{"name": "Mis Materias", "path": "/my_subjects", "roles": ["ALUMNO", "DOCENTE"]},
{"name": "Cartelera de Cursada de Hoy", "path": "/schedule/today_schedule", "roles": ["ALUMNO", "DOCENTE", "BEDELIA"]},
{"name": "Libro de Calificaciones (Gradebook)", "path": "/gradebook", "roles": ["DOCENTE", "ADMIN", "BEDELIA"]},
{"name": "Configuración Global", "path": "/admin/settings", "roles": ["ADMIN"]}
]
CANONICAL_9_STEPS = [
{
"step": 1,
"name": "Sedes",
"route": "/buildings",
"description": "Dar de alta la sede física o campus con nombre, dirección y código.",
"prerequisite": None
},
{
"step": 2,
"name": "Aulas",
"route": "/classrooms/list_classrooms",
"description": "Crear espacios físicos (con aforo y equipamiento) o virtuales (Google Meet).",
"prerequisite": "Sede física existente"
},
{
"step": 3,
"name": "Ciclos Lectivos",
"route": "/admin/academic_periods",
"description": "Definir el período académico (ej. 2026-1C) con fechas de inicio y fin.",
"prerequisite": None
},
{
"step": 4,
"name": "Carreras",
"route": "/admin/careers",
"description": "Registrar planes de estudio y carreras institucionales.",
"prerequisite": None
},
{
"step": 5,
"name": "Asignaturas",
"route": "/admin/subjects",
"description": "Dar de alta las materias y asociarlas a una o más carreras.",
"prerequisite": "Carrera existente"
},
{
"step": 6,
"name": "Comisiones",
"route": "/admin/commissions",
"description": "Crear las divisiones/comisiones de cada materia para el ciclo lectivo.",
"prerequisite": "Asignatura y Ciclo Lectivo activos"
},
{
"step": 7,
"name": "Profesores",
"route": "/admin/professors",
"description": "Asignar docentes titulares o adjuntos a las comisiones.",
"prerequisite": "Comisión activa"
},
{
"step": 8,
"name": "Alumnos",
"route": "/admin/students",
"description": "Matricular a los estudiantes en sus respectivas comisiones.",
"prerequisite": "Comisión activa"
},
{
"step": 9,
"name": "Reserva de Espacio",
"route": "/schedule",
"description": "Asignar aula y banda horaria validando la matriz de conflictos y aforo.",
"prerequisite": "Aula y Comisión completas"
}
]
STEP_GUIDES = {
"crear_sede": {
"title": "Guía: Cómo registrar una nueva Sede",
"target_url": "/buildings",
"steps": [
{
"step_number": 1,
"selector": "#btnNewBuildingModal, button[data-bs-target='#newBuildingModal'], a[href*='building']",
"message": "Paso 1: Haz clic en el botón '+ Nueva Sede' para abrir el formulario.",
"expected_action": "click"
},
{
"step_number": 2,
"selector": "#buildingName, input[name='name']",
"message": "Paso 2: Escribe el nombre institucional de la sede (ej. 'Sede Central').",
"expected_action": "input"
},
{
"step_number": 3,
"selector": "#btnSaveBuilding, button[type='submit']",
"message": "Paso 3: Haz clic en 'Guardar Sede' para confirmar el registro.",
"expected_action": "click"
}
]
},
"crear_aula": {
"title": "Guía: Cómo crear una nueva Aula (Física o Virtual)",
"target_url": "/classrooms/list_classrooms",
"steps": [
{
"step_number": 1,
"selector": "#btnOpenCreateClassroomModal, button[data-bs-target='#createClassroomModal'], .btn-create-classroom, a[href*='classrooms/new']",
"message": "Paso 1: Haz clic en el botón '+ Nueva Aula' para iniciar la creación.",
"expected_action": "click"
},
{
"step_number": 2,
"selector": "#classroomName, input[name='name']",
"message": "Paso 2: Ingresa el nombre o número de aula (ej. 'Aula 204') y define el aforo máximo de alumnos.",
"expected_action": "input"
},
{
"step_number": 3,
"selector": "#btnSaveClassroom, form#createClassroomForm button[type='submit'], .modal-footer .btn-primary",
"message": "Paso 3: Haz clic en 'Guardar Aula' para confirmar el alta.",
"expected_action": "click"
}
]
},
"crear_ciclo": {
"title": "Guía: Cómo dar de alta un Ciclo Lectivo",
"target_url": "/admin/academic_periods",
"steps": [
{
"step_number": 1,
"selector": "#btnNewPeriod, button[data-bs-target='#newPeriodModal'], .btn-new-period",
"message": "Paso 1: Haz clic en '+ Nuevo Ciclo Lectivo' para configurar el período académico.",
"expected_action": "click"
},
{
"step_number": 2,
"selector": "#periodCode, input[name='code']",
"message": "Paso 2: Ingresa el código del ciclo (ej. '2026-1C') y las fechas de inicio y fin.",
"expected_action": "input"
},
{
"step_number": 3,
"selector": "#btnSavePeriod, button[type='submit']",
"message": "Paso 3: Haz clic en 'Guardar Período' para habilitar la cursada.",
"expected_action": "click"
}
]
},
"consultar_cursada": {
"title": "Guía: Cómo consultar el aula de cursada de hoy",
"target_url": "/schedule/today_schedule",
"steps": [
{
"step_number": 1,
"selector": ".today-class-card, #todayScheduleContainer, .table-schedule",
"message": "Aquí puedes ver tus clases del día con el aula física asignada o el botón para unirte a Google Meet.",
"expected_action": "view"
}
]
}
}
class EduSpaceMCPServer:
"""Implementación del servidor MCP institucional para Edu-Space."""
@staticmethod
def get_tools_manifest() -> List[Dict[str, Any]]:
"""Retorna la lista de herramientas disponibles en el protocolo MCP."""
return [
{
"name": "get_application_routes",
"description": "Retorna la lista canónica de rutas, vistas y permisos de Admin Edu-Space.",
"parameters": {
"type": "object",
"properties": {
"role": {"type": "string", "description": "Filtro opcional por rol de usuario (ADMIN, DOCENTE, ALUMNO, BEDELIA)"}
}
}
},
{
"name": "get_canonical_9_steps",
"description": "Retorna la secuencia estandarizada de 9 pasos de Bedelía con descripciones y prerrequisitos.",
"parameters": {"type": "object", "properties": {}}
},
{
"name": "get_step_guide",
"description": "Obtiene la guía interactiva paso a paso con selectores CSS y acciones para iluminar la UI (enseñar a pescar).",
"parameters": {
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": ["crear_sede", "crear_aula", "crear_ciclo", "consultar_cursada"],
"description": "Acción que el usuario desea aprender a realizar."
}
},
"required": ["action"]
}
}
]
@staticmethod
def execute_tool(name: str, arguments: Dict[str, Any]) -> Dict[str, Any]:
"""Ejecuta una herramienta del protocolo MCP y retorna su resultado."""
if name == "get_application_routes":
role_filter = arguments.get("role")
if role_filter:
r_upper = role_filter.upper()
routes = [r for r in CANONICAL_ROUTES if r_upper in r["roles"]]
else:
routes = CANONICAL_ROUTES
return {"routes": routes, "total": len(routes)}
elif name == "get_canonical_9_steps":
return {"steps": CANONICAL_9_STEPS, "total": len(CANONICAL_9_STEPS)}
elif name == "get_step_guide":
action = arguments.get("action", "").lower().strip()
# Mapeo semántico de intenciones
if "sede" in action or "edificio" in action:
key = "crear_sede"
elif "aula" in action:
key = "crear_aula"
elif "ciclo" in action or "periodo" in action:
key = "crear_ciclo"
elif "curso" in action or "clase" in action or "hoy" in action:
key = "consultar_cursada"
else:
key = action
guide = STEP_GUIDES.get(key)
if not guide:
return {
"error": f"No se encontró una guía interactiva para la acción '{action}'.",
"available_actions": list(STEP_GUIDES.keys())
}
return guide
else:
return {"error": f"Herramienta MCP desconocida: '{name}'"}