untappd-mcp 2.3.2 → 2.5.0

package/dist/ratelimit.js

@@ -0,0 +1,236 @@
+// Rate-limit tracking for the ~100 calls/hour Untappd v4 limit.
+//
+// Every response the client receives is recorded as an ApiCallObservation
+// (time, status, and whatever X-Ratelimit-* / Retry-After headers it carried).
+// The headers alone can't be trusted: the v4 API sends `X-Ratelimit-Remaining:
+// 0` on EVERY successful response (observed live 2026-11-02), so a header-only
+// reading would report the quota exhausted after the first call. The estimate
+// therefore rests on a LOCAL count of calls in the rolling hour, and only takes
+// the header into account once it has reported a live (non-zero) value — or
+// when Untappd actually answered 429.
+//
+// The stdio server also persists observations into the shared cache file
+// (`api_calls` table), so a fresh process — or a second one sharing the file —
+// knows what was already spent this hour. `checkRateBudget` merges both views
+// and is the guard every paging sync consults before each page, so it can stop
+// cleanly with resume info instead of failing mid-batch on a 429.
+import { readEnvVar } from '@chrischall/mcp-utils';
+export const RATE_WINDOW_MS = 60 * 60 * 1000;
+/** Untappd's documented per-token limit; override with UNTAPPD_RATE_LIMIT_PER_HOUR. */
+export const DEFAULT_HOURLY_LIMIT = 100;
+/** Calls the guard leaves unspent so interactive tools still work after a sync. */
+export const DEFAULT_RESERVE = 2;
+function intHeader(h, name) {
+    const raw = h.get(name);
+    if (raw === null || raw.trim() === '')
+        return null;
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 0 ? Math.floor(n) : null;
+}
+/** Build an observation from a response's status and headers. */
+export function observeResponse(status, headers, now = Date.now()) {
+    const limit = intHeader(headers, 'x-ratelimit-limit');
+    const reset = intHeader(headers, 'x-ratelimit-reset');
+    let reset_at = null;
+    if (reset !== null) {
+        if (reset > 1e12)
+            reset_at = reset; // epoch ms
+        else if (reset > 1e9)
+            reset_at = reset * 1000; // epoch seconds
+        else
+            reset_at = now + reset * 1000; // seconds from now
+    }
+    const ra = intHeader(headers, 'retry-after');
+    return {
+        at: now,
+        status,
+        remaining: intHeader(headers, 'x-ratelimit-remaining'),
+        limit: limit !== null && limit > 0 ? limit : null,
+        reset_at,
+        retry_after_s: ra !== null && ra > 0 ? ra : null,
+    };
+}
+/** UNTAPPD_RATE_LIMIT_PER_HOUR, when set to a positive integer. */
+export function configuredHourlyLimit() {
+    const raw = readEnvVar('UNTAPPD_RATE_LIMIT_PER_HOUR');
+    const n = raw === undefined || raw === null ? NaN : Number(raw);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : null;
+}
+const iso = (ms) => (ms === null ? null : new Date(ms).toISOString());
+function compute(all, now, opts) {
+    const obs = all.filter((o) => o.at > now - RATE_WINDOW_MS).sort((a, b) => a.at - b.at);
+    const latestWith = (k) => {
+        for (let i = obs.length - 1; i >= 0; i--)
+            if (obs[i][k] !== null)
+                return obs[i];
+        return undefined;
+    };
+    const headerLimit = latestWith('limit')?.limit ?? null;
+    const configured = opts.configuredLimit ?? null;
+    const hourly_limit = configured ?? headerLimit ?? DEFAULT_HOURLY_LIMIT;
+    const limit_source = configured !== null ? 'env' : headerLimit !== null ? 'header' : 'assumed';
+    const lastRemaining = latestWith('remaining');
+    const headerRemaining = lastRemaining?.remaining ?? null;
+    const headerLive = obs.some((o) => o.remaining !== null && o.remaining > 0);
+    const resetMs = lastRemaining?.reset_at ?? null;
+    const headerTrusted = lastRemaining !== undefined && (headerLive || lastRemaining.status === 429) && (resetMs === null || resetMs > now);
+    let blockedUntilMs = null;
+    let last429 = null;
+    for (const o of obs) {
+        if (o.status !== 429)
+            continue;
+        last429 = o.at;
+        const until = o.retry_after_s !== null
+            ? o.at + o.retry_after_s * 1000
+            : o.reset_at ?? (obs[0] ? obs[0].at + RATE_WINDOW_MS : o.at + RATE_WINDOW_MS);
+        if (until > now && (blockedUntilMs === null || until > blockedUntilMs))
+            blockedUntilMs = until;
+    }
+    const local = hourly_limit - obs.length;
+    let estimate = local;
+    if (headerTrusted && headerRemaining !== null)
+        estimate = Math.min(estimate, headerRemaining);
+    if (blockedUntilMs !== null)
+        estimate = 0;
+    return {
+        hourly_limit,
+        limit_source,
+        calls_last_hour: obs.length,
+        estimated_remaining: Math.max(0, estimate),
+        header_remaining: headerRemaining,
+        header_remaining_trusted: headerTrusted,
+        header_reset_at: iso(resetMs),
+        last_response_at: iso(obs.length ? obs[obs.length - 1].at : null),
+        last_429_at: iso(last429),
+        blocked_until: iso(blockedUntilMs),
+        times: obs.map((o) => o.at),
+        blockedUntilMs,
+        headerBoundResetMs: headerTrusted ? resetMs : null,
+    };
+}
+/** The rate-limit picture for a set of observations (pure; for tests and the status tool). */
+export function computeRateLimitStatus(obs, now, opts) {
+    const { times: _t, blockedUntilMs: _b, headerBoundResetMs: _h, ...status } = compute(obs, now, opts);
+    return status;
+}
+/** In-memory record of this process's responses within the rolling hour. */
+export class RateLimitTracker {
+    obs = [];
+    record(o) {
+        this.obs.push(o);
+        this.prune(o.at);
+    }
+    observations(now = Date.now()) {
+        this.prune(now);
+        return [...this.obs];
+    }
+    prune(now) {
+        const cutoff = now - RATE_WINDOW_MS;
+        if (this.obs.length && this.obs[0].at <= cutoff)
+            this.obs = this.obs.filter((o) => o.at > cutoff);
+    }
+}
+/** This process's observations merged with the shared cache log, de-duplicated. */
+async function mergedObservations(client, cache, now) {
+    const tracker = client.rateLimit;
+    const mine = tracker?.observations(now) ?? [];
+    let theirs = [];
+    try {
+        theirs = (await cache?.recentApiCalls?.(now - RATE_WINDOW_MS)) ?? [];
+    }
+    catch {
+        /* an unreadable log just means "this process's view only" */
+    }
+    // The shared log normally already holds this process's own calls (the stdio
+    // server persists each one), so merge as a multiset: per identical
+    // observation, keep the larger of the two counts rather than summing them.
+    // Two genuinely separate calls in the same millisecond stay two.
+    const key = (o) => `${o.at}:${o.status}:${o.remaining}:${o.retry_after_s}`;
+    const group = (xs) => {
+        const m = new Map();
+        for (const o of xs)
+            m.set(key(o), [...(m.get(key(o)) ?? []), o]);
+        return m;
+    };
+    const a = group(mine);
+    const b = group(theirs);
+    const out = [];
+    for (const k of new Set([...a.keys(), ...b.keys()])) {
+        const x = a.get(k) ?? [];
+        const y = b.get(k) ?? [];
+        out.push(...(x.length >= y.length ? x : y));
+    }
+    return out;
+}
+/** The current rate-limit picture (this process + the shared cache log). */
+export async function rateLimitStatus(client, cache) {
+    const now = Date.now();
+    return computeRateLimitStatus(await mergedObservations(client, cache, now), now, {
+        configuredLimit: configuredHourlyLimit(),
+    });
+}
+/**
+ * The stop-before-429 guard: may a sync spend `needed` more calls and still
+ * leave `reserve` unspent? Paging syncs call it before EVERY page and stop
+ * cleanly (progress is persisted per page) with `resume_at` when it says no.
+ */
+export async function checkRateBudget(client, cache, opts = {}) {
+    const needed = opts.needed ?? 1;
+    const reserve = opts.reserve ?? DEFAULT_RESERVE;
+    const now = Date.now();
+    const c = compute(await mergedObservations(client, cache, now), now, { configuredLimit: configuredHourlyLimit() });
+    const base = {
+        estimated_remaining: c.estimated_remaining,
+        calls_last_hour: c.calls_last_hour,
+        hourly_limit: c.hourly_limit,
+        reserve,
+    };
+    if (c.estimated_remaining - needed >= reserve) {
+        return { ok: true, ...base, resume_at: null, resume_after_s: null };
+    }
+    let resumeMs = null;
+    if (c.blockedUntilMs !== null)
+        resumeMs = c.blockedUntilMs;
+    else if (c.headerBoundResetMs !== null)
+        resumeMs = c.headerBoundResetMs;
+    else {
+        // Rolling window: wait until enough of the oldest calls age out.
+        const deficit = needed + reserve - (c.hourly_limit - c.calls_last_hour);
+        if (deficit > 0 && deficit <= c.times.length)
+            resumeMs = c.times[deficit - 1] + RATE_WINDOW_MS;
+    }
+    return {
+        ok: false,
+        ...base,
+        resume_at: iso(resumeMs),
+        resume_after_s: resumeMs === null ? null : Math.max(0, Math.ceil((resumeMs - now) / 1000)),
+        reason: c.blockedUntilMs !== null
+            ? 'Untappd answered 429 (rate limited) and its wait has not elapsed yet.'
+            : `Stopped before Untappd's hourly rate limit: ~${c.estimated_remaining} of ${c.hourly_limit} calls left this hour, ${reserve} held in reserve.`,
+    };
+}
+/** A guard verdict as a sync's stop record. */
+export function stopFromVerdict(v) {
+    return {
+        reason: v.reason ?? 'rate limit',
+        estimated_remaining: v.estimated_remaining,
+        calls_last_hour: v.calls_last_hour,
+        hourly_limit: v.hourly_limit,
+        resume_at: v.resume_at,
+        resume_after_s: v.resume_after_s,
+    };
+}
+/** A 429 that slipped past the guard, as a sync's stop record. */
+export function stopFrom429(e, now = Date.now()) {
+    const ra = e.retryAfterSeconds;
+    return {
+        reason: 'Untappd answered 429 (rate limited); progress up to the last full page is saved.',
+        resume_at: ra !== undefined ? new Date(now + ra * 1000).toISOString() : null,
+        resume_after_s: ra ?? null,
+    };
+}
+/** One-line resume advice for a sync's `note`. */
+export function resumeAdvice(stop, tool) {
+    const when = stop.resume_at ? ` after ${stop.resume_at} (~${Math.ceil((stop.resume_after_s ?? 0) / 60)} min)` : ' later';
+    return `${stop.reason} Progress is saved — run ${tool} again${when} to resume.`;
+}

