untappd-mcp 1.2.0 → 1.3.1

package/dist/cache/db.js

@@ -0,0 +1,293 @@
+import { DatabaseSync } from 'node:sqlite';
+import { mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { readEnvVar } from '@chrischall/mcp-utils';
+function asDict(v) {
+    return v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+}
+function num(v) {
+    return typeof v === 'number' && Number.isFinite(v) ? v : null;
+}
+function str(v) {
+    return typeof v === 'string' && v.length > 0 ? v : null;
+}
+/**
+ * Normalise a raw `/user/checkins` item to a {@link CheckinRow}. Reads only the
+ * documented list fields (the same ones `compactCheckin` uses) and derives
+ * nothing it can't. `created_at` is normalised to ISO-8601 UTC so it sorts
+ * lexicographically = chronologically and date-range filters are plain string
+ * comparisons; the raw RFC-2822 string is kept if it can't be parsed.
+ */
+export function mapCheckinRow(username, item) {
+    const c = asDict(item);
+    const checkin_id = num(c.checkin_id);
+    if (checkin_id === null)
+        return null; // can't key it — skip rather than corrupt the table
+    const beer = asDict(c.beer);
+    const brewery = asDict(c.brewery);
+    const venue = asDict(c.venue); // Untappd sends `venue: []` when none — asDict → {}
+    return {
+        checkin_id,
+        username,
+        bid: num(beer.bid),
+        beer_name: str(beer.beer_name),
+        brewery_id: num(brewery.brewery_id),
+        brewery_name: str(brewery.brewery_name),
+        beer_style: str(beer.beer_style),
+        abv: num(beer.beer_abv),
+        rating: num(c.rating_score),
+        comment: str(c.checkin_comment),
+        venue_id: num(venue.venue_id),
+        venue_name: str(venue.venue_name),
+        created_at: normaliseDate(c.created_at),
+    };
+}
+function normaliseDate(v) {
+    const s = str(v);
+    if (!s)
+        return null;
+    const t = Date.parse(s);
+    return Number.isNaN(t) ? s : new Date(t).toISOString();
+}
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS checkins (
+  checkin_id   INTEGER PRIMARY KEY,
+  username     TEXT NOT NULL,
+  bid          INTEGER,
+  beer_name    TEXT,
+  brewery_id   INTEGER,
+  brewery_name TEXT,
+  beer_style   TEXT,
+  abv          REAL,
+  rating       REAL,
+  comment      TEXT,
+  venue_id     INTEGER,
+  venue_name   TEXT,
+  created_at   TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_checkins_user_bid ON checkins(username, bid);
+CREATE INDEX IF NOT EXISTS idx_checkins_user_brewery ON checkins(username, brewery_id);
+
+CREATE TABLE IF NOT EXISTS sync_state (
+  username          TEXT PRIMARY KEY,
+  oldest_max_id     INTEGER,
+  newest_checkin_id INTEGER,
+  catchup_max_id    INTEGER,
+  last_synced_at    TEXT,
+  backfill_complete INTEGER NOT NULL DEFAULT 0,
+  total_checkins    INTEGER
+);
+`;
+/**
+ * Wraps a single SQLite database file. Usernames are compared
+ * case-insensitively via a lowercased key so `Mer1331` and `mer1331` share one
+ * cache; the original casing the caller passed is preserved in stored rows.
+ */
+export class CheckinCache {
+    db;
+    constructor(db) {
+        this.db = db;
+        this.db.exec(SCHEMA);
+        this.migrate();
+    }
+    // Forward-compat for a sync_state table created before a column existed. Each
+    // ADD COLUMN throws harmlessly if the column is already present.
+    migrate() {
+        for (const col of ['catchup_max_id INTEGER']) {
+            try {
+                this.db.exec(`ALTER TABLE sync_state ADD COLUMN ${col}`);
+            }
+            catch {
+                /* column already exists */
+            }
+        }
+    }
+    /** Open (creating parent dirs) a file-backed cache, or `:memory:` for tests. */
+    static open(path) {
+        if (path !== ':memory:')
+            mkdirSync(dirname(path), { recursive: true });
+        return new CheckinCache(new DatabaseSync(path));
+    }
+    close() {
+        this.db.close();
+    }
+    /**
+     * Upsert a batch of rows (dedupe on checkin_id) inside one transaction and
+     * return the NET number of newly-inserted rows (updates to existing rows count
+     * as 0), which is what "rows added" reports.
+     */
+    upsertCheckins(username, rows) {
+        if (rows.length === 0)
+            return 0;
+        const key = username.toLowerCase();
+        const before = this.cachedCount(username);
+        const stmt = this.db.prepare(`
+      INSERT INTO checkins
+        (checkin_id, username, bid, beer_name, brewery_id, brewery_name, beer_style, abv, rating, comment, venue_id, venue_name, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(checkin_id) DO UPDATE SET
+        username=excluded.username, bid=excluded.bid, beer_name=excluded.beer_name,
+        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
+    `);
+        this.db.exec('BEGIN');
+        try {
+            for (const r of rows) {
+                stmt.run(r.checkin_id, key, r.bid, r.beer_name, r.brewery_id, r.brewery_name, r.beer_style, r.abv, r.rating, r.comment, r.venue_id, r.venue_name, r.created_at);
+            }
+            this.db.exec('COMMIT');
+        }
+        catch (e) {
+            this.db.exec('ROLLBACK');
+            throw e;
+        }
+        return this.cachedCount(username) - before;
+    }
+    /** Total cached check-ins for a user (= distinct check-ins, since PK is checkin_id). */
+    cachedCount(username) {
+        const row = this.db
+            .prepare('SELECT COUNT(*) AS n FROM checkins WHERE username = ?')
+            .get(username.toLowerCase());
+        return row.n;
+    }
+    /** Distinct beers (unique bids) cached for a user. */
+    distinctBeerCount(username) {
+        const row = this.db
+            .prepare('SELECT COUNT(DISTINCT bid) AS n FROM checkins WHERE username = ? AND bid IS NOT NULL')
+            .get(username.toLowerCase());
+        return row.n;
+    }
+    /** Highest cached checkin_id for a user (the true newest once contiguous), or null. */
+    newestCachedId(username) {
+        const row = this.db
+            .prepare('SELECT MAX(checkin_id) AS m FROM checkins WHERE username = ?')
+            .get(username.toLowerCase());
+        return row.m;
+    }
+    getState(username) {
+        const row = this.db.prepare('SELECT * FROM sync_state WHERE username = ?').get(username.toLowerCase());
+        if (!row)
+            return undefined;
+        return { ...row, username: row.username, backfill_complete: row.backfill_complete === 1 };
+    }
+    /**
+     * Insert-or-merge sync state. Only keys PRESENT in `patch` are written, so an
+     * explicit `null` (e.g. clearing `oldest_max_id` when backfill completes)
+     * overrides the stored value — a `??` merge could not do that.
+     */
+    setState(username, patch) {
+        const key = username.toLowerCase();
+        const cur = this.getState(key);
+        const pick = (k, fallback) => k in patch ? patch[k] : (cur?.[k] ?? fallback);
+        const next = {
+            username: key,
+            oldest_max_id: pick('oldest_max_id', null),
+            newest_checkin_id: pick('newest_checkin_id', null),
+            catchup_max_id: pick('catchup_max_id', null),
+            last_synced_at: pick('last_synced_at', null),
+            backfill_complete: pick('backfill_complete', false),
+            total_checkins: pick('total_checkins', null),
+        };
+        this.db
+            .prepare(`INSERT INTO sync_state (username, oldest_max_id, newest_checkin_id, catchup_max_id, last_synced_at, backfill_complete, total_checkins)
+         VALUES (?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(username) DO UPDATE SET
+           oldest_max_id=excluded.oldest_max_id, newest_checkin_id=excluded.newest_checkin_id,
+           catchup_max_id=excluded.catchup_max_id,
+           last_synced_at=excluded.last_synced_at, backfill_complete=excluded.backfill_complete,
+           total_checkins=excluded.total_checkins`)
+            .run(key, next.oldest_max_id, next.newest_checkin_id, next.catchup_max_id, next.last_synced_at, next.backfill_complete ? 1 : 0, next.total_checkins);
+    }
+    /** Exact bid match or case-insensitive substring match on beer name. */
+    hasHad(username, opts) {
+        const where = ['username = ?'];
+        const params = [username.toLowerCase()];
+        if (opts.bid !== undefined) {
+            where.push('bid = ?');
+            params.push(opts.bid);
+        }
+        if (opts.beerName !== undefined) {
+            where.push('beer_name LIKE ? COLLATE NOCASE');
+            params.push(`%${escapeLike(opts.beerName)}%`);
+        }
+        const clause = where.join(' AND ');
+        const agg = this.db
+            .prepare(`SELECT COUNT(*) AS n, MAX(rating) AS best FROM checkins WHERE ${clause}`)
+            .get(...params);
+        // Most-recent first: checkin_id is monotonic in time, a reliable ordering
+        // even though created_at is a formatted string.
+        const matches = this.db
+            .prepare(`SELECT checkin_id, bid, beer_name, rating, venue_name, created_at
+         FROM checkins WHERE ${clause} ORDER BY checkin_id DESC LIMIT 25`)
+            .all(...params);
+        return {
+            had: agg.n > 0,
+            count: agg.n,
+            last_date: matches[0]?.created_at ?? null,
+            best_rating: agg.best,
+            matches,
+        };
+    }
+    query(username, filters) {
+        const where = ['username = ?'];
+        const params = [username.toLowerCase()];
+        if (filters.brewery_id !== undefined) {
+            where.push('brewery_id = ?');
+            params.push(filters.brewery_id);
+        }
+        if (filters.brewery !== undefined) {
+            where.push('brewery_name LIKE ? COLLATE NOCASE');
+            params.push(`%${escapeLike(filters.brewery)}%`);
+        }
+        if (filters.style !== undefined) {
+            where.push('beer_style LIKE ? COLLATE NOCASE');
+            params.push(`%${escapeLike(filters.style)}%`);
+        }
+        if (filters.min_rating !== undefined) {
+            where.push('rating >= ?');
+            params.push(filters.min_rating);
+        }
+        if (filters.venue !== undefined) {
+            where.push('venue_name LIKE ? COLLATE NOCASE');
+            params.push(`%${escapeLike(filters.venue)}%`);
+        }
+        if (filters.venue_id !== undefined) {
+            where.push('venue_id = ?');
+            params.push(filters.venue_id);
+        }
+        // created_at is ISO-8601, so a YYYY-MM-DD bound compares correctly on its date prefix.
+        if (filters.date_from !== undefined) {
+            where.push('substr(created_at, 1, 10) >= ?');
+            params.push(filters.date_from);
+        }
+        if (filters.date_to !== undefined) {
+            where.push('substr(created_at, 1, 10) <= ?');
+            params.push(filters.date_to);
+        }
+        const order = filters.sort === 'oldest'
+            ? 'checkin_id ASC'
+            : filters.sort === 'highest_rated'
+                ? 'rating DESC, checkin_id DESC'
+                : filters.sort === 'lowest_rated'
+                    ? 'rating ASC, checkin_id DESC'
+                    : 'checkin_id DESC';
+        const limit = Math.min(Math.max(filters.limit ?? 25, 1), 200);
+        const rows = this.db
+            .prepare(`SELECT * FROM checkins WHERE ${where.join(' AND ')} ORDER BY ${order} LIMIT ?`)
+            .all(...params, limit);
+        return rows;
+    }
+}
+// Escape LIKE wildcards in user input so a literal % or _ isn't treated as a
+// wildcard. Our LIKE patterns don't set an ESCAPE clause, so we only need to
+// avoid a query that matches unexpectedly; backslash-escaping the specials and
+// pairing with the default is not portable, so we simply strip them.
+function escapeLike(s) {
+    return s.replace(/[%_]/g, ' ');
+}
+/** Default on-disk cache path: `$UNTAPPD_CACHE_DB` or `~/.untappd-mcp/checkins.db`. */
+export function defaultCachePath() {
+    return readEnvVar('UNTAPPD_CACHE_DB') ?? join(homedir(), '.untappd-mcp', 'checkins.db');
+}

package/dist/cache/sync.js

@@ -0,0 +1,202 @@
+import { createHelpfulError, RateLimitError, messageOf } from '@chrischall/mcp-utils';
+import { mapCheckinRow } from './db.js';
+const PAGE_LIMIT = 50; // Untappd's max page size for /user/checkins.
+/** One `/user/checkins` page fetch, tolerant of the fat/undocumented shape. */
+async function fetchPage(client, encodedUser, maxId) {
+    const data = await client.get(`/user/checkins/${encodedUser}`, { limit: PAGE_LIMIT, max_id: maxId });
+    const box = data?.checkins ?? {};
+    const items = Array.isArray(box.items) ? box.items : [];
+    const raw = box.pagination?.max_id;
+    const nextMaxId = typeof raw === 'number' && raw > 0 ? raw : null;
+    return { items, nextMaxId };
+}
+function rowsOf(username, items) {
+    const rows = [];
+    for (const it of items) {
+        const r = mapCheckinRow(username, it);
+        if (r)
+            rows.push(r);
+    }
+    return rows;
+}
+/** Best-effort stats.total_checkins for the % estimate; null if it can't be read. */
+async function fetchTotalCheckins(client, encodedUser) {
+    try {
+        const info = await client.get(`/user/info/${encodedUser}`);
+        const t = info?.user?.stats?.total_checkins;
+        return typeof t === 'number' ? t : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Sync a user's Untappd check-ins into the local cache.
+ *
+ * - **Incremental**: on a repeat sync, page from the top and stop as soon as a
+ *   check-in at or below the stored `newest_checkin_id` appears (already cached).
+ * - **Backfill**: while `backfill_complete` is false, resume paging backwards
+ *   from the stored `oldest_max_id`, up to `maxPages` pages per invocation so a
+ *   single run stays well under the rate limit. State is persisted after EVERY
+ *   page, so an interrupted run (rate limit, crash) resumes exactly where it
+ *   stopped and never loses fetched data.
+ *
+ * `maxPages` is the TOTAL page budget for the invocation (incremental +
+ * backfill), so the call can never fetch more than `maxPages` pages.
+ */
+export async function syncCheckins(client, cache, rawUsername, maxPages = 10) {
+    const encodedUser = encodeURIComponent(rawUsername);
+    const prior = cache.getState(rawUsername);
+    const priorNewest = prior?.newest_checkin_id ?? null;
+    let pages = 0;
+    let added = 0;
+    let newest = priorNewest;
+    let backfillComplete = prior?.backfill_complete ?? false;
+    let oldestMaxId = prior?.oldest_max_id ?? null;
+    // Resume cursor for an unfinished top catch-up. Non-null → a prior run advanced
+    // partway through a burst of new check-ins but ran out of page budget before
+    // reconnecting to the cached block; this run resumes from here.
+    let catchupMaxId = prior?.catchup_max_id ?? null;
+    let catchupInProgress = catchupMaxId !== null;
+    const now = () => new Date().toISOString();
+    // Wrap the very first fetch so a private/non-friend account produces a clear,
+    // actionable error instead of a raw upstream failure. Rate limits are
+    // preserved as-is (they're meaningful and any prior progress is saved).
+    const firstFetch = async (maxId) => {
+        try {
+            return await fetchPage(client, encodedUser, maxId);
+        }
+        catch (e) {
+            if (e instanceof RateLimitError)
+                throw e;
+            throw createHelpfulError(`Could not fetch check-ins for "${rawUsername}": ${messageOf(e)}`, {
+                hint: "Untappd only returns another user's check-ins if their account is public or they're your friend. If the account is private, add them as a friend (untappd_add_friend) first, or sync only your own account.",
+            });
+        }
+    };
+    // ── Phase 1: incremental catch-up of the new-top region (resumable) ──
+    // Only meaningful once we have a cached block (priorNewest set). Pages from the
+    // top (or a resumed cursor) DOWN until it reconnects to the cached block —
+    // i.e. a page whose oldest id <= priorNewest. Crucially, `newest_checkin_id`
+    // is NOT advanced until that reconnection happens: if the run exhausts its page
+    // budget first, the boundary stays put and a resume cursor is saved, so a burst
+    // of more than maxPages*50 new check-ins can never strand a permanent gap.
+    if (priorNewest !== null) {
+        let maxId = catchupMaxId ?? undefined;
+        let caughtUp = false;
+        for (; pages < maxPages;) {
+            const page = pages === 0 ? await firstFetch(maxId) : await fetchPage(client, encodedUser, maxId);
+            pages++;
+            if (page.items.length === 0) {
+                caughtUp = true;
+                break;
+            }
+            const rows = rowsOf(rawUsername, page.items);
+            added += cache.upsertCheckins(rawUsername, rows);
+            const oldestOnPage = rows[rows.length - 1].checkin_id;
+            if (oldestOnPage <= priorNewest) {
+                caughtUp = true; // reconnected to the cached block
+                break;
+            }
+            if (page.nextMaxId === null) {
+                // Paged all the way to the true bottom via the top — the whole history
+                // is now contiguous, so the backfill is complete too.
+                caughtUp = true;
+                backfillComplete = true;
+                oldestMaxId = null;
+                break;
+            }
+            catchupMaxId = page.nextMaxId;
+            // Persist the resume cursor after EVERY page; the boundary stays put.
+            cache.setState(rawUsername, { catchup_max_id: catchupMaxId, last_synced_at: now() });
+            maxId = page.nextMaxId;
+        }
+        if (caughtUp) {
+            // Contiguous from the true newest down to the old block: advance the
+            // boundary and clear the catch-up cursor.
+            newest = cache.newestCachedId(rawUsername);
+            catchupMaxId = null;
+            catchupInProgress = false;
+            cache.setState(rawUsername, {
+                newest_checkin_id: newest,
+                catchup_max_id: null,
+                backfill_complete: backfillComplete,
+                oldest_max_id: oldestMaxId,
+                last_synced_at: now(),
+            });
+        }
+        else {
+            catchupInProgress = true; // budget spent mid-catch-up; next run resumes
+        }
+    }
+    // ── Phase 2: backfill older history (resumable) ──
+    // Skipped while a catch-up is still in progress (that already spent the budget).
+    if (!backfillComplete && !catchupInProgress) {
+        // First-ever sync starts from the top (undefined); a resumed backfill picks
+        // up from the stored cursor.
+        let maxId = oldestMaxId ?? undefined;
+        for (; pages < maxPages;) {
+            const first = pages === 0; // true only on a first-ever sync (phase 1 was skipped)
+            const page = first ? await firstFetch(maxId) : await fetchPage(client, encodedUser, maxId);
+            pages++;
+            if (page.items.length === 0) {
+                backfillComplete = true;
+                break;
+            }
+            const rows = rowsOf(rawUsername, page.items);
+            added += cache.upsertCheckins(rawUsername, rows);
+            if (newest === null)
+                newest = rows[0].checkin_id; // first-ever sync sets the boundary
+            oldestMaxId = page.nextMaxId;
+            if (page.nextMaxId === null)
+                backfillComplete = true;
+            // Persist progress after EVERY page so an interruption never loses work.
+            cache.setState(rawUsername, {
+                newest_checkin_id: newest,
+                oldest_max_id: oldestMaxId,
+                backfill_complete: backfillComplete,
+                last_synced_at: now(),
+            });
+            if (backfillComplete)
+                break;
+            maxId = page.nextMaxId ?? undefined;
+        }
+    }
+    const total = await fetchTotalCheckins(client, encodedUser);
+    const cached = cache.cachedCount(rawUsername);
+    cache.setState(rawUsername, {
+        newest_checkin_id: newest,
+        oldest_max_id: oldestMaxId,
+        catchup_max_id: catchupMaxId,
+        backfill_complete: backfillComplete,
+        total_checkins: total,
+        last_synced_at: now(),
+    });
+    const backfillPercent = total && total > 0
+        ? Math.min(100, Math.round((cached / total) * 100))
+        : backfillComplete && !catchupInProgress
+            ? 100
+            : null;
+    // Another run is needed while EITHER frontier is unfinished: the bottom
+    // backfill, or an in-progress top catch-up of a large burst of new check-ins.
+    const anotherRunNeeded = !backfillComplete || catchupInProgress;
+    const note = catchupInProgress
+        ? 'More new check-ins remain than fit in this run — run untappd_sync_checkins again to finish catching up the newest check-ins.'
+        : backfillComplete
+            ? 'Full history is cached. Re-run occasionally to pick up new check-ins.'
+            : `Backfill incomplete — run untappd_sync_checkins again to fetch the next ${maxPages} pages of older check-ins.`;
+    return {
+        username: rawUsername,
+        rows_added: added,
+        pages_fetched: pages,
+        cached_checkins: cached,
+        distinct_beers: cache.distinctBeerCount(rawUsername),
+        total_checkins: total,
+        backfill_percent: backfillPercent,
+        backfill_complete: backfillComplete,
+        catchup_in_progress: catchupInProgress,
+        another_run_needed: anotherRunNeeded,
+        last_synced_at: now(),
+        note,
+    };
+}

package/dist/index.js

@@ -13,6 +13,7 @@ import { registerFriendActionTools } from './tools/friends.js';
 import { registerWishlistTools } from './tools/wishlist.js';
 import { registerCheckinTools } from './tools/checkin.js';
 import { registerUtilityTools } from './tools/utilities.js';
+import { registerCacheTools } from './tools/cache.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.
@@ -33,5 +34,9 @@ await runMcp({
         (s) => registerWishlistTools(s, client),
         (s) => registerCheckinTools(s, client),
         (s) => registerUtilityTools(s, client),
+        // Cache tools live only on the Node/stdio server: they need a local SQLite
+        // file, which the filesystem-less Cloudflare Worker (src/worker.ts) can't
+        // provide, so they are intentionally NOT registered there.
+        (s) => registerCacheTools(s, client),
     ],
 });