# 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

```bash
npm install
```

### 2. ตั้งค่า Environment Variables

```bash
cp .env.example .env
```

แก้ไขไฟล์ `.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

```bash
# Development (hot reload)
npm run dev:api

# Production
npm run build
npm run start:api
```

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

### 4. รัน MCP Server

```bash
# 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`:

```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