LMS MCP Server

# 🎓 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.** [](https://python.org) [](https://modelcontextprotocol.io) [](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>