ucsd-study-room 0.1.0__tar.gz

ucsd_study_room-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Theo Lee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ucsd_study_room-0.1.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: ucsd-study-room
+Version: 0.1.0
+Summary: CLI & MCP tool to automatically search and book UCSD study rooms via EMS
+Author: Theo Lee
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/TheoLee021/ucsd-study-room
+Project-URL: Issues, https://github.com/TheoLee021/ucsd-study-room/issues
+Keywords: ucsd,study-room,ems,booking,playwright,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Education
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: playwright>=1.40
+Requires-Dist: typer>=0.9
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: mcp>=1.0
+Requires-Dist: rich>=13.0
+Requires-Dist: keyring>=25.0
+Dynamic: license-file
+
+# ucsd-study-room
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+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
+
+```bash
+pip install ucsd-study-room
+playwright install chromium
+```
+
+## Quick Start
+
+**1. Log in with your UCSD credentials (first time only):**
+
+```bash
+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:**
+
+```bash
+study-room search --date 2026-03-11 --start 15:00 --end 17:00
+```
+
+**3. Search and book interactively:**
+
+```bash
+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
+
+```bash
+# Set your contact info (required before booking)
+study-room config --name "Your Name" --email "you@ucsd.edu"
+
+# 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`:
+
+```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.
+
+```yaml
+name: "Your Name"
+email: "you@ucsd.edu"
+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](LICENSE) for details.

ucsd_study_room-0.1.0/README.md

@@ -0,0 +1,155 @@
+# ucsd-study-room
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+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
+
+```bash
+pip install ucsd-study-room
+playwright install chromium
+```
+
+## Quick Start
+
+**1. Log in with your UCSD credentials (first time only):**
+
+```bash
+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:**
+
+```bash
+study-room search --date 2026-03-11 --start 15:00 --end 17:00
+```
+
+**3. Search and book interactively:**
+
+```bash
+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
+
+```bash
+# Set your contact info (required before booking)
+study-room config --name "Your Name" --email "you@ucsd.edu"
+
+# 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`:
+
+```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.
+
+```yaml
+name: "Your Name"
+email: "you@ucsd.edu"
+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](LICENSE) for details.

