# LearnUs MCP

MCP 클라이언트에서 연세대학교 LearnUs의 과제, 일정, 공지, 영상 학습 상태와 강의자료를 조회하는 로컬 서버입니다. 여러 강좌의 정보를 모아 이번 주에 확인할 학업 내용을 정리할 수 있습니다.

TypeScript · 로컬 stdio MCP · LearnUs 읽기 전용

## 빠른 시작

### 1. 설치

Node.js **22.19 이상**, npm, 로컬 stdio MCP를 지원하는 클라이언트가 필요합니다.

```bash
git clone https://github.com/illlilililiililll/LearnUS_MCP.git
cd LearnUS_MCP
npm ci
npx playwright install chromium
npm run build
```

Linux에서 브라우저 시스템 의존성도 설치해야 한다면 `npx playwright install --with-deps chromium`을 사용하세요. TypeScript와 Playwright의 전역 설치는 필요하지 않습니다.

### 2. MCP 클라이언트에 연결

사용하는 클라이언트의 로컬 MCP 서버 설정에 아래 실행 정보를 등록하세요. 설정 파일의 형식은 클라이언트마다 다릅니다.

| 설정 | 값 |
| --- | --- |
| 서버 이름 | `learnus` |
| 실행 명령 | `node` |
| 인자 | `["/absolute/path/LearnUS_MCP/dist/index.js"]` |
| 환경변수 | `LEARNUS_ID`, `LEARNUS_PASSWORD` |

인자 경로는 실제 저장소의 **절대경로**로 바꾸세요. 인증정보는 클라이언트의 환경변수 전달 기능이나 지원되는 비밀정보 관리 기능으로 서버 프로세스에 제공하세요. 서버는 `.env`를 자동으로 읽지 않습니다.

> 인증정보를 채팅, Tool 인자, 명령줄 또는 커밋되는 설정에 넣지 마세요. 연결 원칙과 범위는 [MCP Host 설정](docs/codex-mcp-host-setup.md)을 참고하세요.

이 서버는 웹 주소로 접속하는 서비스가 아닙니다. MCP 클라이언트가 프로세스를 실행하므로 별도로 `npm start`를 켜 둘 필요는 없습니다.

### 3. 첫 질문

연결 후 클라이언트의 도구 목록에 `learnus_*` 도구가 표시되는지 확인하고, 다음처럼 요청하세요.

- “LearnUs에서 수강 중인 강좌를 보여줘.”
- “이번 주 LearnUs 과제와 영상 학습 현황을 정리해 줘.”
- “이 강좌의 최근 공지와 강의자료 목록을 보여줘.”

조회 도구가 필요할 때 자동으로 로그인합니다. `learnus_auth_status`를 먼저 호출할 필요는 없습니다. 실제 도구 선택은 클라이언트와 모델에 따라 달라집니다.

## 제공 도구

주간 과제·출석·학습 질문에는 `learnus_get_weekly_tasks`, 여러 범주의 종합 조회에는 `learnus_get_overview`, 특정 항목에는 개별 도구를 사용합니다. 학업과 무관한 개인 할 일 질문에는 LearnUs를 자동 우선하지 않습니다.

| 분류 | 도구 | 용도 |
| --- | --- | --- |
| 종합 | `learnus_get_weekly_tasks` | 영상 학습을 포함한 주간 학업 요약 |
| 종합 | `learnus_get_overview` | 과제·일정·공지 등 선택한 범주의 요약 |
| 강좌 | `learnus_list_courses` | 수강 강좌 목록 |
| 강좌 | `learnus_get_course` | 특정 강좌의 구조와 활동 |
| 강좌 | `learnus_list_activities` | 강좌별 학습 활동 목록 |
| 과제·일정 | `learnus_get_assignment` | 과제 안내, 마감, 첨부파일과 제출·채점 상태 |
| 과제·일정 | `learnus_upcoming` | 지정 기간의 일정과 마감 |
| 공지·알림 | `learnus_list_announcements` | 공지 목록 |
| 공지·알림 | `learnus_get_announcement` | 공지 본문과 첨부파일 |
| 공지·알림 | `learnus_list_notifications` | 알림 목록 |
| 영상 | `learnus_list_videos` | 강좌별 영상 목록 |
| 영상 | `learnus_get_video_attendance` | 영상별 학습·출석 상태 |
| 영상 | `learnus_get_learning_overview` | 필수 미완료·완료·선택/제외·불명 상태 요약 |
| 자료 | `learnus_list_files` | 강의자료 목록 |
| 자료 | `learnus_download_file` | 요청한 파일을 로컬에 다운로드 |
| 진단 | `learnus_auth_status` | 현재 프로세스의 로그인 상태 확인 |

