ucsd-study-room 0.1.0

CLI & MCP tool to automatically search and book UCSD study rooms via EMS

ucsd-study-room

A CLI tool and MCP server that automatically searches and books UCSD Price Center study rooms (Rooms 1--8) through the EMS Cloud booking system.

Features

• Headless browser automation -- Searches and books rooms using Playwright with real Chrome, no browser window required
• UCSD SSO + Duo Push authentication -- Handles SAML-based single sign-on and Duo two-factor authentication
• Session persistence -- Saves browser sessions (cookies + localStorage) for reuse; credentials stored securely in macOS Keychain
• Automatic re-authentication -- When SSO expires, opens a headed browser for Duo Push re-verification without requiring you to re-enter credentials
• CLI interface -- Simple study-room command for searching and booking from the terminal
• MCP server -- Integrates with Claude Code so you can book rooms using natural language

Requirements

• Python 3.11 or later
• Google Chrome installed
• UCSD account with Duo Push enabled
• macOS (uses Keychain for credential storage)

Installation

pip install ucsd-study-room
playwright install chromium

Quick Start

1. Log in with your UCSD credentials (first time only):

study-room login

A Chrome window will open. Enter your UCSD SSO credentials when prompted, then approve the Duo Push notification on your phone. Your session and credentials are saved for future use.

2. Search for available rooms:

study-room search --date 2026-03-11 --start 15:00 --end 17:00

3. Search and book interactively:

study-room search --date 2026-03-11 --start 15:00 --end 17:00 --book

CLI Commands

Command	Description
study-room login	SSO login with Duo Push (opens browser for first-time auth)
study-room search	Search available rooms with --date, --start, --end options
study-room search --book	Search and book a room interactively
study-room config	View or set user info (--name, --email, --attendees)
study-room status	Check whether the current session is valid

Examples

# Set your contact info (required before booking)
study-room config --name "Your Name" --email "[e-mail]"

# Search for rooms on a specific date and time
study-room search --date 2026-03-11 --start 14:00 --end 16:00

# Search and book in one step
study-room search --date 2026-03-11 --start 14:00 --end 16:00 --book

# Check if your session is still active
study-room status

MCP Server (Claude Code Integration)

The MCP server lets you search and book study rooms using natural language through Claude Code.

Setup

Add the following to your .claude/settings.json:

{
  "mcpServers": {
    "study-room": {
      "command": "python",
      "args": ["-m", "study_room.mcp_server"]
    }
  }
}

Usage

Once configured, you can use natural language in Claude Code:

• "Search for available study rooms tomorrow from 2pm to 4pm"
• "Book Price Center Study Room 3 on March 11 from 3pm to 5pm"
• "Are there any rooms open this Friday afternoon?"

Available MCP Tools

Tool	Description
search_rooms	Search for available rooms by date and time range
book_room	Book a specific room (use after search_rooms)
login	Authenticate via UCSD SSO + Duo Push

How It Works

1. Browser automation -- Uses Playwright with real Chrome (channel="chrome") in headless mode to interact with the EMS Cloud booking system.
2. Authentication -- Navigates to the UCSD SAML SSO page, submits credentials, and waits for Duo Push approval. On first login, a headed browser window opens for the Duo flow.
3. Session management -- After authentication, cookies and browser storage state are saved to ~/.study-room/. Credentials are stored in macOS Keychain via the keyring library. Sessions are valid for 7 days.
4. Auto re-login -- When a session expires during a search or booking operation, the tool automatically opens a headed browser, loads credentials from Keychain, and re-authenticates with Duo Push.
5. Room search -- Navigates to the EMS booking page, fills in date and time fields, and parses available rooms by inspecting the DOM for booking buttons.
6. Booking -- Clicks the add-to-cart button for the selected room, fills in the reservation form (name, email, terms), and submits the reservation.

Configuration

Configuration is stored in ~/.study-room/config.yaml. Default target rooms are Price Center Study Room 1 through 8.

name: "Your Name"
email: "[e-mail]"
default_attendees: 1
rooms:
  - Price Center Study Room 1
  - Price Center Study Room 2
  - Price Center Study Room 3
  - Price Center Study Room 4
  - Price Center Study Room 5
  - Price Center Study Room 6
  - Price Center Study Room 7
  - Price Center Study Room 8

Contributing

Contributions are welcome. To contribute:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-feature)
3. Commit your changes
4. Push to the branch and open a pull request

Please make sure existing tests pass before submitting.

License

This project is licensed under the MIT License. See LICENSE for details.