# SABIS MCP Server 🎓

A **Model Context Protocol (MCP) Server** for accessing academic grades from the **Sakarya University SABIS** (Student Information System). This server enables AI assistants and applications to securely retrieve student academic information through automated web scraping.

## 🌟 Features

- **🔐 Secure Authentication**: Uses environment variables for credentials
- **📊 Comprehensive Grade Retrieval**: Fetches detailed academic information including:
  - Course codes and names
  - Assessment types (Midterm, Quiz, Assignments, Projects, Finals)  
  - Grade percentages and weights
  - Final letter grades
  - Academic year and semester information
- **🤖 MCP Integration**: Compatible with Claude, Cursor, and other MCP-enabled AI assistants
- **🚀 Headless Browser Automation**: Uses Puppeteer for reliable web scraping
- **⚡ Real-time Data**: Fetches live data directly from SABIS system

## 🛠️ Technology Stack

- **TypeScript** - Type-safe development
- **Puppeteer** - Web scraping and browser automation
- **Model Context Protocol SDK** - MCP server implementation
- **Node.js** - Runtime environment

## 📋 Requirements

- Node.js 18+ 
- TypeScript 5.8+
- Valid SABIS credentials (Sakarya University student account)

## 🚀 Installation

1. **Clone the repository:**
   ```bash
   git clone https://github.com/your-username/sabis-mcp-server.git
   cd sabis-mcp-server
   ```

2. **Install dependencies:**
   ```bash
   npm install
   ```

3. **Set up environment variables:**
   Create a `.env` file in the root directory:
   ```env
   USERNAME=your_sabis_username
   PASSWORD=your_sabis_password
   ```

4. **Build the project:**
   ```bash
   npm run build
   ```

## ⚙️ Configuration

### Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `USERNAME` | Your SABIS student ID/username | ✅ Yes |
| `PASSWORD` | Your SABIS account password | ✅ Yes |

### MCP Client Setup

You have two options for configuring credentials with your MCP client:

#### Option 1: Environment Variables in MCP Configuration

Add the server to your MCP client configuration with credentials directly in the config:

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

#### Option 2: Using .env File

Alternatively, create a `.env` file in the project directory and remove the `env` property from the MCP configuration:

**Create `.env` file:**
```env
USERNAME=your_student_number
PASSWORD=your_password
```

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

> **💡 Tip**: Option 1 is more convenient for MCP clients like Cursor, while Option 2 is better for keeping credentials separate from configuration files.

## 🎯 Usage

Once configured, you can use the MCP server with compatible AI assistants:

### Available Tools

#### `get-grades`
Retrieves academic grades from SABIS system.

**Example Usage:**
```typescript
// Through MCP-enabled AI assistant
"Get my grades from SABIS"
```

**Response Format:**
```
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
```

## 🔧 Development

### Running in Development Mode

```bash
# Install dependencies
npm install

# Build the project
npm run build

# Test the server
node build/index.js
```

### Project Structure

```
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
```

### Key Components

- **MCP Server Setup**: Configured using `@modelcontextprotocol/sdk`
- **Authentication**: Environment-based credential management
- **Web Scraping**: Puppeteer-based automation for SABIS portal
- **Data Extraction**: DOM parsing for grade information
- **Error Handling**: Comprehensive error management and logging

## 🛡️ Security & Privacy

- **Credentials**: Stored securely in environment variables
- **Headless Operation**: No UI exposure of sensitive information  
- **HTTPS**: All communication with SABIS uses secure connections
- **No Data Storage**: Grades are fetched in real-time, not stored locally
- **Session Management**: Browser sessions are properly cleaned up

## 🚨 Troubleshooting

### Common Issues

**"Username and password are required"**
- Ensure environment variables `USERNAME` and `PASSWORD` are set
- Check `.env` file exists and contains correct credentials

**"Login failed"**
- Verify SABIS credentials are correct
- Check if SABIS portal is accessible
- Ensure university network access if required

**Browser/Puppeteer errors**
- Install Chromium dependencies on Linux:
  ```bash
  sudo apt-get install -y libgbm-dev libnss3-dev libxss1 libasound2
  ```

## 📚 API Reference

### Tools

#### `get-grades`
Authenticates with SABIS and retrieves academic grade information.

**Parameters:** None (uses environment variables)

**Returns:**
- Academic year and semester
- Course information with grades
- Assessment breakdown with percentages
- Final grades where available

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the ISC 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 terms of service
- Protecting their account credentials
- Using the tool responsibly and ethically

The developers are not responsible for any misuse or consequences arising from the use of this software.

## 👨‍💻 Author

**Mehmet Hanifi Şentürk**

## 🔗 Related Projects

- [Model Context Protocol](https://github.com/modelcontextprotocol) - Official MCP documentation
- [Puppeteer](https://github.com/puppeteer/puppeteer) - Browser automation library
- [Claude MCP Integration](https://claude.ai/docs/mcp) - Using MCP with Claude

---

**Note**: This is an unofficial tool and is not affiliated with Sakarya University or the official SABIS system.