🎓 LMS MCP Server - PAF-IAST University Automation

A powerful Model Context Protocol (MCP) server that automates PAF-IAST LMS interactions with AI assistants like Claude, Cursor, and VS Code Copilot.

🌟 Features

🔐 Smart Authentication

Automated login with advanced CAPTCHA solving
Google Gemini Vision API integration for enhanced accuracy
Secure session management with encryption
Automatic session persistence and restoration

📊 Academic Data Access

Attendance Tracking - Real-time attendance records by subject
Marks & Grades - Comprehensive exam scores and assessments
Timetable Management - Class schedules and academic calendar
Application System - Submit and track university applications

🤖 AI-Powered Automation

Headless browser operation for efficiency
Intelligent form handling and DOM navigation
Robust error handling and retry mechanisms
Multi-method CAPTCHA solving (Vision AI + OCR)

🛡️ Security & Privacy

Environment-based configuration
Encrypted session storage
No hardcoded credentials
Secure API key management

🚀 Quick Start

📋 Prerequisites

Python 3.11+
Git
Chrome Browser (for automation)
Google Gemini API Key (optional, for enhanced CAPTCHA solving)

📦 Installation

Clone the repository:
```
git clone <your-repo-url>
cd LMS-MCP
```

Install dependencies:

# Using uv (recommended)
uv sync

# Or using pip
pip install -e .

Configure environment:

# Copy the example environment file
cp .env.example .env

# Edit with your credentials (see Configuration section)
notepad .env  # Windows
nano .env     # Linux/Mac

⚙️ Configuration

📝 Environment Setup

Edit your .env file with the following settings:

# Required: Your PAF-IAST credentials
LMS_USERNAME=your_student_id_here
LMS_PASSWORD=your_password_here

# Optional: Enhanced CAPTCHA solving
GEMINI_API_KEY=your_gemini_api_key_here

# Browser settings
BROWSER_HEADLESS=true  # Set to false for debugging

# Session settings
SESSION_EXPIRY_HOURS=24
ENCRYPT_SESSIONS=true

🔑 Getting Google Gemini API Key (Optional but Recommended)

Visit Google AI Studio
Sign in with your Google account
Click "Create API Key"
Copy the API key to your .env file

🔧 Setup with AI Assistants

🤖 Claude Desktop Setup

Locate Claude configuration file:

# Windows
%APPDATA%\Claude\claude_desktop_config.json

# macOS
~/Library/Application Support/Claude/claude_desktop_config.json

# Linux
~/.config/Claude/claude_desktop_config.json

Add MCP server configuration:

{
  "mcpServers": {
    "lms-automation": {
      "command": "python",
      "args": ["C:/path/to/your/LMS-MCP/main.py"],
      "env": {
        "PYTHONPATH": "C:/path/to/your/LMS-MCP"
      }
    }
  }
}

Restart Claude Desktop
Test the connection:
```
Can you check my LMS attendance?
```

💻 Cursor IDE Setup

Open Cursor IDE
Go to Settings (Ctrl/Cmd + ,)
Navigate to Extensions → MCP

Add new MCP server:

{
  "name": "LMS Automation",
  "command": "python",
  "args": ["./main.py"],
  "cwd": "/path/to/LMS-MCP",
  "env": {
    "PYTHONPATH": "/path/to/LMS-MCP"
  }
}

Restart Cursor

Test in chat:

@lms-automation login to LMS and check my marks

🆚 VS Code with GitHub Copilot Setup

Install MCP Extension:
- Open VS Code
- Go to Extensions (Ctrl+Shift+X)
- Search for "MCP Client" and install

Configure MCP server:

Create .vscode/settings.json in your project:

{
  "mcp.servers": [
    {
      "name": "lms-automation",
      "command": "python",
      "args": ["main.py"],
      "cwd": "${workspaceFolder}",
      "env": {
        "PYTHONPATH": "${workspaceFolder}"
      }
    }
  ]
}

Use with Copilot Chat:
- Open Copilot Chat (Ctrl+Shift+I)
- Type: @mcp:lms-automation login and get my attendance

🛠️ Available MCP Tools

🔐 Authentication

login_to_lms - Login with credentials and CAPTCHA solving
logout_lms - Logout and clear session

📊 Academic Data

check_attendance - Get attendance records by subject
get_marks - Retrieve marks and grades
get_timetable - Access class schedule

📝 Applications

create_application - Submit university applications
view_application_status - Check application status

🔧 Utilities

solve_captcha - Manual CAPTCHA solving

💡 Usage Examples

Basic Login and Data Retrieval

# Login to LMS
Login to PAF-IAST LMS with my credentials

# Check attendance
What's my current attendance status?

# Get marks
Show me my latest marks and grades

# View timetable
What's my class schedule for today?

Advanced Queries

# Comprehensive report
Generate a summary report of my academic performance including attendance, marks, and upcoming classes

# Specific subject
What's my attendance percentage for Computer Science subjects?

# Application tracking
Check the status of my scholarship application

🔍 Troubleshooting

Common Issues

❌ Login Failed

Verify credentials in .env file
Check if CAPTCHA solving is working
Ensure university LMS is accessible

❌ CAPTCHA Not Solving

Add Gemini API key for better accuracy
Check internet connection
Verify image preprocessing

❌ Session Expired

Sessions expire after 24 hours by default
Re-login will create a new session
Check SESSION_EXPIRY_HOURS setting

❌ Browser Issues

Ensure Chrome is installed and updated
Check BROWSER_HEADLESS setting
Install required browser drivers

Debug Mode

Enable debug mode for troubleshooting:

# In .env file
DEBUG_MODE=true
SAVE_SCREENSHOTS=true
BROWSER_HEADLESS=false

🏗️ Architecture

🧱 Core Components

LMS-MCP/
├── main.py              # MCP server entry point
├── lms_automation.py    # Core automation logic
├── captcha_solver.py    # CAPTCHA solving algorithms
├── session_manager.py   # Session persistence
├── config.py           # Configuration management
├── models/             # Data models
│   ├── attendance.py
│   ├── marks.py
│   └── timetable.py
└── utils/              # Utility functions
    ├── encryption.py
    ├── image_processor.py
    └── web_scraper.py

🔄 Workflow

Initialization - Load configuration and setup browser
Authentication - Login with CAPTCHA solving
Session Management - Save/restore login sessions
Data Extraction - Navigate and scrape academic data
Response Formatting - Structure data for AI consumption

🤝 Contributing

We welcome contributions! Here's how to get started:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Setup

# Clone your fork
git clone https://github.com/yourusername/LMS-MCP.git
cd LMS-MCP

# Install development dependencies
uv sync --dev

# Run tests
python -m pytest

# Run linting
black . && flake8 .

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

⚠️ Disclaimer

This tool is for educational purposes and personal use only. Users are responsible for:

Complying with university policies
Securing their own credentials
Using the tool responsibly
Not overloading university servers

📞 Support

Documentation: Wiki
Issues: GitHub Issues
Discussions: GitHub Discussions

Made with ❤️ for PAF-IAST students

⭐ Star this repo | 🐛 Report Bug | 💡 Request Feature

PAF-IAST LMS Automation