명지전문대 MCP 서버

명지전문대 MCP 서버

AI 에이전트가 명지전문대 학교 데이터를 직접 조회할 수 있게 해주는 어댑터입니다.

챗봇을 새로 만든 것이 아닙니다. 학교가 챗봇을 만들면 그 챗봇 안에서만 쓸 수 있지만,MCP(Model Context Protocol)는 규격이라 Claude든 앞으로 나올 다른 AI 클라이언트든설정 몇 줄만 추가하면 그대로 붙습니다. 우리가 미리 만들어두지 않은 질문에도AI가 툴을 스스로 조합해 답합니다.

30초 설치

git clone https://github.com/4thIS/hachathon_mjc_mcp.git
cd hachathon_mjc_mcp
python -m venv .venv
.venv/Scripts/python -m pip install -r requirements.txt

AI 클라이언트 설정(.mcp.json 등)에 아래를 추가하고 클라이언트를 재시작합니다.경로는 clone한 위치에 맞게 바꿔주세요.

{
  "mcpServers": {
    "mjc": {
      "type": "stdio",
      "command": "C:\\경로\\hachathon_mjc_mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\경로\\hachathon_mjc_mcp\\server.py"]
    }
  }
}

끝입니다. 도서관 좌석·공지·학과 목록 조회는 별도 계정이나 API 키가 필요 없습니다.강좌 검색(search_courses)만 본인 학교 계정 로그인이 필요합니다 — 아래"로그인이 필요한 툴 사용법" 참고.

요구 사항: Python 3.10 이상 (mcp SDK 요구 사항 기준. 개발·검증 환경은 3.14).macOS/Linux는 command를 .venv/bin/python으로 바꿉니다.

이렇게 물어보세요

한 번에 답이 나오는 질문

• "지금 도서관 어디가 제일 한산해?"
• "이번 주 학사공지 알려줘"

AI가 툴을 엮어야 답이 나오는 질문 — 이게 이 프로젝트의 핵심입니다

• "방학 중에 학교 식당 언제 열어?"→ search_notices로 공지 목록을 받고, AI가 제목에서 해당 공지를 골라get_notice로 본문까지 이어서 조회합니다. 운영 기간·시간·영업 매장이 본문에들어 있어 AI가 정리해서 답합니다.
• "지금 학교 가려는데, 도서관 자리 있고 밥 먹을 데 있어?"→ 좌석 조회와 공지 조회가 함께 필요한, 우리가 미리 설계하지 않은 흐름입니다.툴 3개가 모두 호출됩니다.
• "채용공지 중에 이번 주 마감인 거 있어?"→ 목록의 제목·날짜를 훑고 필요하면 본문까지 확인합니다.
• "정보통신공학과 3학년 전공 수업 뭐 있어?"→ list_departments로 학과명을 코드로 바꾸고, 그 코드로 search_courses를호출합니다. 학과 내부 코드를 AI에게 미리 알려줄 필요가 없습니다(로그인 필요,아래 참고).

제공하는 툴

모든 툴은 읽기 전용입니다(read_only_hint=True). 학교 시스템에 무언가를쓰거나 바꾸는 동작은 없습니다.

로그인이 필요한 툴 사용법 (search_courses)

비밀번호를 저장하지 않으므로, 세션이 없거나 만료되면 별도 터미널에서 직접 로그인해야 합니다.

.venv/Scripts/python auth/login_helper.py sugang

학번·비밀번호를 입력하면(화면에 표시되지 않음) 세션만 로컬(%LOCALAPPDATA%\mjc-mcp\, 저장소 밖)에 저장합니다.비밀번호는 어디에도 저장하지 않으므로, 교내 SSO 비밀번호가 90일마다 강제로 바뀌어도다음에 헬퍼를 다시 실행할 때 그 시점의 비밀번호를 입력하면 됩니다. 세션이 만료되면search_courses가 자동으로 재로그인을 시도하지 않고 "헬퍼를 실행하세요"라는안내만 돌려줍니다.

설계 의도 — 왜 목록과 상세를 나눴는지, 왜 게시판 내부 코드를 AI에게 숨기는지,데모 중 서버가 죽어도 답이 나오게 한 캐시 폴백 구조 등 — 은docs/design.md 에 정리했습니다.

