강원대 MCP 서버 (비공식)

강원대학교 춘천캠퍼스의 공개 정보를 조회하는 MCP(Model Context Protocol) 서버입니다. Claude Desktop, Cursor, Cline 등 MCP를 지원하는 클라이언트에서 자연어로 학사일정·학식·공지·버스 정보를 조회할 수 있습니다. 여러 tool을 조합해 "이번주 학식이랑 수강신청 공지 정리해줘" 같은 통합 질문에 한 번에 답하는 것을 목표로 합니다.

강원대는 공식 API가 없어, 이 서버가 사실상 유일한 프로그래매틱 접근점입니다.

⚠️ 비공식 프로젝트입니다. 강원대학교와 무관한 학생 제작 도구이며, 공개 웹페이지 및 공공데이터포털 API에서 정보를 수집합니다. 학교 사이트 구조가 바뀌면 일부 기능이 동작하지 않을 수 있습니다. 로그인이 필요한 정보(수강신청·성적·도서관 좌석 등)는 제공하지 않습니다.

설치

uv sync

로컬 클라이언트 등록 (Claude Desktop 예시)

claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "kangwon": {
      "command": "uv",
      "args": ["run", "--directory", "/절대경로/knu-mcp", "knu-mcp"],
      "env": { "KNU_BUS_API_KEY": "발급받은_공공데이터포털_인증키" }
    }
  }
}

KNU_BUS_API_KEY는 버스 도착 정보 tool에만 필요합니다(아래 참조). 없으면 버스 tool만 에러를 반환하고 나머지는 정상 동작합니다.

제공 도구

tool	설명
`get_academic_calendar(year=올해)`	학사일정(해당 연도 전체)
`get_cafeteria_menu(restaurant="백록관", week=0)`	학식 식단. restaurant: 백록관/천지관/두리, week: 0=이번주,1=다음주
`get_all_cafeteria_menus(week=0)`	3식당 학식 일괄
`search_notices(query, limit=10)`	학사공지(메인 홈페이지) 최근분에서 제목 검색
`get_shuttle_schedule()`	교내 순환버스(두리버스) 시간표. 정규학기만 운영
`get_next_shuttle()`	두리버스 현재 시각 기준 다음 출발
`get_bus_arrival(stop="강원대정문", route="300")`	시내버스 실시간 도착. stop: 강원대정문/후문/중앙도서관/백록관/학병원/남춘천역/춘천역/시외버스터미널

버스 API 키 (get_bus_arrival 전용)

시내버스 실시간 도착은 공공데이터포털 TAGO 버스도착정보 API를 사용합니다.

data.go.kr 로그인 → "국토교통부_(TAGO)_버스도착정보" 활용신청(개발계정, 즉시 승인)
발급된 일반 인증키(Decoding) 를 환경변수 KNU_BUS_API_KEY로 설정

키는 코드에 하드코딩하지 말고 환경변수로만 전달합니다.

전송 모드

기본은 로컬 클라이언트용 stdio. 원격(클라우드/PlayMCP) 배포 시 streamable-http:

KNU_MCP_TRANSPORT=streamable-http PORT=8000 uv run knu-mcp
# 엔드포인트: http://<host>:<PORT>/mcp

환경변수: KNU_MCP_TRANSPORT(stdio|sse|streamable-http, 기본 stdio), PORT(http 포트, 기본 8000).

Docker로 배포

원격 배포는 컨테이너 이미지로 하는 것이 간단합니다. streamable-http 전송이 기본으로 설정되어 있습니다.

docker build -t knu-mcp .
docker run -d --restart unless-stopped -p 8000:8000 \
  -e KNU_BUS_API_KEY=<공공데이터포털_인증키> knu-mcp
# 엔드포인트: http://<host>:8000/mcp

PORT 환경변수를 주입하면 그 포트로 뜹니다(클라우드 플랫폼이 자동 주입하는 경우 그대로 동작).
이미지에 HEALTHCHECK가 포함되어 있어 /mcp 핸드셰이크로 상태를 확인합니다.
API 키는 이미지에 넣지 말고 런타임에 -e로만 주입하세요.

프로젝트 구조

knu_mcp/
  server.py       # FastMCP 서버, tool 7개 등록
  http.py         # 공용 HTTP(get/post) + 10분 TTL 캐시
  academic.py     # 학사일정 (scheduleData 파싱)
  cafeteria.py    # 학식 (POST + 표 파싱)
  notices.py      # 공지 검색 (목록 파싱)
  shuttle.py      # 두리버스 시간표 / 다음 차
  bus.py          # 시내버스 실시간 도착 (TAGO API)
tests/            # 파서 단위 테스트 (fixture 기반, 네트워크 안 탐)
scripts/e2e_smoke.py  # 실 네트워크 E2E 스모크

각 소스 모듈은 하나의 데이터 소스만 담당하며 서로 의존하지 않습니다.

데이터 출처

학사일정·학식·공지·두리버스: www.kangwon.ac.kr 공개 페이지 (스크래핑)
시내버스 실시간 도착: 공공데이터포털 국토교통부 TAGO 버스도착정보 API

개발

uv run pytest              # 단위 테스트 (네트워크 안 탐, fixture 기반)
KNU_BUS_API_KEY=<키> uv run python scripts/e2e_smoke.py   # E2E 스모크 (실 네트워크 왕복)

새 기능은 파서 단위 테스트를 먼저 작성(TDD)하고, 외부 사이트/API 실패 시 예외 대신 {"error": ...}를 반환하는 규칙을 따릅니다.

라이선스

MIT

knu-mcp