KSU ESS API Server & MCP Server

ระบบ middleware สำหรับเชื่อมต่อกับ KSU ESS (Education Support System) SOAP Web Service ของมหาวิทยาลัยกาฬสินธุ์ ประกอบด้วย:

1. REST API Server - สำหรับระบบสารสนเทศทางการศึกษา (Web/Mobile)
2. MCP Server - สำหรับ AI Agents (Claude Desktop, Gemini, etc.)

📋 บริการที่ให้

บริการ	คำอธิบาย
ข้อมูลพื้นฐานนักศึกษา	ชื่อ-สกุล, คณะ, สาขา, หลักสูตร, อ.ที่ปรึกษา
สถานะนักศึกษา	กำลังศึกษา, พ้นสภาพ, สำเร็จการศึกษา
โครงสร้างหลักสูตร	ชื่อหลักสูตร, ค้นหาหลักสูตร
โครงสร้างรายวิชา	หมวดวิชา, กลุ่มวิชา, รายวิชา (tree structure)
แผนการเรียน	รายวิชาทั้งหมด / รายเทอม
วิชายกเว้น	วิชาที่ได้รับการยกเว้น
ผลการเรียน	เกรด, GPA, GPS, หน่วยกิต (transcript)
ผลการลงทะเบียน	ตารางเรียน, สถานที่, อาจารย์ผู้สอน

🚀 การติดตั้ง

1. ติดตั้ง Dependencies

npm install

2. ตั้งค่า Environment Variables

cp .env.example .env

แก้ไขไฟล์ .env:

ESS_USERNAME=your_ess_username
ESS_PASSWORD=your_ess_password
API_PORT=3000
API_KEY=your_api_key    # เว้นว่างไว้สำหรับ development mode

3. รัน API Server

# Development (hot reload)
npm run dev:api

# Production
npm run build
npm run start:api

Server จะเริ่มทำงานที่ http://localhost:3000

4. รัน MCP Server

# Development
npm run dev:mcp

# Production
npm run build
npm run start:mcp

📖 API Documentation

เมื่อรัน API Server แล้ว เข้าดูเอกสาร API ได้ที่:

• Swagger UI: http://localhost:3000/api/docs
• OpenAPI JSON: http://localhost:3000/api/docs.json

🔗 API Endpoints

System

Method	Endpoint	คำอธิบาย
GET	/api/v1/health	Health check

Students

Method	Endpoint	คำอธิบาย
GET	/api/v1/students/:studentNo/profile	ข้อมูลพื้นฐาน
GET	/api/v1/students/:studentNo/status	สถานะนักศึกษา

Curriculum

Method	Endpoint	คำอธิบาย
GET	/api/v1/students/:studentNo/curriculum	หลักสูตรของนักศึกษา
GET	/api/v1/curriculum?yearNo=&eduLevel=&facultyCode=&majorCode=&programCode=	ค้นหาหลักสูตร
GET	/api/v1/students/:studentNo/course-structure	โครงสร้างรายวิชา

Education Plan

Method	Endpoint	คำอธิบาย
GET	/api/v1/students/:studentNo/education-plan	แผนการเรียนทั้งหมด
GET	/api/v1/students/:studentNo/education-plan/semester?yearSeq=&semesterId=	แผนรายเทอม
GET	/api/v1/students/:studentNo/exception-courses	วิชายกเว้น

Education Records

Method	Endpoint	คำอธิบาย
GET	/api/v1/students/:studentNo/education-records	ผลการเรียนทั้งหมด
GET	/api/v1/students/:studentNo/education-records/semester?yearNo=&semesterId=	ผลการเรียนรายเทอม

Registration

Method	Endpoint	คำอธิบาย
GET	/api/v1/students/:studentNo/registration	การลงทะเบียนทั้งหมด
GET	/api/v1/students/:studentNo/registration/semester?yearNo=&semesterId=	การลงทะเบียนรายเทอม

🤖 MCP Server Configuration

สำหรับ Claude Desktop

เพิ่มใน claude_desktop_config.json:

{
  "mcpServers": {
    "ksu-ess": {
      "command": "node",
      "args": ["d:/devSpace/API/dist/mcp/server.js"],
      "env": {
        "ESS_USERNAME": "your_username",
        "ESS_PASSWORD": "your_password"
      }
    }
  }
}

MCP Tools ที่ให้บริการ (12 tools)

Tool	คำอธิบาย
get_student_profile	ดึงข้อมูลพื้นฐานนักศึกษา
get_student_status	ดึงสถานะนักศึกษา
get_curriculum_by_student	ดึงหลักสูตรของนักศึกษา
get_curriculum	ค้นหาหลักสูตร
get_course_structure	ดึงโครงสร้างรายวิชา
get_education_plan_all	ดึงแผนการเรียนทั้งหมด
get_education_plan_semester	ดึงแผนการเรียนรายเทอม
get_exception_courses	ดึงวิชายกเว้น
get_education_records_all	ดึงผลการเรียนทั้งหมด
get_education_records_semester	ดึงผลการเรียนรายเทอม
get_registration_all	ดึงผลการลงทะเบียนทั้งหมด
get_registration_semester	ดึงผลการลงทะเบียนรายเทอม

🔒 Authentication

API Server

• ใช้ API Key ผ่าน header X-API-Key
• ถ้าไม่ตั้ง API_KEY ใน .env จะเปิดให้ใช้ได้อิสระ (development mode)

ESS Web Service

• ใช้ Rijndael-256 (CBC, PKCS7) encryption สำหรับรหัสผ่าน
• Key ได้จาก GetEncryptKey() ใช้ได้ตลอดจนกว่าจะเปลี่ยน

📁 โครงสร้างโปรเจกต์

src/
├── core/                   # Shared Core (ใช้ร่วมกันทั้ง API & MCP)
│   ├── types.ts            # TypeScript interfaces
│   ├── crypto.ts           # Rijndael-256 encryption
│   ├── ess-client.ts       # SOAP Client wrapper
│   └── errors.ts           # Custom error classes
├── api/                    # REST API Server
│   ├── server.ts           # Express.js entry point
│   ├── middleware/
│   │   ├── auth.ts         # API Key authentication
│   │   ├── error-handler.ts
│   │   └── rate-limiter.ts
│   └── routes/
│       ├── health.ts
│       ├── students.ts
│       ├── curriculum.ts
│       ├── education-plan.ts
│       ├── education-records.ts
│       └── registration.ts
└── mcp/                    # MCP Server
    ├── server.ts           # MCP entry point
    └── tools/
        ├── student-tools.ts
        ├── curriculum-tools.ts
        ├── education-tools.ts
        └── registration-tools.ts

🛠 Technology Stack

• Runtime: Node.js + TypeScript
• API Framework: Express.js
• SOAP Client: soap (npm)
• Encryption: rijndael-js (Rijndael-256 CBC PKCS7)
• MCP SDK: @modelcontextprotocol/sdk
• Validation: Zod
• API Docs: Swagger (swagger-jsdoc + swagger-ui-express)

📝 License

MIT