# Edi's Resorts - Partner MCP Integration Guide

Connect AI assistants (Claude or custom MCP clients) to Edi's Resorts to search live availability, rooms, experiences and events (no login needed) and, for partners, manage bookings across 8 resorts:
- Winter mountain resorts (Dec 2026 - Mar 2027): Velmora (wellness), Skarvik (sporty), Lunadol (relaxation), Kordal Peak (sporty)
- Summer seaside resorts (Jun - Sep 2027): Solmara (relaxation), Ventara (sporty), Aurelin (wellness), Corallo (relaxation)

Change notice (Nov 2026): the former resorts Rovinj, Porec, Hvar and Umag were renamed to Velmora, Skarvik, Solmara and Ventara (same hotel_id 1-4), and their room types were renamed. Use search_hotels or get_room_availability to get current room_type names before create_booking. Existing reservations are unaffected.

## 1. Endpoints
- MCP Server URL (Streamable HTTP): https://resorts.edisprojects.com/mcp
- OAuth Metadata: https://resorts.edisprojects.com/.well-known/oauth-authorization-server
- Guest Booking Portal: https://resorts.edisprojects.com/
- For agents: https://resorts.edisprojects.com/agents (examples) and /llms.txt (plain-text summary)
- The previous address https://ubuntu-4gb-fsn1-6.tailbb9a52.ts.net keeps working with the same paths (existing connectors and tokens stay valid; new links point to https://resorts.edisprojects.com).

## 2. Access: public tools and partner login
The MCP server has two tool sets on the same URL:
- **No login (public):** connect without credentials and you get the read-only tools below (resorts, rooms, experiences, events, extras, offers and Ask Edi search), plus the cart tools when the operator has switched public writes on. In Claude: Settings -> Connectors -> Add custom connector -> `https://resorts.edisprojects.com/mcp`, no sign-in.
- **Partner login (OAuth 2.1 + PKCE, or a static API key):** the public tools, the cart tools (always) and the original booking tools (deprecated, see below). Partner credentials are issued privately by Edi's Resorts.

A request with an invalid or expired token gets HTTP 401 with `WWW-Authenticate` (clients then refresh their token); a request without an `Authorization` header gets the public tools.

### Claude Setup (partner login)
1. Open Settings -> Connectors -> Add custom connector.
2. Enter https://resorts.edisprojects.com/mcp
3. Sign in with the partner username and password you were given. Automatic refresh tokens keep your session active.

### Custom MCP Clients
- Grant Types: authorization_code (PKCE S256 required), refresh_token
- Dynamic Client Registration: POST /oauth/register
- Authorize / Token: GET /oauth/authorize and POST /oauth/token
- Transport: Streamable HTTP, stateless (POST /mcp; GET /mcp returns 405)

## 3. MCP Tools

