🎓 AI-Powered Student Assistant (Model Context Protocol + Groq + Web App)

An interactive, AI-driven educational platform built using Model Context Protocol (MCP), Groq LLM (llama-3.3-70b-versatile), Python 3.11+, and a modern Glassmorphic Web Dashboard.

🌟 Project Features

• Model Context Protocol (MCP): Standardized protocol connecting AI reasoning with local file tools & calculations.

• Groq LLM Power: Blazing fast inference for autonomous tool selection and response synthesis.

• 6 Built-in Educational MCP Tools:

  1. 🧮 Calculator: Evaluates math expressions, percentage weights, and GPA formulas.

  2. 📊 Attendance Tracker: Analyzes student attendance records from attendance.csv, detects shortages (<75%), and predicts required classes.

  3. 📈 Marks Analyzer: Computes averages, top scores, letter grades, and performance rankings from marks.csv.

  4. 📄 PDF Reader: Extracts text and searches content from lecture PDF files (notes.pdf).

  5. 🔍 Lecture Notes Search: Keyword and concept search across course revision notes.

  6. 📜 College Regulations Checker: Queries official college handbook (rules.txt) for attendance rules, grading scales, and library policies.

• Interactive Web Interface (Frontend):

  • Dark glassmorphism design with responsive tabs.

  • Live MCP Protocol Visual Trace: Step-by-step pipeline view showing User Prompt -> Groq LLM -> MCP Server -> Tool Run -> Answer.

  • Interactive Analytics Modules: Marks Report Card, Attendance Shortage Predictor, Searchable Rules Explorer, PDF Viewer, and MCP Tool Sandbox.

  • Offline Simulation Mode: Browser fallback engine that works out-of-the-box even before adding an API key!

Related MCP server: FAST-NUCES Flex Student Portal MCP Server

🏗️ Architecture Overview

User Query
    │
    ▼
Frontend Web Dashboard (HTML/CSS/JS)
    │
    ▼
FastAPI Server (backend/api.py)
    │
    ▼
Groq LLM (llama-3.3-70b-versatile)
    │
    ├─► Intercepts Query & Selects Tool
    │
    ▼
MCP Client (backend/client.py)
    │
    ▼
MCP Server (backend/server.py via FastMCP)
    │
    ├─► calculator.py       (Math & GPA)
    ├─► attendance.py       (attendance.csv)
    ├─► marks.py            (marks.csv)
    ├─► pdf_reader.py       (notes.pdf)
    ├─► notes.py            (notes.txt)
    └─► rules.py            (rules.txt)
    │
    ▼
Groq Formats Natural Language Answer -> User

📁 Project Directory Structure

student_mcp/
├── backend/
│   ├── server.py             # FastMCP / MCP Server tool registry
│   ├── client.py             # Groq LLM tool router & MCP integrator
│   ├── api.py                # FastAPI web bridge for Frontend
│   ├── calculator.py         # Calculation logic
│   ├── attendance.py         # Attendance CSV parser
│   ├── marks.py              # Marks CSV calculator
│   ├── pdf_reader.py         # PDF text extractor (PyPDF)
│   ├── notes.py              # Lecture notes search
│   ├── rules.py              # College handbook search
│   ├── prompts.py            # System prompts & tool definitions
│   ├── requirements.txt      # Dependencies list
│   ├── .env                  # Environment config (GROQ_API_KEY)
│   └── data/
│       ├── attendance.csv    # Attendance dataset
│       ├── marks.csv         # Marks dataset
│       ├── notes.pdf         # Sample academic PDF notes
│       ├── notes.txt         # Text notes reference
│       └── rules.txt         # Official college regulations handbook
│
├── frontend/
│   ├── index.html            # Interactive Student Assistant Web Dashboard
│   ├── styles.css            # Dark mode, glassmorphism & micro-animations
│   └── app.js                # App logic, chat UI, MCP protocol visual trace & tool sandbox
│
├── server.py                 # Root server entrypoint
├── client.py                 # Root terminal CLI client
├── create_pdf.py             # Utility to generate notes.pdf
├── requirements.txt          # Root dependencies
├── .env                      # Root environment variables
└── README.md                 # Complete documentation

⚡ Quick Start Guide

1. Install Dependencies

Ensure Python 3.11+ is installed, then run:

pip install mcp groq pandas pypdf python-dotenv fastapi uvicorn

Or install from requirements file:

pip install -r requirements.txt

2. Configure Groq API Key

1. Sign up for a free account at https://console.groq.com.

2. Create an API key (e.g. gsk_xxxxxxxxxxxxxxxx).

3. Open .env and paste your key:

GROQ_API_KEY=gsk_xxxxxxxxxxxxxxxx

3. Run the Applications

Option A: Launch Interactive Web Dashboard (Recommended)

1. Start the backend FastAPI server:

python backend/api.py

(Runs on http://localhost:8000)

2. Open frontend/index.html in your web browser!

Option B: Run via Python CLI Client

Start the terminal client directly:

python client.py

Example queries to try:

• "Calculate Rahul's average marks."

• "Check Priya's attendance in Computer Networks."

• "What is the minimum attendance required and condonation rule?"

• "Search notes for Binary Search Tree."

• "Calculate (88 * 0.25 + 92 * 0.30 + 95 * 0.45)."

Option C: Run MCP FastMCP Server

python server.py

🚀 Deployment (Easy Options)

Below are minimal options to deploy and run the whole app (backend + frontend) with a single command.

1. Local single-process (recommended for development)

• The backend now serves the frontend static files. Start only the backend:

# from project root
uvicorn backend.api:app --reload --host 0.0.0.0 --port 8000

# open http://localhost:8000 in your browser

2. Docker (recommended for repeatable deploys)

Build and run the included Docker image:

docker build -t student-mcp .
docker run -p 8000:8000 student-mcp

3. Cloud: push the Docker image to any container host (Render, Fly, Heroku Container Registry, Azure ACI) and deploy with their web UI.

Notes:

• Set GROQ_API_KEY in environment (.env or container env) to enable Groq-powered question answering.

• Use requirements.txt to reproduce Python dependencies.

🛠️ MCP Tools Reference

🎯 Verification & Testing

Run unit checks on individual modules:

python backend/calculator.py
python backend/attendance.py
python backend/marks.py
python backend/rules.py

Enjoy building with Model Context Protocol (MCP) and Groq! 🚀