UNC LibCal MCP

Claude, Cursor, Codex 또는 모든 MCP 클라이언트에서 UNC Davis Library 스터디 공간을 예약하기 위한 MCP 서버 — 선택적으로 Apple Calendar 통합 지원.

유효한 Onyen을 가진 UNC 학생, 교수진, 직원을 위해 제작되었습니다. UNC Libraries와 제휴하거나 보증하지 않습니다.

기능

에이전트에게 요청하세요:

내일 오후 2시에 Davis 큐브를 예약해 줘

서버는 다음을 수행합니다:

1. LibCal 가용성 확인 (공개 API — 로그인 불필요)

2. 순위가 매겨진 옵션 제안(libcal_suggest) 또는 확인한 슬롯 예약(libcal_book)

3. 브라우저 세션에서 예약 완료 (Playwright + 저장된 Onyen 로그인)

4. 선택적으로 Apple Calendar에 이벤트 추가 (macOS 전용)

Related MCP server: @aiwerk/mcp-server-cal

요구 사항

• Node.js 20+

• UNC Onyen (예약용; 가용성 확인은 로그인 없이 가능)

• Apple Calendar 동기화용 macOS (선택 사항)

• Chromium (Playwright를 통해 자동 설치)

빠른 시작

1. 클론 및 설치

git clone https://github.com/Thespaceblade/unc-libcal-mcp.git
cd unc-libcal-mcp
npm install
npx playwright install chromium
npm run build
npm test

2. LibCal 로그인

npm run login

브라우저가 열리면 Onyen으로 로그인하고(메시지가 표시되면 + Duo), Davis LibCal 페이지가 로드되면 터미널에서 Enter를 누르세요.

세션은 ~/.unc-libcal/storage-state.json에 저장됩니다 (이 파일은 절대 커밋하지 마세요).

3. 구성 (선택 사항)

첫 실행 시 ~/.unc-libcal/config.json이 기본값으로 생성됩니다:

{
  "defaultCategory": "davis-cubes",
  "calendarName": "Calendar",
  "preferSameDay": true,
  "minLeadMinutes": 30,
  "searchHorizonDays": 7,
  "bookingPurpose": "Study session"
}

에이전트에게 libcal_list_calendars 실행을 요청한 다음 calendarName을 원하는 Apple Calendar로 설정하세요. macOS에서 메시지가 표시되면 자동화 권한을 허용하세요 (Terminal 또는 Cursor → Calendar).

4. MCP 클라이언트 연결

모든 클라이언트는 dist/index.js의 절대 경로가 필요합니다. 리포지토리 내부에서:

pwd   # e.g. /Users/you/projects/unc-libcal-mcp
# Use: <that-path>/dist/index.js

또는 한 줄로:

node -e "const p=require('path'); console.log(p.join(process.cwd(),'dist/index.js'))"

아래의 모든 클라이언트는 동일한 stdio 서버를 실행합니다:

{
  "command": "node",
  "args": ["/absolute/path/to/unc-libcal-mcp/dist/index.js"]
}

구성 편집 후 클라이언트를 다시 시작하세요.

Claude Desktop

파일: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "unc-libcal": {
      "command": "node",
      "args": ["/absolute/path/to/unc-libcal-mcp/dist/index.js"]
    }
  }
}

Claude Desktop을 완전히 종료하고 다시 여세요.

Cursor

옵션 A — UI: Settings → MCP → Add server → 위의 JSON 블록을 붙여넣으세요.

옵션 B — 프로젝트 파일: 이 리포지토리의 .cursor/mcp.json (팀원과 공유하기 좋음):

{
  "mcpServers": {
    "unc-libcal": {
      "command": "node",
      "args": ["./dist/index.js"]
    }
  }
}

./dist/index.js는 Cursor의 MCP cwd가 프로젝트 루트인 경우에만 사용하고, 그렇지 않으면 절대 경로를 사용하세요.

OpenAI Codex (CLI)

Codex는 JSON이 아닌 TOML을 사용합니다. 파일: ~/.codex/config.toml (또는 신뢰할 수 있는 프로젝트의 .codex/config.toml).

