Control Escolar — Spring AI + MCP
A school management web app (students, teachers, subjects, classrooms, schedules, grades, reports, users and roles) with an AI assistant built on the Spring AI ChatClient and an MCP server that exposes school data to any MCP client.
Stack
- Java 21
- Spring Boot 4.1.1
- Spring AI 2.0.1
- OpenAI gpt-4o-mini
- text-embedding-3-small
- MCP Streamable HTTP
- SimpleVectorStore
- Spring Security
- Thymeleaf + Bootstrap 5.3
- H2 / PostgreSQL
- Micrometer Prometheus
What's inside
MCP server
16 tools, 5 resources, 1 resource template, 3 prompts and 3 completions at /mcp.
Chat memory
MessageChatMemoryAdvisor with a JDBC repository, one conversation per user.
RAG
QuestionAnswerAdvisor over the school rules and calendar in a SimpleVectorStore.
Safeguards
SafeGuardAdvisor blocks sensitive words before they reach memory.
Streaming & structured output
SSE token streaming and .entity(AnalisisAlumno.class) for student analysis.
Secure tool calling
registrarCalificacion reads the user's role from ToolContext, which the model cannot alter.
MCP tools
- consultar-alumno-por-matricula
- promedio-alumno
- calificaciones-por-materia
- listar-horario-grupo
- buscar-maestro
- generar-reporte-grupo
- listar-alumnos-en-riesgo
- porcentaje-asistencia-alumno
- calificaciones-alumno-periodo
- horario-maestro
- listar-aulas
- promedio-por-materia
- promedio-por-grupo
- resumen-general
- top-alumnos
- consultar-reglamento
Endpoints
| Path | Description |
|---|---|
/mcp | MCP server (Streamable HTTP, SYNC), no login |
/asistente, /asistente/stream | AI assistant page and SSE stream |
POST /api/ia/preguntar | Ask the assistant (JSON) |
GET /api/ia/analisis-alumno/{matricula} | Structured student analysis |
GET /api/alumnos[/…] | Students (by id, ID number, group) |
GET /api/calificaciones[/…] | Grades and averages |
/reportes/exportar-csv | CSV report export |
/actuator/prometheus | Metrics, including gen_ai_client_* |
Run it
export OPENAI_API_KEY=<your key> # optional
mvn spring-boot:run
# open http://localhost:8080 (demo user: admin / admin123)
npx @modelcontextprotocol/inspector # connect to http://localhost:8080/mcp