SABIS MCP Server

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