데이터 수집 원칙

• 대부분의 툴은 로그인 없이 누구나 볼 수 있는 공개 페이지만 조회합니다.search_courses만 예외로, 사용자 본인 계정 로그인이 필요합니다(아래 참고).
• robots.txt를 확인했습니다. www.mjc.ac.kr은 User-agent: * / Allow: /로전면 허용(2026-08-06). sugang.mjc.ac.kr은 robots.txt 자체가 없습니다(2026-08-07,명시적 허용도 거부도 아닌 상태).
• 동일 호스트에 대한 연속 요청 사이에 최소 1초 간격을 둡니다. 사람이 브라우저로접근하는 것보다 높은 빈도로 호출하지 않습니다.
• 프로젝트를 식별할 수 있는 User-Agent(MJC-MCP/0.1 (+저장소 주소))를 보냅니다.
• 조회 결과는 사용자의 AI 클라이언트에만 전달됩니다. 외부로 전송하거나재배포하지 않습니다. 로컬 캐시는 데모 중 장애 대비용이며 저장소에 포함되지 않습니다.
• 이 저장소에는 계정·비밀번호·세션 등 어떤 자격증명도 포함되어 있지 않습니다.
• search_courses(로그인 필요)는 사용자 본인 계정으로만 동작하며, 비밀번호는디스크에 저장하지 않고 세션 쿠키만 저장소 바깥에 저장합니다. 자동 재로그인은하지 않습니다.
• 실제 서비스로 운영하려면 학사팀 협의가 전제입니다.

한계 (정직하게)

• 게시판 페이지네이션을 지원하지 않습니다. 각 게시판의 첫 페이지 범위 안에서만조회됩니다. 오래된 공지는 찾지 못합니다.
• 본문이 이미지로 작성된 공지는 텍스트를 추출할 수 없습니다. 이 경우 그 사실을명시하는 안내 문구와 함께 본문 이미지 링크(body_images), 원문 페이지 주소(source_url), 첨부파일 목록을 돌려줍니다. 없는 내용을 지어내지 않고 사람이직접 보게 넘기는 것이 목적입니다.
• 본문이 4000자를 넘으면 잘립니다. 잘린 경우 응답의 truncated 필드로 그 사실을알려, AI가 잘린 내용을 전체인 것처럼 인용하지 않도록 합니다.
• 학교 사이트 구조가 바뀌면 파싱이 깨집니다. 다만 파싱 계층을 분리해 두어해당 툴 파일 하나만 고치면 되도록 설계했습니다.
• search_courses는 실시간 신청 인원을 제공하지 않습니다. sugang 자체가이 값을 목록 응답에 포함하지 않고 별도 새로고침을 요구합니다 — 정원(capacity)까지만제공합니다.
• search_courses는 사용자가 별도 터미널에서 로그인 헬퍼를 먼저 실행해야동작합니다. 세션이 만료되면 자동으로 재로그인하지 않고 안내 메시지만 돌려줍니다.
• E-class(cyber.mjc.ac.kr) 등 다른 로그인 필요 시스템은 범위 밖입니다. 자격증명취급 원칙은 docs/design.md 8장에 정리했습니다.
• 도서관 좌석 API는 비표준 포트를 쓰기 때문에 일부 제한된 네트워크(게스트 Wi-Fi 등)에서는 도달하지 못할 수 있습니다.

개발

.venv/Scripts/python -m pytest tests/ -v

파서 테스트는 실제 응답을 bytes 원본으로 저장한 fixture를 사용합니다.텍스트로 저장하면 인코딩 버그를 감추기 때문입니다.

server.py        진입점. 각 툴 모듈의 register(mcp) 호출만 한다
common/          http · parse · cache · errors · models · session (공통 레이어)
auth/            login_helper.py — 독립 CLI, 사용자가 직접 실행
tools/           library_seats.py, notices.py, departments.py, course_search.py
tests/fixtures/  실제 응답 원본
docs/design.md   설계 문서

팀

2026년 명지전문대 캡스톤 경진대회 출품작.