# 🎓 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.**

[![Python](https://img.shields.io/badge/Python-3.11+-blue.svg)](https://python.org)
[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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

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

2. **Install dependencies:**
   ```bash
   # Using uv (recommended)
   uv sync
   
   # Or using pip
   pip install -e .
   ```

3. **Configure environment:**
   ```bash
   # 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:

```bash
# 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](https://makersuite.google.com/app/apikey)
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:**
   ```bash
   # 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:**
   ```json
   {
     "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:**
   ```
   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:**
   ```json
   {
     "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:**
   ```
   @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:
   ```json
   {
     "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`

---

## 🛠️ 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:
```bash
# 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

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

```bash
# 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](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](../../wiki)
- **Issues:** [GitHub Issues](../../issues)
- **Discussions:** [GitHub Discussions](../../discussions)

---

<div align="center">

**Made with ❤️ for PAF-IAST students**

[⭐ Star this repo](../../stargazers) | [🐛 Report Bug](../../issues) | [💡 Request Feature](../../issues)

</div>