[mcp_servers.unc-libcal]
command = "node"
args = ["/absolute/path/to/unc-libcal-mcp/dist/index.js"]

또는 CLI를 통해:

codex mcp add unc-libcal -- node /absolute/path/to/unc-libcal-mcp/dist/index.js
codex mcp list   # verify it appears

서버가 표시되지 않으면 프로젝트 로컬 .codex/config.toml을 사용할 때 프로젝트가 신뢰됨(trusted) 상태인지 확인하세요 (리포지토리에서 codex trust).

Claude Code (CLI)

파일: ~/.claude.json (전역) 또는 프로젝트의 .mcp.json:

{
  "mcpServers": {
    "unc-libcal": {
      "command": "node",
      "args": ["/absolute/path/to/unc-libcal-mcp/dist/index.js"]
    }
  }
}

Claude Code 세션에서 /mcp를 실행하여 도구가 로드되었는지 확인하세요.

기타 MCP 클라이언트

stdio MCP를 지원하는 모든 클라이언트는 동일한 command + args를 사용할 수 있습니다. npm run build 후 dist/index.js를 가리키세요.

5. 작동 확인

에이전트에서 다음을 시도하세요:

Check libcal auth status

그런 다음:

Suggest Davis cubes for 2 hours tomorrow

서버가 연결되면 libcal_auth_status, libcal_suggest, libcal_check_availability, libcal_book, libcal_list_calendars를 사용할 수 있습니다.

MCP 도구

예약 워크플로우

1. 구체적인 조건이 없는 요청("큐브 예약", "최대 시간")의 경우 → 에이전트가 먼저 **libcal_suggest**를 호출

2. 에이전트가 번호가 매겨진 옵션을 표시하면 하나를 선택

3. 에이전트가 user_confirmed: true와 선택한 날짜/시간으로 **libcal_book**을 호출

libcal_book은 명시적 확인 없이는 실행되지 않습니다.

공간 카테고리

예시 프롬프트

Book me a study room for as long as possible
→ libcal_suggest shows TODAY vs later; you pick; then libcal_book

Book me a Davis cube tomorrow 11am–1pm
→ libcal_suggest or direct libcal_book with your exact time

Any study rooms free Friday afternoon?
→ libcal_check_availability or libcal_suggest

작동 방식

• 가용성 — 리버스 엔지니어링된 LibCal 그리드 API (/spaces/availability/grid)

• 예약 — Playwright가 실제 LibCal UI를 구동: 슬롯 선택 → 시간 제출 → /spaces/auth 체크아웃 → 양식 확인

• 캘린더 — AppleScript → Calendar.app (macOS 자동화 권한 필요)

세션은 주기적으로 만료됩니다. libcal_auth_status가 만료를 보고하면 npm run login을 다시 실행하세요.

CLI 스크립트

# Refresh Onyen session
npm run login

# Run unit tests (38 tests)
npm test

# Book via CLI (uses saved session)
node dist/scripts/run-task.js --date 2026-09-01 --start 14:00 --duration 120

# Check public bookings page / cancel-link availability
node dist/scripts/list-bookings.js

예약 취소

UNC LibCal은 웹 UI에서 "내 예약(my bookings)" 취소 페이지를 제공하지 않습니다. alerts@mail.libcal.com에서 보낸 확인 이메일의 링크를 통해 취소하세요.

LibCal 제한 사항 (UNC Davis)

• 하루 최대 3시간, 30분 / 1시간 단위로

• 인기 슬롯은 suggest와 book 사이에 차지될 수 있음

• 큐브는 체크아웃 양식에 "강의 또는 그룹 이름"이 필요할 수 있음 (구성의 bookingPurpose로 기본 설정)

개발

npm run build    # compile TypeScript → dist/
npm test         # unit + integration tests
npm run dev      # build and start MCP server on stdio

주의 사항

• 개인 자동화 도구 — 책임감 있게 사용하고 UNC Library 정책을 따르세요

• calendar.lib.unc.edu (UNC Chapel Hill)에서만 테스트됨

• 다른 LibCal 기관은 src/libcal/constants.ts에서 다른 lid/gid 상수가 필요함

라이선스

MIT — LICENSE 참조.