Skip to main content
Glama

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/)에만 저장되며, 외부 서버로 전송되지 않습니다.


Related MCP server: klas-mcp

⚡ 주요 기능

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_* 네임스페이스를 사용합니다.

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. 저장소 클론 및 패키지 설치

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. 초기 런타임 설정

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

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

# 진단 도구 실행
klax doctor

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

Claude Code / Codex 자동 등록

klax install --all
# 또는 개별 등록
klax install --claude
klax install --codex

Claude Desktop 수동 설정 (claude_desktop_config.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에 따라 자유롭게 사용, 수정, 배포할 수 있습니다.

Available Tools

31 tools
klax_auth_statusA

현재 저장된 KLAS 자격증명 구성 상태와 세션 유효성을 진단합니다 (비밀번호 비노출).

NameRequiredDescriptionDefault

No parameters

Output Schema

NameRequiredDescription
resultYes
klax_build_assignment_checklistA

과제 설명(task_id) 또는 로컬에 색인된 강의자료(material_id)에서 제출 요구사항으로 보이는 문장만 규칙 기반으로 추려 locator/출처가 표시된 체크리스트를 만듭니다.

생성형 요약이나 완성 답안을 만들지 않으며, 원문 줄을 그대로 보존한 결정론적 구조화입니다. task_id와 material_id 중 최소 하나를 지정해야 합니다.

NameRequiredDescriptionDefault
task_idNo
course_idYes
yearhakgiNo
material_idNo

Output Schema

NameRequiredDescription
resultYes
klax_download_materialB

강의 자료실 첨부파일을 로컬 디렉토리에 안전하게 다운로드하고 저장 경로 및 해시를 반환합니다.

NameRequiredDescriptionDefault
file_snNo
overwriteNo
attachment_idYes
destination_dirNo

Output Schema

NameRequiredDescription
resultYes
klax_generate_quizA

로컬에 색인된 강의자료 청크(chunk_id)의 본문에서 결정론적 규칙으로 객관식 퀴즈 1개를 생성합니다.

정답/해설은 채점 전 노출을 막기 위해 반환하지 않으며, klax_submit_quiz_answer로 제출해야 확인할 수 있습니다. 생성된 퀴즈는 로컬 학습 저장소(study.db)에 저장되고, 채점 시 자동으로 망각곡선 복습 큐에 등록됩니다. 생성형 요약이 아닌 원문 정의/빈칸 추출 기반입니다.

NameRequiredDescriptionDefault
chunk_idYes
course_idYes

Output Schema

NameRequiredDescription
resultYes
klax_generate_study_guide_htmlA

색인 완료된 로컬 강의자료를 재사용해, 출처와 페이지/슬라이드 locator가 보존된 단일 HTML 학습 가이드를 생성합니다.

먼저 klax_download_material과 klax_index_learning_material로 자료를 로컬 색인해야 합니다. KLAS에는 쓰지 않으며, output_path는 홈 디렉토리 하위의 .html 파일이어야 합니다.

NameRequiredDescriptionDefault
titleNo
course_idYes
output_pathYes
include_link_analysisNo

Output Schema

NameRequiredDescription
resultYes
klax_get_assignment_feedbackB

제출 완료되어 채점된 과제의 점수와 교수 피드백 코멘트를 조회합니다 (조회 전용).

task_id는 klax_get_deadlines로 조회한 과제의 식별자를 사용합니다.

NameRequiredDescriptionDefault
task_idYes
verboseNo
course_idYes
yearhakgiNo

Output Schema

NameRequiredDescription
resultYes
klax_get_attendance_statusA

특정 과목의 전자출결(KW출첵) 현황을 조회하고 결석 위험도를 분석합니다.

위험도 계산은 결석 1/3 이상 시 F 처리되는 일반적 학칙을 가정한 참고용이며 학교의 공식 판정을 대체하지 않습니다.

NameRequiredDescriptionDefault
verboseNo
course_idYes
yearhakgiNo

Output Schema

NameRequiredDescription
resultYes
klax_get_daily_briefingA

오늘/내일 수업 시간표·강의실, 마감 임박 과제 D-Day, 출결 위험 알림을 종합한 일일 학업 브리핑(마크다운)을 생성합니다.

참고용 요약이며 공식 학사 정보를 대체하지 않습니다.

NameRequiredDescriptionDefault
termNo
include_attendanceNo

Output Schema

NameRequiredDescription
resultYes
klax_get_deadlinesB

전체 과목 또는 특정 과목의 과제 및 제출 마감 일정을 조회합니다.

NameRequiredDescriptionDefault
course_idNo

Output Schema

NameRequiredDescription
resultYes
klax_get_learning_excerptA

klax_search_learning_materials 결과의 chunk_id로 원문 발췌 전체(페이지/슬라이드 텍스트)와 출처를 조회합니다.

NameRequiredDescriptionDefault
chunk_idYes

Output Schema

NameRequiredDescription
resultYes
klax_get_lecture_progressB

특정 과목의 온라인 동영상 강의 진도율 및 출석 마감 일정을 조회합니다.

NameRequiredDescriptionDefault
verboseNo
course_idYes
yearhakgiNo

Output Schema

NameRequiredDescription
resultYes
klax_get_overviewB

광운대 KLAS 수강 과목, 마감 임박 과제, 미수강 온라인 강의 종합 현황을 한 번에 요약 조회합니다.

NameRequiredDescriptionDefault
termNo
verboseNo
deadline_daysNo

Output Schema

NameRequiredDescription
resultYes
klax_get_review_queueA

오늘 기준으로 복습해야 할 망각곡선 복습 큐 항목을 조회합니다 (로컬 저장소 조회, KLAS 호출 없음).

course_id를 지정하면 해당 과목으로만 필터링합니다. 항목이 비어 있으면 오늘 복습할 대상이 없다는 뜻입니다.

NameRequiredDescriptionDefault
course_idNo

Output Schema

NameRequiredDescription
resultYes
klax_get_study_planA

마감 임박 과제와 오늘 복습해야 할 망각곡선 큐 항목을 결합한 향후 7일 학습 계획을 생성합니다.

과제는 마감 하루 전 날짜에, 복습 항목은 7일에 걸쳐 분산 배치됩니다. 마감일을 해석할 수 없는 과제는 unscheduled_assignments로 별도 표시되며 임의로 날짜를 추정하지 않습니다.

NameRequiredDescriptionDefault
course_idNo

Output Schema

NameRequiredDescription
resultYes
klax_get_syllabusB

특정 과목의 강의계획서(주차별 진도 계획, 교재, 평가비율)를 상세 조회합니다.

NameRequiredDescriptionDefault
verboseNo
course_idYes
yearhakgiNo

Output Schema

NameRequiredDescription
resultYes
klax_get_timetableA

개인 수업시간표(과목명, 요일, 교시, 강의실, 교수명)를 조회합니다.

generate_ics=True일 때만 응답에 iCal(.ics) 텍스트를 포함합니다. export_ics_path를 지정하면 응답 크기를 늘리지 않고 홈 디렉토리 하위에 klas_timetable.ics 파일로 저장합니다. semester_start(YYYY-MM-DD)를 지정하면 해당 날짜를 기준으로 반복 일정을 계산하며, 미지정 시 오늘 날짜를 기준으로 합니다. weeks는 반복 주차 수(기본 16주)입니다.

NameRequiredDescriptionDefault
termNo
weeksNo
verboseNo
generate_icsNo
semester_startNo
export_ics_pathNo

Output Schema

NameRequiredDescription
resultYes
klax_get_video_transcriptA

색인된 강의자료(material_id) 또는 로컬 동영상 경로의 자막/STT 전사를 타임코드 구간으로 조회합니다.

material_id_or_video_id가 로컬 색인 저장소(SQLite)에 존재하면 저장된 time:HH:MM:SS 청크를 사용하고, 존재하지 않으면 로컬 동영상 경로로 간주해 같은 파일명의 자막(.vtt/.srt) 또는 로컬 STT(faster-whisper/whisper)로 즉시 전사를 시도합니다. start_time/end_time(HH:MM:SS 또는 MM:SS)을 지정하면 해당 구간과 겹치는 청크만 반환합니다. STT 라이브러리 미설치 시 unsupported 상태와 사유를 반환하며, 원격 URL 다운로드나 외부 클라우드 API는 호출하지 않습니다.

NameRequiredDescriptionDefault
end_timeNo
start_timeNo
material_id_or_video_idYes

Output Schema

NameRequiredDescription
resultYes
klax_index_learning_materialA

로컬에 이미 다운로드된 PDF/PPTX 파일을 읽어 페이지/슬라이드 단위로 텍스트를 추출하고 로컬 검색 인덱스에 반영합니다.

KLAS에는 어떤 것도 쓰지 않으며, klax_download_material로 받은 로컬 경로만 처리합니다. 동일 파일 내용(SHA256)이 이미 색인되어 있으면 재처리하지 않고 기존 결과를 반환합니다 (force_reindex=True로 강제 재처리 가능). PyMuPDF/python-pptx 미설치, 스캔본(텍스트 없음), 미지원 확장자는 각각 unsupported/needs_ocr 상태와 사유(error_reason)로 반환됩니다.

NameRequiredDescriptionDefault
titleNo
semesterNo
course_idYes
local_pathYes
source_urlNo
force_reindexNo

Output Schema

NameRequiredDescription
resultYes
klax_list_coursesB

현재 학기(또는 지정 학기)의 수강 과목 목록(과목명, 과목코드, 담당교수, 분반)을 조회합니다.

NameRequiredDescriptionDefault
termNo
verboseNo

Output Schema

NameRequiredDescription
resultYes
klax_list_learning_materialsA

로컬에 색인된(또는 색인 시도된) 강의자료 목록과 처리 상태(pending/processing/completed/failed/unsupported)를 조회합니다.

KLAS 원격 조회가 아닌 로컬 색인 저장소(SQLite) 조회이며, status를 지정하면 해당 상태로만 필터링합니다.

NameRequiredDescriptionDefault
statusNo
course_idYes

Output Schema

NameRequiredDescription
resultYes
klax_list_materialsC

특정 과목의 강의 자료실 게시글과 온라인 강의 콘텐츠에 직접 첨부된 자료(예: 컴퓨터그래픽스의 실습 파일)를 병합한 목록과 첨부파일 ID(atchFileId)를 조회합니다.

NameRequiredDescriptionDefault
verboseNo
course_idYes
yearhakgiNo

Output Schema

NameRequiredDescription
resultYes
klax_refresh_sessionA

KLAS 세션 쿠키를 강제로 재발급받아 로컬 캐시를 갱신합니다.

NameRequiredDescriptionDefault

No parameters

Output Schema

NameRequiredDescription
resultYes
klax_search_course_materialsA

과목의 강의계획서 주차별 내용과 자료실 게시글 제목을 로컬 검색 인덱스(SQLite FTS)에 색인한 뒤 질의어로 검색하여 출처(과목/유형/제목)가 표시된 결과를 반환합니다.

외부 API나 임베딩 서비스로 전송하지 않는 로컬 전용 검색이며, 다른 과목 자료는 결과에 포함되지 않습니다 (권한 인식 검색).

NameRequiredDescriptionDefault
limitNo
queryYes
course_idYes
yearhakgiNo

Output Schema

NameRequiredDescription
resultYes
klax_search_learning_materialsA

색인된 강의자료(PDF/PPTX/HWPX/동영상) 청크를 로컬 FTS로 검색하고 각 결과에 locator, source_url, retrieved_at, freshness를 포함해 반환합니다.

locator 형식은 자료 종류에 따라 다릅니다: PDF는 page:N, PPTX는 slide:N, HWPX는 section:N, 동영상 자막/전사는 time:HH:MM:SS입니다. time: locator가 있는 결과는 klax_get_video_transcript(material_id, start_time, end_time)로 해당 구간 전문을 조회할 수 있습니다. 검색 범위 내에 색인 실패/미지원/처리중 자료가 있으면 partial_failure=True와 사유 목록을 함께 반환해 결과가 불완전할 수 있음을 명시합니다. 외부 API나 임베딩 서비스로 전송하지 않습니다.

NameRequiredDescriptionDefault
limitNo
queryYes
course_idNo
material_typeNo

Output Schema

NameRequiredDescription
resultYes
klax_simulate_gradeA

강의계획서 평가비율과 현재 확보 점수를 이용해 목표 총점 달성에 필요한 잔여 평가 평균 점수를 역산합니다.

current_scores는 klax_get_syllabus의 evaluation_ratio와 동일한 키 (midterm/final/assignment/attendance/quiz/etc)를 사용하며, 아직 채점되지 않은 항목은 생략합니다. 공식 성적 예측이 아닌 가정 기반 시뮬레이션입니다.

NameRequiredDescriptionDefault
course_idYes
yearhakgiNo
target_scoreYes
current_scoresYes

Output Schema

NameRequiredDescription
resultYes
klax_submit_quiz_answerA

생성된 퀴즈(quiz_id)에 대한 답안(user_answer, options 배열의 인덱스)을 채점합니다.

채점 결과(정답 여부, 정답 인덱스, 해설)를 반환하고, 결과에 따라 에빙하우스 망각곡선 기반 복습 큐(review_queue)의 간격을 SM-2 변형 알고리즘으로 자동 갱신합니다.

NameRequiredDescriptionDefault
quiz_idYes
user_answerYes

Output Schema

NameRequiredDescription
resultYes
klax_tutor_conceptC

소크라테스식 점진적 힌트 사다리(Hint Ladder, 1~3단계)를 통해 학생의 개념 이해도를 점검하고 유도합니다.

NameRequiredDescriptionDefault
conceptYes
hint_levelNo
user_answerNo
context_textNo

Output Schema

NameRequiredDescription
resultYes
klax_write_study_note_htmlA

모델이 교안 원문을 읽고 작성한 구조화된 note JSON을, 출처 locator 검증 후 로컬 단일 HTML 학습 노트로 저장합니다.

note 필수 필드: title, overview, sections[]. 각 섹션에는 title, explanation, why_it_matters, source_locators(page:N/slide:N 등)가 필요합니다. 이 도구는 LLM/API를 호출하지 않고 HTML만 렌더링하며, locator가 색인 자료에 없으면 저장을 거부합니다.

NameRequiredDescriptionDefault
noteYes
course_idYes
output_pathYes

Output Schema

NameRequiredDescription
resultYes

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 31 tool updatesv0.1.0
    • First observedklax_analyze_material_links
    • First observedklax_auth_status
    • First observedklax_build_assignment_checklist
    • First observedklax_download_material
    • First observedklax_extract_pdf_links
    • First observedklax_generate_quiz
    • First observedklax_generate_study_guide_html
    • First observedklax_get_assignment_feedback
    • First observedklax_get_attendance_status
    • First observedklax_get_daily_briefing
    • First observedklax_get_deadlines
    • First observedklax_get_learning_excerpt
    • First observedklax_get_lecture_progress
    • First observedklax_get_overview
    • First observedklax_get_review_queue
    • First observedklax_get_study_plan
    • First observedklax_get_syllabus
    • First observedklax_get_timetable
    • First observedklax_get_video_transcript
    • First observedklax_index_learning_material
    • First observedklax_link_assignment_to_materials
    • First observedklax_list_courses
    • First observedklax_list_learning_materials
    • First observedklax_list_materials
    • First observedklax_refresh_session
    • First observedklax_search_course_materials
    • First observedklax_search_learning_materials
    • First observedklax_simulate_grade
    • First observedklax_submit_quiz_answer
    • First observedklax_tutor_concept
    • First observedklax_write_study_note_html

TDQS

B3.4/5.0

Scored across 31 tools

Disambiguation3/5

Most tools target a distinct resource and action, but there are several closely related pairs such as extract_pdf_links vs analyze_material_links, list_materials vs list_learning_materials, and search_course_materials vs search_learning_materials. The detailed descriptions help clarify boundaries, but an agent could still easily misselect among the overlapping material, search, and summary tools.

Naming Consistency4/5

The klax_ prefix and verb_noun style are applied consistently across nearly all tools, such as list_courses, get_deadlines, download_material, and generate_quiz. Minor exceptions like klax_auth_status and klax_tutor_concept deviate from the strict verb-first pattern, but the overall naming scheme remains predictable.

Tool Count2/5

With 31 tools, the server is above the 25-tool threshold and feels heavy for a single MCP. Several tools are variations on material handling, searching, and summary generation, so the set could likely be consolidated without losing core functionality.

Completeness4/5

The tool set covers the main KLAS workflows—courses, deadlines, attendance, timetable, syllabus, and materials—plus a coherent local study loop of downloading, indexing, searching, quizzing, reviewing, and generating study plans. Minor lifecycle gaps exist, such as no unindex/delete for local materials and no listing of generated quizzes or notes, but agents can generally work around them.

Maintenance

ActivitySlowing
ResponsivenessNo recent community issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    B
    maintenance
    Enables AI agents to safely automate Kwangwoon University KLAS tasks, including viewing academic schedules, assignment deadlines, lecture progress, and downloading course materials, with secure session recovery and credential isolation.
    8
    MIT
  • A
    license
    A
    quality
    B
    maintenance
    Runs locally to let agents access Shantou University campus notices, grades, courses, assignments, exams, and schedules from public sites, OA, academic systems, MySTU, and Yuketang. Public data works without login, while personal features use optional school-page logins with local encrypted caching.
    16
    9
    MIT
  • A
    license
    A
    quality
    B
    maintenance
    Enables Claude Code and Claude Desktop to access Hansung University’s LMS (Cosmos) for assignment, quiz, VOD, and course-material workflows, including deadline lists, downloading assignments and materials, weekly summaries, and local lecture transcription, without submitting work.
    24
    106 npm
    Apache 2.0