College Management AI Assistant (v5)

Интеллектуальный административный ассистент колледжа на базе Google Gemini и Model Context Protocol (MCP). Ассистент взаимодействует с реляционной базой данных SQLite через структурированные инструменты FastMCP, чтобы отвечать на вопросы, касающиеся студентов, преподавателей, курсов, зачислений и успеваемости.

Обзор архитектуры

+-------------------------------------------------------------+
|                      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

Возможности

• Генерация синтетических данных: Создаёт реалистичные данные колледжа с помощью Faker, включая студентов, преподавателей, курсы и историю оценок.

• Инструментарий FastMCP: Предоставляет надёжные, соответствующие схеме MCP-инструменты для запросов к академическим данным, курсам, кафедрам и статистике зачислений.

• Интерактивный многошаговый бот: Чат-интерфейс на базе Google GenAI SDK (google-genai) с автоматической оркестрацией вызовов инструментов через MCP.

• Безопасная настройка: Управление API-ключами на основе переменных окружения с поддержкой .env.

Структура проекта

.
├── 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

Схема базы данных

База данных SQLite (college.db) содержит следующие реляционные таблицы:

1. persons: Хранит профили студенты, преподавателей и сотрудников (ID, имя, email, телефон, дата рождения, пол, адрес, роль).

2. courses: Хранит список курсов (ID курса, код курса, название курса, кафедра, кредиты, назначенный преподаватель).

3. student_enrollments: Хранит сведения о зачислении (ID зачисления, ID студента, ID курса, дата, оценка, семестр).

Доступные MCP-инструменты (tooling.py)

• get_student_info(student_id_or_name): Получение профиля студента по ID, имени или email.

• get_course_details(course_code_or_name): Получение информации о курсе и информации о преподавателе.

• get_student_enrollments(student_id_or_name): Вывод списка всех курсов и оценок для студента.

• get_students_by_course(course_code_or_name): Вывод списка студентов, записанных на данный курс.

• list_courses_by_department(department): Вывод списка всех курсов в академическом подразделении.

• get_courses_taught_by_faculty(faculty_id_or_name): Вывод списка курсов, которые ведёт преподаватель.

• search_persons(query, role): Поиск людей по ролям (студент, преподаватель, сотрудник).

• get_course_statistics(course_code_or_name): Сводная статистика (общее количество записанных, распределение оценок).

• list_all_courses(): Полный каталог всех курсов колледжа.

• execute_custom_sql_query(query): Выполнение запросов только для чтения для сложных агрегаций.

Установка и настройка

1. Предварительные требования

• Установлен Python 3.10+

• API-ключ Google Gemini (Google AI Studio)

2. Установка зависимостей

pip install -r requirements.txt

3. Настройка переменных окружения

Создайте или отредактируйте файл .env в корне страницы:

GEMINI_API_KEY=your_actual_gemini_api_key_here

4. Генерация синтетической базы данных

Инициализируйте базу данных синтетическими записями:

python create_data.py

Использование

Запуск интерактивного чат-бота

python bot.py

Введите свои академические или административные вопросы (например, «Покажи все курсы по Computer Science» или «Какие оценки получил Джон Доу?»). Введите exit или quit, чтобы завершить сеанс.

Подключение в качестве MCP-сервера (например, IDE / Claude Desktop / Antigravity)

Обратитесь к mcp_config.example.json, чтобы зарегистрировать tooling.py в конфигурации вашего MCP-клиента:

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