untappd-mcp 2.3.2 → 2.5.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "MCP server for Untappd — beers, breweries, venues, check-ins, wishlists, and your friend feed",
-    "version": "2.3.2"
+    "version": "2.5.0"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "Untappd",
       "source": "./",
       "description": "MCP server for Untappd — search beers/breweries/venues, read profiles/check-ins/wishlists, and post check-ins, toasts, and comments",
-      "version": "2.3.2",
+      "version": "2.5.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "untappd-mcp",
   "displayName": "Untappd",
-  "version": "2.3.2",
+  "version": "2.5.0",
   "description": "MCP server for Untappd — search beers/breweries/venues, read check-ins and wishlists, and post check-ins, toasts, and comments",
   "author": {
     "name": "Chris Hall",

package/README.md

@@ -37,7 +37,9 @@ it goes stale.
 | `UNTAPPD_USER_AGENT` | no | Override the User-Agent (default mimics the app). |
 | `UNTAPPD_TIMEZONE` | no | IANA timezone (e.g. `America/New_York`) that check-ins are stamped with when the call doesn't pass `timezone`. Set it when the server runs somewhere other than the drinker's zone (e.g. a hosted connector, usually UTC). Defaults to the server process's zone. |
 | `UNTAPPD_PHOTO_DIR` | no | The directory `untappd_checkin`'s `photo_path` must be inside (several allowed, separated by `:`). Defaults to `~/Downloads/untappd-mcp` — put a photo there to attach it. Any other file is refused, so a prompt-injected shout or comment can't publish an arbitrary image from your disk. |
-| `UNTAPPD_CACHE_DB` | no | Path to the local check-in cache SQLite file (default `~/.untappd-mcp/checkins.db`). The db file is always made owner-only (`0600`), and so are any directories the server creates plus the default `~/.untappd-mcp`; a directory you point this into that already exists keeps its permissions. Local/stdio only. |
+| `UNTAPPD_CACHE_DB` | no | Path to the local check-in cache SQLite file (default `~/.untappd-mcp/checkins.db`). A relative path or leading `~` resolves against your **home** directory, never the working directory, so every host (Claude Desktop, Claude Code, …) finds the same file; the resolved path is logged to stderr at startup. The db file is always made owner-only (`0600`), and so are any directories the server creates plus the default `~/.untappd-mcp`; a directory you point this into that already exists keeps its permissions. Local/stdio only. |
+| `UNTAPPD_CACHE_DIR` | no | Directory for the cache instead of `~/.untappd-mcp` (the file is `checkins.db` inside it). `UNTAPPD_CACHE_DB` wins if both are set. |
+| `UNTAPPD_RATE_LIMIT_PER_HOUR` | no | The hourly call limit the syncs' stop-before-429 guard enforces (default `100`, Untappd's documented per-token limit). Only change it if Untappd gives your token a different limit. |
 
 Copy `.env.example` to `.env` and fill it in for local use.
 
