POSTECH PLMS MCP

POSTECH PLMS를 자연어로 조회하는 개인용 읽기 전용 MCP 서버입니다. Python 3.11+ / stdio / OAuth Streamable HTTP를 지원합니다. POSTECH 공식 서비스가 아니며, 학생마다 자기 계정으로 설치·운영합니다.

할 수 있는 일

• 현재/지난 수강 과목, 주별 강의자료, 예정·제한된 활동 조회

• 과제 지시사항, 마감, 제출·채점 상태, 첨부파일 읽기

• 온라인 강의의 정상 출석 마감 / 지각 인정 마감 / 강사 본문 지시 구분

• 온라인 학습 진도와 오프라인 전자출결 조회 — 미래·공란·미처리는 출결로 단정하지 않음

• 공지사항 목록·본문·페이지 이동, 과목 내 검색

• 공식 실라버스·추가 계획서 후보, 평가비율·시험·출석·표절 규칙의 원문 근거 추출 및 비교

• 성적부 조회, 주간 할 일, 기한 지난 미제출 과제, ICS 일정 내보내기

• 명시적 조회 간 변경사항 비교(로컬 암호화 기준점)

• PDF, DOCX, PPTX, XLSX, HWP, HWPX, HTML, 텍스트 첨부파일과 페이지/슬라이드/셀 위치

• ZIP 첨부의 안전한 목록과 선택한 내부 문서·소스 파일 읽기

과제 제출, 퀴즈 응시, 쪽지 전송, 영상 재생/시청기록 조작, 출석 변경은 제공하지 않습니다. 스캔 이미지 OCR, 외부 사이트 자동 탐색, 음성/영상 전사는 포함하지 않습니다. 첨부파일의 수식·그림·표 해석이 텍스트만으로 불완전할 수 있으며 추출 경고를 반환합니다.

Related MCP server: Gradescop

빠른 시작: 내 컴퓨터에 연결

Python 3.11 이상과 Git이 필요합니다. 다음은 macOS/Linux 셸 기준이며, 마지막 두 명령은 Codex CLI가 설치된 경우 사용합니다.

git clone https://github.com/junnnnnw00/postech-plms-mcp.git
cd postech-plms-mcp
python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade 'pip>=26.2.1' 'setuptools>=83.0.0'
python -m pip install -e .
plms-mcp login --method sso
plms-mcp doctor
codex mcp add postech-plms -- "$PWD/.venv/bin/plms-mcp" serve --transport stdio
codex mcp list

새 Codex 대화에서 “PLMS 연결 상태를 확인하고 이번 학기 내 과목을 보여 줘”라고 질문합니다. CLI가 없으면 앱 설정의 MCP 등록 절차를 사용합니다. 다른 MCP 클라이언트에서는 설치된 plms-mcp의 절대 경로와 인자 serve --transport stdio를 등록합니다. Windows에서는 py -3 -m venv .venv로 환경을 만들고 .\.venv\Scripts\Activate.ps1로 활성화한 뒤 plms-mcp.exe의 절대 경로를 사용합니다.

아이디와 비밀번호는 실행 중 입력하며 비밀번호는 표시하지 않습니다. 기본은 세션 쿠키만 저장합니다. 자동 재인증이 필요하면 plms-mcp login --method sso --save-password로 로그인하여 비밀번호의 로컬 암호화 저장을 선택할 수 있습니다. 실패한 자동 로그인은 명시적 재로그인 전까지 중단됩니다. PLMS_DATA_DIR로 저장 위치를 지정할 수 있습니다. 키와 암호문을 함께 읽을 수 있는 컴퓨터 관리자는 복호화할 수 있으므로 상태 폴더를 공유하지 마세요.

SSO가 StonePASS나 개인정보 선택을 요구하면 브라우저에서 완료하고 plms-mcp import-cookies /private/path/cookies.json으로 PLMS 도메인 쿠키만 가져옵니다. 학교 인증 절차를 우회하지 않습니다. plms-mcp logout은 이 인스턴스의 로컬 연결 정보를 삭제합니다.

데스크톱 / 모바일

• 로컬 데스크톱: MCP 클라이언트에 .venv/bin/plms-mcp serve --transport stdio 등록.

• 모바일 및 웹: HTTPS 도메인에 서버를 운영하고 OAuth MCP를 개인 plugin으로 등록합니다. 연결 비밀은 PLMS 비밀번호와 다른 임의의 20자 이상 값입니다.

• 모바일 Remote: 연결된 내 컴퓨터에서 로컬 MCP를 실행하는 경로입니다. 최초 기기 연결과 컴퓨터의 전원·네트워크 유지가 필요합니다.

• 다른 학생: 코드를 설치해 자기 인스턴스·자기 계정을 연결합니다. 운영자의 연결 비밀이나 승인된 토큰을 공유하면 운영자의 학업 자료에 접근하게 되므로 공유하지 않습니다.

export PLMS_ISSUER_URL=https://your-personal-host.example
# PLMS_CONNECT_PASSWORD는 비밀 관리자/보호된 환경 파일에 설정
plms-mcp serve --transport http --host 127.0.0.1 --port 8765

연결 주소는 https://your-personal-host.example/mcp. Docker Compose와 HTTPS 터널 예제는 배포 문서, ChatGPT/Codex/모바일 연결은 클라이언트 문서를 참고하세요. 공개 GitHub 저장소만으로 실행 서버나 모바일 연결이 생기지는 않습니다.

HTTP 서비스와 OAuth 동작은 검증 기록의 범위에서 확인했습니다. ChatGPT UI의 최종 승인과 휴대전화 실제 호출은 별도의 확인 단계입니다.

질문 예시

• “이번 주 미제출 과제와 안 들은 온라인 강의 마감을 알려줘.”

• “과제 PDF를 읽고 제출물과 제약조건을 정리해줘. 파일 어디에 나오는지도 알려줘.”

• “온라인 강의 정상 출석 마감과 지각 인정 마감이 달라?”

• “이 과목 출결을 실라버스 규칙과 비교해줘. 미처리 항목도 구분해줘.”

• “최근 공지에서 휴강이나 시험 변경이 있었어?”

• “실라버스 평가비율과 성적부의 현재 점수를 비교해줘.”

응답의 근거와 한계

성공한 조회 결과는 출처 URL, 결과 구성 시각, 시간대, 경고를 포함합니다. 페이지 캐시는 최대 90초 재사용할 수 있습니다. 한국시간 기준이며 날짜만 명시된 항목에 임의로 23:59를 붙이지 않습니다. 원문에서 확정할 수 없는 출석 환산, 예외, 최종 성적은 unknown으로 남깁니다. 검색은 범위가 정해져 있으므로 공지 본문·다음 페이지·첨부파일은 추가 조회가 필요합니다. 실라버스보다 나중에 나온 공지가 있을 수 있어 자동 비교를 공식 판정으로 사용하지 않습니다.

세션·저장 비밀번호·변경 기준점은 Fernet 암호문이며 파일은 0600, 상태 디렉터리는 0700입니다. HTTP는 OAuth 2.1 흐름(S256 PKCE, 짧은 단회 코드, 토큰 회전/폐기, resource 검증)을 적용합니다. 단일 사용자·단일 프로세스 운영을 전제로 하며 다중 학생 공용 서비스는 구현하지 않았습니다.

개발 및 검증

python -m pip install -e '.[dev]'
pytest -q
ruff check src tests
python -m build
pip-audit

테스트는 합성 데이터만 사용합니다. 실제 로그인 및 학교 자료는 Git에 넣지 않습니다. 라이브 검증 범위와 미완료 연결 항목은 검증 기록에 구분하여 기록합니다. 보안 모델과 운영상 주의점은 SECURITY.md를 참고하세요.

• 도구 19개와 입력·반환·예제

• 모듈 구조와 데이터 흐름

라이선스

MIT. 학교 강의자료와 타인의 저작권은 이 코드 라이선스에 포함되지 않습니다.