PAF-IAST LMS Automation

Automatiza interações com o Sistema de Gestão de Aprendizagem (LMS) PAF-IAST para assistentes de IA como Claude e VS Code Copilot.

GitHub

Documentação

🎓 Servidor MCP LMS - Automação da Universidade PAF-IAST

Um poderoso servidor Model Context Protocol (MCP) que automatiza interações com o LMS PAF-IAST usando assistentes de IA como Claude, Cursor e VS Code Copilot.

🌟 Recursos

🔐 Autenticação Inteligente

Login automatizado com resolução avançada de CAPTCHA
Integração com Google Gemini Vision API para maior precisão
Gerenciamento seguro de sessão com criptografia
Persistência e restauração automática de sessão

📊 Acesso a Dados Acadêmicos

Controle de Frequência - Registros de frequência em tempo real por disciplina
Notas e Menções - Pontuações abrangentes de exames e avaliações
Gerenciamento de Horários - Horários de aulas e calendário acadêmico
Sistema de Inscrições - Envie e acompanhe inscrições universitárias

🤖 Automação com IA

Operação em navegador headless para eficiência
Manipulação inteligente de formulários e navegação DOM
Tratamento robusto de erros e mecanismos de repetição
Resolução de CAPTCHA por múltiplos métodos (Vision AI + OCR)

🛡️ Segurança e Privacidade

Configuração baseada em variáveis de ambiente
Armazenamento de sessão criptografado
Sem credenciais codificadas
Gerenciamento seguro de chaves de API

🚀 Início Rápido

📋 Pré-requisitos

Python 3.11+
Git
Navegador Chrome (para automação)
Chave da API Google Gemini (opcional, para resolução aprimorada de CAPTCHA)

📦 Instalação

Clone o repositório:
```
git clone <your-repo-url>
cd LMS-MCP
```

Instale as dependências:

# Using uv (recommended)
uv sync

# Or using pip
pip install -e .

Configure o ambiente:

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

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

⚙️ Configuração

📝 Configuração do Ambiente

Edite seu arquivo .env com as seguintes configurações:

# 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

🔑 Obtendo a Chave da API Google Gemini (Opcional, mas Recomendado)

Visite Google AI Studio
Entre com sua conta Google
Clique em "Create API Key"
Copie a chave da API para seu arquivo .env

🔧 Configuração com Assistentes de IA

🤖 Configuração do Claude Desktop

Localize o arquivo de configuração do Claude:

# Windows
%APPDATA%\Claude\claude_desktop_config.json

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

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

Adicione a configuração do servidor MCP:

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

Reinicie o Claude Desktop
Teste a conexão:
```
Can you check my LMS attendance?
```

💻 Configuração do Cursor IDE

Abra o Cursor IDE
Vá para Configurações (Ctrl/Cmd + ,)
Navegue até Extensões → MCP

Adicione um novo servidor MCP:

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

Reinicie o Cursor

Teste no chat:

@lms-automation login to LMS and check my marks

🆚 Configuração do VS Code com GitHub Copilot

Instale a Extensão MCP:
- Abra o VS Code
- Vá para Extensões (Ctrl+Shift+X)
- Pesquise por "MCP Client" e instale

Configure o servidor MCP:

Crie .vscode/settings.json no seu projeto:

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

Use com o Copilot Chat:
- Abra o Copilot Chat (Ctrl+Shift+I)
- Digite: @mcp:lms-automation login and get my attendance

🛠️ Ferramentas MCP Disponíveis

🔐 Autenticação

login_to_lms - Login com credenciais e resolução de CAPTCHA
logout_lms - Logout e limpeza de sessão

📊 Dados Acadêmicos

check_attendance - Obter registros de frequência por disciplina
get_marks - Recuperar notas e menções
get_timetable - Acessar horário de aulas

📝 Inscrições

create_application - Enviar inscrições universitárias
view_application_status - Verificar status da inscrição

🔧 Utilitários

solve_captcha - Resolução manual de CAPTCHA

💡 Exemplos de Uso

Login Básico e Recuperação de Dados

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

Consultas Avançadas

# 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

🔍 Solução de Problemas

Problemas Comuns

❌ Falha no Login

Verifique as credenciais no arquivo .env
Verifique se a resolução de CAPTCHA está funcionando
Garanta que o LMS da universidade esteja acessível

❌ CAPTCHA Não Resolvendo

Adicione a chave da API Gemini para maior precisão
Verifique a conexão com a internet
Verifique o pré-processamento de imagens

❌ Sessão Expirada

Sessões expiram após 24 horas por padrão
Um novo login criará uma nova sessão
Verifique a configuração de SESSION_EXPIRY_HOURS

❌ Problemas com o Navegador

Garanta que o Chrome esteja instalado e atualizado
Verifique a configuração de BROWSER_HEADLESS
Instale os drivers de navegador necessários

Modo de Depuração

Ative o modo de depuração para solução de problemas:

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

🏗️ Arquitetura

🧱 Componentes Principais

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

🔄 Fluxo de Trabalho

Inicialização - Carregar configuração e configurar navegador
Autenticação - Login com resolução de CAPTCHA
Gerenciamento de Sessão - Salvar/restaurar sessões de login
Extração de Dados - Navegar e coletar dados acadêmicos
Formatação de Respostas - Estruturar dados para consumo pela IA

🤝 Contribuindo

Aceitamos contribuições! Veja como começar:

Faça um fork do repositório
Crie um branch de funcionalidade (git checkout -b feature/amazing-feature)
Faça commit das alterações (git commit -m 'Add amazing feature')
Envie para o branch (git push origin feature/amazing-feature)
Abra um Pull Request

Configuração de Desenvolvimento

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

📄 Licença

Este projeto está licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.

⚠️ Aviso Legal

Esta ferramenta é apenas para fins educacionais e uso pessoal. Os usuários são responsáveis por:

Cumprir as políticas da universidade
Proteger suas próprias credenciais
Usar a ferramenta de forma responsável
Não sobrecarregar os servidores da universidade

📞 Suporte

Documentação: Wiki
Problemas: GitHub Issues
Discussões: GitHub Discussions

Feito com ❤️ para os estudantes da PAF-IAST

⭐ Marque este repositório | 🐛 Reporte um Bug | 💡 Solicite um Recurso