직접 도구를 호출할 때는 조회 결과의 ID를 사용하세요. `courseId`·`moduleId`·`articleId`·`videoId`는 양의 정수 문자열, 과제 상세의 `cmid`는 양의 정수 숫자, `fileId`는 등록된 UUID입니다. 입력 필드와 선택 옵션은 클라이언트에 노출되는 도구 스키마에서 확인할 수 있습니다.

### 조회 결과를 읽는 기준

- 주간 기본 범위는 **한국 시간(Asia/Seoul) 월요일~일요일**입니다.
- `overview`는 기본적으로 일정·과제·공지를 각각 최대 10개 요약합니다. 강좌·알림·학습 상태는 선택 옵션이며, `weekly_tasks`는 학습 상태도 포함합니다.
- 공지·알림·새 파일은 정보성 항목입니다. 반드시 해야 할 일로 취급하지 않으며, 대상이나 마감 근거가 부족하면 `unknown`을 유지합니다.
- 영상의 완료·진도·출석은 구분합니다. Moodle 완료 표시는 다운로드나 실제 독서를 증명하지 않습니다. 일부 조회가 실패하면 경고로 알립니다.

자세한 기준은 [주간 조회](docs/weekly-tasks.md)와 [학습 상태 해석](docs/m86-semantics.md)을 참고하세요.

## 설정

| 환경변수 | 기본값 / 용도 |
| --- | --- |
| `LEARNUS_ID` / `LEARNUS_PASSWORD` | 로그인 인증정보 |
| `LEARNUS_DOWNLOAD_ROOT` | `~/Documents/LearnUS`; 다운로드 폴더 |
| `LEARNUS_MAX_DOWNLOAD_BYTES` | `52428800` (50 MiB); 파일 크기 제한 |
| `LEARNUS_MAX_CONCURRENT_REQUESTS` | `4`; 동시 데이터 요청 수, 1~32 |
| `LEARNUS_CACHE_ENABLED` | `1`; `0`이면 일반 TTL 캐시만 비활성화 |
| `LEARNUS_COURSE_CONTEXT_OVERRIDES` | 선택 사항; 강좌 ID별 `audienceTags` JSON |
| `LEARNUS_INTEGRATION` | `0`; 실계정 조회 테스트 활성화 여부 |
| `LEARNUS_DOWNLOAD_INTEGRATION` | `0`; 다운로드 통합 테스트 추가 활성화 여부 |

기능별 캐시는 별도로 유지됩니다. 상세 동작은 [캐시·요청 제어](docs/performance.md)를 참고하세요.

## 보안과 제한

Playwright로 실제 SSO 페이지에서 인증하고, 인증된 요청으로 LearnUs 데이터를 조회합니다. 세션과 쿠키는 메모리에 보관하며 CAPTCHA·다중 인증을 우회하지 않습니다.

- 과제 제출, 퀴즈 시작, 영상 재생·진도 변경, 알림 읽음·삭제는 수행하지 않습니다.
- 다운로드는 사용자가 요청한 등록 파일만 처리합니다. 지정 폴더에 저장하고 기존 파일을 덮어쓰지 않습니다.
- `ubfile`과 과제 첨부파일을 지원합니다. 일부 `resource`·`folder` 자료는 `FILE_SOURCE_RESEARCH_REQUIRED`를 반환할 수 있습니다.
- 사이트 HTML 변경 시 파서 수정이 필요할 수 있습니다. 시간표의 실제 조회 기능과 원격 MCP 연결은 제공하지 않습니다.

문제가 생기면 [보안 및 제한 사항](docs/security.md)을 확인하세요. [이슈](https://github.com/illlilililiililll/LearnUS_MCP/issues)를 남길 때는 인증정보·쿠키·개인 학습자료를 제외하세요.

## 개발 및 검증

```bash
npm run build
npm run lint
npm test
npm run test:browser
npm run test:inspector
```

Inspector UI는 `npm run inspector`로 실행합니다. 실계정 검증은 인증정보와 `LEARNUS_INTEGRATION=1`을 안전하게 전달한 환경에서 `npm run test:integration:release`로 실행하세요. 다운로드 검증에는 별도 활성화가 필요하며, 일반 CI에는 실계정 인증정보를 설정하지 않습니다.

구조와 검증의 세부 사항은 아래 문서에 정리되어 있습니다.

- [아키텍처](docs/architecture.md)
- [응답 크기·토큰 평가](docs/m9-token-evaluation.md) — `npm run evaluate:tokens`; 실제 LLM 토큰 수나 클라이언트의 도구 선택을 검증하는 측정은 아닙니다.
- [릴리스 체크리스트](docs/release-checklist.md)

## 라이선스

[MIT](LICENSE)