### Public tools (no login, read-only)
Every result has `structuredContent` (JSON) and the same JSON as text, with absolute links to the matching website page. Resorts can be named by city, name, slug or id ("Velmora", "Kordal Peak", "kordal-peak", 1). Invalid input returns `isError` with a message saying what to fix.
- **search_resorts** `{ season?, character?, city?, check_in?, check_out?, max_rate_eur? }`: matching resorts with `from_price_ro_eur` (lowest room-only nightly rate from today with a room free). Without dates also `seasons` (the home page's Destinations overview per season). With dates (both, at most 28 nights): `available` and `cheapest_room` (room only, for those nights).
- **get_resort** `{ resort, check_in?, check_out? }`: profile, rooms (size, max guests; with dates `rooms_left`, `avg_nightly_eur` and `total_stay_eur` per meal plan RO / BB / HB), facilities by kind, meal plans, and `calendar` (open-night ranges from today with the cheapest free room-only rate, plus open nights per month).
- **list_experiences** `{ resort?, category?, season?, from?, to? }`: up to 20 experiences with price, `price_unit` (person | group), duration and `next_slot`.
- **get_experience_slots** `{ experience, from?, to? }`: one experience (slug or exact name) and up to 60 slots (`slot_id`, `starts_at`, `spots_left`, `capacity`, `sold_out`).
- **list_extras** `{ resort?, category? }`: extras and meal plans with `price_eur`, `unit` and `needs_date`.
- **list_events** `{ resort?, season?, from?, limit? (1-20, default 10) }`: upcoming dated events, soonest first.
- **list_offers** `{ resort? }`: featured offers (editorial only; no price effect).
- **ask_edi** `{ question, answer_slot?, history?, asked? }`: the Ask Edi search (same contract as POST /api/v1/search, lists trimmed to the `display` counts, `trips` = bundles). Over MCP it uses rules only, never an AI model. To answer a `clarify` group, send the chosen option's text as `question`, `answer_slot` = the group's slot, `history` = earlier questions (max 4) and `asked` = the response's `asked`. Limits per client IP as for the search API (429-style errors come back as `isError` with `reason` and `retry_after`).

### Cart, checkout and orders
Available to partners (OAuth or API key) and, once the operator switches public writes on, also without login. Same rules, prices and checks as the website cart (see "Cart and checkout" below). **Demo only: no payment is taken and no card number is ever asked for.**
- **create_cart** `{}`: new cart; returns `cart_id` (the only key to the cart; keep it) and `website_url`.
- **add_room** `{ cart_id?, resort, room (id or name), check_in, check_out, guests, quantity?, meal_plan? }`: without `cart_id` a new cart is created and returned. `guests` = guests per room as the user stated (never assumed).
- **add_experience** `{ cart_id?, slot_id, quantity }`: a slot from get_experience_slots / list_events; `quantity` = persons (group experiences count once).
- **add_extra** `{ cart_id, parent_item_id, extra, quantity?, service_date? }`: an extra code from list_extras on a room line of the same resort; extras with `needs_date` need `service_date` within the stay.
- **view_cart** `{ cart_id }`, **remove_item** `{ cart_id, item_id }` (removing a room removes its extras).
- **checkout** `{ cart_id, confirm: true, first_name, surname, email, idempotency_key, expected_total_eur }`: books everything, all or nothing. Call it only after the user confirmed the summary. If the cart now costs something other than `expected_total_eur`, nothing is booked and the error carries `current_total_eur`. `idempotency_key` (8-64 characters `A-Z a-z 0-9 - _`) is unique **per cart**: a retry with the same cart, key and email returns the same order (`replayed: true`) without booking again; the same key with another email is refused. Returns the order (`EDO-…`) with one `EDI-…` reservation per room.
- **get_order** `{ code, email }`: an order (`EDO-…`) or a single reservation (`EDI-…`); `found: false` when the code or email doesn't match.
- **cancel_order** `{ code, email, confirm: true }`: cancels a whole order (rooms and experience spots are released) or one reservation.
- Every open-cart result has `website_url` (`/cart/open/<code>`): it opens the cart in a browser for 30 minutes ("finish on the website"). The page asks before replacing a cart the browser already has; the code is not the cart id.
- Limits: per cart and hour 200 cart changes and 20 checkout attempts; per client IP the website numbers (30 new carts, 200 changes, 20 checkouts, 60 order lookups per hour, plus the overall booking cap per IP), except for Claude's hosted clients (Anthropic's range 160.79.104.0/21), which share only the per-cart limits and the hourly ceilings for all AI-assistant traffic together (300 new carts, 60 checkouts, 200 order lookups). Over a limit: `isError` with `reason: "rate_limited"` and `limit`.
- Errors are `isError` results with a message saying what to fix, plus `status` (400 / 404 / 409 / 429) where it applies.


