# reservations-mcp

An **auditable** [Model Context Protocol](https://modelcontextprotocol.io) server for
restaurant **discovery** and **reservations**, across multiple providers.

Built as a transparent alternative to the "just `npx` this mystery package" reservation
MCPs floating around: every line is here in `src/`, it talks **only** to each provider's
own API, it uses **no** browser automation or bot-detection evasion, and credentials come
**only** from your own environment or local config — never logged, never sent anywhere else.

## What it does

| Provider | Discovery | Availability | Booking |
| --- | --- | --- | --- |
| **Resy** | ✅ venue search | ✅ | ✅ (two-step, opt-in) |
| **Google Places** | ✅ (rich: `goodForChildren`, `outdoorSeating`, `servesCocktails`) | — | — |
| **Yelp** | ✅ (`outdoor_seating`, price, term) | — | — |
| **Tock** | ⚠️ stub in v1 (returns a direct link; see `src/providers/tock.ts`) | — | — |

> **OpenTable is intentionally excluded.** It has no public reservation API, so booking it
> requires browser automation that violates its ToS and risks an account ban. Out of scope.

## Tools

- `discover_restaurants` — natural-language search ("Hudson waterfront, skyline view, outdoor, kid-friendly, great cocktails"). Read-only.
- `resy_search` — find Resy venue ids by name/keyword.
- `resy_availability` — open slots for a venue / date / party size.
- `resy_booking_preview` — **step 1**: resolve a slot, surface time + seating + any cancellation/no-show fee. Does not book.
- `resy_book` — **step 2, irreversible**: books a `book_token`. Requires `confirm: true`.
- `resy_payment_methods` — list saved card ids (some bookings require a card).
- `resy_login` — exchange email+password for a token once (password never stored). Prefer `RESY_AUTH_TOKEN`.
- `resy_my_reservations` — your upcoming reservations.
- `tock_search` — best-effort stub (see note above).
- `status` — which providers are configured.

## Setup

```bash
npm install
npm run build
cp .env.example .env   # then fill in keys/tokens you want
```

### Credentials (all optional — set only what you need)

- **`RESY_AUTH_TOKEN`** — required for Resy availability/booking. Log in at resy.com, open
  DevTools → Network, click any restaurant, and copy the `X-Resy-Auth-Token` header. (Or call
  the `resy_login` tool once.)
- **`RESY_PAYMENT_METHOD_ID`** — default card for bookings (`resy_payment_methods` lists ids).
- **`YELP_API_KEY`** — free from the [Yelp Fusion](https://www.yelp.com/developers) console.
- **`GOOGLE_PLACES_API_KEY`** — [Google Places API (New)](https://developers.google.com/maps/documentation/places/web-service).

`RESY_API_KEY` defaults to the public key embedded in Resy's own web client; override if it rotates.

## Connect to Claude

Add to your Claude Code / Claude Desktop MCP config:

```json
{
  "mcpServers": {
    "reservations": {
      "command": "node",
      "args": ["/absolute/path/to/reservations-mcp/dist/index.js"],
      "env": {
        "RESY_AUTH_TOKEN": "…",
        "GOOGLE_PLACES_API_KEY": "…",
        "YELP_API_KEY": "…"
      }
    }
  }
}
```

## Booking is deliberately two-step

`resy_book` will refuse without `confirm: true`. The intended flow:

1. `resy_availability` → pick a slot (`bookToken`)
2. `resy_booking_preview` → review time, seating type, and **fees**, get a real `book_token`
3. `resy_book` with `confirm: true` → reserved

This makes the one irreversible, money-adjacent action explicit and reviewable.

## Safety / honesty notes

- Resy's API is **unofficial**; endpoints may change. Calls fail loudly rather than guess.
- Nothing here evades bot detection or scrapes rendered HTML.
- Secrets live in `.env` / `~/.config/reservations-mcp/` (gitignored, `0600`), never in the repo.
- Tock is a labelled stub — it does not return fabricated availability.

## License

MIT