untappd-mcp 2.3.2 → 2.4.0

package/dist/tools/cache.js

@@ -4,16 +4,17 @@ import { beerMetaFrom } from '../cache/store.js';
 import { syncCheckins } from '../cache/sync.js';
 import { syncUserBeers } from '../cache/sync-beers.js';
 import { CONFIRM_FLOW, confirmWrite } from './confirm.js';
+import { clampToQuota } from '../quota.js';
 // Re-fetch cached beer metadata at most this often; a hit newer than this skips
 // the beer/info API call.
 const BEER_META_TTL_MS = 30 * 24 * 60 * 60 * 1000;
-const UsernameArg = z
+export const UsernameArg = z
     .string()
     .min(1)
     .optional()
     .describe('Untappd username. Omit to use your own configured account (UNTAPPD_USERNAME).');
 /** Resolve the target username (raw, un-encoded) — explicit arg else configured login. */
-function resolveUser(username, loginName) {
+export function resolveUser(username, loginName) {
     const u = username ?? loginName;
     if (!u) {
         throw createHelpfulError('No username given and no configured account to fall back to.', {
@@ -22,6 +23,12 @@ function resolveUser(username, loginName) {
     }
     return u;
 }
+/** Report the quota only when Untappd told us it (and say when it cut the budget). */
+export function quotaFields(q) {
+    if (q.quota_remaining === null)
+        return {};
+    return { quota_remaining: q.quota_remaining, ...(q.clamped ? { budget_clamped_to_quota: true } : {}) };
+}
 function pct(cached, total, complete) {
     if (total && total > 0)
         return Math.min(100, Math.round((cached / total) * 100));
@@ -33,7 +40,7 @@ function pct(cached, total, complete) {
  * by the API for non-self accounts) and the user/beers distinct-beers sync
  * (complete has-had coverage) — so a caller knows exactly which caveats apply.
  */
-async function freshness(cache, username) {
+export async function freshness(cache, username) {
     const state = await cache.getState(username);
     const cachedCheckins = await cache.cachedCount(username);
     const cachedBeers = await cache.distinctBeersCount(username);
@@ -84,6 +91,29 @@ async function freshness(cache, username) {
  * platform-specific code.
  */
 export function registerCacheTools(server, client, cacheProvider) {
+    server.registerTool('untappd_cache_status', {
+        title: 'Show the local cache location, schema and per-user coverage',
+        description: 'Diagnostics for the LOCAL check-in cache — NO API call. Returns the resolved cache file path, its size on ' +
+            'disk (db + WAL), journal mode, schema version, the number of cached menu-line resolutions and beer-metadata ' +
+            'rows, and for every cached user: cached vs total distinct beers, cached check-ins, coverage_complete, the ' +
+            'resume offset of an unfinished user/beers backfill, and last_synced_at. Use it to confirm the cache ' +
+            'persisted across restarts or to see how far a backfill has got.',
+        annotations: toolAnnotations({ title: 'Show the local cache location, schema and per-user coverage', readOnly: true, idempotent: true, openWorld: false }),
+        inputSchema: z.object({}),
+    }, async () => {
+        const cache = cacheProvider();
+        const stats = await cache.stats();
+        // The file details only exist for a file-backed store (the node:sqlite
+        // CheckinCache); another backend reports the logical stats alone.
+        const file = cache.fileInfo?.();
+        return minifiedResult({
+            ...(file ? { cache_path: file.path, file_size_bytes: file.bytes, journal_mode: file.journal_mode } : {}),
+            schema_version: stats.schema_version,
+            resolution_cache_entries: stats.resolution_cache_entries,
+            beer_meta_entries: stats.beer_meta_entries,
+            users: stats.users,
+        });
+    });
     server.registerTool('untappd_sync_checkins', {
         title: 'Sync a user\'s check-ins into the cache',
         description: "Fetch a user's detailed check-ins (venue, date, comment) into the cache from user/checkins. Incremental and " +
@@ -110,11 +140,14 @@ export function registerCacheTools(server, client, cacheProvider) {
         }),
     }, async ({ username, max_pages, force_backfill }) => {
         const user = resolveUser(username, client.loginName);
+        // Floor of 1: the shared catch-up/backfill page split (sync.ts) is only
+        // defined for a budget of at least one page.
+        const quota = clampToQuota(client, max_pages ?? 10, 1);
         const summary = await syncCheckins(client, cacheProvider(), user, {
-            maxPages: max_pages ?? 10,
+            maxPages: quota.budget,
             force: force_backfill ?? false,
         });
-        return minifiedResult(summary);
+        return minifiedResult({ ...summary, ...quotaFields(quota) });
     });
     server.registerTool('untappd_sync_user_beers', {
         title: "Sync a user's complete distinct-beers list into the cache",
@@ -137,8 +170,9 @@ export function registerCacheTools(server, client, cacheProvider) {
         }),
     }, async ({ username, max_pages }) => {
         const user = resolveUser(username, client.loginName);
-        const summary = await syncUserBeers(client, cacheProvider(), user, max_pages ?? 10);
-        return minifiedResult(summary);
+        const quota = clampToQuota(client, max_pages ?? 10, 1);
+        const summary = await syncUserBeers(client, cacheProvider(), user, quota.budget);
+        return minifiedResult({ ...summary, ...quotaFields(quota) });
     });
     server.registerTool('untappd_cache_has_had', {
         title: 'Check if a user has had a beer (from the cache)',
@@ -176,23 +210,19 @@ export function registerCacheTools(server, client, cacheProvider) {
     }, async ({ username, bids }) => {
         const user = resolveUser(username, client.loginName);
         const cache = cacheProvider();
-        const seen = new Set();
+        const verdicts = await cache.hasHadMany(user, bids);
         const results = [];
         let hadCount = 0;
-        for (const bid of bids) {
-            if (seen.has(bid))
-                continue;
-            seen.add(bid);
-            const r = await cache.hasHad(user, { bid });
+        for (const [bid, r] of verdicts) {
             if (r.had)
                 hadCount++;
             results.push({ bid, had: r.had, count: r.count, last_date: r.last_date, best_rating: r.best_rating, sources: r.sources });
         }
         return minifiedResult({
             username: user,
-            checked: seen.size,
+            checked: verdicts.size,
             had: hadCount,
-            not_had: seen.size - hadCount,
+            not_had: verdicts.size - hadCount,
             results,
             freshness: await freshness(cache, user),
         });
@@ -212,21 +242,14 @@ export function registerCacheTools(server, client, cacheProvider) {
     }, async ({ username, bids }) => {
         const user = resolveUser(username, client.loginName);
         const cache = cacheProvider();
-        const seen = new Set();
+        const verdicts = await cache.hasHadMany(user, bids);
         const notHad = [];
         const had = [];
-        for (const bid of bids) {
-            if (seen.has(bid))
-                continue;
-            seen.add(bid);
-            if ((await cache.hasHad(user, { bid })).had)
-                had.push(bid);
-            else
-                notHad.push(bid);
-        }
+        for (const [bid, r] of verdicts)
+            (r.had ? had : notHad).push(bid);
         return minifiedResult({
             username: user,
-            checked: seen.size,
+            checked: verdicts.size,
             not_had_count: notHad.length,
             had_count: had.length,
             not_had: notHad,
@@ -295,16 +318,14 @@ export function registerCacheTools(server, client, cacheProvider) {
         const user = resolveUser(username, client.loginName);
         const cache = cacheProvider();
         const topN = top_n ?? 2;
-        const budget = api_budget ?? 25;
+        const quota = clampToQuota(client, api_budget ?? 25);
+        const budget = quota.budget;
         const nowMs = Date.now();
         const nowIso = new Date().toISOString();
         // Dedupe candidates, then filter to not-had using the cache only (no API).
         const candidates = [...new Set(bids)];
-        const notHad = [];
-        for (const bid of candidates) {
-            if (!(await cache.hasHad(user, { bid })).had)
-                notHad.push(bid);
-        }
+        const verdicts = await cache.hasHadMany(user, candidates);
+        const notHad = candidates.filter((bid) => !verdicts.get(bid).had);
         // Read cached metadata; a hit newer than the TTL is used as-is, otherwise
         // the bid needs a beer/info fetch.
         const metaByBid = new Map();
@@ -399,6 +420,7 @@ export function registerCacheTools(server, client, cacheProvider) {
                 partial,
                 another_run_needed: partial,
                 ...(rateLimited ? { rate_limited: true } : {}),
+                ...quotaFields(quota),
             },
             freshness: await freshness(cache, user),
         });

package/dist/tools/menu.js

@@ -0,0 +1,104 @@
+import { z } from 'zod';
+import { createHelpfulError, minifiedResult, toolAnnotations } from '@chrischall/mcp-utils';
+import { menuPick, venuePick } from '../menu/pick.js';
+import { freshness, quotaFields, resolveUser, UsernameArg } from './cache.js';
+import { clampToQuota } from '../quota.js';
+import { parseUntappdUrl } from './resolve.js';
+const StyleFilter = z
+    .string()
+    .min(1)
+    .optional()
+    .describe('Case-insensitive substring filter on the beer style or parent style for the picks (e.g. "ipa", "stout").');
+const TopN = z.number().int().min(1).max(10).optional().describe('How many picks to return (default 2, max 10).');
+const ApiBudget = z
+    .number()
+    .int()
+    .min(1)
+    .max(100)
+    .optional()
+    .describe('Max Untappd API calls this run, shared by the cache sync, searches and rating lookups (default 60; Untappd allows ~100/hour). ' +
+    'If it runs out, the result says another_run_needed and a re-run continues from what was cached.');
+/** Parse a venue argument: a bare id, a numeric string, or an untappd.com/v/<slug>/<id> URL. */
+export function parseVenueArg(v) {
+    if (typeof v === 'number')
+        return v;
+    const t = v.trim();
+    if (/^\d+$/.test(t))
+        return Number(t);
+    const r = parseUntappdUrl(t);
+    if (r?.type === 'venue' && r.id)
+        return r.id;
+    throw createHelpfulError(`"${v}" is not an Untappd venue id or venue URL.`, {
+        hint: 'Pass the numeric venue id, or a URL like https://untappd.com/v/<slug>/<venue_id>. untappd_search_venue finds ids by name.',
+    });
+}
+export function registerMenuTools(server, client, cacheProvider, deps = {}) {
+    server.registerTool('untappd_menu_pick', {
+        title: "Pick beers off a tap list that a user hasn't had",
+        description: 'One call from a tap list to "order this": give the raw menu lines as read from a photo and get back the ' +
+            'top-rated beers the user has NOT had. It (1) refreshes the user\'s distinct-beers cache — an incremental ' +
+            'refresh when the cache is complete, otherwise it backfills automatically within api_budget, no separate ' +
+            'sync needed; (2) resolves each line to an Untappd beer (prices/punctuation stripped, scored on brewery + ' +
+            'name match and check-in volume, venue_city as tie-breaker; resolutions are cached locally so repeat venues ' +
+            'are instant); (3) treats "<Brewery> SEASONAL/ROTATING" as a list of possible beers (needs_confirmation) ' +
+            'and "ROTATING CIDER"-style lines as unresolved ("ask bartender"); (4) checks every beer against the cache; ' +
+            '(5) ranks the not-had ones by global rating. Returns picks, not_had, had, possible, unresolved, a sync ' +
+            'block (what the refresh did) and freshness (coverage); if coverage is still incomplete a "not had" may be ' +
+            'a false negative and another_run_needed is true. api_budget is also capped to the quota Untappd reports, ' +
+            'when it reports one. Omit username for your own account.',
+        annotations: toolAnnotations({ title: "Pick beers off a tap list that a user hasn't had", readOnly: false, idempotent: false, openWorld: true, destructive: false }),
+        inputSchema: z.object({
+            username: UsernameArg,
+            items: z
+                .array(z.string().min(1).max(200))
+                .min(1)
+                .max(60)
+                .describe('Raw menu lines as read from the menu, e.g. ["JACKALOPE FENNARIO IPA $7", "BLACK ABBEY SEASONAL", "ROTATING CIDER"].'),
+            style_filter: StyleFilter,
+            top_n: TopN,
+            venue_city: z.string().min(1).optional().describe('City of the venue (e.g. "Nashville") — breaks ties between same-named beers toward local breweries.'),
+            api_budget: ApiBudget,
+            refresh_resolutions: z.boolean().optional().describe('Ignore cached line→beer matches and re-search every line (default false).'),
+        }),
+    }, async ({ username, items, style_filter, top_n, venue_city, api_budget, refresh_resolutions }) => {
+        const user = resolveUser(username, client.loginName);
+        const cache = cacheProvider();
+        const quota = clampToQuota(client, api_budget ?? 60);
+        const out = await menuPick(client, cache, {
+            username: user,
+            items,
+            styleFilter: style_filter,
+            topN: top_n ?? 2,
+            apiBudget: quota.budget,
+            venueCity: venue_city,
+            refreshResolutions: refresh_resolutions,
+        }, deps);
+        return minifiedResult({ username: user, ...out, ...quotaFields(quota), freshness: await freshness(cache, user) });
+    });
+    server.registerTool('untappd_venue_pick', {
+        title: "Pick beers off a venue's Untappd menu that a user hasn't had",
+        description: 'Like untappd_menu_pick, but takes an Untappd venue (URL or id) instead of menu lines: it pulls the venue\'s ' +
+            'FULL verified menu (walking every section page until complete, within api_budget), refreshes the user\'s ' +
+            'distinct-beers cache (incremental, or an automatic backfill), checks every menu beer against it and ranks ' +
+            'the not-had ones by global rating. Returns the same picks / not_had / had / sync shape plus a venue block ' +
+            '(menu_complete is false only if the budget ran out mid-menu). A venue with no verified menu comes back ' +
+            'unresolved — use untappd_menu_pick with the tap list instead. Omit username for your own account.',
+        annotations: toolAnnotations({ title: "Pick beers off a venue's Untappd menu that a user hasn't had", readOnly: false, idempotent: false, openWorld: true, destructive: false }),
+        inputSchema: z.object({
+            venue: z
+                .union([z.string().min(1), z.number().int().positive()])
+                .describe('Untappd venue URL (https://untappd.com/v/<slug>/<id>) or numeric venue id.'),
+            username: UsernameArg,
+            style_filter: StyleFilter,
+            top_n: TopN,
+            api_budget: ApiBudget,
+        }),
+    }, async ({ venue, username, style_filter, top_n, api_budget }) => {
+        const venueId = parseVenueArg(venue);
+        const user = resolveUser(username, client.loginName);
+        const cache = cacheProvider();
+        const quota = clampToQuota(client, api_budget ?? 60);
+        const out = await venuePick(client, cache, { username: user, venueId, styleFilter: style_filter, topN: top_n ?? 2, apiBudget: quota.budget }, deps);
+        return minifiedResult({ username: user, ...out, ...quotaFields(quota), freshness: await freshness(cache, user) });
+    });
+}

package/dist/tools/venue.js

@@ -1,6 +1,7 @@
 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) {
     server.registerTool('untappd_search_venue', {
         title: 'Search Untappd venues',
@@ -50,98 +51,19 @@ export function registerVenueTools(server, client) {
             sort: z.string().optional().describe("Menu sort key (e.g. 'publish_order', 'highest_rated'). Optional."),
         }),
     }, async ({ venue_id, menu_id, section_limit, section_offset, max_pages, sort }) => {
-        // venue/info pages its MENUS with limit/offset, but caps each menu's SECTION
-        // list — echoing `section_limit`/`section_offset` back as accepted params
-        // (the response even carries a `section_offset ` key with a stray trailing
-        // space; the real param name is the clean one the web menu UI sends). We
-        // forward them and walk sections, deduping by menu+section+bid so overlapping
-        // or param-ignoring pages can't double-count. 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.
-        //
-        // Termination is driven by SECTION availability, not a running beer count:
-        // a page that returns fewer sections than we asked for is the end of the
-        // list. That's what makes resuming correct — this tool is stateless across
-        // calls, so on a resumed tail (section_offset > 0) `beers.length` covers
-        // only this run and can never equal the whole-menu total, which would
-        // otherwise mislabel a finished tail as truncated.
-        const pageSize = section_limit ?? 50;
-        const budget = max_pages ?? 3;
+        // 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;
-        let offset = startOffset;
-        const seen = new Set();
-        const beers = [];
-        let totalCount = 0;
-        let sawMenu = false;
-        let pagesFetched = 0;
-        let reachedEnd = false; // hit full coverage, or the section list ran out
-        for (let page = 0; page < budget; page++) {
-            const data = await client.get(`/venue/info/${venue_id}`, {
-                section_limit: pageSize,
-                section_offset: offset,
-                menu_id,
-                sort,
-            });
-            pagesFetched++;
-            const vb = data?.venue?.verfied_beers;
-            if (!vb) {
-                reachedEnd = true; // no menu payload — nothing more to page
-                break;
-            }
-            sawMenu = true;
-            let added = 0;
-            let matchedItemCount = 0;
-            let sectionsReturned = 0;
-            for (const wrap of vb.items ?? []) {
-                const menu = wrap?.menu;
-                if (!menu)
-                    continue;
-                if (menu_id && menu.menu_id !== menu_id)
-                    continue;
-                if (typeof menu.total_item_count === 'number')
-                    matchedItemCount += menu.total_item_count;
-                const sections = menu.sections?.items ?? [];
-                for (const section of sections) {
-                    sectionsReturned++;
-                    for (const it of section.items ?? []) {
-                        const beer = it?.beer;
-                        if (!beer || typeof beer.bid !== 'number')
-                            continue;
-                        const key = `${String(menu.menu_id)}:${String(section.section_id)}:${beer.bid}`;
-                        if (seen.has(key))
-                            continue;
-                        seen.add(key);
-                        const sectionName = section.section_name;
-                        beers.push({
-                            bid: beer.bid,
-                            name: beer.beer_name,
-                            brewery: it.brewery?.brewery_name,
-                            style: beer.beer_style,
-                            abv: beer.beer_abv,
-                            price: it.price?.value,
-                            serving_type: it.serving_type,
-                            menu: menu.menu_name,
-                            section: typeof sectionName === 'string' ? sectionName.trim() : sectionName,
-                        });
-                        added++;
-                    }
-                }
-            }
-            // Coverage target: with a menu_id filter, aim for THAT menu's own item
-            // count — verfied_beers.total_count spans every menu, so a single-menu
-            // slice could never reach it (it would burn the whole page budget and
-            // wrongly report a shortfall). Without a filter, the venue-wide total.
-            totalCount = menu_id ? matchedItemCount : typeof vb.total_count === 'number' ? vb.total_count : totalCount;
-            offset += pageSize;
-            if (totalCount > 0 && beers.length >= totalCount) {
-                reachedEnd = true; // full coverage from this walk
-                break;
-            }
-            if (sectionsReturned < pageSize || added === 0) {
-                reachedEnd = true; // a short (or all-duplicate) page is the end of the section list
-                break;
-            }
-        }
+        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.' });
         }
@@ -157,7 +79,7 @@ export function registerVenueTools(server, client) {
             returned: beers.length,
             pages_fetched: pagesFetched,
             another_run_needed,
-            ...(another_run_needed ? { next_section_offset: offset } : {}),
+            ...(another_run_needed ? { next_section_offset: walk.nextOffset } : {}),
             truncated,
             beers,
         });

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.3.2'; // x-release-please-version
+export const VERSION = '2.4.0'; // x-release-please-version

package/mint.yaml

@@ -5,6 +5,18 @@ summary: >-
   Search Untappd beers, breweries, and venues; read profiles, check-ins,
   wishlists, and your friend feed; and post check-ins, toasts, and comments
   to your account
+examples:
+  - prompt: >-
+      What's trending on Untappd right now? Split it into the big macro beers
+      and the smaller craft ones.
+    note: Read-only; uses the trending beers list.
+  - prompt: >-
+      Look up Tree House Brewing on Untappd and list their highest-rated beers.
+    note: Read-only; brewery search, then its beer list sorted by rating.
+  - prompt: >-
+      Here's the tap list at the bar I'm at. Which two of these have I not had
+      yet, ranked by rating?
+    note: Checks your synced check-in history; nothing is posted.
 env:
   - name: UNTAPPD_USERNAME
     required: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "untappd-mcp",
-  "version": "2.3.2",
+  "version": "2.4.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>",
@@ -58,5 +58,9 @@
     "typescript": "^7.0.2",
     "vite": "^8.2.2",
     "vitest": "^5.0.0"
+  },
+  "allowScripts": {
+    "esbuild": false,
+    "fsevents": false
   }
 }

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/untappd-mcp",
     "source": "github"
   },
-  "version": "2.3.2",
+  "version": "2.4.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "untappd-mcp",
-      "version": "2.3.2",
+      "version": "2.4.0",
       "transport": {
         "type": "stdio"
       },
@@ -92,6 +92,13 @@
           "isRequired": false,
           "format": "string",
           "isSecret": false
+        },
+        {
+          "name": "UNTAPPD_CACHE_DIR",
+          "description": "Directory for the cache instead of ~/.untappd-mcp (the file is checkins.db inside it). UNTAPPD_CACHE_DB wins if both are set. Local/stdio only.",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": false
         }
       ]
     }