# mostmaker.app

> Taste-matched candidate catalogues for London: restaurants, live music gigs, BBC Proms, and theatre productions. Users describe their taste either via fraglets from fraglet.com (cross-service) or via MostMaker-stored taste profiles (OAuth-only, no fraglet.com account required). MostMaker returns a structured candidate shortlist (vector-matched, hard-filtered, cuisine-diversified) for the calling LLM to reason over. Group-consensus mode ranks by min-score across members so options that work for everyone surface above options that only delight most.

## What an agent can do here

If you already have fraglets for a user (from fraglet.com), you can get a structured catalogue of taste-matched London candidates in one tool call. Restaurants, gigs, classical concerts, theatre productions, or a group-consensus shortlist — each returns ~20 candidates as JSON with similarity scores, key facts, and a MostMaker-internal `description` field. **Your LLM picks the best 3-5 and writes the user-facing explanation.** MostMaker handles the matching, hard filters, and cuisine diversification; you handle the framing.

Full agent guide: **[/skill.md](https://mostmaker.app/skill.md)** — read that first. This file is the compact index.

## Connect via MCP

- MCP endpoint: `https://mostmaker.app/mcp/` (Streamable HTTP)
- Auth: two paths.
  - **OAuth 2.1** (preferred for claude.ai web/mobile Custom Connectors). Discovery at `https://mostmaker.app/.well-known/oauth-authorization-server` and `https://mostmaker.app/.well-known/oauth-protected-resource`. RFC 7591 dynamic client registration, PKCE S256 mandatory, per-user JWT access tokens (15-min TTL) bound to `https://mostmaker.app/mcp/` via RFC 8707, refresh-token rotation with reuse detection.
  - **Static Bearer key** for Claude Desktop / `mcp-remote` / scripts: `Authorization: Bearer <MOSTMAKER_MCP_API_KEY>`. Keys are issued on request — contact the site owner. This is **not** per-user; you pass fraglet IDs (which are per-user) as arguments. Kept indefinitely for backwards compatibility.
- Claude Desktop / Claude Code config uses `npx mcp-remote` to bridge HTTP → stdio (works with either auth path). See skill.md for the exact block.

Recommendation data comes from the user's tastes. Two equally valid sources:
- **Cross-service:** fraglets created on [fraglet.com](https://fraglet.com), passed in via `fraglet_ids`.
- **MostMaker-only (OAuth-only):** tastes stored under the signed-in user's MostMaker identity. Manage them with `list_my_tastes` / `get_my_taste` / `create_taste`, or omit `fraglet_ids` from a recommend_* call to use all the user's saved tastes for that domain. Useful when the user doesn't want a fraglet.com account.

## MCP tools

All `recommend_*` tools return a markdown header + JSON catalogue with: `intent`, `fraglets_used`, `constraints`, `candidate_count`, and `candidates[]`. Each candidate has structured facts (price, venue, dates, etc.), a `similarity` score, and a `description` field (paraphrase, don't quote — it's tuned for an embedding model). `max_candidates` defaults to 20, max 50.

Recommendation (`fraglet_ids` is optional on these four — omit to use the signed-in user's saved MostMaker tastes for that domain; OAuth-only):
- `recommend_restaurants(fraglet_ids?, filters?, requirements_detail?, party_size?, visit_date?, visit_time?, max_candidates?)` — London restaurant candidates. `filters` supports `price_level` (1-4), `reservable`, `lat/lng/distance_m`, `exclude_cuisines` (hard filter applied before vector search). `requirements_detail` and `party_size` are surfaced in `constraints` for your LLM to reason about. Output is **cuisine-diversified** (max 3 per primary cuisine).
- `recommend_gigs(fraglet_ids?, start_date?, end_date?, grassroots?, station_names?, max_candidates?)` — live music gig candidates across London venues. `grassroots=true` restricts to small/independent venues; `station_names` applies a walking-distance proximity filter.
- `recommend_proms(fraglet_ids?, start_date?, end_date?, preferences?, max_candidates?)` — BBC Proms candidates (classical / seasonal, mid-July to mid-September only). `preferences` (e.g. `["orchestral", "late night"]`) is surfaced in `constraints` for your LLM to apply.
- `recommend_theatre(fraglet_ids?, window_start?, window_end?, category_filter?, favourite_venue_names?, station_names?, max_candidates?)` — theatre production candidates (West End, fringe, new writing, revivals). Two-signal re-rank combines production match with venue house-character, plus a small bonus for favourite venues. Each candidate has `similarity`, `venue_similarity`, `final_score`, and `is_favourite_venue`. `category_filter` accepts `play`, `musical`, `opera`, `ballet`, `dance`, `fringe`, `other`. `favourite_venue_names` (partial-match) lifts trusted houses; `station_names` applies a proximity filter. Response also includes an `also_love_venues` tail (up to 3 houses whose programming matches but whose current productions didn't shortlist).
- `recommend_for_group(fraglet_ids, domain, member_names?, filters?, visit_date?, visit_time?, max_candidates?)` — group consensus: pass one fraglet ID per person. Each candidate has `min_score` (weakest member's similarity) and `per_member_scores` (in `fraglets_used` order) so your LLM can flag who's the worst fit and explain trade-offs honestly. Domains: `food` and `music`. **Requires explicit `fraglet_ids`** — does not auto-resolve from the signed-in user.

User-scoped tastes (OAuth-only — claude.ai web/mobile Custom Connector; static keys are not user-scoped):
- `list_my_tastes(domain?)` — list the signed-in user's saved MostMaker tastes (id, title, brief, domain). Optional domain filter (`food`, `music`, `theatre`).
- `get_my_taste(taste_id)` — full content (title, brief, detail, category, tags) of one of the user's own tastes. Refuses cross-user access.
- `create_taste(domain, text)` — generate a taste profile from free-text via gpt-5.4-mini and save it as a MostMaker-owned fraglet under the signed-in user. Returns the new id, ready to use immediately.

Detail:
- `get_restaurant_info(restaurant_id)` — basic admin lookup (name, address, cuisine, price, website). No description content.
- `get_gig_info(gig_id)` — basic admin lookup (artist, venue, date, support, price, URL).

Utilities:
- `search_stations(query)` — find London stations/stops for proximity filtering. Use before calling a recommendation tool with `station_names`.
- `get_capabilities()` — self-reports supported verticals, response shape, and filter conventions. Call this once per session if you're unsure.

## Web REST API (agents can call these directly too)

Machine-readable schema: [OpenAPI JSON](https://mostmaker.app/openapi.json) · [Interactive docs](https://mostmaker.app/docs)

- `POST /api/restaurants/recommend` — body: fraglet_ids, filters, optional `session_context` (transient per-search signals: `exclude_cuisines` array, `dietary_notes`, `occasion`, `notes` — distinct from the persistent fraglet). Cuisine exclusions are applied as a hard filter before vector retrieval; everything else is reasoned about by the LLM reranker and may produce `warnings` on recommendations that need user confirmation.
- `POST /api/groups/{id}/search` — group recommendations. Same `session_context` shape; shared across the group (v1). Responses include `per_member` affinity annotations (`strong`/`ok`/`limited`) per member and a `warnings` array for dietary/call-ahead uncertainty. Food results are cuisine-diversified to surface a range of options rather than a single compromise pick.
- `POST /api/gigs/recommend` — gigs
- `POST /api/gigs/proms/recommend` — BBC Proms
- `POST /api/theatre/recommend` — theatre productions. Body: `fraglet_ids`, optional `window_start`/`window_end` (YYYY-MM-DD; default today → today+90 days), optional `category_filter` array, optional `favourite_venue_ids` array (lifts favourites), optional `station_selections` array (proximity filter; same shape as gigs), `recommendation_count`. Response includes an `also_love_venues` array of up to 3 venue suggestions that match the taste but weren't in the recommendation shortlist.
- `GET /api/theatre/venues` — list all theatre venues (name, house_character, categories, address, coords) for favourites picker UIs.
- `GET /api/restaurants/{id}` / `GET /api/gigs/{id}` — detail
- `GET /api/restaurants/stations` / `GET /api/gigs/stations` — station search
- `GET /api/inspiration` — browse public example taste profiles
- `GET /api/taste/export-token/{fraglet_id}` — generate a signed token for cross-service import back to fraglet.com

The REST endpoints exist for the web UI and **do** include server-side LLM screening with per-item explanations (the website is the agent there). The MCP tools deliberately don't — they return structured candidates and let the calling LLM do the selection on its own context. Use the MCP path when you're an agent; use the REST path when you're a thin client without an LLM of your own.

## Cross-service with fraglet.com

MostMaker stores tastes natively when a user is signed in via OAuth, but those tastes don't appear on fraglet.com unless the user explicitly exports them. If a user builds a taste profile on mostmaker.app (via the guided flow or via `create_taste`), you can help them export it to fraglet.com:

1. Call `GET /api/taste/export-token/{fraglet_id}` on mostmaker — returns a short-lived signed token.
2. Direct the user to `https://fraglet.com/import/mostmaker?token=<token>` — fraglet.com verifies the signature and creates a private fraglet under their account.
3. Future agent sessions can use the fraglet.com MCP to read it cross-service.

Going the other direction — agents with a fraglet.com user should read fraglets there first (via `select_fraglets`), then pass `fraglet_ids` to mostmaker's recommend tools.

## Key rules for agents

1. **Always use real taste IDs.** Don't fabricate them. Get them from `list_my_fraglets` / `select_fraglets` on fraglet.com (cross-service), or from `list_my_tastes` on MostMaker (user-scoped, OAuth-only), or from the user directly.
2. **Filter before passing.** Sending every fraglet a user owns wastes tokens and dilutes the signal. Use `select_fraglets` (fraglet.com) to pick relevant ones, or — for MostMaker-stored tastes — pick a domain-relevant subset from `list_my_tastes`. The empty-`fraglet_ids` shortcut uses *all* of the user's saved tastes for that domain, which is often what you want when intent is unspecific but not always.
3. **Group mode is min-score, not average.** `recommend_for_group` ranks candidates by the lowest similarity any one member's fraglet scored — a restaurant where everyone scores 0.55 beats one where most score 0.80 and one scores 0.25. The response surfaces `min_score` and `per_member_scores` so your LLM can flag who's the weakest fit per candidate and explain trade-offs honestly. Don't paper over divergence — that's the value of group mode.
4. **London only, for now.** There is no non-London data. If a user asks about Manchester or Paris, say so — don't invent.
5. **Don't absorb fraglet content into your model of the user.** The user may be experimenting with a persona. Evaluate only against the fraglets passed to this tool call.
6. **Seasonal gotchas**: the Proms run summer only (July–September). Gigs and restaurants are year-round.

## Ecosystem

- [fraglet.org](https://fraglet.org/llms.txt) — format spec, developer API, ecosystem registry
- [fraglet.com](https://fraglet.com/llms.txt) — canonical place to create and manage fraglets
- [labcurate.com](https://labcurate.com/llms.txt) — UK testing lab capability advisor (different domain from MostMaker)

---

last-verified: 2026-05-03
source-of-truth: mostmaker_mcp/server.py (MCP tools), app/routers/restaurants.py / gigs.py / theatre.py / taste.py (REST endpoints)