# KLAX (klax)

> **광운대학교 학사관리시스템(KLAS) Model Context Protocol (MCP) 서버 & 학업 보조 CLI**  
> Claude Desktop, Claude Code, Codex, Cursor 등 AI 에이전트에 광운대 학사 일정 및 강의자료 인텔리전스를 연결합니다.

---

## ⚠️ 중요한 면책 고지 (Disclaimer)

1. **비공식 오픈소스 프로젝트**: 본 프로젝트는 광운대학교 공식 소프트웨어가 아니며, 학생 개인의 학업 생산성 향상을 위해 개발된 비공식 오픈소스 학업 비서입니다.
2. **학칙 및 윤리 준수 (Strict Academic Integrity)**: 
   - **자동 출석, 매크로 조작, 동영상 자동 재생 기능이 일절 포함되어 있지 않습니다.**
   - **교수 저작물(강의 영상)의 무단 복제/다운로드 기능을 제공하지 않습니다.**
   - 시험 공정성을 해치는 행위(시험 힌트 추출, 부정행위)와 관련된 로직이 완전히 배제되어 있습니다.
3. **Local-First & 개인정보 보호**:
   - 학생 자격증명(학번, 비밀번호)은 오직 로컬 머신의 **OS 키체인(macOS Keychain / Windows Credential Manager)**에만 암호화되어 보관됩니다.
   - 모든 교안 색인 및 퀴즈/노트 데이터는 로컬 SQLite(`~/.klax/`)에만 저장되며, 외부 서버로 전송되지 않습니다.

---

## ⚡ 주요 기능

### 1. 학사 일정 & 학업 대시보드
- **종합 현황 요약 (`klax_get_overview`)**: 수강 과목 수, 마감 임박 과제, 미수강 동영상 강의 진도율 종합 진단.
- **마감 일정 관리 (`klax_get_deadlines`)**: 과목별 과제 제출 마감 일시 및 제출 여부 조회.
- **수업시간표 & 캘린더 생성 (`klax_get_timetable`)**: 개인 시간표(요일/교시/강의실) 조회 및 표준 iCal(`.ics`) 파일 생성.
- **일일 학업 브리핑 (`klax_get_daily_briefing`)**: 오늘/내일 수업 시간표, D-Day 임박 과제, 출결 위험도를 종합한 마크다운 리포트.
- **강의계획서 & 학점 시뮬레이터 (`klax_get_syllabus`, `klax_simulate_grade`)**: 평가 비율 분석 및 목표 학점(A+) 달성에 필요한 잔여 평가 최저 점수 역산.

### 2. 강의자료 로컬 인텔리전스 (Local-First FTS)
- **자료실 첨부파일 수집 (`klax_list_materials`, `klax_download_material`)**: 강의계획서 및 자료실 파일을 로컬에 안전하게 다운로드.
- **슬라이드 단위 정확한 색인 (`klax_index_learning_material`)**: PDF/PPTX 교안을 페이지/슬라이드 단위로 분해하여 로컬 SQLite FTS5에 색인.
- **출처 기반 인용 검색 (`klax_search_learning_materials`)**: 검색어와 관련된 교안의 정확한 위치(`page:N`, `slide:N`) 및 원문 발췌문 조회.
- **교안 외부 링크 & 맥락 분석 (`klax_extract_pdf_links`, `klax_analyze_material_links`)**: 교안 속 웹 링크를 추출하고 슬라이드 전후 문맥과 웹페이지 핵심을 분석해 실전 학습 활용법 도출.

### 3. AI 적응형 학습 & 독자적 학습 노트
- **과제 요구사항 분해 (`klax_build_assignment_checklist`, `klax_link_assignment_to_materials`)**: 과제 지문에서 필수 구현 요구사항을 추출하고 관련 교안 슬라이드를 자동 매핑.
- **소크라테스식 개념 튜터 (`klax_tutor_concept`)**: 점진적 힌트 사다리(Hint Ladder, 1~3단계)로 학생 스스로 개념을 떠올리도록 유도.
- **자가 진단 퀴즈 & 에빙하우스 복습 큐 (`klax_generate_quiz`, `klax_submit_quiz_answer`, `klax_get_review_queue`)**: 교안 원문 기반 객관식 퀴즈 생성 및 망각곡선 주기 복습 스케줄러.
- **단일 HTML 학습 노트 생성 (`klax_write_study_note_html`)**: 모델이 작성한 구조화 노트를 원문 locator 전수 검증 후 브라우저에서 바로 읽는 단일 HTML 파일로 렌더링.

### MCP 도구 이름

등록되는 도구는 모두 `klax_*` 네임스페이스를 사용합니다.

```text
klax_get_overview
klax_list_courses
klax_get_deadlines
klax_get_lecture_progress
klax_list_materials
klax_download_material
klax_auth_status
klax_refresh_session
klax_get_timetable
klax_get_syllabus
klax_get_attendance_status
klax_get_assignment_feedback
klax_get_daily_briefing
klax_simulate_grade
klax_search_course_materials
klax_list_learning_materials
klax_index_learning_material
klax_search_learning_materials
klax_get_video_transcript
klax_get_learning_excerpt
klax_build_assignment_checklist
klax_generate_quiz
klax_submit_quiz_answer
klax_get_review_queue
klax_get_study_plan
klax_link_assignment_to_materials
klax_tutor_concept
klax_extract_pdf_links
klax_analyze_material_links
klax_write_study_note_html
klax_generate_study_guide_html
```

`klax_get_timetable`은 기본적으로 구조화된 시간표만 반환합니다. iCal 텍스트가 필요할 때만
`generate_ics=true`를 지정하세요. 원본 진단 payload는 지원되는 조회 도구에서
`verbose=true`를 지정한 경우에만 포함됩니다.

---

## 🛠️ 설치 및 설정

Python 3.10 이상이 필요합니다.

### 1. 저장소 클론 및 패키지 설치

```bash
git clone https://github.com/goonbam0306/klax.git
cd klax

python3 -m venv .venv
source .venv/bin/activate  # Windows: .\.venv\Scripts\Activate.ps1
pip install -e ".[materials]"
```

### 2. 초기 런타임 설정

```bash
# 세션 브리지용 헤드리스 Chromium 설치
klax setup

# KLAS 학번 및 비밀번호 저장 (OS 키체인 안전 보관)
klax configure

# 진단 도구 실행
klax doctor
```

### 3. AI 클라이언트에 원클릭 등록

#### Claude Code / Codex 자동 등록
```bash
klax install --all
# 또는 개별 등록
klax install --claude
klax install --codex
```

#### Claude Desktop 수동 설정 (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "klax": {
      "command": "/path/to/klax/.venv/bin/python",
      "args": ["-m", "klax.server"]
    }
  }
}
```

---

## 🔒 보안 및 개인정보 수칙

- `klax`는 비밀번호를 평문으로 저장하지 않으며, OS Secure Enclave / Keyring을 최우선 사용합니다.
- 학생 본인의 KLAS 계정 정보는 외부 클라우드, 원격 API, 분석 서버로 일절 전송되지 않습니다.
- 로컬 SQLite 데이터베이스(`~/.klax/`)는 소유자 전용 권한(`0700`, `0600`)으로 보호됩니다.

---

## 📄 라이선스

본 프로젝트는 [MIT License](LICENSE)에 따라 자유롭게 사용, 수정, 배포할 수 있습니다.