untappd-mcp 2.3.1 → 2.4.0

package/dist/cache/db.js

@@ -1,6 +1,6 @@
 import { DatabaseSync } from 'node:sqlite';
-import { chmodSync, closeSync, existsSync, mkdirSync, openSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { chmodSync, closeSync, existsSync, mkdirSync, openSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { readEnvVar } from '@chrischall/mcp-utils';
 import { CheckinStoreCore, LocalCacheStore } from './store.js';
@@ -9,26 +9,45 @@ import { CheckinStoreCore, LocalCacheStore } from './store.js';
 // (src/cache/store.ts); this file only adapts `node:sqlite` to the SqlDriver
 // surface and manages the file handle. Another deployment can adapt a
 // different driver to the same surface.
+// Upper bound on cached prepared statements per connection.
+const STATEMENT_CACHE_MAX = 200;
 /** Adapts a `node:sqlite` DatabaseSync to the driver surface the core needs. */
 class NodeSqlDriver {
     db;
+    // Prepared statements, reused by SQL text: an upsert page runs the same
+    // INSERT 50 times. IN-lists make some SQL vary with the list length, so the
+    // cache is bounded and simply reset when full.
+    stmts = new Map();
     constructor(db) {
         this.db = db;
     }
+    prepared(sql) {
+        let st = this.stmts.get(sql);
+        if (!st) {
+            if (this.stmts.size >= STATEMENT_CACHE_MAX)
+                this.stmts.clear();
+            st = this.db.prepare(sql);
+            this.stmts.set(sql, st);
+        }
+        return st;
+    }
     execScript(sql) {
         this.db.exec(sql);
     }
     run(sql, params) {
-        this.db.prepare(sql).run(...params);
+        this.prepared(sql).run(...params);
     }
     get(sql, params) {
-        return this.db.prepare(sql).get(...params);
+        return this.prepared(sql).get(...params);
     }
     all(sql, params) {
-        return this.db.prepare(sql).all(...params);
+        return this.prepared(sql).all(...params);
     }
     transaction(fn) {
-        this.db.exec('BEGIN');
+        // IMMEDIATE takes the write lock up front. A DEFERRED transaction that
+        // reads and then writes can hit SQLITE_BUSY on the lock upgrade, which
+        // busy_timeout does NOT retry — the failure mode of two hosts open at once.
+        this.db.exec('BEGIN IMMEDIATE');
         try {
             fn();
             this.db.exec('COMMIT');
@@ -42,9 +61,13 @@ class NodeSqlDriver {
 /** A file-backed check-in cache. `open()` creates parent dirs and the schema. */
 export class CheckinCache extends LocalCacheStore {
     db;
-    constructor(db) {
+    path;
+    constructor(db, 
+    /** Absolute path of the backing file, or `:memory:`. */
+    path) {
         super(new CheckinStoreCore(new NodeSqlDriver(db)));
         this.db = db;
+        this.path = path;
     }
     /**
      * Open (creating parent dirs) a file-backed cache, or `:memory:` for tests.
@@ -54,11 +77,40 @@ export class CheckinCache extends LocalCacheStore {
     static open(path) {
         if (path !== ':memory:')
             preparePrivateFile(path);
-        const cache = new CheckinCache(new DatabaseSync(path));
+        const db = new DatabaseSync(path);
+        // Set before the schema/migration transaction so even that waits out a
+        // second process instead of failing. WAL lets readers and one writer run
+        // concurrently (two hosts open at once); NORMAL sync is the WAL-safe default.
+        db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`);
+        if (path !== ':memory:') {
+            db.exec('PRAGMA journal_mode = WAL');
+            db.exec('PRAGMA synchronous = NORMAL');
+        }
+        const cache = new CheckinCache(db, path);
         if (path !== ':memory:')
             tightenSidecars(path);
         return cache;
     }
+    /** The SQLite journal mode actually in effect (`wal` for a file, `memory` for :memory:). */
+    journalMode() {
+        const row = this.db.prepare('PRAGMA journal_mode').get();
+        return String(row?.journal_mode ?? 'unknown');
+    }
+    /** On-disk footprint: the db file plus its -wal/-shm side files. */
+    fileInfo() {
+        let bytes = 0;
+        if (this.path !== ':memory:') {
+            for (const suffix of ['', '-wal', '-shm']) {
+                try {
+                    bytes += statSync(this.path + suffix).size;
+                }
+                catch {
+                    /* side file not present */
+                }
+            }
+        }
+        return { path: this.path, bytes, journal_mode: this.journalMode() };
+    }
     close() {
         this.db.close();
     }
@@ -66,14 +118,19 @@ export class CheckinCache extends LocalCacheStore {
 /**
  * Create the cache's directory (0700 — `mode` applies to every dir mkdir
  * creates) and the db file itself (0600) BEFORE SQLite opens it, so the file is
- * never briefly umask-readable. Pre-existing loose entries from older versions
- * are tightened too; chmod failures (e.g. a shared dir the user doesn't own)
- * are best-effort, never fatal.
+ * never briefly umask-readable. The db file is always tightened, and so is the
+ * server's own default directory (`~/.untappd-mcp`, which an older version may
+ * have left loose). A directory the user pointed `UNTAPPD_CACHE_DB` into that
+ * already existed is left as it is: it may hold other files (a shared Dropbox
+ * folder), and making it owner-only would break access to them. chmod failures
+ * (e.g. a shared dir the user doesn't own) are best-effort, never fatal.
  */
 function preparePrivateFile(path) {
     const dir = dirname(path);
+    const dirExisted = existsSync(dir);
     mkdirSync(dir, { recursive: true, mode: 0o700 });
-    bestEffortChmod(dir, 0o700);
+    if (!dirExisted || resolve(dir) === resolve(defaultCacheDir()))
+        bestEffortChmod(dir, 0o700);
     if (!existsSync(path))
         closeSync(openSync(path, 'a', 0o600));
     bestEffortChmod(path, 0o600);
@@ -93,10 +150,52 @@ function bestEffortChmod(path, mode) {
         /* best-effort — not every filesystem supports POSIX modes */
     }
 }
-/** Default on-disk cache path: `$UNTAPPD_CACHE_DB` or `~/.untappd-mcp/checkins.db`. */
+// How long a write waits for another process's lock before failing.
+const BUSY_TIMEOUT_MS = 5000;
+/**
+ * The on-disk cache path, always ABSOLUTE: `$UNTAPPD_CACHE_DB` (a file), else
+ * `$UNTAPPD_CACHE_DIR/checkins.db`, else `~/.untappd-mcp/checkins.db`.
+ *
+ * It must not depend on how the host launched the server — Claude Desktop runs
+ * the .mcpb from its own extension dir, Claude Code from the project dir — so a
+ * relative override resolves against the HOME directory, never the working
+ * directory (which would silently give each host its own empty cache), and a
+ * leading `~` is expanded.
+ */
 export function defaultCachePath() {
-    return readEnvVar('UNTAPPD_CACHE_DB') ?? join(homedir(), '.untappd-mcp', 'checkins.db');
+    const file = readEnvVar('UNTAPPD_CACHE_DB');
+    if (file)
+        return file === ':memory:' ? file : absolutise(file);
+    const dir = readEnvVar('UNTAPPD_CACHE_DIR');
+    return join(dir ? absolutise(dir) : defaultCacheDir(), 'checkins.db');
+}
+function absolutise(p) {
+    const expanded = p === '~' ? homedir() : p.startsWith('~/') ? join(homedir(), p.slice(2)) : p;
+    return isAbsolute(expanded) ? expanded : resolve(homedir(), expanded);
+}
+/** One stderr line naming the resolved cache file, for the startup log. */
+export function describeCachePath(path) {
+    let state = 'not created yet';
+    try {
+        // Count the -wal too: after an unclean exit most recent writes live there.
+        let bytes = statSync(path).size;
+        try {
+            bytes += statSync(`${path}-wal`).size;
+        }
+        catch {
+            /* no WAL */
+        }
+        state = `exists, ${bytes} bytes`;
+    }
+    catch {
+        /* not created yet */
+    }
+    return `[untappd-mcp] cache: ${path} (${state})`;
 }
 // Re-export the shared types/helpers tests and tools import from here so their
 // existing import paths keep working.
 export { mapCheckinRow, } from './store.js';
+/** The directory the server owns by default: `~/.untappd-mcp`. */
+function defaultCacheDir() {
+    return join(homedir(), '.untappd-mcp');
+}

package/dist/cache/store.js

@@ -180,7 +180,11 @@ export const SCHEMA_STATEMENTS = [
      beers_rescan_target INTEGER
    )`,
 ];
-/** Columns added after the initial release, each applied idempotently on open. */
+/**
+ * Columns added to the v1 tables before the schema was versioned. A database
+ * at user_version 0 may predate any of them, so each is applied idempotently
+ * (ADD COLUMN throws harmlessly when the column already exists).
+ */
 export const MIGRATIONS = [
     'ALTER TABLE sync_state ADD COLUMN catchup_max_id INTEGER',
     'ALTER TABLE sync_state ADD COLUMN checkins_truncated INTEGER NOT NULL DEFAULT 0',
@@ -191,6 +195,35 @@ export const MIGRATIONS = [
     'ALTER TABLE sync_state ADD COLUMN beers_accepted_gap INTEGER NOT NULL DEFAULT 0',
     'ALTER TABLE sync_state ADD COLUMN beers_rescan_target INTEGER',
 ];
+/**
+ * Forward-only, versioned migrations, tracked in SQLite's `PRAGMA user_version`.
+ * Version 1 is the baseline (SCHEMA_STATEMENTS + the legacy MIGRATIONS above);
+ * every later change is appended here with the next version number and is
+ * ADDITIVE — a migration never drops or rewrites user rows, so upgrading can't
+ * silently wipe a cache that took an hour of rate-limited calls to fill.
+ */
+export const VERSIONED_MIGRATIONS = [
+    {
+        version: 2,
+        statements: [
+            `CREATE TABLE IF NOT EXISTS item_resolutions (
+         key         TEXT PRIMARY KEY,
+         item        TEXT NOT NULL,
+         status      TEXT NOT NULL,
+         bid         INTEGER,
+         data        TEXT,
+         resolved_at TEXT NOT NULL
+       )`,
+        ],
+    },
+    {
+        // untappd_cache_query's default (and date-range) ordering.
+        version: 3,
+        statements: ['CREATE INDEX IF NOT EXISTS idx_checkins_user_created ON checkins(username, created_at)'],
+    },
+];
+/** The schema version this code writes. */
+export const SCHEMA_VERSION = VERSIONED_MIGRATIONS.reduce((v, m) => Math.max(v, m.version), 1);
 /**
  * The cache logic over a synchronous {@link SqlDriver}. Usernames are keyed
  * case-insensitively via a lowercased key so `Mer1331` and `mer1331` share one
@@ -198,20 +231,54 @@ export const MIGRATIONS = [
  */
 export class CheckinStoreCore {
     db;
+    version = 0;
     constructor(db) {
         this.db = db;
-        for (const stmt of SCHEMA_STATEMENTS)
-            this.db.execScript(stmt);
-        // Forward-compat for a table created before a column existed; each ADD COLUMN
-        // throws harmlessly if the column is already present.
-        for (const mig of MIGRATIONS) {
-            try {
-                this.db.execScript(mig);
+        this.migrate();
+    }
+    /**
+     * Bring the schema up to {@link SCHEMA_VERSION}. Runs in ONE write
+     * transaction and re-reads the version inside it, so two processes opening a
+     * fresh file at once can't both apply the same step. A file written by a
+     * NEWER build is left untouched (its migrations are additive, so this build's
+     * queries still work) rather than "repaired" downwards.
+     */
+    migrate() {
+        this.db.transaction(() => {
+            const current = Number(this.db.get('PRAGMA user_version', [])?.user_version ?? 0);
+            if (current > SCHEMA_VERSION) {
+                console.error(`[untappd-mcp] cache schema v${current} is newer than this build (v${SCHEMA_VERSION}); using it as-is.`);
+                this.version = current;
+                return;
             }
-            catch {
-                /* column already exists */
+            if (current < 1) {
+                for (const stmt of SCHEMA_STATEMENTS)
+                    this.db.execScript(stmt);
+                // A pre-versioning file may lack any of these columns; each ADD COLUMN
+                // throws harmlessly if the column is already present.
+                for (const mig of MIGRATIONS) {
+                    try {
+                        this.db.execScript(mig);
+                    }
+                    catch {
+                        /* column already exists */
+                    }
+                }
             }
-        }
+            for (const m of VERSIONED_MIGRATIONS) {
+                if (m.version <= current)
+                    continue;
+                for (const stmt of m.statements)
+                    this.db.execScript(stmt);
+            }
+            if (current !== SCHEMA_VERSION)
+                this.db.execScript(`PRAGMA user_version = ${SCHEMA_VERSION}`);
+            this.version = SCHEMA_VERSION;
+        });
+    }
+    /** The schema version of the open database. */
+    schemaVersion() {
+        return this.version;
     }
     /**
      * Upsert real check-in rows (dedupe on checkin_id) in one transaction; return
@@ -221,7 +288,7 @@ export class CheckinStoreCore {
         if (rows.length === 0)
             return 0;
         const key = username.toLowerCase();
-        const before = this.cachedCount(username);
+        let added = 0;
         const sql = `
       INSERT INTO checkins
         (checkin_id, username, bid, beer_name, brewery_id, brewery_name, beer_style, abv, rating, comment, venue_id, venue_name, created_at)
@@ -231,7 +298,14 @@ export class CheckinStoreCore {
         brewery_id=excluded.brewery_id, brewery_name=excluded.brewery_name, beer_style=excluded.beer_style,
         abv=excluded.abv, rating=excluded.rating, comment=excluded.comment,
         venue_id=excluded.venue_id, venue_name=excluded.venue_name, created_at=excluded.created_at`;
+        // "Net new" = ids this user didn't already have, read inside the write
+        // transaction so another process's concurrent inserts can't skew it. It
+        // looks up only this batch's ids; COUNT(*)-before/after scanned the user's
+        // whole history on every page, which made a long backfill quadratic.
         this.db.transaction(() => {
+            const ids = [...new Set(rows.map((r) => r.checkin_id))];
+            const had = this.existing('checkins', 'checkin_id', key, ids);
+            added = ids.filter((id) => !had.has(id)).length;
             for (const r of rows) {
                 this.db.run(sql, [
                     r.checkin_id, key, r.bid, r.beer_name, r.brewery_id, r.brewery_name, r.beer_style,
@@ -239,14 +313,14 @@ export class CheckinStoreCore {
                 ]);
             }
         });
-        return this.cachedCount(username) - before;
+        return added;
     }
     /** Upsert distinct-beer rows (dedupe on username+bid); return the NET new count. */
     upsertDistinctBeers(username, rows) {
         if (rows.length === 0)
             return 0;
         const key = username.toLowerCase();
-        const before = this.distinctBeersCount(username);
+        let added = 0;
         const sql = `
       INSERT INTO distinct_beers
         (username, bid, beer_name, brewery_id, brewery_name, beer_style, abv, rating, had_count, first_had, last_had)
@@ -256,6 +330,9 @@ export class CheckinStoreCore {
         beer_style=excluded.beer_style, abv=excluded.abv, rating=excluded.rating,
         had_count=excluded.had_count, first_had=excluded.first_had, last_had=excluded.last_had`;
         this.db.transaction(() => {
+            const bids = [...new Set(rows.map((r) => r.bid))];
+            const had = this.existing('distinct_beers', 'bid', key, bids);
+            added = bids.filter((b) => !had.has(b)).length;
             for (const r of rows) {
                 this.db.run(sql, [
                     key, r.bid, r.beer_name, r.brewery_id, r.brewery_name, r.beer_style, r.abv,
@@ -263,7 +340,17 @@ export class CheckinStoreCore {
                 ]);
             }
         });
-        return this.distinctBeersCount(username) - before;
+        return added;
+    }
+    /** Which of `ids` already exist in `table.column` for this (lowercased) user. */
+    existing(table, column, key, ids) {
+        const found = new Set();
+        for (const part of chunks(ids)) {
+            const rows = this.db.all(`SELECT ${column} AS id FROM ${table} WHERE username = ? AND ${column} IN (${part.map(() => '?').join(', ')})`, [key, ...part]);
+            for (const r of rows)
+                found.add(Number(r.id));
+        }
+        return found;
     }
     /** Total cached check-in rows for a user. */
     cachedCount(username) {
@@ -312,6 +399,11 @@ export class CheckinStoreCore {
      * merge could not do that.
      */
     setState(username, patch) {
+        // Read-merge-write in one write transaction, so a second process's patch
+        // can't land between the read and the write and be silently reverted.
+        this.db.transaction(() => this.mergeState(username, patch));
+    }
+    mergeState(username, patch) {
         const key = username.toLowerCase();
         const cur = this.getState(key);
         const pick = (k, fallback) => k in patch ? patch[k] : (cur?.[k] ?? fallback);
@@ -421,6 +513,46 @@ export class CheckinStoreCore {
             matches,
         };
     }
+    /**
+     * {@link hasHad} for many bids at once, in two grouped queries per chunk
+     * instead of ~4 per bid. Same merge rules: a hit in either source counts,
+     * `count` prefers user/beers' authoritative had_count, dates and ratings take
+     * the max across both. No per-check-in `matches` — callers of the batch form
+     * only want the verdict. Every requested bid gets an entry.
+     */
+    hasHadMany(username, bids) {
+        const key = username.toLowerCase();
+        const out = new Map();
+        const unique = [...new Set(bids)];
+        for (const bid of unique)
+            out.set(bid, { had: false, count: 0, last_date: null, best_rating: null, sources: [] });
+        for (const part of chunks(unique)) {
+            const ph = part.map(() => '?').join(', ');
+            for (const r of this.db.all(`SELECT bid, COUNT(*) AS c, MAX(rating) AS best, MAX(created_at) AS last
+         FROM checkins WHERE username = ? AND bid IN (${ph}) GROUP BY bid`, [key, ...part])) {
+                const v = out.get(Number(r.bid));
+                v.had = true;
+                v.count = Number(r.c);
+                v.best_rating = num(r.best);
+                v.last_date = str(r.last);
+                v.sources.push('checkins');
+            }
+            for (const r of this.db.all(`SELECT bid, had_count, rating, last_had, first_had FROM distinct_beers WHERE username = ? AND bid IN (${ph})`, [key, ...part])) {
+                const v = out.get(Number(r.bid));
+                v.had = true;
+                // Prefer the user/beers count; else keep the check-in-derived count; else 1.
+                v.count = num(r.had_count) ?? (v.count || 1);
+                const rating = num(r.rating);
+                if (rating !== null && (v.best_rating === null || rating > v.best_rating))
+                    v.best_rating = rating;
+                const last = str(r.last_had) ?? str(r.first_had);
+                if (last && (v.last_date === null || last > v.last_date))
+                    v.last_date = last;
+                v.sources.push('beers');
+            }
+        }
+        return out;
+    }
     query(username, filters) {
         const where = ['username = ?'];
         const params = [username.toLowerCase()];
@@ -482,6 +614,59 @@ export class CheckinStoreCore {
         });
         return removed;
     }
+    getDistinctBeers(username, bids) {
+        if (bids.length === 0)
+            return [];
+        const placeholders = bids.map(() => '?').join(', ');
+        return this.db.all(`SELECT * FROM distinct_beers WHERE username = ? AND bid IN (${placeholders})`, [username.toLowerCase(), ...bids]);
+    }
+    getResolutions(keys) {
+        if (keys.length === 0)
+            return [];
+        const placeholders = keys.map(() => '?').join(', ');
+        return this.db.all(`SELECT * FROM item_resolutions WHERE key IN (${placeholders})`, keys);
+    }
+    upsertResolutions(rows) {
+        if (rows.length === 0)
+            return;
+        const sql = `
+      INSERT INTO item_resolutions (key, item, status, bid, data, resolved_at)
+      VALUES (?, ?, ?, ?, ?, ?)
+      ON CONFLICT(key) DO UPDATE SET
+        item=excluded.item, status=excluded.status, bid=excluded.bid,
+        data=excluded.data, resolved_at=excluded.resolved_at`;
+        this.db.transaction(() => {
+            for (const r of rows)
+                this.db.run(sql, [r.key, r.item, r.status, r.bid, r.data, r.resolved_at]);
+        });
+    }
+    stats() {
+        const n = (sql) => Number(this.db.get(sql, [])?.n ?? 0);
+        const names = this.db
+            .all(`SELECT username FROM sync_state
+         UNION SELECT DISTINCT username FROM distinct_beers
+         UNION SELECT DISTINCT username FROM checkins
+         ORDER BY username`, [])
+            .map((r) => String(r.username));
+        const users = names.map((username) => {
+            const st = this.getState(username);
+            return {
+                username,
+                cached_distinct_beers: this.distinctBeersCount(username),
+                total_distinct_beers: st?.beers_total ?? null,
+                cached_checkins: this.cachedCount(username),
+                coverage_complete: (st?.beers_complete ?? false) || (st?.backfill_complete ?? false),
+                beers_offset: st?.beers_offset ?? null,
+                last_synced_at: st?.last_synced_at ?? null,
+            };
+        });
+        return {
+            schema_version: this.version,
+            users,
+            resolution_cache_entries: n('SELECT COUNT(*) AS n FROM item_resolutions'),
+            beer_meta_entries: n('SELECT COUNT(*) AS n FROM beer_meta'),
+        };
+    }
     getBeerMeta(bids) {
         if (bids.length === 0)
             return [];
@@ -547,6 +732,9 @@ export class LocalCacheStore {
     async hasHad(username, opts) {
         return this.core.hasHad(username, opts);
     }
+    async hasHadMany(username, bids) {
+        return this.core.hasHadMany(username, bids);
+    }
     async query(username, filters) {
         return this.core.query(username, filters);
     }
@@ -559,6 +747,27 @@ export class LocalCacheStore {
     async forgetUser(username) {
         return this.core.forgetUser(username);
     }
+    async getDistinctBeers(username, bids) {
+        return this.core.getDistinctBeers(username, bids);
+    }
+    async getResolutions(keys) {
+        return this.core.getResolutions(keys);
+    }
+    async upsertResolutions(rows) {
+        this.core.upsertResolutions(rows);
+    }
+    async stats() {
+        return this.core.stats();
+    }
+}
+// SQLite caps bound parameters per statement (999 on older builds); IN-lists
+// are split well under that.
+const IN_CHUNK = 500;
+function chunks(xs) {
+    const out = [];
+    for (let i = 0; i < xs.length; i += IN_CHUNK)
+        out.push(xs.slice(i, i + IN_CHUNK));
+    return out;
 }
 // Case-insensitive substring match whose pattern is built by escapeLike(): the
 // ESCAPE clause makes a backslash-prefixed %, _ or backslash match itself literally.

package/dist/cache/sync-beers.js

@@ -51,6 +51,7 @@ export async function syncUserBeers(client, cache, rawUsername, maxPages = 10) {
     let complete = false;
     let pages = 0;
     let added = 0;
+    let stoppedAtBid = null;
     const firstFetch = async (o) => {
         try {
             return await fetchBeersPage(client, encodedUser, o);
@@ -72,17 +73,37 @@ export async function syncUserBeers(client, cache, rawUsername, maxPages = 10) {
         // An empty (e.g. first) page still means the list is fully paged.
         let atEnd = page.items.length === 0;
         if (!atEnd) {
-            const rows = rowsOf(rawUsername, page.items);
+            let rows = rowsOf(rawUsername, page.items);
+            // Incremental refresh of a complete cache: the list is sorted by each
+            // beer's MOST RECENT check-in, so the first item whose cached copy is
+            // unchanged (same last-had date and count) marks where this refresh
+            // meets the previous one — everything below it was last had earlier and
+            // is already cached. Stop there instead of paging the whole list. A beer
+            // that is cached but CHANGED (re-had since) does not stop the walk: a
+            // brand-new beer can sit below it.
+            let hitKnown = false;
+            if (refreshing) {
+                const known = new Map((await cache.getDistinctBeers(rawUsername, rows.map((r) => r.bid))).map((r) => [r.bid, r]));
+                const stop = rows.findIndex((r) => {
+                    const k = known.get(r.bid);
+                    return k !== undefined && k.last_had === r.last_had && k.had_count === r.had_count;
+                });
+                if (stop !== -1) {
+                    hitKnown = true;
+                    stoppedAtBid = rows[stop].bid;
+                    rows = rows.slice(0, stop);
+                }
+            }
             const netNew = await cache.upsertDistinctBeers(rawUsername, rows);
             added += netNew;
             offset += page.items.length;
             // End conditions: caught the whole list, a short (final) page, or — during an
-            // incremental top refresh — a page that added nothing new.
-            if (total !== null && offset >= total)
+            // incremental top refresh — reaching an unchanged cached beer.
+            if (hitKnown)
                 atEnd = true;
-            else if (page.items.length < PAGE_LIMIT)
+            else if (total !== null && offset >= total)
                 atEnd = true;
-            else if (refreshing && netNew === 0)
+            else if (page.items.length < PAGE_LIMIT)
                 atEnd = true;
             else if (rescanTarget !== null && (await gapNow()) <= rescanTarget)
                 atEnd = true;
@@ -135,6 +156,7 @@ export async function syncUserBeers(client, cache, rawUsername, maxPages = 10) {
         backfill_percent: percent,
         beers_complete: complete,
         incremental,
+        stopped_at_bid: stoppedAtBid,
         another_run_needed: anotherRunNeeded,
         last_synced_at: now(),
         note,

package/dist/client.js

@@ -13,6 +13,8 @@ if (import.meta.url) {
 const BASE_URL = 'https://api.untappd.com/v4';
 const SERVICE = 'Untappd';
 const REQUEST_TIMEOUT_MS = 30_000;
+// Untappd's limit is per hour, so a remaining-count older than that says nothing.
+const QUOTA_WINDOW_MS = 60 * 60 * 1000;
 // Non-secret client constants that mimic the Untappd iPad app (v4.7.13). The
 // API accepts requests carrying these; NONE are user secrets (the secrets are
 // UNTAPPD_CLIENT_ID / UNTAPPD_CLIENT_SECRET / UNTAPPD_USERNAME / _PASSWORD,
@@ -151,6 +153,8 @@ export class UntappdClient {
     userAgent = readEnvVar('UNTAPPD_USER_AGENT') ?? DEFAULTS.userAgent;
     token;
     loginInFlight = null;
+    /** Last `X-Ratelimit-Remaining` seen, and when (see {@link quotaRemaining}). */
+    lastQuota = null;
     tokenIsSupplied;
     /**
      * Defer the config error so the server can still start (and respond to the
@@ -206,6 +210,25 @@ export class UntappdClient {
     get loginName() {
         return this._loginName;
     }
+    /**
+     * Calls left this hour, from the most recent response's
+     * `X-Ratelimit-Remaining` — or null when no response has carried the header
+     * within the hour. Untappd's public API documents the header; whether the
+     * private v4 endpoints send it is unverified, so every consumer must treat
+     * null as "unknown" and fall back to its own budget.
+     */
+    get quotaRemaining() {
+        if (!this.lastQuota || Date.now() - this.lastQuota.at > QUOTA_WINDOW_MS)
+            return null;
+        return this.lastQuota.remaining;
+    }
+    noteQuota(res) {
+        const raw = res.headers.get('x-ratelimit-remaining');
+        const n = raw === null ? NaN : Number(raw);
+        if (raw !== null && raw.trim() !== '' && Number.isFinite(n) && n >= 0) {
+            this.lastQuota = { remaining: Math.floor(n), at: Date.now() };
+        }
+    }
     /** App creds for a write; reached only once a token is in hand. */
     requireAppCreds() {
         if (!this.clientId || !this.clientSecret) {
@@ -315,6 +338,7 @@ export class UntappdClient {
             body = f.toString();
         }
         const res = await this.send(method, `${BASE_URL}${path}${qs}`, { headers, body });
+        this.noteQuota(res);
         // A 401 means the token went stale. Re-minting one needs a login, and a
         // deployment that SUPPLIED the token may have no username/password to log
         // in with — that fell through to `missingCredsError()` and told the

package/dist/index.js

@@ -14,16 +14,21 @@ import { registerWishlistTools } from './tools/wishlist.js';
 import { registerCheckinTools } from './tools/checkin.js';
 import { registerUtilityTools } from './tools/utilities.js';
 import { registerCacheTools } from './tools/cache.js';
+import { registerMenuTools } from './tools/menu.js';
 import { logRegisteredTools } from './tools/diagnostics.js';
-import { CheckinCache, defaultCachePath } from './cache/db.js';
+import { CheckinCache, defaultCachePath, describeCachePath } from './cache/db.js';
 // Build the env-based client once and inject it into each registrar. The
 // constructor defers its config error, so the server still boots (and answers
 // the host's install-time tools/list probe) when credentials are absent.
 const client = new UntappdClient();
 // The stdio server backs the cache with a local `node:sqlite` file, opened lazily
 // on first cache-tool use so the server still boots when no path is configured.
+// The path is resolved (and logged) once at startup, so it can't drift with the
+// working directory a host happens to launch from.
+const cachePath = defaultCachePath();
+console.error(describeCachePath(cachePath));
 let nodeCache;
-const nodeCacheProvider = () => (nodeCache ??= CheckinCache.open(defaultCachePath()));
+const nodeCacheProvider = () => (nodeCache ??= CheckinCache.open(cachePath));
 await runMcp({
     name: 'untappd-mcp',
     version: VERSION,
@@ -43,6 +48,7 @@ await runMcp({
         // The cache is backed by a local `node:sqlite` file here; the provider is
         // injectable, so another deployment can back the same tools differently.
         (s) => registerCacheTools(s, client, nodeCacheProvider),
+        (s) => registerMenuTools(s, client, nodeCacheProvider),
         // Keep last: logs the full registered toolset (count + names) at startup.
         (s) => logRegisteredTools(s, 'stdio'),
     ],