Metadata-Version: 2.4
Name: hs-mcp
Version: 0.1.0
Summary: MCP server for Hansung University student services, starting with facility reservation.
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.0.0
Requires-Dist: keyring>=25.0.0
Requires-Dist: mcp>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: respx>=0.21.0; extra == "dev"

# 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` 형식만 허용합니다.

## 설치/개발

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

## CLI

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

## MCP 클라이언트 설정 예시

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

## 제공 도구

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

지원 `area` 값:

- `coding_lounge`
- `sangsang_park_plus`
- `sangsang_base`

예시 요청:

```text
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/엔드포인트 변경 가능성이 있으므로 통합 테스트를 통해 점진적으로 보강해야 합니다.
