# 🎓 Student Assistant MCP (Model Context Protocol) Server & Groq Client

A complete, production-ready Python MCP project built with **FastMCP** and **Groq LLM Client** that provides intelligent student assistance for academic calculations, attendance tracking, marks analysis, and syllabus reading.

---

## 📁 Project Structure

```
student_assistant_mcp/
├── server.py              # Main FastMCP server registering all tools
├── client_groq.py         # Groq LLM client with MCP tool-calling loop
├── requirements.txt       # Python dependencies (mcp, groq, pandas, pypdf)
├── .env.example           # Environment template
├── tools/
│   ├── __init__.py
│   ├── calculator.py      # Prompt 2: Math, GPA, and attendance deficit tool
│   ├── attendance.py      # Prompt 3: Attendance CSV reader & defaulter tool
│   ├── marks.py           # Prompt 4: Marks CSV reader & averages calculator
│   └── pdf_reader.py      # Prompt 5: PyPDF syllabus extractor & keyword search
└── data/
    ├── attendance.csv     # Student attendance records dataset
    ├── marks.csv          # Student marks, totals, grades, and ranks
    └── sample_syllabus.pdf # Course syllabus document
```

---

## 🚀 Quickstart Guide

### 1. Prerequisites
- Python 3.10+ installed
- A free [Groq API Key](https://console.groq.com) (for `client_groq.py`)

### 2. Create Virtual Environment & Install Dependencies
```bash
# Create virtual environment
python3 -m venv venv

# Activate virtual environment
# On Linux/macOS:
source venv/bin/activate
# On Windows:
venv\Scripts\activate

# Install required packages
pip install -r requirements.txt
```

### 3. Configure Environment Variables
```bash
cp .env.example .env
# Edit .env and paste your GROQ_API_KEY
```

### 4. Run the FastMCP Server
```bash
python server.py
```
Or run in development mode with MCP Inspector:
```bash
mcp dev server.py
```

### 5. Run the Groq Student Assistant Client
In a separate terminal:
```bash
python client_groq.py
```

---

## 🛠️ MCP Tools Overview

| Tool Name | Prompt | Description |
|-----------|--------|-------------|
| `calculate` | Prompt 2 | Safe math evaluation, arithmetic, and GPA formulas |
| `calculate_target_attendance` | Prompt 2 | Calculates consecutive classes needed to reach 75% |
| `get_attendance` | Prompt 3 | Look up student attendance from `attendance.csv` |
| `list_attendance_defaulters` | Prompt 3 | List all students with attendance below 75% |
| `get_marks` | Prompt 4 | Retrieve subject scores, grade, and rank from `marks.csv` |
| `get_marks_averages` | Prompt 4 | Compute class averages and top score per subject |
| `read_pdf` | Prompt 5 | Extract syllabus text using `pypdf.PdfReader` |
| `search_pdf` | Prompt 5 | Search syllabus for grading policy or exam dates |

---

## 🧪 Example Queries for the Student Assistant
- *"What is Alice Johnson's attendance and marks rank?"*
- *"Bob Smith has 68% attendance. How many more classes must he attend to reach 75%?"*
- *"What are the class averages in Computer Science and Math?"*
- *"Search the syllabus PDF for the final exam date and grading breakdown."*