# 국민대 eCampus MCP

국민대 학생이 **자기 계정으로 강의자료를 조회·다운로드하고 AI에서 읽는 설치형 MCP**입니다. 각자 컴퓨터에서 실행하며 운영 서버나 Chrome 확장이 필요하지 않습니다. 국민대학교 공식 제품은 아닙니다.

PDF·PPTX·DOCX·HWPX·텍스트 읽기, PDF 페이지 이미지, 자료 검색, Markdown 저장과 오프라인 캐시를 지원합니다. 저장된 일정 조회와 ICS 내보내기도 제공하지만 **학교 일정 자동 동기화는 이 설치형 버전에 포함되지 않습니다.** 자료 동기화와 일정 가져오기는 별개입니다.

## 설치

[Node.js 24 이상](https://nodejs.org/en/download)을 설치한 뒤 MCP 클라이언트에 아래 설정을 추가하세요. 현재 배포는 **GitHub Release의 npm 패키지 파일**을 사용하며 npm 계정이 필요하지 않습니다.

```json
{
  "mcpServers": {
    "ecampus": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/KimJinwoo2198/kookmin-campus-mcp/releases/download/v1.2.0/kookmin-campus-mcp-1.2.0.tgz"
      ]
    }
  }
}
```

Codex CLI에서는 다음 명령을 사용할 수 있습니다.

```sh
codex mcp add ecampus -- npx -y https://github.com/KimJinwoo2198/kookmin-campus-mcp/releases/download/v1.2.0/kookmin-campus-mcp-1.2.0.tgz
```

Windows의 실행 설정과 수동 설치는 [설치 안내](docs/INSTALL.md)를 참고하세요. 처음 실행할 때 의존성 다운로드에 시간이 걸릴 수 있습니다.

## 로그인하고 사용하기

1. MCP를 연결한 AI에 **“eCampus의 start_school_login을 실행하고 로그인 창을 열어줘”**라고 요청합니다.
2. 열린 로컬 창에 학교 포털 계정을 직접 입력합니다. 비밀번호를 AI 대화에 보내지 마세요.
3. **“eCampus 연결을 확인하고 내 강의자료를 동기화해줘”**라고 요청합니다.
4. **“선형대수 강의노트를 읽고 페이지를 근거로 핵심 개념을 설명해줘”**처럼 사용할 수 있습니다.

브라우저는 계정 입력 창에만 사용합니다. 로그인 후 조회·다운로드·본문 읽기는 MCP가 학교에 직접 연결해 처리합니다. 세션이 만료되면 로그인 도구를 다시 호출합니다.

터미널에서 로그인할 수도 있습니다.

```sh
npx -y https://github.com/KimJinwoo2198/kookmin-campus-mcp/releases/download/v1.2.0/kookmin-campus-mcp-1.2.0.tgz login
```

## 제공 기능

로컬 stdio에서 도구 23개를 제공합니다. 전체 인자와 제한은 [자료 안내](docs/MATERIALS.md)에 있습니다.

| 기능 | 대표 도구 |
|---|---|
| 로그인·인증 확인 | start_school_login, get_school_connection |
| 자료·주차 목록 | sync_materials, list_materials, get_course_outline |
| 개별·일괄 다운로드 | get_material, download_material, download_materials |
| 본문·페이지·목차 | read_material, render_material_page, get_material_outline |
| 검색·내보내기·캐시 | index_materials, search_materials, export_material_markdown, get_material_cache |
| 가져온 일정 조회 | get_courses, get_agenda, search_items, get_item |
| 일정 상태·변경·ICS | get_source_status, get_schedule_changes, export_calendar |

list_personal_tasks는 기존 조회 인터페이스이며 로컬 배포에서는 개인 할 일 쓰기를 제공하지 않습니다. 과제 제출·시험 응시·출석 조작도 구현하지 않습니다. 스캔 PDF는 페이지 이미지로 확인할 수 있으나 OCR은 제공하지 않습니다.

## 개인 데이터

설치 파일과 개인 데이터는 분리됩니다. 업데이트하거나 npx 캐시를 지워도 사용자 데이터 폴더는 유지됩니다.

| 운영체제 | 기본 저장 위치 |
|---|---|
| macOS | ~/Library/Application Support/kookmin-campus-mcp |
| Windows | %LOCALAPPDATA%\kookmin-campus-mcp |
| Linux | XDG_DATA_HOME/kookmin-campus-mcp 또는 ~/.local/share/kookmin-campus-mcp |

ECAMPUS_DATA_DIR 또는 --data-dir로 변경할 수 있습니다. 개발용 src/stdio.js를 직접 실행하는 기존 설정과 설치형 CLI의 기본 저장 위치는 다릅니다. 서로 다른 학교 계정을 같은 OS 사용자에서 쓸 경우 별도 데이터 폴더를 지정하세요.

학교 비밀번호는 저장하지 않습니다. 인증 세션과 다운로드한 문서는 각 컴퓨터에 저장되며 운영자에게 업로드하지 않습니다. AI가 요청한 본문은 사용하는 AI 클라이언트로 전달됩니다. 자세한 내용은 [데이터와 인증](docs/PRIVACY.md)을 확인하세요.

## 검증 범위

실제 국민대 계정으로 SSO 로그인, MCP 인증 확인, 자료 조회·PDF 다운로드·본문 읽기를 확인했습니다. 추가 인증이나 학교 화면 변경으로 일부 계정은 지원되지 않을 수 있습니다. Windows/Linux에서의 학교 로그인은 실제 계정으로 별도 검증하지 않았습니다.

일정 도구를 쓰려면 본인이 수집한 정규화 JSON을 import-schedule로 가져와야 합니다. 새 설치에서 일정이 없다는 응답은 실제 학교 과제가 없다는 뜻이 아닙니다. [일정 가져오기](docs/INSTALL.md#일정-가져오기)를 참고하세요.

## 개발

```sh
git clone https://github.com/KimJinwoo2198/kookmin-campus-mcp.git
cd kookmin-campus-mcp
npm ci --ignore-scripts
npm test
npm run check
npm run verify:package
```

기존 원격 일정 웹 서버와 Chrome 확장은 별도의 개발용 구성입니다. [원격 서버 안내](docs/REMOTE_SERVER.md)와 [운영 문서](docs/DEPLOYMENT.md)를 참고하세요. 이 릴리스는 해당 서버를 공개 운영하는 배포가 아닙니다.

MIT 라이선스입니다. 라이선스는 프로그램 소스에 적용되며 학교 강의자료를 포함하거나 그 권리를 변경하지 않습니다. 학교의 공식 자동화 허가를 받았다고 주장하지 않습니다.