hs-mcp 0.1.0

MCP server for Hansung University student services, starting with facility reservation.

Hs-MCP

한성대학교 학생 서비스용 로컬 MCP 서버입니다. MVP는 시설예약 기능부터 제공합니다.

이 프로젝트는 한성대학교 공식 서비스가 아닙니다.

MVP 범위

지원 예약 영역:

• coding_lounge: 코딩라운지 세미나실 101호~113호
• sangsang_park_plus: 상상파크 플러스 소모임실 6개
  • Critical Thinking, Creativity, Convergence, Communication, Collaboration, Challenge
  • 1회 최대 3시간 제한
• sangsang_base: 상상베이스 세미나실/IB 공간
  • 세미나실(IB111), IB101~IB108

지원 기능:

• 예약 공간 목록 조회
• 특정 날짜/시간 예약 가능 여부 확인
• 가능한 대체 공간 추천
• 실제 예약 신청(명시 확인 필요)
• 내 예약 목록 조회

보안/인증 원칙

• 학생 개인 PC에서 로컬 MCP 서버로 실행합니다.
• 학교 계정 정보는 개발자 서버로 전송하지 않습니다.
• 비밀번호는 저장하지 않습니다.
• 로그인 후 발급된 세션 쿠키만 OS 보안 저장소(macOS Keychain, Windows Credential Manager, Linux Secret Service 등)에 저장합니다.
• 언제든 hs-mcp logout으로 저장된 세션을 삭제할 수 있습니다.
• 실제 예약은 기본값 dry_run=true이며, dry_run=false와 confirm=true가 모두 있어야 실행됩니다.
• 실제 예약 후 내 예약 목록에서 신청 내역을 확인하지 못하면 성공으로 처리하지 않습니다.
• 내 예약 목록의 이름/학번은 기본적으로 마스킹되며, 필요한 경우에만 include_personal_info=true로 명시 조회합니다.
• 날짜는 YYYY-MM-DD, 시간은 정각 HH:00 형식만 허용합니다.

설치/개발

python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
pytest

CLI

hs-mcp login    # 학교 계정 로그인, 세션만 OS 보안 저장소에 저장
hs-mcp status   # 저장된 세션 확인
hs-mcp logout   # 저장된 세션 삭제
hs-mcp doctor   # 로컬 환경 점검

MCP 클라이언트 설정 예시

{
  "mcpServers": {
    "hansung_facility": {
      "command": "hs-mcp-server",
      "args": []
    }
  }
}

제공 도구

모든 도구는 선택 파라미터 area를 지원합니다. 기본값은 coding_lounge입니다.

지원 area 값:

• coding_lounge
• sangsang_park_plus
• sangsang_base

예시 요청:

facility_list_spaces(area="sangsang_park_plus")
facility_check_availability(area="sangsang_base", space="IB101", date="2026-05-22", start_time="13:00", end_time="15:00")
facility_create_reservation(area="sangsang_park_plus", space="소모임실 Creativity", date="2026-05-22", start_time="13:00", end_time="15:00", dry_run=true)

도구 목록:

• facility_status
• facility_list_spaces
• facility_check_availability
• facility_find_alternatives
• facility_create_reservation
• facility_list_my_reservations — 기본적으로 개인정보 마스킹, 필요 시 include_personal_info=true

현재 구현 상태

현재 버전은 MVP 스캐폴딩입니다. 핵심 도메인 로직과 MCP/CLI 뼈대, 안전장치, 테스트를 포함합니다. 실제 학교 사이트 연동은 HTML/엔드포인트 변경 가능성이 있으므로 통합 테스트를 통해 점진적으로 보강해야 합니다.