@@ -88,7 +90,163 @@ Writes (each asks you to confirm first — see [Confirmations](#confirmations)):
 
 Check-in cache: `untappd_sync_checkins`, `untappd_sync_user_beers`,
 `untappd_cache_has_had`, `untappd_cache_has_had_many`, `untappd_cache_not_had`,
-`untappd_cache_query`, `untappd_top_not_had`, `untappd_cache_forget`.
+`untappd_cache_query`, `untappd_top_not_had`, `untappd_cache_status`, `untappd_cache_forget`,
+`untappd_sync_wishlist` (mirrors a user's wishlist locally so picks can boost wishlisted beers),
+`untappd_sync_brewery_likes` (mirrors the breweries a user likes/follows on Untappd, as "untappd" favorites),
+`untappd_sync_user_venues` + `untappd_cache_has_visited` (a user's full venue history — "has this person
+been here?" — which pages fully for any public/friend account, unlike their check-ins).
+
+Trip planning: `untappd_trip_check` takes a user (or `usernames` + `mode`) and up to 25 stops — each a
+`venue_id`, a `name` (+ `city`/`state`), a `lat`/`lng`, and/or a `brewery_id` — and returns per stop:
+whether they've been there (first/recent visit, total visits, the matched venues incl. Untappd's
+"(duplicate of …)" copies; a brewery stop is matched by the brewery's name), how many of the brewery's
+beers they've had, and the top N (default 4) **not-had** beers by Untappd global rating, with an
+optional `style` filter (out-of-production beers skipped unless asked). Visits and has-had are answered
+from the cache only; the one API call it may make is `brewery/beer_list` for a brewery whose list isn't
+cached or is past its 7-day TTL — at most `api_budget` (default 5; `0` = strictly cache-only, using a
+stale list flagged `stale`), under the rate-limit guard. Favorite venues and breweries are flagged,
+`prefer_favorites` (default true) boosts wishlisted and favorite-brewery beers (liked on Untappd, derived or
+manual), and a stop within
+`near_favorite_radius_m` (default 2 km) of a favorite venue gets `near_favorites` and a "Near a
+favorite: …" hint.
+
+Group checks: `untappd_cache_has_had_many` and `untappd_top_not_had` accept `usernames` (up to 10)
+with `mode: "none_had"` (default — beers new to everyone) or `"any_not_had"` (beers at least one of
+them still needs); each beer says who has and hasn't had it.
+
+What they drank at a venue (opt-in, costs calls): `untappd_sync_venue_drinks` fetches the beer from
+each cached venue's first and most-recent visit check-in (`checkin/view`, budgeted by `max_calls`,
+stops before the rate limit). It's a partial picture — two check-ins per venue at most — shown in
+`untappd_cache_has_visited` as `drinks`.
+
+Favorites (cache only, never written to Untappd): `untappd_favorites_list` lists a user's favorite
+beers, breweries and venues, each once with its `sources` and a `reason`. **Derived** favorites come
+from the synced history — venues with ≥5 check-ins or visits spanning ≥3 distinct months; breweries
+with ≥5 beers had and an average rating ≥3.75, or ≥15 beers; beers rated ≥4.25 or had ≥3 times —
+and every threshold can be overridden per call. **Manual** favorites are added and removed with
+`untappd_favorite_add` / `untappd_favorite_remove` (local table, optional note). Results from
+`untappd_cache_has_had`, `untappd_cache_has_had_many`, `untappd_cache_has_visited`, `untappd_brewery_beers`, `untappd_venue_menu`
+and `untappd_top_not_had` carry a `favorite` field `{is_favorite, sources, reason}`, and
+`untappd_top_not_had` ranks wishlisted beers and beers from favorite breweries higher by default
+(`prefer_favorites: false` turns that off); `untappd_trip_check` carries the same flags and boost.
+
+**Untappd** favorites (breweries only): `untappd_sync_brewery_likes` mirrors the breweries a user
+"likes" on Untappd (`user/brewerylikes` — the app calls them "followings"; works for another user's
+public/friend account, ~50 per call). Like the wishlist sync it's a full pass from the top, resumable
+(cursor saved every page, `another_run_needed`, `percent`), stops before the rate limit with
+`stopped_for_rate_limit` + resume info, and only drops unliked breweries once a pass finishes. Liked
+breweries then carry the source `untappd` everywhere favorites appear — merged with `derived` and
+`manual`, each source listed once — and count for the `prefer_favorites` boost and trip_check's flags.
+`untappd_cache_status` reports each user's `brewery_likes` coverage, and `untappd_cache_forget` removes them.
+
+Untappd has **no followed or favorite *venue* list** at all (no web or API route; `venue/info` has no
+per-user flag), so venue favorites are derived + manual only. `brewery/info`'s
+`claimed_status.follow_status` describes the **signed-in** account, like `have_had` below, so it is
+never used for anyone else — the synced likes list is how to see another user's.
+
+Cached reads (to stretch the ~100 calls/hour limit): `untappd_brewery_beers` keeps each brewery's
+list for 7 days, and `untappd_venue_menu` / `untappd_venue_activity` keep results for 6 hours; each
+reports where the answer came from and takes `refresh: true` to re-fetch. Untappd's `have_had` on a
+brewery's beer list describes the **signed-in** account, never the user you're asking about, so it
+isn't cached or returned — use `untappd_cache_has_had_many` for any user.
+
+Menu picks: `untappd_menu_pick` (tap-list lines in, ranked not-had beers out),
+`untappd_venue_pick` (same, from a venue's Untappd menu).
+
+## Picking a beer off a menu
+
+`untappd_menu_pick` turns "find Mer a beer" from a menu photo into one call.
+Give it the lines as read off the board:
+
+```json
+{
+  "username": "mer",
+  "items": [
+    "HAP & HARRY'S TENNESSEE LAGER $6",
+    "I BELIEVE IN NASHVILLE BLONDE",
+    "JACKALOPE FENNARIO IPA",
+    "BEARDED IRIS HOMESTYLE",
+    "BLACK ABBEY SEASONAL",
+    "ROTATING CIDER"
+  ],
+  "venue_city": "Nashville",
+  "top_n": 2
+}
+```
+
+In one call it:
+
+1. **Freshens the cache.** If the user's distinct-beers list is already complete
+   it does an incremental refresh, stopping at the first beer that's cached and
+   unchanged (usually one page). If the list is empty or partial it backfills
+   in the same call until done or `api_budget` (default 60 calls, shared by
+   every step) runs out. You never need to call a sync tool first.
+2. **Resolves each line to a beer.** It strips prices, sizes, ABV and
+   punctuation, searches Untappd (falling back to a query without the style
+   word, because Untappd search matches every term), and scores the candidates
+   on brewery match, beer-name match (so "Homestyle" isn't read as "Double
+   Homestyle"), check-in volume (the canonical entry wins over a 3-check-in
+   duplicate) and `venue_city`. Up to 4 searches run at once, and a 429 is
+   retried with backoff. Resolutions are cached on disk, so the next visit to
+   the same venue costs no searches.
+3. **Handles generic lines.** `<Brewery> SEASONAL` / `ROTATING` becomes a
+   `possible` list of that brewery's seasonal-looking beers, marked
+   `needs_confirmation`. A line with no brewery (`ROTATING CIDER`) comes back
+   `unresolved: "ask bartender"`.
+4. **Checks every beer against the cache** (both sources, as `has_had_many` does).
+5. **Ranks the not-had beers** by global rating, applies `style_filter`, and
+   returns the top `top_n` as `picks`.
+
+Output for the call above, with Mer having had Fennario (abridged: `not_had`
+also lists the Tennessee Lager at 3.33, `possible` lists six candidates, and a
+`freshness` block is appended):
+
+```json
+{
+  "picks": [
+    { "item": "BEARDED IRIS HOMESTYLE", "bid": 1502190, "name": "Homestyle", "brewery": "Bearded Iris Brewing",
+      "style": "IPA - New England / Hazy", "abv": 6, "global_rating": 3.98,
+      "reason": "not had · 3.98 global rating · #1 of 3 not-had beers on this list" },
+    { "item": "I BELIEVE IN NASHVILLE BLONDE", "bid": 3780741, "name": "I Believe In Nashville",
+      "brewery": "I Believe Brewing Company", "style": "Blonde / Golden Ale - American", "abv": 4.5,
+      "global_rating": 3.54, "reason": "not had · 3.54 global rating · #2 of 3 not-had beers on this list" }
+  ],
+  "had": [
+    { "item": "JACKALOPE FENNARIO IPA", "bid": 1893601, "name": "Fennario", "brewery": "Jackalope Brewing Company",
+      "count": 3, "last_date": "2025-08-01T20:00:00.000Z", "user_rating": 3.75 }
+  ],
+  "possible": [
+    { "item": "BLACK ABBEY SEASONAL", "brewery": "The Black Abbey Brewing Company",
+      "reason": "seasonal-looking beers from this brewery",
+      "candidates": [
+        { "bid": 1223176, "name": "Chronicles Festbier", "style": "Festbier", "abv": 4.9, "global_rating": 3.672, "had": false }
+      ],
+      "needs_confirmation": true }
+  ],
+  "unresolved": [{ "item": "ROTATING CIDER", "reason": "ask bartender" }],
+  "sync": { "mode": "backfill", "api_calls": 1 },
+  "api_calls": 11,
+  "api_budget": 60,
+  "another_run_needed": false
+}
+```
+
+`sync` says what the refresh did; coverage lives in `freshness`. If the budget
+runs out before the backfill finishes, `freshness.coverage_complete` is `false`,
+`another_run_needed` is `true`, and the `freshness` caveat warns that a "not
+had" may be a false negative. Calling again continues from where it stopped.
+
+**Quota.** When an Untappd response carries `X-Ratelimit-Remaining`, the server
+remembers it for the hour, and every budgeted tool (`menu_pick`, `venue_pick`,
+`top_not_had`, both syncs) caps its budget to what's left. The result then
+includes `quota_remaining`, plus `budget_clamped_to_quota: true` when the cap
+applied. Untappd's public API documents the header; if the private API this
+server uses doesn't send it, budgets work exactly as before.
+
+`untappd_venue_pick` takes an Untappd venue URL (`https://untappd.com/v/<slug>/<id>`)
+or id instead of `items`. It pages through the venue's whole verified menu, takes
+the venue's city from it, and runs the same check and ranking. Menu items already
+carry beer ids, so there is no search step.
 
 ## Check-in cache
 
@@ -96,10 +254,19 @@ The Untappd API only exposes paged lists (50 per page) and has **no** "has this
 user ever had beer X?" lookup — answering that from the API alone means paging an
 entire history (often 11k+ check-ins) against a tight ~100-calls/hour rate limit.
 These tools maintain a SQLite mirror so the question is answered instantly,
-offline, with zero API calls. The mirror is a local file
-(`node:sqlite`, path via `UNTAPPD_CACHE_DB`); the store is injectable, so another
+offline, with zero API calls. The mirror is a local SQLite file
+(`node:sqlite`, default `~/.untappd-mcp/checkins.db`, overridable with
+`UNTAPPD_CACHE_DB` / `UNTAPPD_CACHE_DIR`). The store is injectable, so another
 deployment can back it differently without the tools changing.
 
+**Persistence.** The file survives restarts, and a backfill that was cut off
+(rate limit, crash, host quit) resumes from its saved offset on the next sync.
+The file runs in WAL mode with a busy timeout and does every write in a
+transaction, so two hosts open at the same time can share it. The schema is
+versioned (`PRAGMA user_version`) and only ever migrated forward, adding
+columns and tables, so an upgrade never wipes it. `untappd_cache_status` shows
+the resolved path, size, schema version and per-user coverage.
+
 Two sync sources fill the cache:
 
 - **`untappd_sync_user_beers`** pages `user/beers` — the user's **complete
@@ -119,6 +286,18 @@ Both are resumable: they fetch `max_pages` per call (default 10), persist
 progress after every page, and set `another_run_needed: true` until done — just
 call again until it's `false`.
 
+**Rate limit.** Every API response is recorded (time, status and any
+`X-Ratelimit-*` / `Retry-After` headers) and, once the cache is open, logged in
+the cache file so every process sharing it — and the next one — counts the same
+hour. The syncs check that count **before every page** and stop cleanly with
+`stopped_for_rate_limit: true` and `rate_limit.resume_at` when the next call
+would leave fewer than 2 of the ~100 hourly calls; a 429 that slips through also
+stops the run cleanly instead of failing it. Progress is already saved, so
+re-run after `resume_at`. `untappd_cache_status` shows the current picture under
+`rate_limit`. Note: the v4 API sends `X-Ratelimit-Remaining: 0` on every
+successful response, so that header is ignored until it reports a live
+(non-zero) value; the estimate rests on the local call count.
+
 **Query** the cache with no further API calls. The has-had tools consult **both**
 sources (a hit in either counts as had):
 
@@ -155,7 +334,8 @@ telling you to add them as a friend first.
 user's dated check-ins, comments and venues — stay until you remove them. The
 file is created owner-only (directory `0700`, database `0600`, and older
 installs are tightened on open). `untappd_cache_forget` deletes one user's
-cached check-ins, distinct-beers list and sync state after a confirmation
+cached check-ins, distinct-beers list, venue history, wishlist copy, liked
+breweries, local favorites, venue drinks and sync state after a confirmation
 (preview shows the username and row counts); it touches only the local cache,
 never Untappd, and a later sync can re-fetch. Deleting the file removes
 everything.