### Interactive cards (MCP Apps)
Hosts that support the MCP Apps extension (`io.modelcontextprotocol/ui`, spec 2026-01-26) show interactive cards next to these tools; other hosts use the normal results. The cards are `ui://edis/resorts.html` (`search_resorts`), `ui://edis/rooms.html` (`get_resort`), `ui://edis/slots.html` (`get_experience_slots`) and `ui://edis/cart.html` (`create_cart`, `add_room`, `add_experience`, `add_extra`, `view_cart`, `remove_item`), served as `text/html;profile=mcp-app`.
- Resort carousel: the website's Destinations overview per season, resort photos with from-prices, "See rooms", "Website".
- Rooms: the website's date calendar, rooms with prices per meal plan, guests (always chosen by the user), Add to cart.
- Experience times: the website's date → time → persons picker, Add to cart.
- Cart: lines by resort, Remove, total, "Finish on website" (opens the cart link) and "Check out here" (asks the assistant in the chat, which then collects the guest details and the confirmation). Cards can't call `checkout` or `cancel_order`: those tools are model-only (`_meta.ui.visibility: ["model"]`).
- Security: content security policy allows only images from images.unsplash.com and no network connections; links open only pages of this website; all data is shown as text.

### Partner tools (login required; deprecated)
These keep their names, parameters and behavior. They will be replaced by the v2 tools; there is no removal date yet.
- search_hotels (Read-Only, use search_resorts): Filter by check_in, check_out (YYYY-MM-DD), city (Velmora, Skarvik, Lunadol, Kordal Peak, Solmara, Ventara, Aurelin, Corallo), season (summer, winter), character (sporty, wellness, relaxation), or max_rate_eur. Winter resorts run Dec 2026 - Mar 2027; summer resorts run Jun 2027 - Sep 2027.
- get_room_availability (Read-Only, use get_resort): Get room categories, sqm, descriptions, remaining inventory, and RO/BB/HB pricing for hotel_id (1-8), check_in, and check_out.
- create_booking (Write): Book with hotel_id, room_type, meal_plan (RO, BB, HB), first_name, surname, email, card_number (16 digits), check_in, and check_out. Returns reservation_code (e.g. EDI-1002).
- cancel_booking (Destructive): Cancel by reservation_code and email, restoring inventory.
- list_bookings (Read-Only): Look up one reservation. Requires both reservation_code and the holder's email; returns { bookings: [...] } with the match, or an empty list. Breaking change (Nov 2026): it no longer lists all reservations, and calls without both parameters are rejected.

## 4. JSON API
Base URL: https://resorts.edisprojects.com/api/v1. The read-only endpoints below need no authentication. Responses are JSON; an invalid enum value (season, character, kind, category) or a malformed date (YYYY-MM-DD) returns 400 `{ "error": "..." }`, and an unknown resort or experience returns 404.

Allowed values: season `summer | winter`; character `sporty | wellness | relaxation`; facility kind `restaurant | bar | club | beach | ski_track | wellness | sport`; experience category `tour | boat | ski_lesson | ski_tour | tennis | water_sport | wellness | dining | kids | event | nightlife | sport`; extras category `meal_plan | drinks | transfer | equipment | other`.

Resorts and availability:
- GET /api/v1/resorts?season=&character=&city= : all resorts with season dates, character and the season from-price (`min_season_rate`).
- GET /api/v1/resorts/{id or slug}?check_in=&check_out= : resort profile with rooms (sqm, max guests, rooms left and stay pricing when dates are given) and facilities grouped by kind (restaurants, bars, clubs, beaches / ski tracks, wellness, sport).
- GET /api/v1/resorts/{id or slug}/calendar : every night of the resort's season with `open` (a room is left), `rooms_left` and `min_rate_eur` (cheapest room-only rate among the rooms still free; null when sold out). Nights outside the season are not listed.
- GET /api/v1/facilities?kind=&season=&resort=
- GET /api/v1/availability?check_in=&check_out=&season=&character=&city=&max_rate= : resorts with free rooms for the stay (check_in and check_out are required).
- GET /api/v1/availability/calendar : `{ days: [{ stay_date, total_rooms_left, min_rate }] }` across all resorts.
- GET /api/v1/meal-plans : RO / BB / HB with `supplement_per_night` (EUR, flat per room per night on top of the room-only rate).

