@striderlabs/mcp-orangetheory 1.0.0

package/README.md

@@ -0,0 +1,199 @@
+# @striderlabs/mcp-orangetheory
+
+Orangetheory Fitness MCP server for personal AI agents. Find studios, view class schedules, book and cancel classes, and track your workout performance — all through natural language.
+
+Built by [Strider Labs](https://striderlabs.ai).
+
+## Features
+
+- **Find Studios** — Search for Orangetheory locations by city, zip code, or address
+- **Class Schedules** — View upcoming classes with coach names, times, and available spots
+- **Book Classes** — Reserve your spot in any available class
+- **Cancel Bookings** — Cancel upcoming class reservations (with late-cancel warnings)
+- **Workout History** — View past workouts with splat points, calories, heart rate zones, and coach info
+- **Membership Status** — Check membership type, classes remaining, billing dates, and home studio
+- **Performance Tracking** — Aggregated stats over time: streaks, averages, totals
+- **Upcoming Classes** — See all your booked classes and reminders
+
+## Installation
+
+```bash
+npm install -g @striderlabs/mcp-orangetheory
+npx patchright install chromium
+```
+
+## MCP Configuration
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "orangetheory": {
+      "command": "npx",
+      "args": ["-y", "@striderlabs/mcp-orangetheory"]
+    }
+  }
+}
+```
+
+### Cursor / Other MCP Clients
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "orangetheory": {
+        "command": "npx",
+        "args": ["-y", "@striderlabs/mcp-orangetheory"],
+        "transport": "stdio"
+      }
+    }
+  }
+}
+```
+
+### Using npx (no install required)
+
+```json
+{
+  "mcpServers": {
+    "orangetheory": {
+      "command": "npx",
+      "args": ["@striderlabs/mcp-orangetheory"]
+    }
+  }
+}
+```
+
+## Authentication
+
+This connector uses browser automation to interact with the Orangetheory member portal. Your session is saved locally so you only need to log in once.
+
+### Login
+
+Use the `orangetheory_login` tool with your credentials:
+
+```
+orangetheory_login(email="you@example.com", password="yourpassword")
+```
+
+Or call `orangetheory_login` without arguments to get a manual login URL.
+
+Session cookies are saved to `~/.strider/orangetheory/` and reused automatically.
+
+### Session Persistence
+
+- Cookies are stored in `~/.strider/orangetheory/cookies.json`
+- Session info is stored in `~/.strider/orangetheory/session.json`
+- Sessions typically last several weeks before requiring re-login
+- Use `orangetheory_logout` to clear all saved data
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `orangetheory_status` | Check login status and session info |
+| `orangetheory_login` | Authenticate with email/password |
+| `orangetheory_logout` | Clear session and cookies |
+| `orangetheory_find_studios` | Find studios by location |
+| `orangetheory_class_schedule` | View class schedules for a studio |
+| `orangetheory_book_class` | Book an available class (requires confirm=true) |
+| `orangetheory_cancel_booking` | Cancel a booked class (requires confirm=true) |
+| `orangetheory_workout_history` | View past workouts with stats |
+| `orangetheory_membership_status` | Check membership details and billing |
+| `orangetheory_performance_summary` | Aggregated performance stats over time |
+| `orangetheory_upcoming_classes` | View upcoming booked classes |
+
+## Example Usage
+
+### Finding a Studio and Booking a Class
+
+```
+User: Find Orangetheory studios near Austin, TX and book me into tomorrow's 6am class
+
+Agent:
+1. orangetheory_find_studios(location="Austin, TX")
+   → Returns list of studios with IDs
+
+2. orangetheory_class_schedule(studio_id="austin-domain", date="2024-01-16")
+   → Returns available classes including a 6:00 AM slot (class_id: "abc123")
+
+3. orangetheory_book_class(class_id="abc123", confirm=true)
+   → "Successfully booked class! Booking ID: BK987654"
+```
+
+### Checking Workout Performance
+
+```
+User: How have my workouts been going this month?
+
+Agent:
+1. orangetheory_performance_summary(period="month")
+   → Total Workouts: 12
+   → Avg Splat Points: 18
+   → Avg Calories: 542 kcal
+   → Current Streak: 4 workouts
+
+2. orangetheory_workout_history(limit=5)
+   → Last 5 workouts with detailed heart rate and zone data
+```
+
+### Managing Bookings
+
+```
+User: What classes do I have coming up? Cancel the one on Thursday.
+
+Agent:
+1. orangetheory_upcoming_classes()
+   → Lists booked classes including Thursday at 7am (booking_id: "BK111222")
+
+2. orangetheory_cancel_booking(booking_id="BK111222", confirm=true)
+   → "Successfully cancelled booking BK111222"
+```
+
+## Booking Safety
+
+- **Book confirmation**: `orangetheory_book_class` requires `confirm=true` to prevent accidental bookings
+- **Cancel confirmation**: `orangetheory_cancel_booking` requires `confirm=true`
+- **Late cancel warning**: The tool warns if a cancellation may incur a fee (within 8 hours of class)
+
+## Technical Details
+
+- **Browser automation**: Uses [Patchright](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright) (stealth Playwright) to interact with Orangetheory's web portal
+- **Headless mode**: Runs in background without visible browser window
+- **Session persistence**: Cookies saved locally, no credentials stored in plain text after initial login
+- **Platform**: Node.js 18+, macOS/Linux/Windows
+
+## Limitations
+
+- Requires initial manual login (CAPTCHA may appear on first login)
+- Class IDs and booking IDs depend on the current page structure
+- Orangetheory website changes may require connector updates
+- Does not support in-studio features (heart rate monitor pairing, etc.)
+
+## Troubleshooting
+
+**"Not logged in" error**: Run `orangetheory_login` to re-authenticate.
+
+**Login CAPTCHA**: Try logging in manually through the browser at https://app.orangetheory.com, then the saved cookies will work for automation.
+
+**No studios found**: Try a different location format (zip code works most reliably), or increase the radius parameter.
+
+**Browser crashes**: Ensure Chromium is installed: `npx patchright install chromium`
+
+## Development
+
+```bash
+git clone https://github.com/striderlabs/mcp-orangetheory
+cd mcp-orangetheory
+npm install
+npm run build
+node dist/index.js
+```
+
+## License
+
+MIT — [Strider Labs](https://striderlabs.ai)