Skip to main content
Glama
zaikaman

SGU Academic MCP Server

by zaikaman
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

SGU Academic MCP Server

Python 3.10+ Model Context Protocol Tests Coverage Docker License: MIT

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

Related MCP server: FAST-NUCES Flex Student Portal MCP Server

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

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:

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:

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!

Chạy trực tiếp MCP Server qua dòng lệnh

  • Chế độ stdio:

    python -m sgu_mcp.server --transport stdio

  • Chế độ SSE (HTTP Web Service):

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

Triển khai với Docker

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:

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

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:

# 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ế:

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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers