🎓 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

🛠️ 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

🏗️ 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

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

🤝 Contributing

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

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. 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

🚀 Quick Start

📋 Prerequisites

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

📦 Installation

1. Clone the repository:

   Copy

   git clone <your-repo-url>
   cd LMS-MCP

2. Install dependencies:

   Copy

   # Using uv (recommended)
   uv sync
   
   # Or using pip
   pip install -e .

3. Configure environment:

   Copy

   # 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)

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

🔧 Setup with AI Assistants

🤖 Claude Desktop Setup

1. Locate Claude configuration file:

   Copy

   # Windows
   %APPDATA%\Claude\claude_desktop_config.json
   
   # macOS
   ~/Library/Application Support/Claude/claude_desktop_config.json
   
   # Linux
   ~/.config/Claude/claude_desktop_config.json

2. Add MCP server configuration:

   Copy

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

3. Restart Claude Desktop

4. Test the connection:

   Copy

   Can you check my LMS attendance?

💻 Cursor IDE Setup

1. Open Cursor IDE

2. Go to Settings (Ctrl/Cmd + ,)

3. Navigate to Extensions → MCP

4. Add new MCP server:

   Copy

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

5. Restart Cursor

6. Test in chat:

   Copy

   @lms-automation login to LMS and check my marks

🆚 VS Code with GitHub Copilot Setup

1. Install MCP Extension:

   • Open VS Code
   • Go to Extensions (Ctrl+Shift+X)
   • Search for "MCP Client" and install

2. Configure MCP server:

   Create .vscode/settings.json in your project:

   Copy

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

3. Use with Copilot Chat:

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

💡 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