Experiences, events, extras, offers:
- GET /api/v1/experiences?resort=&category=&season=&from=&to= : tours, lessons, boat trips, wellness, dining, kids, nightlife and events. Experiences can be booked without a room stay; the resort is only where they take place.
- GET /api/v1/experiences/{slug} and /api/v1/experiences/{slug}/slots?from=&to= : dated slots (`id` = slot_id for the cart, `starts_at` YYYY-MM-DDTHH:MM, `capacity`, `spots_left`). Prices are per person or per group (`price_unit`).
- GET /api/v1/events?from=&limit=&resort=&season= : upcoming event slots in date order.
- GET /api/v1/extras?resort=&category= : hotel extras with `price_eur`, `unit` (`per_stay`, `per_night`, `per_person`, `per_person_night`, `per_item`) and `needs_date` (1 = a service date within the stay is required in the cart).
- GET /api/v1/deals?resort= : featured offers. Editorial only: they do not change prices.
- GET /api/v1/home?season= : what the home page shows: `events` (next 6), `deals` (featured offers; with a season, that season's plus the all-resort ones) and `resorts` (one highlight per resort with `tagline`, `photo_url`, `from_price_ro_eur` = lowest room-only nightly rate among the season nights still bookable, null when sold out, and `counts` of restaurants, bars and clubs, ski tracks, beaches and experiences) and `seasons` (one entry per season: `season_start`, `season_end`, `resorts` with slug / name / city / photo_url, `ski_tracks`, `ski_km`, `beaches`, `wellness`, `experiences` (events not included), `top_categories`, `upcoming_event_dates`, `from_price_ro_eur` = lowest of that season's resorts).