ucsd_study_room-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "ucsd-study-room"
+version = "0.1.0"
+description = "CLI & MCP tool to automatically search and book UCSD study rooms via EMS"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+    {name = "Theo Lee"}
+]
+keywords = ["ucsd", "study-room", "ems", "booking", "playwright", "mcp"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Education",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "playwright>=1.40",
+    "typer>=0.9",
+    "pyyaml>=6.0",
+    "mcp>=1.0",
+    "rich>=13.0",
+    "keyring>=25.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/TheoLee021/ucsd-study-room"
+Issues = "https://github.com/TheoLee021/ucsd-study-room/issues"
+
+[project.scripts]
+study-room = "study_room.cli:app"
+
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["study_room*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

ucsd_study_room-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ucsd_study_room-0.1.0/study_room/auth.py

@@ -0,0 +1,184 @@
+import json
+from datetime import datetime, timedelta
+from pathlib import Path
+
+import keyring
+from playwright.async_api import async_playwright
+
+SESSION_DIR = Path.home() / ".study-room"
+SESSION_PATH = SESSION_DIR / "session.json"
+STORAGE_STATE_PATH = SESSION_DIR / "storage_state.json"
+SESSION_MAX_AGE_DAYS = 7
+EMS_URL = "https://ucsdevents.emscloudservice.com/web/"
+SAML_URL = "https://ucsdevents.emscloudservice.com/web/samlauth.aspx"
+DUO_TIMEOUT_MS = 60_000
+KEYRING_SERVICE = "study-room-booking"
+KEYRING_USERNAME_KEY = "ucsd-sso-username"
+
+
+def save_credentials(username: str, password: str) -> None:
+    keyring.set_password(KEYRING_SERVICE, KEYRING_USERNAME_KEY, username)
+    keyring.set_password(KEYRING_SERVICE, username, password)
+
+
+def load_credentials() -> tuple[str, str] | None:
+    username = keyring.get_password(KEYRING_SERVICE, KEYRING_USERNAME_KEY)
+    if username is None:
+        return None
+    password = keyring.get_password(KEYRING_SERVICE, username)
+    if password is None:
+        return None
+    return username, password
+
+
+def save_session(cookies: list, path: Path = SESSION_PATH) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    data = {
+        "cookies": cookies,
+        "created_at": datetime.now().isoformat(),
+    }
+    path.write_text(json.dumps(data, indent=2))
+
+
+def load_session(path: Path = SESSION_PATH) -> dict | None:
+    if not path.exists():
+        return None
+    return json.loads(path.read_text())
+
+
+def is_session_valid(path: Path = SESSION_PATH) -> bool:
+    session = load_session(path)
+    if session is None:
+        return False
+    created = datetime.fromisoformat(session["created_at"])
+    return datetime.now() - created < timedelta(days=SESSION_MAX_AGE_DAYS)
+
+
+async def login(username: str, password: str, session_path: Path = SESSION_PATH) -> list:
+    """SSO 로그인 + Duo Push 인증 후 쿠키를 저장한다."""
+    async with async_playwright() as p:
+        browser = await p.chromium.launch(headless=False, channel="chrome")
+        context = await browser.new_context()
+        page = await context.new_page()
+
+        # 1. SAML 인증 페이지로 직접 이동 → UCSD SSO 리다이렉트
+        await page.goto(SAML_URL)
+        await page.wait_for_load_state("networkidle")
+
+        # 2. UCSD SSO 로그인 — username + password
+        await page.wait_for_selector("#ssousername", timeout=15000)
+        await page.locator("#ssousername").fill(username)
+        await page.locator("#ssopassword").fill(password)
+        await page.locator("button[type='submit']").click()
+
+        # 3. Duo Push 대기 — EMS 페이지로 돌아오면 인증 완료
+        print("Duo Push가 전송되었습니다. 폰에서 승인해주세요...")
+        await page.wait_for_url("**/web/**", timeout=DUO_TIMEOUT_MS)
+
+        # 4. credentials를 keychain에 저장
+        save_credentials(username, password)
+
+        # 5. storage state 전체 저장 (쿠키 + localStorage + sessionStorage)
+        cookies = await context.cookies()
+        save_session(cookies, session_path)
+
+        storage_state_path = session_path.parent / "storage_state.json"
+        await context.storage_state(path=str(storage_state_path))
+        print(f"로그인 성공! {len(cookies)}개 쿠키 + storage state 저장됨.")
+
+        await browser.close()
+        return cookies
+
+
+async def get_authenticated_context(playwright, session_path: Path = SESSION_PATH, headless: bool = True, channel: str | None = "chrome"):
+    """저장된 storage state로 인증된 브라우저 컨텍스트를 반환한다."""
+    if not is_session_valid(session_path):
+        return None
+
+    storage_state_path = session_path.parent / "storage_state.json"
+    launch_args = {"headless": headless}
+    if channel:
+        launch_args["channel"] = channel
+    browser = await playwright.chromium.launch(**launch_args)
+
+    if storage_state_path.exists():
+        context = await browser.new_context(storage_state=str(storage_state_path))
+    else:
+        session = load_session(session_path)
+        context = await browser.new_context()
+        await context.add_cookies(session["cookies"])
+
+    return context
+
+
+async def _headed_login_and_save(session_path: Path = SESSION_PATH):
+    """SSO 만료 시 headed 브라우저로 재로그인. Keychain → 자동입력, 실패 → 수동입력."""
+    import asyncio
+
+    creds = load_credentials()
+
+    async with async_playwright() as p:
+        browser = await p.chromium.launch(headless=False, channel="chrome")
+        context = await browser.new_context()
+        page = await context.new_page()
+
+        await page.goto(SAML_URL)
+        await page.wait_for_load_state("networkidle")
+
+        await page.wait_for_selector("#ssousername", timeout=15000)
+
+        if creds:
+            username, password = creds
+            print("Keychain에서 credentials 로드 → 자동 입력 중...")
+            await page.locator("#ssousername").fill(username)
+            await page.locator("#ssopassword").fill(password)
+            await page.locator("button[type='submit']").click()
+        else:
+            print("Keychain에 credentials 없음 → 브라우저에서 직접 로그인해주세요.")
+
+        print("Duo Push가 전송되었습니다. 폰에서 승인해주세요...")
+        await page.wait_for_url("**/web/**", timeout=DUO_TIMEOUT_MS)
+
+        # 세션 저장
+        cookies = await context.cookies()
+        save_session(cookies, session_path)
+        storage_state_path = session_path.parent / "storage_state.json"
+        await context.storage_state(path=str(storage_state_path))
+        print("재로그인 성공! 세션 갱신됨.")
+
+        await browser.close()
+
+
+async def authenticate(page, session_path: Path = SESSION_PATH):
+    """SAML 인증. SSO 유효 시 자동 통과, 만료 시 headed 브라우저로 Duo 인증."""
+    import asyncio
+
+    print("SAML 인증 중...")
+
+    await page.goto(SAML_URL)
+    await page.wait_for_load_state("networkidle")
+    await asyncio.sleep(2)
+
+    # SSO 로그인 페이지가 나왔는지 확인
+    sso_form = page.locator("#ssousername")
+    if await sso_form.count() > 0:
+        # SSO 만료 — headed 브라우저로 Duo 인증
+        print("SSO 세션 만료. headed 브라우저로 로그인 진행...")
+        await page.context.browser.close()
+        await _headed_login_and_save(session_path)
+        return "relogin_needed"
+
+    # SSO 유효 → 자동으로 EMS 리다이렉트
+    await page.wait_for_url("**/web/**", timeout=15000)
+
+    # storage state 갱신
+    context = page.context
+    cookies = await context.cookies()
+    save_session(cookies, session_path)
+    storage_state_path = session_path.parent / "storage_state.json"
+    await context.storage_state(path=str(storage_state_path))
+    print("인증 완료.")
+
+
+class SessionExpiredError(Exception):
+    pass