🎓 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!

---

🏗️ 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

Tool Name	File	Description	Example Query
calculate_expression	calculator.py	Evaluates math formulas, percentages, GPA	Calculate (92*0.4 + 88*0.6)
check_attendance	attendance.py	Reads attendance.csv, checks shortage (<75%)	Check Rahul's attendance
get_marks_summary	marks.py	Reads marks.csv, computes student averages & grades	Calculate Rahul's average marks
read_pdf_notes	pdf_reader.py	Extracts text from notes.pdf via PyPDF	Search PDF for Dijkstra
search_lecture_notes	notes.py	Topic search across course notes	Search notes for OSI model
search_college_rules	rules.py	Queries rules.txt for policies	What is the attendance condonation policy?

---

🎯 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! 🚀