College Management AI Assistant (v5)

Un asistente administrativo universitario inteligente impulsado por Google Gemini y el Model Context Protocol (MCP). El asistente interactúa con una base de datos relacional SQLite mediante herramientas FastMCP estructuradas para responder consultas sobre estudiantes, profesorado, asignaturas, matrículas y rendimiento académico.

Descripción general de la arquitectura

+-------------------------------------------------------------+
|                      User / Client                          |
+-------------------------------------------------------------+
                              |
                              v
+-------------------------------------------------------------+
|                   Gemini LLM Assistant                      |
|                         (bot.py)                            |
+-------------------------------------------------------------+
                              |
                     MCP Protocol (stdio)
                              |
                              v
+-------------------------------------------------------------+
|                     FastMCP Server                          |
|                      (tooling.py)                           |
+-------------------------------------------------------------+
                              |
                        SQLite Queries
                              |
                              v
+-------------------------------------------------------------+
|                   College SQLite Database                   |
|                        (college.db)                         |
|   - persons (students, faculty, staff)                      |
|   - courses                                                 |
|   - student_enrollments                                     |
+-------------------------------------------------------------+

Related MCP server: College Scorecard MCP Server

Características

• Generación de datos sintéticos: crea registros universitarios realistas con Faker, incluidos estudiantes, profesorado, asignaturas e historiales de calificaciones.

• Herramientas FastMCP: ofrece herramientas MCP robustas y conformes al esquema para consultar registros académicos, asignaturas, departamentos y estadísticas de matrícula.

• Bot interactivo multiturno: interfaz de chat que aprovecha el SDK de Google GenAI (google-genai), con orquestación automática de llamadas a herramientas mediante MCP.

• Configuración segura: gestión de la clave de API basada en variables de entorno con soporte para .env.

Estructura del proyecto

.
├── bot.py                   # Interactive Gemini chatbot integrating MCP tools via stdio
├── tooling.py               # FastMCP Server exposing database querying tools
├── create_data.py           # SQLite database schema initializer & synthetic data generator
├── college.db               # SQLite database file (generated by create_data.py)
├── system_prompt.txt        # System instruction prompt for the AI assistant
├── prompt.txt               # Context and initial project design prompts
├── mcp_config.example.json  # Example configuration for MCP client registration
├── requirements.txt         # Python package dependencies
├── .env                     # Environment variables (GEMINI_API_KEY)
└── .gitignore               # Git ignore file for Python, SQLite, and secrets

Esquema de la base de datos

La base de datos SQLite (college.db) incluye las siguientes tablas relacionales:

1. persons: almacena los perfiles de estudiantes, profesorado y personal (ID, nombre, correo electrónico, teléfono, fecha de nacimiento, género, dirección y rol).

2. courses: almacena los datos de las asignaturas (ID de la asignatura, código, nombre de la asignatura, departamento, créditos y profesor asignado).

3. student_enrollments: almacena los detalles de matrícula (ID de matrícula, ID de estudiante, ID de asignatura, fecha, calificación y semestre).

Herramientas MCP disponibles (tooling.py)

• get_student_info(student_id_or_name): obtiene el perfil de un estudiante por ID, nombre o correo electrónico.

• get_course_details(course_code_or_name): obtiene los detalles de la asignatura y la información del profesor.

• get_student_enrollments(student_id_or_name): lista todas las asignaturas y calificaciones de un estudiante.

• get_students_by_course(course_code_or_name): lista los estudiantes matriculados en una asignatura determinada.

• list_courses_by_department(department): lista todas las asignaturas de un departamento académico.

• get_courses_taught_by_faculty(faculty_id_or_name): lista las asignaturas impartidas por un miembro del profesorado.

• search_persons(query, role): busca personas en todos los roles (estudiante, profesorado, personal).

• get_course_statistics(course_code_or_name): resumen estadístico (total de matriculados, distribución de calificaciones).

• list_all_courses(): directorio completo de todas las asignaturas de la universidad.

• execute_custom_sql_query(query): ejecuta consultas de solo lectura para agregaciones complejas.

Configuración e instalación

1. Requisitos previos

• Python 3.10+ instalado

• Clave de API de Google Gemini (Google AI Studio)

2. Instalar las dependencias

pip install -r requirements.txt

3. Configurar las variables de entorno

Crea o edita tu archivo .env en la raíz del proyecto:

GEMINI_API_KEY=your_actual_gemini_api_key_here

4. Generar la base de datos sintética

Inicializa la base de datos con datos sintéticos:

python create_data.py

Uso

Ejecutar el bot de IA interactivo

python bot.py

Escribe tus preguntas académicas o administrativas (p. ej., "Muéstrame todas las asignaturas de Informática" o "¿Qué calificaciones recibió John Doe?"). Escribe exit o quit para finalizar la sesión.

Conectarse como servidor MCP (p. ej., IDE / Claude Desktop / Antigravity)

Usa mcp_config.example.json para registrar tooling.py en la configuración de tu cliente MCP:

{
  "mcpServers": {
    "college-tools-mcp": {
      "command": "python",
      "args": [
        "-Wignore",
        "<FULL_PATH_TO>/tooling.py"
      ]
    }
  }
}