""" 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}'"}