College AI Assistant

An MCP-powered AI assistant for students, built with FastMCP (tool server), CrewAI + Gemini (agent/LLM), FastAPI (backend API), SQLAlchemy (SQLite DB), and a vanilla HTML/CSS/JS chat UI.

Students can ask about: subjects, marks, average marks, performance reports (strong/weak subjects + improvement suggestions), timetable, exam schedules, previous papers (exam prep), fee dues, college events, upcoming holidays, and assignments.

Architecture

Browser (frontend/) --> FastAPI backend (/api/chat) --> CrewAI Agent (Gemini LLM)
                                                              |
                                                     MCP tools over HTTP
                                                              v
                                              FastMCP server (mcp_server/server.py)
                                                              |
                                                              v
                                                  SQLAlchemy models <-> SQLite DB

• app/models.py — SQLAlchemy tables (students, subjects, marks, timetable, exam schedule, previous papers, fees, events, holidays, assignments, chat history).

• app/seed_data.py — populates the DB with mock students/subjects/etc.

• app/mcp_server/server.py — FastMCP server exposing tools that query the DB.

• app/agent/crew.py — CrewAI agent that connects to the MCP server and uses Gemini as the LLM to answer each chat turn, capturing tool-call details.

• app/backend/main.py — FastAPI app: /api/students, /api/chat, /api/chat/history/{id}, and serves the frontend.

• app/frontend/ — chat UI with a "Details" toggle under each AI response showing which tools were called, their arguments, and results.

Related MCP server: Isparta Uni OBS MCP Server

Setup

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Copy .env.example to .env and fill in your own GEMINI_API_KEY (never commit real keys).

Security note: the API key that was included in the original prompt is considered exposed. Rotate it in Google AI Studio and put the new key only in your local .env (already gitignored).

Model name note: gemini/gemma-4-31b-it (as given) does not match a published Gemini/Gemma model. If chat calls fail with a "model not found" error, change GEMINI_MODEL in .env to a real model such as gemini/gemma-3-27b-it or gemini/gemini-2.0-flash.

Running

Seed the database (safe to re-run, it skips if already seeded):

python -m app.seed_data

Start the MCP tool server (terminal 1):

python -m app.mcp_server.server

Start the backend + frontend (terminal 2):

uvicorn app.backend.main:app --reload --port 8000

Open http://127.0.0.1:8000 and pick a student from the dropdown to start chatting.

Seeded test students

CS21001 Aarav Sharma, CS21002 Diya Patel, CS21003 Rohan Mehta, CS21004 Isha Verma — all in Computer Science, semester 4, with mock marks, timetable, exams, fees, assignments, events and holidays.