# klas-mcp

광운대학교 학사관리시스템(KLAS) 연동을 위한 **Model Context Protocol (MCP)** 서버입니다.  
Claude Desktop, Cursor, Hermes Agent 등 다양한 AI 에이전트에서 학사 일정, 과제 마감, 온라인 강의 진도율, 강의 자료실 다운로드를 안전하게 자동화할 수 있습니다.

---

## 🌟 주요 특징

1. **자가 치유 세션 브릿지 (Self-Healing Session)**
   - 평상시에는 가벼운 비동기 HTTP(`httpx`) 통신을 수행하여 초고속으로 데이터를 조회합니다.
   - KLAS 세션이 만료되면 백그라운드에서 격리된 Playwright 헤드리스 브라우저가 자동 기동되어 세션을 복구합니다.
2. **보안 자격증명 격리 (Credential Security)**
   - 학번과 비밀번호를 LLM 프롬프트나 로그에 일체 노출하지 않습니다.
   - OS Keychain(`keyring`) 또는 권한 `0600` 격리 파일을 통해 안전하게 보관됩니다.
3. **다운로드 안전 가드 (Path Traversal Guard)**
   - 강의 자료실 첨부파일을 다운로드할 때 시스템 루트 탈출을 원천 방어하며, SHA256 해시값과 로컬 경로를 LLM에 전달합니다.

---

## 🚀 빠른 시작

### 1. 설치 및 브라우저 준비
```bash
# uv 사용 시 (권장)
uv pip install -e .
uv run klas-mcp setup
```

### 2. 자격증명 설정
대화형 CLI를 통해 1회 안전하게 학번과 비밀번호를 등록합니다:
```bash
uv run klas-mcp configure
```

### 3. 상태 확인
```bash
uv run klas-mcp status
```

---

## 🔌 MCP 클라이언트 연동 가이드

### 1. Claude Desktop
`~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "klas": {
      "command": "uvx",
      "args": ["--from", "/Users/goonbam/hermesWorkspace/projects/klas-agent", "klas-mcp"]
    }
  }
}
```

### 2. Hermes Agent (`~/.hermes/config.yaml`)
```yaml
mcp_servers:
  klas:
    command: "uv"
    args: ["--directory", "/Users/goonbam/hermesWorkspace/projects/klas-agent", "run", "klas-mcp"]
```

---

## 🛠️ 제공 도구 (Tools)

| Tool 이름 | 설명 |
| :--- | :--- |
| `klas_get_overview` | 이번 주 할 일 요약 (수강 과목, 마감 임박 과제, 미수강 강의) |
| `klas_list_courses` | 현재 학기 수강 과목 목록 조회 |
| `klas_get_deadlines` | 과제 및 퀴즈 마감 일정 조회 |
| `klas_get_lecture_progress` | 특정 과목 온라인 동영상 강의 진도율 및 출석 마감 조회 |
| `klas_list_materials` | 강의 자료실 게시글 및 첨부파일 목록 조회 |
| `klas_download_material` | 강의 자료 첨부파일 로컬 다운로드 (경로 및 SHA256 반환) |
| `klas_auth_status` | 로그인 상태 및 세션 유효성 진단 |
| `klas_refresh_session` | 세션 쿠키 강제 재발급 및 갱신 |