""" 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 / Edificios", "path": "/buildings/list_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_terms_list", "roles": ["ADMIN", "BEDELIA"]}, {"name": "Paso 4: Carreras", "path": "/admin/careers_list", "roles": ["ADMIN", "BEDELIA"]}, {"name": "Paso 5: Asignaturas", "path": "/admin/subjects_list", "roles": ["ADMIN", "BEDELIA"]}, {"name": "Paso 6: Comisiones & Cursadas", "path": "/admin/commissions_list", "roles": ["ADMIN", "BEDELIA"]}, {"name": "Paso 7: Profesores y Docentes", "path": "/admin/users_list", "roles": ["ADMIN", "BEDELIA"]}, {"name": "Paso 8: Alumnos y Matrícula", "path": "/admin/users_list", "roles": ["ADMIN", "BEDELIA"]}, {"name": "Paso 9: Reserva de Espacios Áulicos", "path": "/schedule/list_reservations", "roles": ["ADMIN", "BEDELIA", "DOCENTE"]}, {"name": "Mis Materias", "path": "/my_subjects/my_subjects_list", "roles": ["ALUMNO", "DOCENTE"]}, {"name": "Cartelera de Clases del Día", "path": "/schedule/today_schedule", "roles": ["ALUMNO", "DOCENTE", "BEDELIA"]}, {"name": "Libro de Calificaciones (Gradebook)", "path": "/schedule/gradebook", "roles": ["DOCENTE", "ADMIN", "BEDELIA"]}, {"name": "Optimizador Genético IA", "path": "/genetic_algorithm_web/genetic_optimizer", "roles": ["ADMIN", "BEDELIA"]}, {"name": "Importador Google Sheets", "path": "/admin/google_sheets_import", "roles": ["ADMIN", "BEDELIA"]}, {"name": "Configuración Global", "path": "/admin/settings", "roles": ["ADMIN"]} ] CANONICAL_9_STEPS = [ { "step": 1, "name": "Sedes / Edificios", "route": "/buildings/list_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 aulas físicas (con aforo y piso) o virtuales (Campus Virtual / Meet).", "prerequisite": "Sede física existente" }, { "step": 3, "name": "Ciclos Lectivos", "route": "/admin/academic_terms_list", "description": "Definir el período académico (ej. 2026-2) con fechas de inicio y fin.", "prerequisite": None }, { "step": 4, "name": "Carreras", "route": "/admin/careers_list", "description": "Registrar planes de estudio y carreras oficiales de UniCABA.", "prerequisite": None }, { "step": 5, "name": "Asignaturas", "route": "/admin/subjects_list", "description": "Dar de alta las materias y asociarlas a una o más carreras.", "prerequisite": "Carrera existente" }, { "step": 6, "name": "Comisiones", "route": "/admin/commissions_list", "description": "Crear las divisiones/comisiones de cada materia para el ciclo lectivo.", "prerequisite": "Asignatura y Ciclo Lectivo activos" }, { "step": 7, "name": "Profesores", "route": "/admin/users_list", "description": "Asignar docentes titulares o adjuntos a las comisiones.", "prerequisite": "Comisión activa" }, { "step": 8, "name": "Alumnos", "route": "/admin/users_list", "description": "Matricular a los estudiantes en sus respectivas comisiones.", "prerequisite": "Comisión activa" }, { "step": 9, "name": "Reserva de Espacio", "route": "/schedule/list_reservations", "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 o Edificio", "target_url": "/buildings/list_buildings", "steps": [ { "step_number": 1, "selector": "a[href*='/buildings/add_building'], a[href*='add_building'], a[href*='list_buildings']", "message": "Paso 1: Haz clic en el botón 'Nuevo Edificio' para abrir el formulario.", "expected_action": "click" }, { "step_number": 2, "selector": "#buildingNameInput, input[name='name']", "message": "Paso 2: Escribe el nombre institucional de la sede (ej. 'Sede Central').", "expected_action": "input" }, { "step_number": 3, "selector": "#buildingCodeInput, input[name='code']", "message": "Paso 3: Ingresa el código identificador de la sede (ej. 'CENTRAL').", "expected_action": "input" }, { "step_number": 4, "selector": "#buildingForm button[type='submit'], button[type='submit']", "message": "Paso 4: Haz clic en 'Crear Edificio' para confirmar el alta.", "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": "a[href*='/classrooms/add_classroom'], a[href*='add_classroom'], a[href*='list_classrooms']", "message": "Paso 1: Haz clic en el botón 'Agregar Aula Física' para iniciar la creación.", "expected_action": "click" }, { "step_number": 2, "selector": "#building_id, select[name='building_id']", "message": "Paso 2: Selecciona la Sede o Edificio correspondiente.", "expected_action": "input" }, { "step_number": 3, "selector": "#room_number, input[name='room_number']", "message": "Paso 3: Ingresa el número o nombre del aula (ej. 'Aula 204').", "expected_action": "input" }, { "step_number": 4, "selector": "#capacity, input[name='capacity']", "message": "Paso 4: Define la capacidad de alumnos para el aforo.", "expected_action": "input" }, { "step_number": 5, "selector": "#classroom-form button[type='submit'], button[type='submit']", "message": "Paso 5: Haz clic en 'Crear Aula' para confirmar el guardado.", "expected_action": "click" } ] }, "crear_ciclo": { "title": "Guía: Cómo dar de alta un Ciclo Lectivo", "target_url": "/admin/academic_terms_list", "steps": [ { "step_number": 1, "selector": "button[data-bs-target='#modalAddTerm'], a[href*='academic_terms_list']", "message": "Paso 1: Haz clic en '+ Nuevo Ciclo Lectivo' para abrir la ventana de carga.", "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": "a[href*='today_schedule'], .today-class-card, #todayScheduleContainer", "message": "Aquí puedes ver tus clases del día con el aula física asignada y enlace a Google Meet.", "expected_action": "view" } ] }, "gradebook": { "title": "Guía: Libro de Calificaciones y Actas", "target_url": "/schedule/gradebook", "steps": [ { "step_number": 1, "selector": "a[href*='gradebook']", "message": "Accede al Libro de Calificaciones desde el menú lateral para registrar parciales y regularidades.", "expected_action": "click" } ] }, "importar_sheets": { "title": "Guía: Importador Masivo de Google Sheets", "target_url": "/admin/google_sheets_import", "steps": [ { "step_number": 1, "selector": "a[href*='google_sheets_import']", "message": "Accede al Importador de Google Sheets desde el menú lateral para sincronizar planillas.", "expected_action": "click" } ] } } 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}'"}