# SGU Academic MCP Server

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![Model Context Protocol](https://img.shields.io/badge/MCP-Protocol-purple.svg)](https://modelcontextprotocol.io/)
[![Tests](https://img.shields.io/badge/tests-48%20passed-brightgreen.svg)](tests/)
[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](tests/)
[![Docker](https://img.shields.io/badge/docker-ready-blue.svg)](Dockerfile)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

> A production-grade **Model Context Protocol (MCP)** Server bridging AI Assistants (Claude Desktop, Antigravity, Cursor) directly with the **Saigon University (SGU) Academic Portal** (`thongtindaotao.sgu.edu.vn`).

---

## Giới thiệu

**SGU Academic MCP Server** được xây dựng theo chuẩn mở [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) của Anthropic. Hệ thống đóng vai trò cầu nối thông minh (Bridge Middleware), giúp các Trợ lý AI có thể tương tác trực tiếp với dữ liệu học tập thực tế từ cổng thông tin đào tạo Đại học Sài Gòn (SGU) bằng ngôn ngữ tự nhiên.

### Tính năng nổi bật

* **100% Dữ liệu thực tế:** Tích hợp trực tiếp với API cổng đào tạo SGU (`thongtindaotao.sgu.edu.vn`), không dùng dữ liệu giả lập.
* **Cơ chế Reverse-Engineered Security:** Tự động tạo dynamic header `ua` với thuật toán mã hóa timestamp + XOR bitwise, tương thích hoàn toàn với cơ chế bảo mật của cổng đào tạo.
* **Smart SQLite Caching:** Tự động cache kết quả học tập và thời khóa biểu cục bộ, đảm bảo tốc độ phản hồi < 0.05s và giảm thiểu áp lực request lên máy chủ trường.
* **Hỗ trợ đa phương thức truyền tải (Transports):**
  * `stdio`: Tích hợp chuẩn cho Claude Desktop, Cursor, Antigravity.
  * `SSE` (Server-Sent Events): Dùng khi triển khai dạng dịch vụ mạng LAN hoặc Web container.
* **Bộ tính năng phong phú:** 15 Tools, 4 Resources ngữ cảnh, và 3 Prompts mẫu thông minh.

---

## Kiến trúc hệ thống

```
┌────────────────────────────────────────────────────────┐
│                   Trợ lý AI (Clients)                  │
│       Claude Desktop  │  Cursor IDE  │   Antigravity   │
└───────────────────────────┬────────────────────────────┘
                            │ JSON-RPC (stdio / SSE)
                            ▼
┌───────────────────────────────────────────────────────────┐
│                   SGU ACADEMIC MCP SERVER                 │
│                                                           │
│  [15 MCP Tools]      [4 Resources]       [3 Prompts]      │
│  • TKB tuần / ngày   • Lộ trình CNTT     • Kế hoạch học   │
│  • Lịch thi & Đếm    • Chuẩn tốt nghiệp  • Ôn thi cấp tốc │
│  • Điểm & GPA audit  • Quy chế học vụ    • Audit hồ sơ    │
│  • Học phí & Nợ môn  • Danh bạ cơ sở                      │
│                                                           │
│  [Security & Performance Engine]                          │
│  • SguEncryptor: Thuật toán tạo header dynamic 'ua'       │
│  • SguCache: SQLite Caching & Fallback Controller         │
└───────────────────────────┬───────────────────────────────┘
                            │ HTTPS (REST API)
                            ▼
┌────────────────────────────────────────────────────────┐
│              Cổng thông tin đào tạo SGU                │
│              thongtindaotao.sgu.edu.vn                 │
└────────────────────────────────────────────────────────┘
```

---

## Danh mục năng lực MCP

### 1. 15 MCP Tools (Hành động có thể gọi)

| STT | Tool Name | Mô tả |
| :---: | :--- | :--- |
| 1 | `sgu_login` | Đăng nhập tài khoản sinh viên vào cổng thông tin đào tạo SGU |
| 2 | `get_registered_courses` | Lấy danh sách các môn đã đăng ký thành công trong kỳ |
| 3 | `get_weekly_schedule` | Lấy thời khóa biểu học kỳ chi tiết theo từng thứ trong tuần |
| 4 | `get_today_schedule` | Tra cứu nhanh lịch học hôm nay và ngày mai (phòng, ca, giảng viên) |
| 5 | `check_schedule_conflict` | Kiểm tra xung đột lịch học khi dự định đăng ký môn mới |
| 6 | `get_exam_schedule` | Tra cứu lịch thi chính thức từ SGU (ngày thi, phòng, ca, SBD) |
| 7 | `get_exam_countdown` | Đếm ngược ngày thi và cảnh báo lịch thi dồn dập trong cùng 1 ngày |
| 8 | `get_student_profile` | Lấy hồ sơ sinh viên chính thức (họ tên, MSSV, lớp, ngành, CVHT) |
| 9 | `get_semester_grades` | Lấy bảng điểm chi tiết theo từng học kỳ |
| 10 | `calculate_gpa_summary` | Tổng hợp GPA tích lũy, số tín chỉ đạt và danh sách môn nợ |
| 11 | `simulate_target_gpa` | Thuật toán mô phỏng điểm số cần đạt ở các môn tới để đạt mục tiêu GPA |
| 12 | `get_tuition_fees` | Tra cứu học phí từng kỳ, số tiền đã đóng và số tiền nợ đọng |
| 13 | `get_sgu_notifications` | Lấy thông báo mới nhất từ Nhà trường và Phòng Đào tạo |
| 14 | `get_course_offerings` | Tra cứu danh sách lớp học phần đang mở kèm số lượng chỗ còn lại |
| 15 | `check_prerequisites` | Kiểm tra điều kiện môn tiên quyết ngành CNTT SGU |

### 2. 4 MCP Resources (Tài nguyên đọc ngữ cảnh)

* `sgu://curriculum/it-roadmap`: Toàn bộ lộ trình 8 học kỳ và khung chương trình ngành CNTT SGU.
* `sgu://regulations/academic-warning`: Quy chế tính điểm hệ 4 và các khung cảnh cáo học vụ.
* `sgu://graduation/standards`: Điều kiện xét tốt nghiệp (tín chỉ, chuẩn ngoại ngữ TOEIC 500/VSTEP, tin học).
* `sgu://campuses/directory`: Danh bạ cơ sở và ký hiệu các phòng học tại trường Đại học Sài Gòn.

### 3. 3 MCP Prompts (Mẫu tác vụ AI định sẵn)

* `plan_weekly_routine`: Tự động phân bổ lịch tự học và sinh hoạt dựa trên thời khóa biểu tuần thực tế.
* `exam_cramming_strategy`: Lập chiến lược ôn thi nước rút tối ưu theo mức độ khẩn cấp của lịch thi.
* `graduation_audit`: Đối soát toàn diện điểm số và tín chỉ tích lũy so với chuẩn đầu ra tốt nghiệp.

---

## Cài đặt & Sử dụng (1-Click Setup)

### 1. Yêu cầu môi trường
* Python 3.10 trở lên

### 2. Các bước thiết lập

**Bước 1: Tải mã nguồn & cài đặt thư viện**
```bash
git clone https://github.com/your-username/sgu-academic-mcp.git
cd sgu-academic-mcp
pip install -r requirements.txt
```

**Bước 2: Cấu hình tài khoản sinh viên**
Tạo file `.env` từ `.env.example` và điền tài khoản SGU của bạn:
```env
SGU_STUDENT_ID=3122xxxxxx
SGU_PASSWORD=MatKhauCuaBan
```

**Bước 3: Tích hợp tự động vào AI Clients (1-Click)**
Chạy script cài đặt tự động:
```bash
python setup.py
```
*(Trên Windows, bạn chỉ cần nhấp đúp chuột vào file `setup.bat`)*

> **Script `setup.py` sẽ tự động:**
> - Tự nhận diện đường dẫn tuyệt đối của Python và dự án trên máy bạn.
> - Tự chèn cấu hình vào **Claude Desktop** (`%APPDATA%\Claude\claude_desktop_config.json`).
> - Tự tạo cấu hình Workspace cho **Cursor / Antigravity** (`.cursor/mcp.json`).
> 
> Sau khi chạy xong, bạn chỉ cần mở Claude Desktop hoặc Cursor lên là 15 công cụ tra cứu SGU đã sẵn sàng trong khung chat!

---

<details>
<summary><b>Cấu hình thủ công & Triển khai nâng cao (Docker, SSE, Manual JSON)</b></summary>

### Chạy trực tiếp MCP Server qua dòng lệnh
* Chế độ **stdio**:
  ```bash
  python -m sgu_mcp.server --transport stdio
  ```
* Chế độ **SSE** (HTTP Web Service):
  ```bash
  python -m sgu_mcp.server --transport sse --port 8000
  ```

### Triển khai với Docker
```bash
docker compose up -d --build
```
Dịch vụ MCP Server sẽ chạy ở cổng `8000` (`http://localhost:8000/sse`).

### Cấu hình thủ công file JSON (nếu không dùng `setup.py`)

Thêm đoạn JSON sau vào `claude_desktop_config.json` hoặc `.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "sgu_academic_server": {
      "command": "python",
      "args": [
        "-m",
        "sgu_mcp.server",
        "--transport",
        "stdio"
      ],
      "cwd": "C:/path/to/sgu-academic-mcp",
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}
```
</details>

---

## Kiểm thử tự động (Unit Tests & 100% Coverage)

Dự án đi kèm bộ test tự động sử dụng `pytest` với **độ bao phủ tuyệt đối 100%** toàn bộ mã nguồn:

```bash
# Chạy toàn bộ 48 test cases kèm báo cáo độ bao phủ
pytest --cov=sgu_mcp --cov-report=term-missing
```

Kết quả kiểm thử thực tế:
```text
============================= test session starts =============================
platform win32 -- Python 3.12.10, pytest-9.0.2
collected 48 items

tests\test_cache.py ....                                                 [  8%]
tests\test_crypto.py ..                                                  [ 12%]
tests\test_mcp_server.py ........                                        [ 29%]
tests\test_modules.py ..................                                 [ 66%]
tests\test_sgu_client.py .............                                   [ 93%]
tests\test_tools_offline.py ...                                          [100%]

=============================== tests coverage ================================
Name                           Stmts   Miss  Cover   Missing
------------------------------------------------------------
sgu_mcp\__init__.py                1      0   100%
sgu_mcp\config.py                 14      0   100%
sgu_mcp\core\cache.py             47      0   100%
sgu_mcp\core\crypto.py            38      0   100%
sgu_mcp\core\sgu_client.py        99      0   100%
sgu_mcp\modules\academic.py       49      0   100%
sgu_mcp\modules\exams.py          32      0   100%
sgu_mcp\modules\schedule.py       87      0   100%
sgu_mcp\modules\tuition.py        45      0   100%
sgu_mcp\prompts\templates.py       1      0   100%
sgu_mcp\resources\content.py       2      0   100%
sgu_mcp\server.py                101      0   100%
------------------------------------------------------------
TOTAL                            516      0   100%
============================== 48 passed in 3.93s ==============================
```

---

## Cấu trúc thư mục

```
sgu-academic-mcp/
├── sgu_mcp/
│   ├── config.py              # Cấu hình Pydantic BaseSettings
│   ├── server.py              # Entrypoint MCP Server (Stdio & SSE)
│   ├── core/
│   │   ├── crypto.py          # Reverse-engineered dynamic 'ua' header
│   │   ├── cache.py           # SQLite Caching Layer & Fallback
│   │   └── sgu_client.py      # HTTP API Client kết nối thongtindaotao.sgu.edu.vn
│   ├── modules/
│   │   ├── schedule.py        # 5 Tools: Thời khóa biểu, đăng ký môn & kiểm tra trùng
│   │   ├── exams.py           # 2 Tools: Lịch thi & đếm ngược ngày thi
│   │   ├── academic.py        # 4 Tools: Hồ sơ, bảng điểm & mô phỏng GPA
│   │   └── tuition.py         # 4 Tools: Học phí, thông báo & môn tiên quyết
│   ├── resources/
│   │   └── content.py         # 4 MCP Resources ngữ cảnh học vụ
│   └── prompts/
│       └── templates.py       # 3 MCP Prompt templates
├── skills/
│   └── sgu-academic/
│       └── SKILL.md           # Agent Skill tích hợp cho AI assistants
├── hands_on_lab/
│   └── HANDS_ON_LAB.md        # Hướng dẫn thực hành từng bước (Hands-on Guide)
├── tests/                     # 48 unit tests tự động (100% Coverage)
│   ├── test_cache.py          # Kiểm thử SQLite Caching, TTL & Error handling
│   ├── test_crypto.py         # Kiểm thử tạo header 'ua' reverse-engineered
│   ├── test_sgu_client.py     # Kiểm thử API Client, Auto-login & HTTP communication
│   ├── test_modules.py        # Kiểm thử toàn diện 15 Tools & nghiệp vụ học vụ
│   ├── test_mcp_server.py     # Kiểm thử MCP Protocol (Tools, Resources, Prompts & CLI)
│   └── test_tools_offline.py  # Kiểm thử offline mô phỏng GPA & môn tiên quyết
├── Dockerfile                 # Container image build
├── docker-compose.yml         # Container orchestration
└── requirements.txt           # Python dependencies
```

---

## Bảo mật & Quyền riêng tư

* **Xử lý cục bộ (Local Execution):** Mọi thông tin đăng nhập và dữ liệu học tập cá nhân được xử lý hoàn toàn trên máy cục bộ của người dùng.
* **Không lưu trữ tập trung:** Máy chủ không chuyển tiếp hoặc lưu trữ thông tin nhạy cảm lên bất kỳ server bên thứ ba nào.
* **File `.env` được bảo vệ:** Cấu hình git mặc định đã ignore `.env` và database cache để tránh vô tình công khai tài khoản.

---

## Giấy phép (License)

Dự án được phát hành theo giấy phép [MIT License](LICENSE).
Tự do sử dụng, chỉnh sửa và tích hợp cho các mục đích học tập và nghiên cứu cá nhân.