feat: servidor mcp institucional y asistente interactivo guiado con spotlight didactico (SDD-011, v3.8.27)

This commit is contained in:
2026-10-27 08:23:04 -03:00
parent a5b014efbe
commit bf5b7c3ae7
20 changed files with 1339 additions and 12 deletions
+1 -1
View File
@@ -7,7 +7,7 @@ from typing import Any
from database import db, get_db, engine, SessionLocal, session
from config.config import Config
__version__ = "3.8.26"
__version__ = "3.8.27"
class DummyContext:
def __enter__(self):
+85
View File
@@ -0,0 +1,85 @@
"""
app/services/guide_service.py - Servicio de Guías Interactivas y Spotlight para UdeCi (SDD-011)
Detecta intenciones de tutorial paso a paso y emite directivas estructuradas
para que el frontend ilumine los botones y campos interactivos ("enseñar a pescar").
"""
import re
import unicodedata
from typing import Optional
from schemas.ai_chat import GuideStepDTO
from mcp_server import STEP_GUIDES
def _normalize(text: str) -> str:
"""Elimina acentos y pasa a minúsculas para matching semántico tolerante."""
nfkd = unicodedata.normalize('NFKD', text)
return ''.join([c for c in nfkd if not unicodedata.combining(c)]).lower()
class GuideService:
"""Servicio de resolución de pasos y directivas de UI para el asistente UdeCi."""
@classmethod
def detect_guide_step(cls, query: str, user_role: str = "alumno") -> Optional[GuideStepDTO]:
"""
Analiza la consulta del usuario y retorna el primer paso interactivo
si el usuario solicita aprender a realizar una acción en el sistema.
"""
if not query:
return None
q = _normalize(query)
# Acción: Crear Aula
if "aula" in q and ("crear" in q or "nueva" in q or "nuevo" in q or "alta" in q or "como" in q or "registrar" in q):
guide = STEP_GUIDES["crear_aula"]
step1 = guide["steps"][0]
return GuideStepDTO(
target_url=guide["target_url"],
selector=step1["selector"],
message=step1["message"],
expected_action=step1["expected_action"],
step_number=1,
total_steps=len(guide["steps"])
)
# Acción: Crear Sede
if ("sede" in q or "edificio" in q) and ("crear" in q or "nueva" in q or "nuevo" in q or "alta" in q or "registrar" in q or "como" in q):
guide = STEP_GUIDES["crear_sede"]
step1 = guide["steps"][0]
return GuideStepDTO(
target_url=guide["target_url"],
selector=step1["selector"],
message=step1["message"],
expected_action=step1["expected_action"],
step_number=1,
total_steps=len(guide["steps"])
)
# Acción: Crear Ciclo Lectivo
if ("ciclo" in q or "periodo" in q) and ("crear" in q or "nuevo" in q or "alta" in q or "como" in q or "registrar" in q):
guide = STEP_GUIDES["crear_ciclo"]
step1 = guide["steps"][0]
return GuideStepDTO(
target_url=guide["target_url"],
selector=step1["selector"],
message=step1["message"],
expected_action=step1["expected_action"],
step_number=1,
total_steps=len(guide["steps"])
)
# Acción: Consultar Cursada de Hoy (para Alumnos / Docentes)
if ("donde curso" in q or "aula de cursada" in q or "clases de hoy" in q or "aula de hoy" in q or "horario de hoy" in q):
guide = STEP_GUIDES["consultar_cursada"]
step1 = guide["steps"][0]
return GuideStepDTO(
target_url=guide["target_url"],
selector=step1["selector"],
message=step1["message"],
expected_action=step1["expected_action"],
step_number=1,
total_steps=len(guide["steps"])
)
return None
+3
View File
@@ -20,6 +20,7 @@ from routers.students import students_router
from routers.dashboard import dashboard_router
from routers.optimizer import optimizer_router, genetic_router
from routers.ai_chat import router as ai_chat_router
from routers.mcp import router as mcp_router
# Initialize FastAPI Application
app = FastAPI(
@@ -54,6 +55,8 @@ app.include_router(optimizer_router)
app.include_router(genetic_router)
app.include_router(ai_chat_router, prefix="/api/chat")
app.include_router(ai_chat_router, prefix="/api/v1/chat")
app.include_router(mcp_router, prefix="/api/mcp")
app.include_router(mcp_router, prefix="/api/v1/mcp")
if __name__ == "__main__":
+257
View File
@@ -0,0 +1,257 @@
"""
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}'"}
+4 -1
View File
@@ -12,6 +12,7 @@ from dependencies import get_optional_current_user, require_roles
from app.models.setting import SystemSetting
from app.models.user import User
from app.services.rag_service import RAGService
from app.services.guide_service import GuideService
from schemas.ai_chat import (
ChatRequest,
ChatResponse,
@@ -190,10 +191,12 @@ async def get_agent_response(
ai_data = response.json()
raw_reply = ai_data["choices"][0]["message"]["content"]
clean_reply, options = _extract_options_from_reply(raw_reply, effective_role)
guide_step = GuideService.detect_guide_step(last_query, effective_role)
return ChatResponse(
response=clean_reply,
quick_options=options,
conversation_id=user_identifier
conversation_id=user_identifier,
guide_step=guide_step
)
except httpx.TimeoutException:
raise HTTPException(
+100
View File
@@ -0,0 +1,100 @@
"""
routers/mcp.py - Router FastAPI para el Servidor MCP de Edu-Space (SDD-011)
Expone contratos OpenAPI y endpoints compatibles con JSON-RPC 2.0 y REST.
"""
from typing import Dict, Any, Optional
from fastapi import APIRouter, HTTPException, status
from pydantic import BaseModel, Field
from mcp_server import EduSpaceMCPServer
router = APIRouter(prefix="", tags=["Model Context Protocol (MCP)"])
class MCPToolExecutionRequest(BaseModel):
name: str = Field(..., description="Nombre de la herramienta MCP a ejecutar")
arguments: Optional[Dict[str, Any]] = Field(default_factory=dict, description="Parámetros de la herramienta")
class JSONRPCRequest(BaseModel):
jsonrpc: str = Field("2.0", description="Versión del protocolo JSON-RPC")
id: Optional[Any] = Field(None, description="Identificador de la petición")
method: str = Field(..., description="Método MCP: tools/list, tools/call")
params: Optional[Dict[str, Any]] = Field(default_factory=dict, description="Parámetros del método")
@router.get("/tools")
def list_mcp_tools():
"""Lista el catálogo de herramientas institucionales expuestas por el servidor MCP."""
return {
"status": "success",
"tools": EduSpaceMCPServer.get_tools_manifest()
}
@router.post("/execute")
def execute_mcp_tool(request: MCPToolExecutionRequest):
"""Ejecuta una herramienta del catálogo MCP de Edu-Space vía REST."""
result = EduSpaceMCPServer.execute_tool(request.name, request.arguments or {})
if "error" in result:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail=result["error"]
)
return {
"status": "success",
"tool": request.name,
"result": result
}
@router.post("")
@router.post("/")
def jsonrpc_mcp_endpoint(req: JSONRPCRequest):
"""
Endpoint estándar compatible con el protocolo MCP (JSON-RPC 2.0).
Soporta 'tools/list' y 'tools/call'.
"""
if req.jsonrpc != "2.0":
return {
"jsonrpc": "2.0",
"id": req.id,
"error": {"code": -32600, "message": "Versión JSON-RPC inválida, debe ser 2.0"}
}
if req.method in ["tools/list", "tools.list"]:
return {
"jsonrpc": "2.0",
"id": req.id,
"result": {
"tools": EduSpaceMCPServer.get_tools_manifest()
}
}
elif req.method in ["tools/call", "tools.call"]:
params = req.params or {}
name = params.get("name")
arguments = params.get("arguments", {})
if not name:
return {
"jsonrpc": "2.0",
"id": req.id,
"error": {"code": -32602, "message": "Parámetro 'name' requerido para tools/call"}
}
tool_result = EduSpaceMCPServer.execute_tool(name, arguments)
return {
"jsonrpc": "2.0",
"id": req.id,
"result": {
"content": [{"type": "text", "text": str(tool_result)}],
"data": tool_result
}
}
else:
return {
"jsonrpc": "2.0",
"id": req.id,
"error": {"code": -32601, "message": f"Método MCP no soportado: '{req.method}'"}
}
+10
View File
@@ -13,10 +13,20 @@ class ChatRequest(BaseModel):
conversation_id: Optional[str] = Field(None, description="Identificador único de conversación o sesión del usuario")
class GuideStepDTO(BaseModel):
target_url: str = Field(..., description="Ruta relativa de la vista de Edu-Space")
selector: str = Field(..., description="Selector CSS del elemento a iluminar con el Spotlight")
message: str = Field(..., description="Instrucción del paso para que el usuario actúe")
expected_action: str = Field("click", description="Acción del usuario: click, input, view")
step_number: int = Field(1, ge=1, description="Número de paso actual")
total_steps: int = Field(1, ge=1, description="Cantidad total de pasos")
class ChatResponse(BaseModel):
response: str = Field(..., description="Respuesta generada por el agente conversacional")
quick_options: Optional[List[str]] = Field(default_factory=list, description="Lista de opciones o preguntas sugeridas para botones interactivos")
conversation_id: Optional[str] = Field(None, description="Identificador único de conversación o sesión del usuario")
guide_step: Optional[GuideStepDTO] = Field(None, description="Directiva de Spotlight interactivo para guiar al usuario e iluminar elementos")
class RAGReindexResponse(BaseModel):
+1 -1
View File
@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
setup(
name="edu-space-admin",
version="3.8.26",
version="3.8.27",
description="Administrative interface for Edu-Space Classroom Management System (FastAPI ASGI Core)",
author="Edu-Space Development Team",
author_email="admin@edu-space.com",
+153
View File
@@ -0,0 +1,153 @@
"""
backend/tests/test_mcp_and_walkthrough.py - Pruebas para el Servidor MCP y Walkthrough (SDD-011)
Valida herramientas MCP institucionales, endpoints JSON-RPC 2.0 / REST y directivas de Spotlight.
"""
from unittest.mock import AsyncMock, patch, MagicMock
import pytest
from fastapi.testclient import TestClient
from main import app
from mcp_server import EduSpaceMCPServer
from app.services.guide_service import GuideService
def test_mcp_server_manifest_and_execution():
"""Valida el manifiesto de herramientas MCP y la ejecución local."""
manifest = EduSpaceMCPServer.get_tools_manifest()
assert len(manifest) >= 3
tool_names = [t["name"] for t in manifest]
assert "get_application_routes" in tool_names
assert "get_canonical_9_steps" in tool_names
assert "get_step_guide" in tool_names
# 1. get_application_routes
routes_all = EduSpaceMCPServer.execute_tool("get_application_routes", {})
assert "routes" in routes_all
assert routes_all["total"] >= 10
routes_alumno = EduSpaceMCPServer.execute_tool("get_application_routes", {"role": "ALUMNO"})
assert routes_alumno["total"] < routes_all["total"]
assert any("/schedule/today_schedule" in r["path"] for r in routes_alumno["routes"])
# 2. get_canonical_9_steps
steps_result = EduSpaceMCPServer.execute_tool("get_canonical_9_steps", {})
assert "steps" in steps_result
assert steps_result["total"] == 9
assert steps_result["steps"][0]["name"] == "Sedes"
assert steps_result["steps"][8]["name"] == "Reserva de Espacio"
# 3. get_step_guide
guide_aula = EduSpaceMCPServer.execute_tool("get_step_guide", {"action": "crear_aula"})
assert "steps" in guide_aula
assert guide_aula["target_url"] == "/classrooms/list_classrooms"
assert len(guide_aula["steps"]) >= 3
def test_mcp_rest_endpoints():
"""Valida los endpoints REST /api/v1/mcp/tools y /api/v1/mcp/execute."""
client = TestClient(app)
# GET /tools
tools_res = client.get("/api/v1/mcp/tools")
assert tools_res.status_code == 200
assert tools_res.json()["status"] == "success"
# POST /execute válido
exec_res = client.post("/api/v1/mcp/execute", json={
"name": "get_canonical_9_steps",
"arguments": {}
})
assert exec_res.status_code == 200
data = exec_res.json()
assert data["status"] == "success"
assert data["result"]["total"] == 9
# POST /execute inválido
bad_res = client.post("/api/v1/mcp/execute", json={
"name": "herramienta_fantasma"
})
assert bad_res.status_code == 400
def test_mcp_jsonrpc_endpoint():
"""Valida el endpoint estándar JSON-RPC 2.0 /api/v1/mcp."""
client = TestClient(app)
# tools/list
rpc_list = client.post("/api/v1/mcp", json={
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list",
"params": {}
})
assert rpc_list.status_code == 200
res1 = rpc_list.json()
assert res1["jsonrpc"] == "2.0"
assert "tools" in res1["result"]
# tools/call
rpc_call = client.post("/api/v1/mcp", json={
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "get_step_guide",
"arguments": {"action": "crear_sede"}
}
})
assert rpc_call.status_code == 200
res2 = rpc_call.json()
assert res2["jsonrpc"] == "2.0"
assert res2["result"]["data"]["target_url"] == "/buildings"
def test_guide_service_intent_detection():
"""Valida que GuideService identifique consultas de acción y construya GuideStepDTO."""
# Crear Aula
step_aula = GuideService.detect_guide_step("¿Cómo creo un aula?", "bedelia")
assert step_aula is not None
assert step_aula.target_url == "/classrooms/list_classrooms"
assert "#btnOpenCreateClassroomModal" in step_aula.selector
# Crear Sede
step_sede = GuideService.detect_guide_step("Quiero crear una sede nueva", "bedelia")
assert step_sede is not None
assert step_sede.target_url == "/buildings"
# Consulta no guiada
step_none = GuideService.detect_guide_step("¿Quién es el decano?", "alumno")
assert step_none is None
def test_chat_endpoint_emits_guide_step_when_requested(init_database):
"""Verifica que el endpoint /api/chat adjunte el guide_step cuando se solicita tutorial."""
client = TestClient(app)
mock_response = MagicMock()
mock_response.status_code = 200
mock_response.json.return_value = {
"choices": [
{
"message": {
"role": "assistant",
"content": "Para crear un aula, presiona el botón Nueva Aula. OPCIONES: [Siguiente paso | Cancelar]"
}
}
]
}
mock_response.raise_for_status = MagicMock()
with patch("httpx.AsyncClient.post", new_callable=AsyncMock) as mock_post:
mock_post.return_value = mock_response
res = client.post("/api/chat", json={
"messages": [{"role": "user", "content": "¿Cómo creo un aula?"}],
"user_role": "bedelia"
})
assert res.status_code == 200
data = res.json()
assert "guide_step" in data
assert data["guide_step"] is not None
assert data["guide_step"]["target_url"] == "/classrooms/list_classrooms"
assert "#btnOpenCreateClassroomModal" in data["guide_step"]["selector"]
assert data["guide_step"]["step_number"] == 1