Amrita Vishwa Vidyapeetham (Chennai) Academic Calendar MCP Server & OpenAPI REST API

An OpenAPI 3.1 compatible Model Context Protocol (MCP) Server and REST API for the Amrita Vishwa Vidyapeetham, Chennai Campus Academic Calendar (AY 2026-27).

Designed specifically for LLMs (Claude, GPT, Gemini, Cursor, Cline, Antigravity) to query academic schedules, examination dates, class days (CD01..CD90), holidays, faculty feedback sessions, class committee meetings, and timetable swaps.

🎯 Key Features

1. Dual Compatibility:

   • MCP Protocol: Native support for tools, resources, and prompt templates over stdio and SSE transports via FastMCP.

   • OpenAPI 3.1 REST API: Complete FastAPI service providing Swagger UI (/docs), ReDoc (/redoc), OpenAPI JSON (/openapi.json), and OpenAPI YAML (/openapi.yaml).

2. Comprehensive Academic Dataset:

   • Covers all 374 days of Academic Year 2026-27 (June 1, 2026 – June 9, 2027).

   • Tracks separate cohorts:

     • Senior UG/PG: Semesters III, IV, V, VI, VII, VIII UG and Sem III, IV PG.

     • First Year UG/PG: Semesters I and II UG and PG.

   • Class Day progression from CD01 to CD90 for each semester.

   • Special Saturday timetable replacements (e.g., Saturday working with Monday Timetable).

   • Categorized academic milestones: Commencements, Midterms, Missed Midterms, Practical Exams, End Semester Theory Exams, Faculty Feedbacks, and Class Committee Meetings.

3. OpenAPI Schema Access for LLMs:

   • LLM agents can query get_openapi_specification dynamically or fetch /openapi.json directly to discover all endpoints and data schemas.

Related MCP server: webcal-mcp

📁 Repository Structure

.
├── AVV_Chennai_Academic_Calendar_AY2026-27.json  # Raw academic calendar source dataset
├── calendar_service.py                          # Data indexing, search & calculation engine
├── fastapi_app.py                               # FastAPI app implementing OpenAPI 3.1 REST endpoints
├── mcp_server.py                                # FastMCP server with tools, resources & prompts
├── server.py                                    # Unified CLI entry point (stdio / HTTP / export)
├── openapi.json                                 # Pre-generated OpenAPI 3.1 JSON specification
├── openapi.yaml                                 # Pre-generated OpenAPI 3.1 YAML specification
├── mcp_config.json                              # Example MCP client configuration
├── test_server.py                               # 21 pytest & integration tests
└── README.md                                    # Documentation

🚀 How to Run

1. Run as MCP Server (Stdio Mode)

Use this mode when connecting from Claude Desktop, Cursor, Cline, or any stdio-based MCP client:

python3 server.py --stdio

2. Run as Systemd Background Service (Port 8003 - Active)

The server is deployed as a persistent Linux systemd daemon for 24/7 background operation.

📋 Service Quick Reference Card

🌐 Service URLs (Port 8003)

• OpenAPI 3.1 JSON: http://localhost:8003/openapi.json

• OpenAPI 3.1 YAML: http://localhost:8003/openapi.yaml

• Interactive Swagger UI: http://localhost:8003/docs

• ReDoc Documentation: http://localhost:8003/redoc

• MCP SSE Transport: http://localhost:8003/sse

• Health Check: http://localhost:8003/health

🛠️ Service Management Commands

# Check service status and health
systemctl status academic-calendar.service

# Restart the service (e.g. after code changes or updates)
systemctl restart academic-calendar.service

# Stop the service
systemctl stop academic-calendar.service

# Start the service
systemctl start academic-calendar.service

# Enable autostart on system boot
systemctl enable academic-calendar.service

# Disable autostart on system boot
systemctl disable academic-calendar.service

# Reload systemd configuration after modifying the unit file
systemctl daemon-reload

