Skip to main content
Glama
apurva8255

Student Assistant MCP Server

by apurva8255
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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

Related MCP server: UofT Student Helper MCP Server

Tech Stack

  • Python 3.10+

  • MCP Python SDK

  • uv package manager

  • JSON and text files

  • MCP Inspector

  • Visual Studio Code

Project Structure

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:

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

Example output:

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:

{
  "subject": "DAA"
}

Example output:

DAA: Complete Assignment 4 — 2026-09-15

search_notes

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

Example input:

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

Example output:

It does not work correctly with negative edge weights.

Installation

1. Clone the repository

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 -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Restart the terminal after installation.

3. Install dependencies

uv sync

Running the MCP Server

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:

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:

{
  "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:

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.

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

Available Tools

3 tools
calculate_cgpaC

Calculate CGPA from semester SGPA values.

Args: semester_sgpas: List of SGPA values.

ParametersJSON Schema
NameRequiredDescriptionDefault
semester_sgpasYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden, yet it discloses nothing: whether the result is a plain arithmetic mean or credit-weighted, what happens with an empty list, or whether the operation is pure/side-effect-free. For a calculation whose correctness depends on the aggregation rule, this is a meaningful gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded in one sentence with no padding. The appended 'Args:' block largely duplicates the input schema rather than adding information, which is minor waste but not harmful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and as a pure calculation the tool needs no safety or auth disclosure. However, the aggregation semantics of the single required input remain ambiguous, leaving the agent guessing at the one thing that matters for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the single parameter is only echoed back as 'List of SGPA values', which adds almost nothing beyond the schema's array-of-numbers definition. The description does not specify expected value ranges, ordering, whether credits are accounted for, or minimum list length.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb+resource ('Calculate CGPA') and the input basis ('from semester SGPA values'), so an agent immediately knows what the tool produces. Sibling tools (get_upcoming_deadlines, search_notes) are unrelated, so no differentiation is needed, but the description also doesn't name the tool's domain context beyond the calculation itself.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives, no prerequisite statements, and no mention of what kind of input this calculation expects (e.g., a grading system's 0-10 scale). The agent must infer everything about invocation context from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_upcoming_deadlinesC

Get college assignment deadlines.

Args: subject: Optional subject name used to filter deadlines.

ParametersJSON Schema
NameRequiredDescriptionDefault
subjectNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It does not define what 'upcoming' means (time window, horizon), whether results are sorted, or whether the call is a safe read — the read-only nature is only implied by 'Get'. A significant gap for a query tool whose name hinges on a temporal qualifier.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Compact and front-loaded with the core purpose first, then the single parameter. The raw 'Args:' formatting is a minor stylistic artifact but wastes no space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained. For a one-parameter query tool this is close to adequate, but the undefined 'upcoming' window is a real gap an agent would need resolved before trusting the results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, and it does minimally: it explains that 'subject' is an optional subject name used to filter deadlines. It does not clarify matching behavior (exact vs. substring, case sensitivity) or what happens when the parameter is omitted.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb+resource ('Get college assignment deadlines') and the resource is distinguishable from siblings like calculate_cgpa and search_notes. However, the central qualifier in the tool name — 'upcoming' — is never explained in the description, leaving the temporal scope unspecified.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use, when-not-to-use, or alternative-tool guidance is given. The only usage hint is that subject is an optional filter, which is inferred rather than stated as a usage condition.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_notesB

Search for a word or phrase in subject notes.

Args: subject: Subject name, such as DAA or DBMS. query: Word or phrase to search for.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
subjectYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. It does not disclose matching semantics (case sensitivity, substring vs whole-word), whether results are paginated or capped, or what happens when nothing matches. Only the basic read nature of the operation is implied.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short and front-loads the purpose before listing arguments. The Args block is slightly redundant with the schema but remains compact and earns its place by supplying the missing param semantics.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained. However, for a search tool with zero annotation coverage and 0% schema description coverage, the description omits result behavior (matching rules, limits, empty results), leaving a real gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, and it does: both required parameters are explained, with 'subject' given concrete example values ('DAA or DBMS') and 'query' clarified as a word or phrase. It adds meaningful semantics beyond the bare schema types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (search) and resource (subject notes) with the scope of the search target. It doesn't need to differentiate from siblings, since calculate_cgpa and get_upcoming_deadlines are unrelated, but it also stops short of anything beyond the basic statement of purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives, nor any conditions, prerequisites, or exclusions. The reader can infer it is for finding text in notes, but nothing is stated explicitly.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedcalculate_cgpa
    • First observedget_upcoming_deadlines
    • First observedsearch_notes
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.2/5.0

Scored across 3 tools

Disambiguation5/5

The three tools have clearly distinct purposes: grade calculation, deadline retrieval, and note search. An agent can easily tell which tool applies to a given student query.

Naming Consistency5/5

All tools follow a consistent snake_case verb_noun pattern: calculate_cgpa, get_upcoming_deadlines, search_notes. The convention is predictable and readable.

Tool Count4/5

Three tools is a lean but reasonable set for a narrow student assistant scope. It could slightly benefit from additional tools for common tasks, but no tool feels redundant.

Completeness2/5

The surface is read/calculate-only: no tools to add or update deadlines, save/edit notes, or record semester grades. Common student assistant workflows like creating reminders or managing notes would hit dead ends.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers