plato-mcp

부산대학교(PNU)의 무들(Moodle) 기반 LMS인 PLATO(https://plato.pusan.ac.kr/)를 위한 비공식 MCP(Model Context Protocol) 서버입니다. Claude 같은 AI 어시스턴트가 여러분을 대신해 PLATO에 로그인하지 않고도, 여러분이 이미 접근 권한을 가진 강좌 자료·공지·과제·성적·Q&A를 조회·작성·다운로드할 수 있게 해 줍니다.

아직 개발 중입니다. 전체 구현 계획은 PLAN.md를, 현재 진행 상황은 GitHub Issues / Project 보드를 참고하세요.

이 서버는 새로운 권한을 부여하지 않습니다. 여러분의 PLATO 학번·비밀번호로 인증하며, 브라우저로 직접 열람할 때 볼 수 있는 것만 볼 수 있습니다 — 다만 그 내용이 AI와의 대화로 흘러 들어간다는 차이가 있습니다. 시작하기 전에 아래 면책조항과 개인정보 안내를 반드시 읽어 주세요.

시작하기

이 프로젝트는 두 부류의 독자를 대상으로 합니다 — 그냥 써보고 싶은 일반 사용자와 코드를 고치거나 기여하고 싶은 개발자. 아래에서 본인에게 맞는 쪽을 고르세요.

일반 사용자 — 그냥 써보고 싶다면

코드를 내려받거나 서버를 직접 실행할 필요가 없습니다. 이 서버는 공식 MCP Registry에 io.github.jin-1119/plato-mcp로 등록되어 있고, 실제 주소는 https://plato-mcp.onrender.com/mcp(Streamable HTTP)입니다.

Smithery 마켓플레이스는 더 이상 쓰지 않습니다 — Smithery가 신규 외부 서버 등록을 막고 2026-10-31에 전체 서비스를 종료하면서, 공식 레지스트리로 옮겼습니다. 자세한 배경은 docs/smithery_deployment_model.md를 참고하세요.

1. 사용 중인 MCP 클라이언트에서 아래 주소를 원격(remote) MCP 서버로 추가합니다:
   • Claude.ai / Claude Desktop: 설정 → Connectors → Add custom connector → URL에 https://plato-mcp.onrender.com/mcp 입력.
   • Claude Code: claude mcp add --transport http plato-mcp https://plato-mcp.onrender.com/mcp
   • MCP Registry를 직접 검색할 수 있는 클라이언트라면 io.github.jin-1119/plato-mcp로 찾아도 됩니다.
2. 연결 시 PLATO 학번과 비밀번호를 (클라이언트가 지원하는 경우) 커넥터 설정 값으로, 아니면 헤더/쿼리 파라미터(pnu_id, pnu_password)로 입력합니다. 이 값은 서버 디스크에 저장되지 않으며, 요청을 처리하는 동안만 메모리에 존재합니다 — 자세한 내용은 SECURITY.md를 확인하세요.
3. 연결되면 AI 어시스턴트에게 자연어로 요청하면 됩니다. 예:
   • "이번 주에 제출해야 할 과제가 뭐가 있어?"
   • "이번 학기 성적 알려줘"
   • "OO 과목 3주차 강의자료 다운로드해줘"
   • "OO 과목 공지사항 최근 것부터 보여줘"

시작하기 전에 반드시 아래 면책조항과 개인정보 안내를 읽어 주세요. 특히 과제 제출·Q&A 등록처럼 되돌릴 수 없는 동작(✏️ 표시)은 실행 전 미리보기 확인을 거치도록 되어 있습니다.

직접 배포해 보고 싶다면 docs/smithery_publish_guide.md의 비전공자용 단계별 가이드를 참고하세요.

개발자 — 코드를 고치거나 기여하고 싶다면

버그 수정, 새 도구 추가, 문서 개선 등 기여를 환영합니다. 이슈/브랜치/PR을 이 저장소가 실제로 어떻게 운영하는지는 CONTRIBUTING.md에 정리되어 있습니다 — PR을 보내기 전에 먼저 읽어 주세요. 로컬 개발 환경 설정은 바로 아래 개발 환경 설정 섹션을 참고하세요.

제공하는 도구 (MCP Tools)

공식 Moodle webservice API로 동작하는 도구와, ubboard(공지/Q&A) HTML을 본인 세션으로 스크레이핑하는 도구로 나뉩니다. 쓰기 도구(✏️)는 실행 전 확인 절차를 거칩니다 (자세한 내용은 docs/write_confirmation_pattern.md). PLATO가 실제로 제공하는 439개 Moodle API 함수 전체를 이 MCP가 어떻게 다뤘는지(구현/중복/ 비활성화/권한없음/미구현 사유)는 docs/moodle_api_coverage.md 참고.

강좌 / 과제 / 성적 / 일정 / 쪽지 — 공식 API

• list_courses — 수강 중인 강좌 목록
• get_course_contents — 강좌 콘텐츠(주차별 자료 등)
• get_course_updates_since — 강좌 변경사항 감지 (표준 Moodle 모듈만 — ubfile/ubboard/vod는 변경감지 콜백 미구현, 포함 안 됨)
• get_course_module — cmid로 모듈 직접 조회
• search_courses — PLATO 전체 강좌 카탈로그 검색 (수강 중인 강좌만이 아님)
• get_recent_courses — 최근 접속한 강좌 목록
• get_recent_items — 최근 열어본 강의자료/활동 목록 (강좌 단위가 아닌 모듈 단위)
• get_starred_courses — 즐겨찾기한 강좌 목록
• list_video_conferences — 화상강의(BigBlueButton) 조회 (참여 기능은 미지원, 실사용 사례 없는 forward-looking 기능)
• list_lessons — Lesson 활동 조회 (응시 기능은 미지원, 실사용 사례 없음)
• list_workshops — Workshop(상호평가) 활동 조회 (제출/평가 기능은 미지원, 실사용 사례 없음)
• list_feedbacks — Feedback(설문) 활동 조회 (응답 기능은 미지원, 실사용 사례 없음)
• list_choices / list_surveys — Choice(투표)/Survey 활동 조회 (응답 기능은 미지원, 실사용 사례 없음)
• list_scorms / list_h5p_activities — SCORM/H5P 패키지 콘텐츠 조회 (실행/추적 기능은 미지원, 실사용 사례 없음)
• list_glossaries — Glossary(용어집) 조회 (항목 읽기/쓰기는 미지원, 실사용 사례 없음)
• list_database_activities — Database 활동 조회 (항목 읽기/쓰기는 미지원, 실사용 사례 없음)
• list_wikis / list_chats — Wiki/실시간 채팅 활동 조회 (읽기/쓰기는 미지원, 실사용 사례 없음)
• get_user_profile — 사용자 프로필 조회 (같은 강좌 수강생만, 전체 검색 아님)
• get_private_files_info / add_private_file ✏️ — 개인파일 영역 조회/업로드 (⚠️ 삭제 도구 없음, 실제 삭제는 PLATO 웹에서)
• get_user_preferences — 사용자 환경설정 조회 (대부분 내부 UI 상태값)
• get_my_course_groups — 강좌 내 소속 그룹 조회
• get_enrolled_users — 강좌 수강생 명단 조회 (PLATO 참가자 목록과 동일 정보)
• list_assignments — 과제 목록
• get_assignment_detail — 과제 상세
• submit_assignment ✏️ — 과제 제출
• remove_submission ✏️ — 과제 제출 철회 (⚠️ 실제 실행 경로는 아직 PLATO에서 invalidparameter 오류 발생, 미리보기만 동작 확인됨)
• get_grades — 성적 조회
• get_grades_access_info — 이 계정의 성적 조회 권한 확인 (전체 열람 권한 등)
• list_calendar_events — 캘린더 일정
• get_calendar_access_info — 캘린더 관리 권한 확인
• create_calendar_event / delete_calendar_event ✏️ — 개인 캘린더 일정 생성/삭제 (본인 소유 개인 일정만 가능, 강좌/그룹 일정은 불가)
• get_unread_messages / get_unread_notification_count — 안 읽은 쪽지 (⚠️ PLATO는 1:1 메시징/대화 기능이 사이트 전체에서 비활성화되어 있음 — 알림만 동작)
• get_course_completion_status — 강좌 단위 이수 현황 (이수 기준이 설정된 강좌만)
• get_activity_completion_status — 강좌 내 활동/자료별 이수 현황 (동영상 강의 시청률 포함)
• get_upcoming_action_events — 마감 임박한 할 일(과제/시청 기한 등) 통합 조회
• get_courses_by_timeline — 진행 중/예정/종료 강좌 필터링
• get_grades_overview — 전체 강좌 종합 성적 한 번에 조회
• list_quizzes / get_quiz_attempts / get_quiz_best_grade — 퀴즈 조회
• get_quiz_access_information / get_quiz_required_qtypes / get_quiz_feedback_for_grade / get_quiz_combined_review_options — 퀴즈 응시 전 확인용 조회 (⚠️ 응답 형태 미검증 — 실제 퀴즈가 있는 강좌가 없어서 파라미터만 라이브로 확인됨)
• start_quiz_attempt / get_quiz_attempt_data / save_quiz_attempt_responses / process_quiz_attempt / get_quiz_attempt_summary / get_quiz_attempt_review ✏️ — 퀴즈 응시 흐름 (⚠️ 전체 미검증, 실제 퀴즈로 끝까지 테스트된 적 없음 — 사용 전 반드시 재검증 권장)
• list_forums / get_forum_discussions / get_discussion_posts — 표준 Moodle 포럼 조회 (PLATO 자체 공지/Q&A인 ubboard와는 다른 모듈)
• add_discussion / add_discussion_post ✏️ — 포럼 글쓰기/답글

공지사항 / Q&A(ubboard) — 로그인 세션 스크레이핑

• list_notices — 공지사항 목록
• get_notice_detail — 공지사항 상세
• list_qna — Q&A 게시글 목록
• get_qna_detail — Q&A 게시글 상세
• post_qna_question ✏️ — Q&A 질문 등록

파일

• download_course_file — 강좌 첨부파일 다운로드 (원격 실행 시 링크 반환, 위 개인정보 안내 참고)

아키텍처

src/plato_mcp/
├── server.py            # FastMCP 앱, tool 등록 진입점
├── config.py            # Smithery config 스키마 (pnu_id, pnu_password, ...)
├── auth.py              # 세션별 wstoken + requests.Session 쿠키 in-memory 캐시
├── moodle_client.py     # webservice/rest/server.php 범용 REST 호출 래퍼
├── ubboard/
│   ├── scraper.py       # list_notices/get_notice_detail/list_qna/get_qna_detail
│   ├── writer.py        # post_qna_question (sesskey 처리)
│   └── parser.py        # BeautifulSoup 파싱
├── files.py             # download_course_file
├── tools/                # MCP tool 등록 (courses/assignments/grades/calendar/messages/notices_qna/downloads)
├── models.py              # pydantic 응답 스키마
├── errors.py               # 타입 예외 (AuthError, MoodleAPIError, ScrapeError, RateLimitError)
└── security.py              # 로그/자격증명 마스킹, rate limiting

인증 흐름: 세션 시작 시 login/token.php로 wstoken을 발급받아 메모리에 캐시합니다. ubboard(공지/Q&A) 접근 시에만 추가로 쿠키 로그인을 수행해 sesskey를 스크레이핑합니다. 어떤 경우도 디스크에 저장하지 않습니다. 배경이 된 사전 조사는 PLATO_MCP_사전조사.md, 전체 로드맵은 PLAN.md를 참고하세요.

개발 환경 설정 (기여자용)

아래는 이 프로젝트의 코드를 수정/기여하려는 개발자용 명령어입니다. PLATO를 그냥 써보고 싶은 일반 사용자는 몰라도 되는 내용이며, 실행해도 PLATO 계정에 연결되지 않습니다 — 코드와 테스트 도구(pytest, ruff 등)를 내 컴퓨터에 설치할 뿐입니다.

사전 요건

• Python 3.11+
• 로컬 개발/테스트에는 실제 PLATO 계정이 필요 없습니다 (테스트는 mock 기반)

pip install -e ".[dev]"
pytest

면책조항

• 부산대학교(PNU) 또는 PLATO/무들 플랫폼과 아무런 제휴 관계가 없으며, 이들의 승인을 받지 않았습니다. 이 프로젝트는 여러분이 이미 브라우저로 하고 있는 것과 동일한 PLATO 계정 접근을 자동화하는 독립적인 커뮤니티 프로젝트입니다 — 새로운 권한을 부여하지 않으며 PNU를 대신해 어떠한 행위도 하지 않습니다.
• 모든 사용은 본인 책임이며, PNU의 이용약관을 준수해야 합니다. 특히 공지사항/Q&A 게시판(ubboard)은 공식 API가 없어 로그인된 본인 세션으로 렌더링된 HTML을 직접 스크레이핑하는데, 이 사이트의 robots.txt는 Disallow: /를 명시하고 있습니다. 이 지침은 익명 크롤러를 겨냥한 것이며 인증된 사용자 본인의 열람 행위를 겨냥한 것은 아니지만, 그래도 스크레이핑인 것은 사실입니다. 이 서버를 계정에 연결하기 전에 본인 계정에 대한 PNU의 acceptable-use 정책에 부합하는지 확인할 책임은 사용자에게 있습니다. 권장 사용 방식은 개인적·저빈도 사용이며, 사이트 전체를 대상으로 한 자동 대량 스크레이핑은 권장하지 않습니다.
• PLATO 로그인 정보는 이 서버에 의해 디스크에 영구 저장되지 않습니다. 무엇이, 얼마나 오래 저장/보관되는지 정확한 내용은 SECURITY.md를 참고하세요.
• 이 프로젝트는 제3자에 의한 독립적인 보안 감사를 받지 않았습니다. 개발 과정에서 자체적으로 여러 자격증명 처리·오남용 방지 이슈를 발견하고 수정했습니다 (docs/security_audit.md, docs/abuse_prevention_review.md 참고) — 하지만 스스로 찾아 고친 것은 외부 감사와 같은 수준의 보증이 아닙니다.

개인정보 안내

이 서버는 강좌 콘텐츠를 그대로 전달합니다 — Q&A 게시판의 경우 다른 학생들의 이름과 게시글도 포함됩니다. 이는 본인 계정이 PLATO를 통해 이미 정당하게 접근할 수 있는 내용이며, 이 도구가 새로운 접근 권한을 부여하는 것은 아닙니다. 브라우저로 PLATO를 직접 열람할 때와 다른 점은, 이 내용이 AI 어시스턴트와 나누는 대화의 일부가 된다는 것입니다. 즉 도구 출력으로서 해당 AI/LLM 제공업체(예: Anthropic)에 전송됩니다. 강좌 Q&A 게시판을 대상으로 폭넓은 질문을 하기 전에 이 점을 유념하세요.

전체 검토 내용과 알려진 미해결 사항(PLATO가 Q&A 게시글의 "비공개/강사 전용" 플래그를 서버 측에서 실제로 강제하는지 — 즉 이 도구가 그런 게시글을 애초에 볼 수 없는지 — 여부는 아직 실증적으로 검증되지 않았습니다)은 docs/pii_review.md에서 확인할 수 있습니다.

원격으로 실행할 경우 (로컬 Claude Code/Desktop이 아니라 Claude.ai 커넥터 등을 통해 실행하는 경우), 인라인 전송 크기 제한을 초과하는 큰 파일에 대해 download_course_file은 파일 자체가 아니라 다운로드 링크를 반환하며, 이 링크에는 살아있는 PLATO 액세스 토큰이 포함되어 있습니다. 이 토큰은 해당 파일 하나에만 한정되지 않습니다 — 실제로 확인해 본 결과 본인 계정에 대한 임의의 PLATO API 호출을 인증하는 데 사용할 수 있었습니다. 이 링크나 이 링크가 포함된 대화 기록을 공유하는 것은 파일 하나를 공유하는 것이 아니라 계정에 대한 활성 자격증명을 공유하는 것과 같습니다. 자세한 내용은 SECURITY.md와 docs/smithery_deployment_model.md를 참고하세요.

• Lint: ruff check .
• 이슈/보드 운영 방식은 PLAN.md를 참고하세요.
• 기여 방법은 CONTRIBUTING.md를 참고하세요.

라이선스

AGPL-3.0입니다. 이 서버(또는 수정본)를 네트워크 서비스로 돌려 다른 사람에게 제공하는 경우, AGPL에 따라 해당 소스코드도 함께 공개해야 합니다.