┌────────────────────────────────────────────────────────┐
│                   Trợ lý AI (Clients)                  │
│ Claude Desktop │ Antigravity │ VS Code │ Cursor │ CLI  │
└───────────────────────────┬────────────────────────────┘
                            │ 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                 │
└────────────────────────────────────────────────────────┘

git clone https://github.com/zaikaman/SGU-Academic-MCP.git
cd SGU-Academic-MCP
pip install -r requirements.txt

SGU_STUDENT_ID=3122xxxxxx
SGU_PASSWORD=MatKhauCuaBan

python -m sgu_mcp.server --transport sse --port 8000

# 1. Khởi động MCP Server ở chế độ nền (Background)
docker compose up -d --build

# 2. Xem logs hoạt động thời gian thực
docker compose logs -f

# 3. Kiểm tra trạng thái container và healthcheck
docker compose ps

# 4. Dừng dịch vụ
docker compose down

# Build image
docker build -t sgu-mcp-server:latest .

# Chạy container kèm mount thư mục data và nạp .env
docker run -d \
  --name sgu_mcp_academic_server \
  -p 8000:8000 \
  --env-file .env \
  -v ${PWD}/data:/app/data \
  sgu-mcp-server:latest

{
  "mcpServers": {
    "sgu_academic_server": {
      "command": "python",
      "args": [
        "-m",
        "sgu_mcp.server",
        "--transport",
        "stdio"
      ],
      "cwd": "C:/path/to/sgu-academic-mcp",
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

# Chạy toàn bộ 52 test cases kèm báo cáo độ bao phủ
python -m pytest --cov=sgu_mcp --cov-branch --cov-report=term-missing tests/

============================= test session starts =============================
platform win32 -- Python 3.12.10, pytest-9.1.1, pluggy-1.6.0
collected 52 items

tests/test_cache.py ....                                                 [  7%]
tests/test_crypto.py ..                                                  [ 11%]
tests/test_mcp_server.py .............                                   [ 32%]
tests/test_modules.py ..................                                 [ 67%]
tests/test_sgu_client.py ...............                                 [ 94%]
tests/test_tools_offline.py ...                                          [100%]

=============================== tests coverage ================================
Name                           Stmts   Miss Branch BrPart  Cover   Missing
--------------------------------------------------------------------------
sgu_mcp\__init__.py                1      0      0      0   100%
sgu_mcp\config.py                 12      0      0      0   100%
sgu_mcp\core\cache.py             45      0      6      0   100%
sgu_mcp\core\crypto.py            38      0      4      0   100%
sgu_mcp\core\sgu_client.py        76      0     12      0   100%
sgu_mcp\modules\academic.py       49      0     12      0   100%
sgu_mcp\modules\exams.py          31      0     12      0   100%
sgu_mcp\modules\schedule.py       84      0     34      0   100%
sgu_mcp\modules\tuition.py        45      0     12      0   100%
sgu_mcp\prompts\templates.py       2      0      0      0   100%
sgu_mcp\resources\content.py       2      0      0      0   100%
sgu_mcp\server.py                102      0      8      0   100%
--------------------------------------------------------------------------
TOTAL                            487      0    100      0   100%
======================== 52 passed, 1 warning in 6.49s ========================

SGU-Academic-MCP/
├── AGENTS.md                  # Hướng dẫn đa môi trường & cây quyết định cho AI Agents
├── 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 nghiệp vụ học vụ SGU
├── hands_on_lab/
│   └── HANDS_ON_LAB.md        # Hướng dẫn thực hành từng bước (Hands-on Guide)
├── tests/                     # 52 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 & Server Lifecycle)
│   └── test_tools_offline.py  # Kiểm thử offline mô phỏng GPA & môn tiên quyết
├── setup.py                   # Script cài đặt tự động 3-in-1 đa nền tảng (Polyglot)
├── setup.bat                  # 1-Click setup dành cho Windows
├── setup.sh                   # 1-Click setup dành cho Linux / WSL
├── Dockerfile                 # Container image build (Python 3.12-slim, non-root)
├── docker-compose.yml         # Container orchestration & live volume mount
└── requirements.txt           # Python dependencies