# iitkgp-erp-mcp

MCP server for IIT Kharagpur ERP. Query your grades, CGPA, attendance, timetable, placements, and more through any AI agent.

Works with: **Claude Code, Claude Desktop, Cursor, Cline, Continue, Zed, custom agents** — anything that speaks MCP.

## Install

```bash
pip install iitkgp-erp-mcp
playwright install chromium
```

## Setup

```bash
iitkgp-erp-setup
```

This stores your credentials securely in your OS keychain.

## Usage

Add to your MCP client config (`.mcp.json`, `mcp_servers.json`, etc.):

```json
{
  "mcpServers": {
    "iitkgp-erp": {
      "command": "iitkgp-erp-mcp"
    }
  }
}
```

Then ask your AI agent:
- "What's my CGPA?"
- "Show my grades for semester 4"
- "Compare my performance in CS vs MA subjects"
- "If I get A in all subjects this sem, what's my CGPA?"
- "Which breadth electives should I take?"
- "Any new placement notices for SDE roles?"
- "Can I skip tomorrow's Signals class?"
- "What's my schedule today?"
- "Export my timetable to Google Calendar"
- "Browse the fee payment page"

## Available Tools (25)

### Grades & GPA
| Tool | Description |
|------|-------------|
| `erp_login` | Login to ERP (handles OTP) |
| `erp_logout` | End session |
| `get_grades` | Fetch grades (all or specific semester) |
| `get_cgpa` | Current CGPA |
| `get_sgpa` | SGPA for a semester |
| `get_cgpa_trend` | Semester-wise CGPA/SGPA progression |
| `compare_subjects` | Compare across subjects |
| `what_if_cgpa` | Projected CGPA calculator |
| `get_grade_distribution` | Grade breakdown (EX/A/B/C/D/P/F counts) |

### Attendance
| Tool | Description |
|------|-------------|
| `get_attendance` | All subjects with attendance % |
| `get_attendance_alerts` | Subjects below 80% danger zone |
| `can_i_skip` | How many classes you can safely miss |

### Elective Recommender
| Tool | Description |
|------|-------------|
| `recommend_electives` | Suggests electives based on your grade patterns |
| `get_strengths_weaknesses` | Your top 5 best/worst subjects |
| `get_department_performance` | Average GPA by department |

### Timetable & Schedule
| Tool | Description |
|------|-------------|
| `get_timetable` | Full week or specific day schedule |
| `get_today_classes` | Today's classes |
| `where_is_prof` | Find a professor's location via timetable |
| `export_timetable_ics` | Export to ICS format (Google Calendar, Apple Calendar) |

### Placements & Notices
| Tool | Description |
|------|-------------|
| `get_placement_notices` | CDC notices, filterable by keyword |
| `get_notice_detail` | Full text of a specific notice |
| `get_academic_notices` | Academic announcements |

### Explorer
| Tool | Description |
|------|-------------|
| `browse_erp_page` | Navigate any ERP page freely |
| `search_erp_pages` | Find ERP pages by keyword |

### Utility
| Tool | Description |
|------|-------------|
| `clear_cache` | Clear locally cached data |

## Security

- Credentials stored in OS keychain (never plaintext)
- Session is local to your machine
- OTP entered live, never stored
- Nothing sensitive is committed to git

## How it works

```
Your AI Agent ←→ MCP Protocol (stdio) ←→ iitkgp-erp-mcp server
                                              │
                                              ├── iitkgp-erp-login (auth)
                                              ├── requests + BeautifulSoup (scraping)
                                              └── Playwright (JS-heavy pages)
                                              │
                                              ▼
                                        erp.iitkgp.ac.in
```

## Grading Scale

| Grade | Points |
|-------|--------|
| EX | 10 |
| A | 9 |
| B | 8 |
| C | 7 |
| D | 6 |
| P | 5 |
| F | 0 |

## Roadmap

- [x] Grades & GPA tools
- [x] Attendance tracking + alerts
- [x] Elective recommender
- [x] Placement notice integration
- [x] Timetable extraction
- [x] Calendar sync (ICS export)
- [x] Prof finder
- [x] Academic notices
- [x] Freeform ERP browser
- [ ] Batch grade distributions (historical data)
- [ ] Registration status
- [ ] Fee payment status
- [ ] Hostel info

## Contributing

PRs welcome! The scrapers in `src/scrapers/` may need selector updates if ERP changes its HTML structure.

## License

MIT