# Student Assistant MCP Server

A local Model Context Protocol (MCP) server built with Python that allows AI assistants to calculate CGPA, view assignment deadlines, and search subject notes.

## Features

- Calculate CGPA from semester SGPA values
- Read assignment deadlines from a JSON file
- Filter deadlines by subject
- Search local subject notes
- Connect with MCP-compatible clients such as VS Code
- Test tools using MCP Inspector

## Tech Stack

- Python 3.10+
- MCP Python SDK
- uv package manager
- JSON and text files
- MCP Inspector
- Visual Studio Code

## Project Structure

```text
student-assistant-mcp/
├── .vscode/
│   └── mcp.json
├── notes/
│   ├── daa.txt
│   └── dbms.txt
├── src/
│   └── student_assistant_mcp/
│       ├── __init__.py
│       └── server.py
├── .gitignore
├── .python-version
├── deadlines.json
├── pyproject.toml
├── README.md
└── uv.lock
```

## Available MCP Tools

### `calculate_cgpa`

Calculates an estimated CGPA from a list of semester SGPA values.

Example input:

```json
{
  "semester_sgpas": [8.5, 8.9, 9.1]
}
```

Example output:

```text
Your estimated CGPA is 8.83.
```

The current calculation treats every semester as having equal weight.

### `get_upcoming_deadlines`

Reads deadlines from `deadlines.json` and optionally filters them by subject.

Example input:

```json
{
  "subject": "DAA"
}
```

Example output:

```text
DAA: Complete Assignment 4 — 2026-09-15
```

### `search_notes`

Searches for a word or phrase inside a subject's text file.

Example input:

```json
{
  "subject": "DAA",
  "query": "negative"
}
```

Example output:

```text
It does not work correctly with negative edge weights.
```

## Installation

### 1. Clone the repository

```bash
git clone https://github.com/apurva8255/student-assistant-mcp.git
cd student-assistant-mcp
```

### 2. Install uv

Follow the installation guide at:

https://docs.astral.sh/uv/getting-started/installation/

On Windows PowerShell:

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

Restart the terminal after installation.

### 3. Install dependencies

```powershell
uv sync
```

## Running the MCP Server

```powershell
uv run python -m student_assistant_mcp.server
```

The terminal may remain blank because the server communicates through standard input and output and waits for an MCP client.

Press `Ctrl + C` to stop the server.

## Testing with MCP Inspector

Node.js 22.19 or newer is required for the current MCP Inspector.

Run:

```powershell
npx @modelcontextprotocol/inspector uv run python -m student_assistant_mcp.server
```

Open the local URL shown in the terminal, connect to the server, and select **Tools → List Tools**.

## Connecting to VS Code

Create `.vscode/mcp.json` with the following configuration:

```json
{
  "servers": {
    "studentAssistant": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "python",
        "-m",
        "student_assistant_mcp.server"
      ],
      "cwd": "${workspaceFolder}"
    }
  }
}
```

In VS Code:

1. Open the Command Palette using `Ctrl + Shift + P`.
2. Run `MCP: List Servers`.
3. Select `studentAssistant`.
4. Start the server.
5. Open VS Code Chat in Agent mode.

Example prompts:

```text
Calculate my CGPA for SGPAs 8.5, 8.9 and 9.1.

Show my DAA deadlines.

Search my DAA notes for negative edge weights.
```

## How It Works

The AI assistant discovers the tools exposed by the MCP server. When a user asks a relevant question, the AI selects a tool and supplies the required arguments.

The Python server executes the function, reads any required local data, and returns the result to the AI assistant.

```text
User → AI assistant → MCP server → Python tool
User ← AI response  ← Tool result ←─────────
```

## Future Improvements

- Credit-weighted CGPA calculation
- Automatic deadline sorting
- Completed-task tracking
- PDF and DOCX note search
- Semantic search using embeddings
- SQLite database integration
- Google Calendar integration
- Deadline reminders
- Remote deployment with authentication

## Author

**Apurva Sidhawar**  
B.Tech Computer Science and Engineering — Artificial Intelligence and Machine Learning  
Vishwakarma Institute of Technology, Pune