# Roamio MCP Server

Event discovery based on your actual schedule, location, and who's free -- delivered inside iMessage via Poke.

## What It Does

- Pulls events from Ticketmaster, Eventbrite, Luma, and ATL Scoop
- Filters them to slots where you're actually free (via your connected calendar)
- Lets you invite friends via a link (no app needed)
- Shows you events where multiple friends are free at the same time

## Setup

### 1. Install dependencies

```bash
pip install -r requirements.txt
```

### 2. Add your API keys

```bash
cp src/.env.example src/.env
# Fill in TICKETMASTER_API_KEY, EVENTBRITE_API_KEY, LUMA_API_KEY
```

Get your keys here:
- Ticketmaster: https://developer.ticketmaster.com
- Eventbrite: https://www.eventbrite.com/platform/api
- Luma: https://lu.ma/developers

### 3. Run the server locally

```bash
python src/server.py
```

Server starts on http://localhost:3000/mcp

### 4. Connect to Poke via CLI tunnel

```bash
npx poke@latest login
npx poke@latest tunnel http://localhost:3000/mcp -n "Roamio" --recipe
```

This gives you a recipe link + QR code you can share.

### 5. Deploy to production

Deploy to Railway, Fly.io, or any host that runs Python. Then register the hosted URL directly in Poke Kitchen:

```bash
npx poke@latest mcp add https://your-domain.com/mcp -n "Roamio"
```

## Tools Exposed to Poke

| Tool | What it does |
|------|-------------|
| `get_events` | Events near you that fit your free windows |
| `invite_friend` | Generates a no-account-needed availability link |
| `get_friend_overlap` | Events where you AND friends are free |

## Architecture

```
iMessage / Poke
     |
     v
Poke AI (reads your calendar free slots)
     |
     v
Roamio MCP Server
     |
     +-- Ticketmaster API
     +-- Eventbrite API
     +-- Luma API
     +-- ATL Scoop scraper (AI parser)
     |
     v
Filtered events + friend overlap
```

## Roadmap

- [ ] ATL Scoop Instagram scraper + AI caption parser
- [ ] Lightweight friend availability web page (roamio.app/avail/:id)
- [ ] Persistent DB for friend store (swap out in-memory dict)
- [ ] City expansion (swap ATL Scoop for local equivalent per city)
- [ ] Poke Kitchen recipe publish + payouts