SABIS MCP Server

Acesse notas acadêmicas do sistema SABIS da Universidade de Sakarya por meio de raspagem automatizada da web.

Documentação

Servidor MCP SABIS 🎓

Um Servidor MCP (Model Context Protocol) para acessar notas acadêmicas do SABIS da Universidade de Sakarya (Sistema de Informação do Estudante). Este servidor permite que assistentes de IA e aplicativos recuperem informações acadêmicas de estudantes com segurança por meio de web scraping automatizado.

🌟 Recursos

🔐 Autenticação Segura: Usa variáveis de ambiente para credenciais
📊 Recuperação Abrangente de Notas: Busca informações acadêmicas detalhadas, incluindo:
- Códigos e nomes de disciplinas
- Tipos de avaliação (Prova Parcial, Quiz, Trabalhos, Projetos, Provas Finais)
- Percentuais e pesos das notas
- Notas finais em letras
- Informações de ano letivo e semestre
🤖 Integração MCP: Compatível com Claude, Cursor e outros assistentes de IA habilitados para MCP
🚀 Automação de Navegador Headless: Usa Puppeteer para web scraping confiável
⚡ Dados em Tempo Real: Busca dados ao vivo diretamente do sistema SABIS

🛠️ Pilha de Tecnologia

TypeScript - Desenvolvimento com segurança de tipos
Puppeteer - Web scraping e automação de navegador
Model Context Protocol SDK - Implementação do servidor MCP
Node.js - Ambiente de execução

📋 Requisitos

Node.js 18+
TypeScript 5.8+
Credenciais SABIS válidas (conta de estudante da Universidade de Sakarya)

🚀 Instalação

Clone o repositório:

git clone https://github.com/your-username/sabis-mcp-server.git
cd sabis-mcp-server

Instale as dependências:
```
npm install
```
Configure as variáveis de ambiente: Crie um arquivo .env no diretório raiz:
```
USERNAME=your_sabis_username
PASSWORD=your_sabis_password
```
Compile o projeto:
```
npm run build
```

⚙️ Configuração

Variáveis de Ambiente

Variável	Descrição	Obrigatória
`USERNAME`	Seu ID/nome de usuário SABIS	✅ Sim
`PASSWORD`	Sua senha da conta SABIS	✅ Sim

Configuração do Cliente MCP

Você tem duas opções para configurar as credenciais com seu cliente MCP:

Opção 1: Variáveis de Ambiente na Configuração MCP

Adicione o servidor à configuração do seu cliente MCP com as credenciais diretamente na configuração:

{
  "mcpServers": {
    "sabis-mcp-server": {
      "command": "node",
      "args": [
        "/path/to/sabis-mcp-server/build/index.js"
      ],
      "env": {
        "USERNAME": "your_student_number",
        "PASSWORD": "your_password"
      }
    }
  }
}

Opção 2: Usando o Arquivo .env

Alternativamente, crie um arquivo .env no diretório do projeto e remova a propriedade env da configuração MCP:

Crie o arquivo .env:

USERNAME=your_student_number
PASSWORD=your_password

Configuração MCP:

{
  "mcpServers": {
    "sabis-mcp-server": {
      "command": "node",
      "args": [
        "/path/to/sabis-mcp-server/build/index.js"
      ]
    }
  }
}

💡 Dica: A Opção 1 é mais conveniente para clientes MCP como o Cursor, enquanto a Opção 2 é melhor para manter as credenciais separadas dos arquivos de configuração.

🎯 Uso

Uma vez configurado, você pode usar o servidor MCP com assistentes de IA compatíveis:

Ferramentas Disponíveis

`get-grades`

Recupera notas acadêmicas do sistema SABIS.

Exemplo de Uso:

// Through MCP-enabled AI assistant
"Get my grades from SABIS"

Formato da Resposta:

Login successful! 🎓

Academic Year: 2024 - Semester: Bahar

=== SWE310 - MOBİL UYGULAMA GELİŞTİRME ===
Grup: 1. Öğretim A Grubu
• Ara Sınav (45%): 95
• Ödev (5%): 100
• Final (50%): 85
📋 Final Grade: AA

🔧 Desenvolvimento

Executando em Modo de Desenvolvimento

# Install dependencies
npm install

# Build the project
npm run build

# Test the server
node build/index.js

Estrutura do Projeto

sabis-mcp-server/
├── src/
│   └── index.ts          # Main MCP server implementation
├── build/                # Compiled JavaScript output
├── package.json         # Dependencies and scripts
├── tsconfig.json        # TypeScript configuration
└── README.md           # This file

Componentes Principais

Configuração do Servidor MCP: Configurado usando @modelcontextprotocol/sdk
Autenticação: Gerenciamento de credenciais baseado em ambiente
Web Scraping: Automação baseada em Puppeteer para o portal SABIS
Extração de Dados: Análise de DOM para informações de notas
Tratamento de Erros: Gerenciamento abrangente de erros e registro de logs

🛡️ Segurança e Privacidade

Credenciais: Armazenadas com segurança em variáveis de ambiente
Operação Headless: Sem exposição de informações sensíveis na interface
HTTPS: Toda comunicação com o SABIS usa conexões seguras
Sem Armazenamento de Dados: As notas são buscadas em tempo real, não armazenadas localmente
Gerenciamento de Sessão: As sessões do navegador são devidamente limpas

🚨 Solução de Problemas

Problemas Comuns

"Nome de usuário e senha são obrigatórios"

Certifique-se de que as variáveis de ambiente USERNAME e PASSWORD estão definidas
Verifique se o arquivo .env existe e contém as credenciais corretas

"Falha no login"

Verifique se as credenciais SABIS estão corretas
Verifique se o portal SABIS está acessível
Garanta o acesso à rede da universidade, se necessário

Erros de navegador/Puppeteer

Instale as dependências do Chromium no Linux:

sudo apt-get install -y libgbm-dev libnss3-dev libxss1 libasound2

📚 Referência da API

Ferramentas

`get-grades`

Autentica com o SABIS e recupera informações de notas acadêmicas.

Parâmetros: Nenhum (usa variáveis de ambiente)

Retorna:

Ano letivo e semestre
Informações das disciplinas com notas
Detalhamento das avaliações com percentuais
Notas finais quando disponíveis

🤝 Contribuindo

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

📄 Licença

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

⚠️ Aviso Legal

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

Cumprir os termos de serviço da universidade
Proteger suas credenciais de conta
Usar a ferramenta de forma responsável e ética

Os desenvolvedores não são responsáveis por qualquer uso indevido ou consequências decorrentes do uso deste software.

👨‍💻 Autor

Mehmet Hanifi Şentürk

🔗 Projetos Relacionados

Model Context Protocol - Documentação oficial do MCP
Puppeteer - Biblioteca de automação de navegador
Integração MCP com Claude - Usando MCP com Claude

Nota: Esta é uma ferramenta não oficial e não é afiliada à Universidade de Sakarya ou ao sistema SABIS oficial.