untappd-mcp 2.4.0 → 2.5.0

package/dist/tools/venue.js

@@ -2,7 +2,18 @@ import { z } from 'zod';
 import { minifiedResult, resolveView, toolAnnotations, viewParam, viewResult } from '@chrischall/mcp-utils';
 import { compactCheckins, UNTAPPD_VIEWS, upstreamCompact } from '../compact.js';
 import { walkVenueMenu } from '../menu/venue-menu.js';
-export function registerVenueTools(server, client) {
+import { cachedResponse, VENUE_RESPONSE_TTL_MS } from '../cache/response-cache.js';
+import { optionalCache } from './cache-optional.js';
+import { favoriteLookup } from '../cache/favorites.js';
+const TTL_HOURS = VENUE_RESPONSE_TTL_MS / 3_600_000;
+const RefreshArg = z
+    .boolean()
+    .optional()
+    .describe(`Bypass the ${TTL_HOURS}-hour local cache and call Untappd (default false)`);
+export function registerVenueTools(server, client, cacheProvider) {
+    const cacheOrNone = optionalCache(cacheProvider);
+    /** The `cache` block a cached result carries (only when a cache is in use). */
+    const cacheBlock = (r) => r.expires_at === null ? {} : { cache: { hit: r.hit, fetched_at: r.fetched_at, expires_at: r.expires_at } };
     server.registerTool('untappd_search_venue', {
         title: 'Search Untappd venues',
         description: 'Search Untappd for venues (bars, breweries, restaurants) by name. Returns matches with their venue id, ' +
@@ -37,10 +48,15 @@ export function registerVenueTools(server, client) {
             'spans multiple sections — e.g. a 23-beer wall that comes back with 2 items. This tool forwards the ' +
             'section_limit / section_offset paging params venue/info echoes back but never receives, walks sections up to a ' +
             'per-call max_pages budget (respecting the ~100 calls/hour limit — it does NOT loop to completion in one call), and ' +
-            'flattens to [{bid, name, brewery, style, abv, price, serving_type, menu, section}]. Like the sync tools it is ' +
+            'flattens to [{bid, name, brewery, brewery_id, style, abv, price, serving_type, menu, section}]. Like the sync tools it is ' +
             'resumable: when the budget runs out before full coverage it returns another_run_needed:true plus next_section_offset ' +
             'to pass back on the next call. truncated:true means the upstream returned no more sections short of total_count ' +
-            '(e.g. it ignored the paging params) — not resumable. Get an id from untappd_search_venue. Read-only.',
+            '(e.g. it ignored the paging params) — not resumable. Results are cached locally for ' + TTL_HOURS + ' hours per ' +
+            'venue + paging params (cache.hit, fetched_at, expires_at) so repeated trip planning does not re-spend calls; ' +
+            'refresh:true re-fetches. With the cache, the result also carries favorite {is_favorite, sources, reason} for the ' +
+            'venue, and favorite / brewery_favorite on each beer that is one (derived from username\'s history or added ' +
+            'with untappd_favorite_add; default your account) — applied on read, so never stale. Get an id from ' +
+            'untappd_search_venue. Read-only.',
         annotations: toolAnnotations({ title: "Get a venue's verified beer menu (section-paged)", readOnly: true, idempotent: true, openWorld: true }),
         inputSchema: z.object({
             venue_id: z.number().int().positive().describe('Untappd venue id'),
@@ -49,40 +65,72 @@ export function registerVenueTools(server, client) {
             section_offset: z.number().int().min(0).optional().describe('Section offset to start from; pass a prior next_section_offset to resume (default 0).'),
             max_pages: z.number().int().min(1).max(10).optional().describe('API calls to spend THIS run — page budget, not page size (default 3). Resume with next_section_offset if another_run_needed.'),
             sort: z.string().optional().describe("Menu sort key (e.g. 'publish_order', 'highest_rated'). Optional."),
+            refresh: RefreshArg,
+            username: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('Whose favorites to mark (cache only; default your configured account)'),
         }),
-    }, async ({ venue_id, menu_id, section_limit, section_offset, max_pages, sort }) => {
-        // Per CLAUDE.md's rate-limit design this spends at most `max_pages` API
-        // calls per run and hands the caller next_section_offset to resume, rather
-        // than looping to completion. The walk itself lives in walkVenueMenu.
-        const startOffset = section_offset ?? 0;
-        const walk = await walkVenueMenu(client, venue_id, {
-            menuId: menu_id,
-            sectionLimit: section_limit,
-            sectionOffset: startOffset,
-            maxPages: max_pages ?? 3,
-            sort,
-        });
-        const { totalCount, sawMenu, pagesFetched, reachedEnd } = walk;
-        const beers = walk.beers.map(({ rawBeer: _b, rawBrewery: _w, ...b }) => b);
-        if (!sawMenu) {
-            return minifiedResult({ venue_id, total_count: 0, returned: 0, pages_fetched: pagesFetched, another_run_needed: false, truncated: false, beers: [], note: 'No verified menu on this venue.' });
-        }
-        const covered = totalCount > 0 && beers.length >= totalCount;
-        const another_run_needed = !reachedEnd; // stopped only because the page budget ran out mid-list
-        // Only a walk that started at the top of the list can judge a genuine
-        // shortfall as truncated; a resumed tail legitimately returns fewer than
-        // the whole-menu total_count and is not truncated.
-        const truncated = reachedEnd && !covered && startOffset === 0 && totalCount > 0;
+    }, async ({ venue_id, menu_id, section_limit, section_offset, max_pages, sort, refresh, username }) => {
+        const key = `venue_menu:${venue_id}:${JSON.stringify([menu_id ?? null, section_limit ?? null, section_offset ?? 0, max_pages ?? 3, sort ?? null])}`;
+        const cache = cacheOrNone();
+        const r = await cachedResponse(cache, key, 'venue_menu', () => fetchMenu(), { refresh });
+        // Favorites are applied on read (not cached), so a change shows even on a cache hit.
+        const user = username ?? client.loginName;
+        if (!cache || !user)
+            return minifiedResult({ ...r.data, ...cacheBlock(r) });
+        const beers = (Array.isArray(r.data.beers) ? r.data.beers : []);
+        const ids = (k) => beers.map((b) => b[k]).filter((x) => typeof x === 'number');
+        const favs = await favoriteLookup(cache, [user], { venue: [venue_id], beer: ids('bid'), brewery: ids('brewery_id') });
         return minifiedResult({
-            venue_id,
-            total_count: totalCount,
-            returned: beers.length,
-            pages_fetched: pagesFetched,
-            another_run_needed,
-            ...(another_run_needed ? { next_section_offset: walk.nextOffset } : {}),
-            truncated,
-            beers,
+            ...r.data,
+            favorite: favs.get('venue', venue_id),
+            beers: beers.map((b) => {
+                const beerFav = favs.get('beer', b.bid);
+                const breweryFav = favs.get('brewery', b.brewery_id);
+                return {
+                    ...b,
+                    ...(beerFav.is_favorite ? { favorite: beerFav } : {}),
+                    ...(breweryFav.is_favorite ? { brewery_favorite: breweryFav } : {}),
+                };
+            }),
+            ...cacheBlock(r),
         });
+        async function fetchMenu() {
+            // Per CLAUDE.md's rate-limit design this spends at most `max_pages` API
+            // calls per run and hands the caller next_section_offset to resume, rather
+            // than looping to completion. The walk itself lives in walkVenueMenu.
+            const startOffset = section_offset ?? 0;
+            const walk = await walkVenueMenu(client, venue_id, {
+                menuId: menu_id,
+                sectionLimit: section_limit,
+                sectionOffset: startOffset,
+                maxPages: max_pages ?? 3,
+                sort,
+            });
+            const { totalCount, sawMenu, pagesFetched, reachedEnd } = walk;
+            const beers = walk.beers.map(({ rawBeer: _b, rawBrewery: w, ...b }) => typeof w?.brewery_id === 'number' ? { ...b, brewery_id: w.brewery_id } : b);
+            if (!sawMenu) {
+                return { venue_id, total_count: 0, returned: 0, pages_fetched: pagesFetched, another_run_needed: false, truncated: false, beers: [], note: 'No verified menu on this venue.' };
+            }
+            const covered = totalCount > 0 && beers.length >= totalCount;
+            const another_run_needed = !reachedEnd; // stopped only because the page budget ran out mid-list
+            // Only a walk that started at the top of the list can judge a genuine
+            // shortfall as truncated; a resumed tail legitimately returns fewer than
+            // the whole-menu total_count and is not truncated.
+            const truncated = reachedEnd && !covered && startOffset === 0 && totalCount > 0;
+            return {
+                venue_id,
+                total_count: totalCount,
+                returned: beers.length,
+                pages_fetched: pagesFetched,
+                another_run_needed,
+                ...(another_run_needed ? { next_section_offset: walk.nextOffset } : {}),
+                truncated,
+                beers,
+            };
+        }
     });
     server.registerTool('untappd_venue_by_foursquare', {
         title: 'Look up an Untappd venue by Foursquare id',
@@ -99,17 +147,23 @@ export function registerVenueTools(server, client) {
     server.registerTool('untappd_venue_activity', {
         title: 'Get recent check-ins at a venue',
         description: 'Get the recent public check-ins at a venue by its id — who was there, what they drank, and their ratings. ' +
-            'Page backwards with max_id (the pagination.max_id from a prior call). Read-only.',
+            'Page backwards with max_id (the pagination.max_id from a prior call). Cached locally for ' + TTL_HOURS + ' hours ' +
+            'per venue + limit + max_id (cache.hit, fetched_at, expires_at); refresh:true re-fetches. Read-only.',
         annotations: toolAnnotations({ title: 'Get recent check-ins at a venue', readOnly: true, idempotent: false, openWorld: true }),
         inputSchema: z.object({
             venue_id: z.number().int().positive().describe('Untappd venue id'),
             limit: z.number().int().min(1).max(50).optional().describe('Max check-ins (1–50, default 25)'),
             max_id: z.number().int().positive().optional().describe('Return check-ins older than this id (for paging)'),
+            refresh: RefreshArg,
             view: viewParam(UNTAPPD_VIEWS, { note: 'compact projects each check-in to {id, user, beer, brewery, venue, rating, comment, toast/comment counts}; "full" returns Untappd\'s whole ~5 KB record.' }),
         }),
-    }, async ({ venue_id, limit, max_id, view }) => {
-        const data = await client.get(`/venue/checkins/${venue_id}`, { limit, max_id });
+    }, async ({ venue_id, limit, max_id, refresh, view }) => {
+        // The RAW response is cached, so either view can be served from one entry.
+        const key = `venue_activity:${venue_id}:${limit ?? ''}:${max_id ?? ''}`;
+        const r = await cachedResponse(cacheOrNone(), key, 'venue_activity', () => client.get(`/venue/checkins/${venue_id}`, { limit, max_id }), { refresh });
         const v = resolveView(view, UNTAPPD_VIEWS);
-        return viewResult(v, v === 'compact' ? compactCheckins(data) : data);
+        const shaped = v === 'compact' ? compactCheckins(r.data) : r.data;
+        const extra = cacheBlock(r);
+        return viewResult(v, Object.keys(extra).length && shaped && typeof shaped === 'object' ? { ...shaped, ...extra } : shaped);
     });
 }

package/dist/version.js

@@ -3,4 +3,4 @@
 // json's `extra-files`), and `versionSyncTest` guards that it stays equal to
 // package.json. Import VERSION wherever the version is needed rather than
 // re-declaring it.
-export const VERSION = '2.4.0'; // x-release-please-version
+export const VERSION = '2.5.0'; // x-release-please-version

package/mint.yaml

@@ -43,6 +43,11 @@ env:
     help: >-
       IANA timezone (e.g. America/New_York) that check-ins are stamped with
       when a call passes no timezone. Defaults to the server's own zone.
+  - name: UNTAPPD_RATE_LIMIT_PER_HOUR
+    required: false
+    help: >-
+      Hourly Untappd API call limit the syncs' stop-before-429 guard enforces
+      (default 100, Untappd's documented per-token limit).
   - name: UNTAPPD_PHOTO_DIR
     required: false
     help: >-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "untappd-mcp",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "mcpName": "io.github.chrischall/untappd-mcp",
   "description": "Untappd MCP server for Claude — developed and maintained by AI (Claude Code)",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/untappd-mcp",
     "source": "github"
   },
-  "version": "2.4.0",
+  "version": "2.5.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "untappd-mcp",
-      "version": "2.4.0",
+      "version": "2.5.0",
       "transport": {
         "type": "stdio"
       },
@@ -79,6 +79,13 @@
           "format": "string",
           "isSecret": false
         },
+        {
+          "name": "UNTAPPD_RATE_LIMIT_PER_HOUR",
+          "description": "Hourly Untappd API 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.",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": false
+        },
         {
           "name": "UNTAPPD_PHOTO_DIR",
           "description": "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.",

package/skills/untappd-mcp/SKILL.md

@@ -205,6 +205,36 @@ Query tools (has-had ones consult BOTH sources — a hit in either = had):
   capped at `api_budget` per run (partial/another_run_needed when exceeded).
 - `untappd_cache_query` — filter cached check-ins by brewery, style, `min_rating`,
   venue, and date range.
+- **Groups:** `untappd_cache_has_had_many` and `untappd_top_not_had` take
+  `usernames` (instead of `username`) plus `mode`: `none_had` (default — new to
+  everyone) or `any_not_had` (at least one of them still needs it). Each beer
+  lists `had_by` / `not_had_by`; freshness is reported per user.
+- `untappd_sync_venue_drinks` — opt-in, costs one call per check-in: fetches the
+  beer from each cached venue's first/recent visit (`checkin/view`), budgeted by
+  `max_calls`; `untappd_cache_has_visited` then shows them as `drinks`. Partial
+  by design (two check-ins per venue at most).
+- **Favorites** (local, no API): `untappd_favorites_list` (filter `kind`
+  beer|brewery|venue, `source` derived|manual|untappd, override `thresholds`),
+  `untappd_favorite_add` / `untappd_favorite_remove` (manual, with a note —
+  never written to Untappd). Derived defaults: venue ≥5 check-ins or ≥3 distinct
+  months; brewery ≥5 beers with avg ≥3.75, or ≥15 beers; beer rated ≥4.25 or
+  had ≥3 times. has_had / has_had_many / has_visited / brewery_beers / venue_menu /
+  top_not_had results carry `favorite` {is_favorite, sources, reason};
+  `untappd_top_not_had` boosts wishlisted (+0.5) and favorite-brewery (+0.25)
+  beers unless `prefer_favorites: false`. `untappd_sync_brewery_likes` mirrors
+  the breweries a user likes/follows on Untappd (resumable, rate-guarded); they
+  carry the source `untappd` (merged with derived/manual) and count for the boost.
+  Untappd has no followed-venue list, so venue favorites are derived + manual.
+  `brewery_info`'s `follow_status` is the signed-in account's, never another user's.
+- `untappd_trip_check` — a whole trip in one call: per stop (`venue_id`, `name`
+  + `city`/`state`, `lat`/`lng`, and/or `brewery_id`) → visited with dates,
+  beers had from that brewery, and the top N (default 4) not-had beers by global
+  rating (`style` filter). Cache only, except `brewery/beer_list` for a missing or
+  >7-day-old list (`api_budget`, default 5; 0 = cache only). Flags favorite
+  venues/breweries, boosts wishlist/favorite-brewery beers (`prefer_favorites`),
+  and hints when a favorite venue is within `near_favorite_radius_m` (2 km).
+  Sync first: `untappd_sync_user_venues`, `untappd_sync_user_beers`,
+  `untappd_sync_wishlist`, `untappd_sync_brewery_likes`.
 
 **Retention.** The cache keeps what you sync until you remove it — including
 friends' dated check-ins, comments and venues. `untappd_cache_forget` (confirmation-gated)