### Search (Ask Edi, experimental)
POST /api/v1/search `{ "q": "spa weekend 5-7 Feb for two" }`, or, to answer a clarifying question, `{ "q": <option.text>, "answer": <the group's slot>, "history": [earlier questions, max 4], "asked": <response.asked> }`
- Answers only from our own data (8 fictional resorts). Rules and full-text search run first; only a free-form question may be ranked by an AI model, which can only reorder our records.
- **A question without `answer` starts fresh**: `history` and `asked` are used only together with `answer` (a clarifying-chip reply), so earlier dates or activities never leak into a new question.
- **Dates and party size are never invented.** Suggested trips (`bundles`) are returned only when the question (or the conversation) has exact dates AND a party size. A month ("in March") is a range for the results (resorts show `range_label` "Open in March" / "Full in March" and `nightly_from_eur` = lowest room-only rate in that month), not a trip.
- Missing details come back as `clarify.groups`: `[{ slot, question, options }]` in the order dates, activity, party, budget (budget is optional). Each option has a `label` and a `text` to send back as `q` with `answer: slot`; a dates option may instead have an `href` (our calendar page). `clarify.slot` / `question` / `options` repeat the first group. Date options are concrete stays chosen from the resorts' availability (e.g. "Fri 5 Mar – Sun 7 Mar" → `text` "5-7 mar").
- Vague words ("nice", "good resort") carry no intent; they lead to the activity question.
- Response: `tier` (`rules` | `clarify` when chips are shown | `ai`), `filters` (what was understood: activities, season, exact dates, month, party, budget, meal plan, resort), `results` (`resorts`, `rooms`, `experiences`, `events`, `extras`, each with `id`, `url` and live availability / prices from our database), `bundles` (suggested trips: `stay`, `party`, `lines`, `total_eur` priced by the cart's own code, `fits_budget`, and `add_items` to add the whole trip in one call), `clarify`, `asked`, `not_in_data` (topics we have no data for, with a link to our own page), `notices`, `links`.
- `focus` and `display`: `focus` is `name` (the question names one experience / event / extra), `resort` (one named resort), `room_type` (one room type such as "suite" or "villa": only rooms of that type) or `broad`. `display` gives, per list (`bundles`, `resorts`, `rooms`, `experiences`, `events`, `extras`), how many results to show before a "Show more" control; `0` means show the list collapsed. Specific questions show 1–3; broad ones 5 trips, 3 resorts, 5 rooms, 5 experiences, 3 events, 3 extras. When trips are returned, `display.rooms` is 0 (every trip already includes its room). The lists themselves hold at most 8 resorts / trips and 10 of everything else, best first.
- Prices are never produced by the AI; totals are re-checked by the cart on add and at checkout.
- Limits per client IP: 60 searches per hour; AI-ranked answers 10 per hour and 30 per day; 1-300 characters; the same question twice in 10 minutes → 400; repeated limit hits → 30-minute cooldown. Over a limit: HTTP 429 with `Retry-After`. Errors: `{ "error", "reason" }`.
- Add a suggested trip: POST /api/v1/carts/{cart_id}/items with `{ "items": bundle.add_items }`.
- Over MCP the same search is the `ask_edi` tool (rules only, no AI model).

### Cart and checkout (write)
One cart can hold room stays at several resorts and dates, experience slots and extras. Prices and availability are computed on every read and re-checked at checkout; nothing is held. Checkout books everything in one transaction: either every line is booked or nothing is.

**Demo only: no real payment is taken. Never send a real card number; use the test card 4242 4242 4242 4242.** Only the last 4 digits are stored.

- POST /api/v1/carts -> 201 `{ cart_id, cart }`. `cart_id` is a secret token: anyone holding it can view and change the cart.
- GET /api/v1/carts/{cart_id} -> `{ cart: { status, items[], total_eur, can_checkout, order_code } }`. Each item has `available` and, if not, a `problem`.
- POST /api/v1/carts/{cart_id}/items with one of:
  - `{ "kind": "room", "hotel_id": 1 | "velmora", "room_id": 1, "check_in": "2026-12-18", "check_out": "2026-12-21", "quantity": 1-5, "guests": 1-max, "meal_plan": "RO|BB|HB" }`
  - `{ "kind": "experience", "slot_id": 123, "quantity": persons }` (group experiences always count as 1; adding the same slot again adds to its quantity)
  - `{ "kind": "extra", "parent_item_id": <room line id>, "extra": "DRINKS" | extra id, "quantity": n }`. Extras belong to a room line at the same resort. Per-person extras default to the number of guests; `per_night` / `per_person_night` extras are charged for every night of that room. Extras with `needs_date: 1` in /api/v1/extras (airport transfer, ski tune, private guide day, sports massage, sunset hamper) also need `"service_date": "YYYY-MM-DD"` between the room's check_in and check_out (both included); the same extra on two dates is two lines. PATCH accepts `service_date` too.
  -> 201 `{ item_id, cart }`
- POST /api/v1/carts/{cart_id}/items `{ "items": [ ...up to 10 lines... ] }` adds several lines in one transaction: all or nothing (one bad line → 400/409, nothing added). An extra refers to a room line of the same request with `"parent_ref": <index of that room line>` instead of `parent_item_id`. -> 201 `{ item_ids, cart }`
- PATCH /api/v1/carts/{cart_id}/items/{item_id} `{ quantity, guests, meal_plan }` (guests / meal_plan for room lines) and DELETE /api/v1/carts/{cart_id}/items/{item_id} (removing a room also removes its extras).
- POST /api/v1/carts/{cart_id}/checkout `{ first_name, surname, email, card_number }` -> 201 `{ order }` with `code` (EDO-XXXX-XXXX-XXXX) and one `EDI-` reservation code per room. 409 if a line became unavailable (nothing is booked) or if the cart was already checked out (`order_code` included).
- POST /api/v1/orders/lookup `{ code, email }` -> `{ order }`, or 404 if the code or the email does not match.
- POST /api/v1/orders/{code}/cancel `{ email }` cancels the whole order and releases rooms and experience spots. Single rooms can still be cancelled with cancel_booking (EDI code + email).

Limits per client IP and hour: 30 new carts, 200 cart changes, 20 checkout attempts, 60 order lookups or cancels (HTTP 429 with Retry-After). IPv6 clients are counted per /64. There is also an overall booking cap per client IP that counts every room booked; checkout returns 429 when it is reached. A cart holds at most 20 lines, and a stay is at most 28 nights. Errors are `{ "error": "..." }` with status 400, 404, 409 or 429.

Over MCP the same cart is available as the cart tools (see section 3).
