🎓 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 (for client_groq.py)

2. Create Virtual Environment & Install Dependencies

# 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

cp .env.example .env
# Edit .env and paste your GROQ_API_KEY

4. Run the FastMCP Server

python server.py

Or run in development mode with MCP Inspector:

mcp dev server.py

5. Run the Groq Student Assistant Client

In a separate terminal:

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."

mcp-student-assistance