untappd-mcp 1.3.0 → 1.4.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": "1.3.0"
+    "version": "1.4.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": "1.3.0",
+      "version": "1.4.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "untappd-mcp",
   "displayName": "Untappd",
-  "version": "1.3.0",
+  "version": "1.4.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

@@ -33,6 +33,7 @@ it goes stale.
 | `UNTAPPD_DEVICE_ID` | no | Stable device UUID the token is keyed to (a default is provided). |
 | `UNTAPPD_UTV` | no | API version param (default `4.0.0`). |
 | `UNTAPPD_USER_AGENT` | no | Override the User-Agent (default mimics the app). |
+| `UNTAPPD_CACHE_DB` | no | Path to the local check-in cache SQLite file (default `~/.untappd-mcp/checkins.db`). Local/stdio only. |
 
 Copy `.env.example` to `.env` and fill it in for local use.
 
@@ -81,6 +82,59 @@ Writes (confirm-gated — return a dry-run preview unless called with
 `untappd_wishlist_add`, `untappd_wishlist_remove`, `untappd_delete_checkin`,
 `untappd_add_friend`, `untappd_accept_friend`, `untappd_reject_friend`, `untappd_remove_friend`.
 
+Check-in cache: `untappd_sync_checkins`, `untappd_cache_has_had`,
+`untappd_cache_has_had_many`, `untappd_cache_query`.
+
+## Check-in cache
+
+The Untappd API only exposes paged, most-recent-first check-in 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 of a
+user's check-ins so the question is answered instantly, offline, with zero API
+calls. The mirror is a local file on the stdio/desktop server (`node:sqlite`,
+path via `UNTAPPD_CACHE_DB`) and a per-user Durable Object on the remote
+connector — the tools and behaviour are identical either way.
+
+**Recommended workflow — sync first, then query:**
+
+1. **Sync** with `untappd_sync_checkins` (omit `username` for your own account).
+   It is incremental (stops as soon as it reaches already-cached check-ins) and
+   resumable: while the initial backfill is incomplete it pages backwards up to
+   `max_pages` per call (default 10) and **persists progress after every page**,
+   so an interrupted run never loses data. The summary reports `rows_added`,
+   `pages_fetched`, a `backfill_percent` estimate, and `another_run_needed` — if
+   that is `true`, just call it again (and again) until it is `false`. That
+   covers both extending the backfill downwards and catching up a burst of new
+   check-ins too large for one run (`catchup_in_progress`). Spreading the work
+   across several runs keeps you under the rate limit.
+2. **Query** the cache with no further API calls:
+   - `untappd_cache_has_had` — has the user had a beer, by exact `bid` or a
+     case-insensitive `beer_name` substring; returns count, best rating, last
+     date, and the matching check-ins.
+   - `untappd_cache_has_had_many` — cross-check a whole list of `bids` in one
+     call (e.g. a venue's menu) → had/not-had per beer.
+   - `untappd_cache_query` — filter cached check-ins by brewery, style,
+     `min_rating`, venue, and/or date range, with sorting and a limit.
+
+   Every read result carries a `freshness` block (`last_synced_at`,
+   `backfill_complete`, `backfill_percent`) and, when the backfill is
+   incomplete, a `caveat` — so a "not found" can be reported as possibly a false
+   negative for older history until the sync finishes.
+
+Syncing **another** user goes through the same authed endpoint as
+`untappd_user_checkins`, so Untappd's privacy rules apply: it only works if that
+account is public or your friend. Otherwise the sync returns a clear error
+telling you to add them as a friend first.
+
+On the remote connector each logged-in user gets their **own** durable cache
+(keyed by their account), holding only the check-ins their account was allowed
+to fetch — one user can never read another's cache. See
+[`docs/DEPLOY-CONNECTOR.md`](docs/DEPLOY-CONNECTOR.md) for the one-time deploy
+step this adds. `untappd_healthcheck` reports the running version and the exact
+tool set (count + names + a stable hash), so you can confirm which build a
+connector is serving.
+
 ## Development
 
 ```sh

package/SKILL.md

@@ -45,3 +45,32 @@ Each returns a dry-run preview and makes NO network call unless called with
   `untappd_search_beer`; optional `rating` 0–5 in 0.25 steps, `shout`, venue).
 
 Photo attachment and wishlist add/remove are not yet supported.
+
+## Check-in cache
+
+The API can't answer "has this user ever had beer X?" without paging their whole
+history (50/page, rate-limited). These tools keep a SQLite mirror so that
+question is answered instantly with **no** API calls. On the stdio server the
+mirror is a local file (`UNTAPPD_CACHE_DB`, default `~/.untappd-mcp/checkins.db`);
+on the remote connector it's a per-user Durable Object. Same tools either way.
+
+**Sync first, then query:**
+
+- `untappd_sync_checkins` — fetch check-ins into the cache. Incremental (stops at
+  already-cached check-ins) and resumable: while the backfill is incomplete it
+  pages backwards up to `max_pages` per call (default 10) and saves progress
+  after every page. If the returned `another_run_needed` is true, call it again
+  until it is false (covers both the backfill and catching up large bursts of
+  new check-ins). Omit `username` for your own account;
+  syncing another user needs their account public or a friend (friends-only, same
+  as `untappd_user_checkins`).
+- `untappd_cache_has_had` — has the user had a beer? By exact `bid` or a
+  case-insensitive `beer_name` substring.
+- `untappd_cache_has_had_many` — batch had/not-had for a list of `bids` in one
+  call (venue-menu cross-check).
+- `untappd_cache_query` — filter cached check-ins by brewery, style, `min_rating`,
+  venue, and date range, with sort + limit.
+
+Every cache read returns a `freshness` block (and a `caveat` when the backfill is
+incomplete) so you can flag that a "not found" may be a false negative until the
+sync finishes.