package/dist/tools/beer.js

@@ -13,9 +13,12 @@ async function seedBeerMeta(cache, beers) {
         return;
     try {
         const now = new Date().toISOString();
+        // Search results carry no rating. Seeding one would overwrite a real cached
+        // rating with null under a fresh timestamp, so the ranking tools would
+        // trust it for 30 days — only rows that actually carry a rating are seeded.
         const rows = beers
             .map((b) => beerMetaFrom(b.beer, b.brewery, now))
-            .filter((m) => m !== null);
+            .filter((m) => m !== null && (m.weighted_rating_score ?? m.rating_score) !== null);
         if (rows.length)
             await cache().upsertBeerMeta(rows);
     }

package/dist/tools/brewery.js

@@ -1,7 +1,11 @@
 import { z } from 'zod';
 import { minifiedResult, resolveView, toolAnnotations, viewParam, viewResult } from '@chrischall/mcp-utils';
-import { UNTAPPD_VIEWS, compactBreweryBeers, upstreamCompact } from '../compact.js';
-export function registerBreweryTools(server, client) {
+import { UNTAPPD_VIEWS, compactBreweryBeerList, upstreamCompact } from '../compact.js';
+import { BREWERY_BEERS_DEFAULT_LIMIT, BREWERY_BEERS_TTL_MS, getBreweryBeers } from '../cache/brewery-beers.js';
+import { optionalCache } from './cache-optional.js';
+import { favoriteLookup } from '../cache/favorites.js';
+export function registerBreweryTools(server, client, cacheProvider) {
+    const cacheOrNone = optionalCache(cacheProvider);
     server.registerTool('untappd_search_brewery', {
         title: 'Search Untappd breweries',
         description: 'Search Untappd for breweries by name. Returns matches with their brewery id, location, type, and beer ' +
@@ -19,7 +23,9 @@ export function registerBreweryTools(server, client) {
     server.registerTool('untappd_brewery_info', {
         title: 'Get Untappd brewery detail',
         description: 'Get full detail for a brewery by its Untappd brewery id: description, location, type, rating, total ' +
-            'check-ins, and popular beers. Get an id from untappd_search_brewery. Read-only.',
+            'check-ins, and popular beers. Get an id from untappd_search_brewery. Read-only. Its ' +
+            'claimed_status.follow_status is whether the SIGNED-IN account follows/likes the brewery — never another ' +
+            "user's; for theirs, run untappd_sync_brewery_likes and read untappd_favorites_list (source \"untappd\").",
         annotations: toolAnnotations({ title: 'Get Untappd brewery detail', readOnly: true, idempotent: true, openWorld: true }),
         inputSchema: z.object({
             brewery_id: z.number().int().positive().describe('Untappd brewery id'),
@@ -32,8 +38,17 @@ export function registerBreweryTools(server, client) {
     });
     server.registerTool('untappd_brewery_beers', {
         title: "Get a brewery's beer list",
-        description: 'Get the beers a brewery makes, by brewery id, with per-beer rating and check-in counts. Supports sorting ' +
-            'and paging. Get an id from untappd_search_brewery. Read-only.',
+        description: 'Get the beers a brewery makes, by brewery id, with per-beer global rating, check-in count, ABV, style and ' +
+            'in_production. Supports sorting and paging. Get an id from untappd_search_brewery. Lists are CACHED locally ' +
+            `for ${BREWERY_BEERS_TTL_MS / 86_400_000} days (source:"cache"|"api", fetched_at, expires_at): a fresh cached list answers ` +
+            'without an API call — the default popularity order from the cached top-of-list, other sorts once the whole ' +
+            'list is cached (sorted locally). refresh:true re-fetches. The compact result has the same keys with or ' +
+            'without the cache (source:"api" and null fetched_at/expires_at when no cache is available), with ' +
+            'pagination {offset, limit, next_offset}. Untappd\'s per-beer has_had / your-count on this endpoint ' +
+            'describe the AUTHENTICATED account, never the user you are asking about, so have_had / your_count are ' +
+            'never cached or returned on either path — use untappd_cache_has_had_many for any user. With the cache, the result carries favorite {is_favorite, sources, ' +
+            'reason} for the brewery and on each favorite beer (derived from username\'s history or added with ' +
+            'untappd_favorite_add; default your account). view:"full" always calls Untappd and returns its raw page. Read-only.',
         annotations: toolAnnotations({ title: "Get a brewery's beer list", readOnly: true, idempotent: true, openWorld: true }),
         inputSchema: z.object({
             brewery_id: z.number().int().positive().describe('Untappd brewery id'),
@@ -43,19 +58,42 @@ export function registerBreweryTools(server, client) {
                 .enum(['name', 'style', 'abv', 'rating', 'count'])
                 .optional()
                 .describe('Sort order (default by popularity)'),
+            refresh: z.boolean().optional().describe('Re-fetch from Untappd even if a fresh cached list exists (default false)'),
+            username: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('Whose favorites to mark (cache only; default your configured account)'),
             view: viewParam(UNTAPPD_VIEWS, {
-                note: 'compact keeps each beer\'s identity, rating and counts and drops the description, label URLs and the copy of this brewery repeated on every row; "full" returns Untappd\'s whole page.',
+                note: 'compact keeps each beer\'s identity, rating and counts and drops the description, label URLs and the copy of this brewery repeated on every row; "full" returns Untappd\'s whole page (always fetched live).',
             }),
         }),
     }, 
     // Unlike its `/brewery/info` sibling above, this rung is NOT forwarded to
     // Untappd: `/brewery/beer_list/` is not one of the endpoints documented to
     // honour an upstream `compact`, and sending an unverified parameter to see
-    // what happens is not a rung. The projection is entirely ours and is
-    // grounded on a live capture — see `compactBreweryBeer`.
-    async ({ brewery_id, limit, offset, sort, view }) => {
+    // what happens is not a rung. The projection is entirely ours — see
+    // `compactBreweryBeerList`, the ONE shape both the cached and no-cache
+    // paths return.
+    async ({ brewery_id, limit, offset, sort, refresh, username, view }) => {
         const v = resolveView(view, UNTAPPD_VIEWS);
-        const data = await client.get(`/brewery/beer_list/${brewery_id}`, { limit, offset, sort });
-        return viewResult(v, v === 'compact' ? compactBreweryBeers(data) : data);
+        const cache = cacheOrNone();
+        // view:"full" wants Untappd's raw page, so it always fetches (and seeds the cache).
+        // Without a cache this is a plain fetch mapped through the same rows.
+        const r = await getBreweryBeers(client, cache, brewery_id, { limit, offset, sort, refresh: refresh || v === 'full' });
+        if (v === 'full')
+            return viewResult(v, r.raw);
+        // Drift-safe like every compact rung: a fetched page without beers.items is
+        // returned raw (with a stderr note) rather than as an empty projection.
+        if (r.source === 'api' && !Array.isArray(r.raw?.beers?.items)) {
+            process.stderr.write('[untappd-mcp] compact: expected beers.items array; returning raw response\n');
+            return viewResult(v, r.raw);
+        }
+        // Favorites are applied on read (never cached): the brewery itself, and any favorite beer.
+        const user = username ?? client.loginName;
+        const favs = cache && user ? await favoriteLookup(cache, [user], { brewery: [brewery_id], beer: r.beers.map((b) => b.bid) }) : null;
+        return viewResult(v, compactBreweryBeerList(r, { offset: offset ?? 0, limit: limit ?? BREWERY_BEERS_DEFAULT_LIMIT }, favs
+            ? { brewery: favs.get('brewery', brewery_id), beer: (bid) => (favs.isFavorite('beer', bid) ? favs.get('beer', bid) : undefined) }
+            : undefined));
     });
 }

package/dist/tools/cache-optional.js

@@ -0,0 +1,22 @@
+/**
+ * Wrap an optional cache provider for tools whose cache is an optimisation, not
+ * their answer: no provider, or a cache that fails to open, means "call the API"
+ * (with one stderr note) rather than failing the read.
+ */
+export function optionalCache(provider) {
+    let warned = false;
+    return () => {
+        if (!provider)
+            return undefined;
+        try {
+            return provider();
+        }
+        catch (e) {
+            if (!warned) {
+                warned = true;
+                console.error(`[untappd-mcp] response cache unavailable, calling Untappd directly: ${e?.message ?? e}`);
+            }
+            return undefined;
+        }
+    };
+}