feat: servidor mcp institucional y asistente interactivo guiado con spotlight didactico (SDD-011, v3.8.27)
This commit is contained in:
@@ -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):
|
||||
|
||||
@@ -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
|
||||
@@ -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__":
|
||||
|
||||
@@ -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}'"}
|
||||
@@ -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(
|
||||
|
||||
@@ -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}'"}
|
||||
}
|
||||
@@ -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
@@ -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",
|
||||
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user