# View real-time streaming logs
journalctl -u academic-calendar.service -f

# View the last 50 log entries without paging
journalctl -u academic-calendar.service -n 50 --no-pager

# Verify that the server is actively listening on port 8003
ss -tulpn | grep 8003

🧪 Quick curl Verification

# 1. Health check
curl -s http://localhost:8003/health

# 2. Get OpenAPI spec
curl -s http://localhost:8003/openapi.json

# 3. Query calendar entry for Gandhi Jayanthi (Holiday)
curl -s http://localhost:8003/api/v1/date/2026-10-02

# 4. Search for Midterm Exam dates
curl -s "http://localhost:8003/api/v1/search?q=Midterm"

# 5. Get all working Saturdays with swapped timetables
curl -s http://localhost:8003/api/v1/timetable-swaps

3. Run Manually via CLI (Development Mode)

# HTTP & SSE Mode on custom port
python3 server.py --http --port 8003 --host 0.0.0.0

# Stdio MCP Mode (for interactive terminal / stdin pipe)
python3 server.py --stdio

4. Re-export OpenAPI Specifications

Generate fresh openapi.json and openapi.yaml files:

python3 server.py --export-openapi

🔌 Connecting to LLM Clients

Claude Desktop Configuration

Add the following to your claude_desktop_config.json (located at ~/.config/Claude/claude_desktop_config.json on Linux or %APPDATA%/Claude/claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "avv-chennai-academic-calendar": {
      "command": "python3",
      "args": [
        "/home/hirthikbalaji/SocialMedia/ACADEMIC_CALENDER/server.py",
        "--stdio"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Cursor Configuration (.cursor/mcp.json)

{
  "mcpServers": {
    "academic-calendar": {
      "command": "python3 /home/hirthikbalaji/SocialMedia/ACADEMIC_CALENDER/server.py --stdio"
    }
  }
}

🛠️ MCP Tools Reference

📦 MCP Resources & Prompts

Resources

• calendar://metadata - Calendar document information, approval, and legend definitions.

• calendar://holidays - Complete list of 23 official named festival and public holidays.

• calendar://milestones - All 48 key academic milestones (exams, feedbacks, commencements).

• calendar://timetable-swaps - All 19 working Saturdays and special day orders.

• calendar://full - The complete raw JSON calendar document.

• openapi://schema.json - Complete OpenAPI 3.1 specification for the REST API.

Prompts

• academic_advising(cohort, current_date): Template guiding an LLM in advising a student on upcoming exams, feedback, and deadlines.

• holiday_and_leave_inquiry(month): Template guiding an LLM in summarizing monthly holidays and long weekends.

• attendance_and_class_day_counter(cohort, from_date, to_date): Template for calculating student attendance and remaining instructional days against the 90 class days requirement.

🌐 OpenAPI REST Endpoints

All endpoints are documented interactively at /docs (Swagger UI):

• GET /api/v1/metadata - Get official calendar metadata

• GET /api/v1/date/{target_date} - Detailed query for single date

• GET /api/v1/calendar - Range and filter query

• GET /api/v1/search - Keyword search

• GET /api/v1/holidays - List holidays (with named_only filter)

• GET /api/v1/timetable-swaps - List timetable replacement days

• GET /api/v1/milestones - List academic milestones

• GET /api/v1/upcoming - List upcoming events

• GET /api/v1/stats/class-days - Count instructional class days (CDs) and working days

• GET /api/v1/export/full - Full raw JSON data

• GET /openapi.yaml - OpenAPI YAML specification

• GET /health - Service healthcheck

🧪 Testing

Run the automated test suite with pytest:

python3 -m pytest -p no:anyio test_server.py -v

All 21 test cases cover metadata validation, single-date lookups, holidays filtering, class day counters, timetable swaps, milestone categorization, FastAPI routes, and FastMCP tool executions.