258 lines
11 KiB
Python
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}'"}
|