UNC LibCal MCP

MCP-сервер для бронирования учебных помещений UNC Davis Library из Claude, Cursor, Codex или любого MCP-клиента — с опциональной интеграцией с Apple Calendar.

Создан для студентов, преподавателей и сотрудников UNC с действующим Onyen. Не аффилирован с UNC Libraries и не одобрен ими.

Что он делает

Спросите своего агента:

Забронируй мне куб в Davis на завтра в 14:00

Сервер:

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 (для бронирования; проверка доступности работает без входа)

• macOS для синхронизации с Apple Calendar (необязательно)

• 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. Предоставьте разрешение Automation, когда 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 — интерфейс: Настройки → MCP → Добавить сервер → вставьте JSON-блок выше.

Вариант B — файл проекта: .cursor/mcp.json в этом репозитории (удобно для совместной работы с коллегами):

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

Используйте ./dist/index.js только если рабочая директория MCP в Cursor — корень проекта; в противном случае используйте абсолютный путь.

OpenAI Codex (CLI)

Codex использует TOML, а не JSON. Файл: ~/.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 trust в репозитории) при использовании локального для проекта .codex/config.toml.

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. Укажите ему dist/index.js после npm run build.

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. Агент вызывает libcal_book с user_confirmed: true и выбранными датой/временем

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

Как это работает

• Доступность — реверс-инженеренный grid API LibCal (/spaces/availability/grid)

• Бронирование — Playwright управляет реальным интерфейсом LibCal: выбор слота → отправка времени → оформление на /spaces/auth → форма подтверждения

• Календарь — AppleScript → Calendar.app (требуется разрешение Automation в macOS)

Сеансы периодически истекают. Выполните npm run login снова, когда libcal_auth_status сообщит об истечении.

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 не предоставляет страницу отмены «мои бронирования» в веб-интерфейсе. Отмените бронирование по ссылке в письме с подтверждением от 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

• Протестировано только с calendar.lib.unc.edu (UNC Chapel Hill)

• Другим учреждениям LibCal потребуются другие константы lid/gid в src/libcal/constants.ts

Лицензия

MIT — см. LICENSE.