untappd-mcp 1.3.0 → 1.4.0

package/dist/cache/db.js

@@ -0,0 +1,65 @@
+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';
+import { CheckinStoreCore, LocalCacheStore } from './store.js';
+// The `node:sqlite` backend for the check-in cache — a local on-disk SQLite file
+// used by the stdio/desktop server. The query logic lives in CheckinStoreCore
+// (src/cache/store.ts); this file only adapts `node:sqlite` to the SqlDriver
+// surface and manages the file handle. (The remote Cloudflare connector uses a
+// Durable Object backend instead — see src/cache/durable.ts.)
+/** Adapts a `node:sqlite` DatabaseSync to the driver surface the core needs. */
+class NodeSqlDriver {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    execScript(sql) {
+        this.db.exec(sql);
+    }
+    run(sql, params) {
+        this.db.prepare(sql).run(...params);
+    }
+    get(sql, params) {
+        return this.db.prepare(sql).get(...params);
+    }
+    all(sql, params) {
+        return this.db.prepare(sql).all(...params);
+    }
+    transaction(fn) {
+        this.db.exec('BEGIN');
+        try {
+            fn();
+            this.db.exec('COMMIT');
+        }
+        catch (e) {
+            this.db.exec('ROLLBACK');
+            throw e;
+        }
+    }
+}
+/** A file-backed check-in cache. `open()` creates parent dirs and the schema. */
+export class CheckinCache extends LocalCacheStore {
+    db;
+    constructor(db) {
+        super(new CheckinStoreCore(new NodeSqlDriver(db)));
+        this.db = db;
+    }
+    /** 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();
+    }
+}
+/** 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');
+}
+// Re-export the shared types/helpers tests and tools import from here so their
+// existing import paths keep working.
+export { mapCheckinRow, } from './store.js';

package/dist/cache/store.js

@@ -0,0 +1,333 @@
+// Storage-agnostic core for the Untappd check-in cache.
+//
+// The cache exists because the Untappd API only exposes paged, most-recent-first
+// lists (50/page) and NO "has user X ever had beer Y" lookup — answering that
+// from the API means paging the entire history every time, against a
+// ~100-calls/hour rate limit. We sync once (incrementally + resumable backfill)
+// into this cache, then answer every "has had" / filter query locally with zero
+// API calls.
+//
+// The SQL logic lives here ONCE, parameterised over a tiny synchronous
+// {@link SqlDriver}, so the exact same schema and queries back both storage
+// engines: `node:sqlite` on the stdio server (src/cache/db.ts) and a Cloudflare
+// Durable Object's SQLite storage on the remote connector (src/cache/durable.ts).
+// This module imports nothing platform-specific so it is safe in both the Node
+// and Workers bundles.
+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();
+}
+/** Schema statements, split so a driver that only runs one statement per call works. */
+export const SCHEMA_STATEMENTS = [
+    `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
+   )`,
+];
+/** Columns added after the initial release, applied idempotently on open. */
+export const MIGRATIONS = ['ALTER TABLE sync_state ADD COLUMN catchup_max_id INTEGER'];
+/**
+ * The check-in cache logic over a synchronous {@link SqlDriver}. Usernames are
+ * keyed case-insensitively via a lowercased key so `Mer1331` and `mer1331` share
+ * one cache; stored rows keep whatever casing they arrived with in other fields.
+ */
+export class CheckinStoreCore {
+    db;
+    constructor(db) {
+        this.db = db;
+        for (const stmt of SCHEMA_STATEMENTS)
+            this.db.execScript(stmt);
+        // Forward-compat for a sync_state table created before a column existed; the
+        // ADD COLUMN throws harmlessly if the column is already present.
+        for (const mig of MIGRATIONS) {
+            try {
+                this.db.execScript(mig);
+            }
+            catch {
+                /* column already exists */
+            }
+        }
+    }
+    /**
+     * 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 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)
+      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.transaction(() => {
+            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,
+                    r.abv,
+                    r.rating,
+                    r.comment,
+                    r.venue_id,
+                    r.venue_name,
+                    r.created_at,
+                ]);
+            }
+        });
+        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.get('SELECT COUNT(*) AS n FROM checkins WHERE username = ?', [username.toLowerCase()]);
+        return Number(row?.n ?? 0);
+    }
+    /** Distinct beers (unique bids) cached for a user. */
+    distinctBeerCount(username) {
+        const row = this.db.get('SELECT COUNT(DISTINCT bid) AS n FROM checkins WHERE username = ? AND bid IS NOT NULL', [username.toLowerCase()]);
+        return Number(row?.n ?? 0);
+    }
+    /** Highest cached checkin_id for a user (the true newest once contiguous), or null. */
+    newestCachedId(username) {
+        const row = this.db.get('SELECT MAX(checkin_id) AS m FROM checkins WHERE username = ?', [username.toLowerCase()]);
+        return num(row?.m);
+    }
+    getState(username) {
+        const row = this.db.get('SELECT * FROM sync_state WHERE username = ?', [username.toLowerCase()]);
+        if (!row)
+            return undefined;
+        return {
+            username: String(row.username),
+            oldest_max_id: num(row.oldest_max_id),
+            newest_checkin_id: num(row.newest_checkin_id),
+            catchup_max_id: num(row.catchup_max_id),
+            last_synced_at: str(row.last_synced_at),
+            backfill_complete: Number(row.backfill_complete) === 1,
+            total_checkins: num(row.total_checkins),
+        };
+    }
+    /**
+     * 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.run(`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`, [
+            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.get(`SELECT COUNT(*) AS n, MAX(rating) AS best FROM checkins WHERE ${clause}`, 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.all(`SELECT checkin_id, bid, beer_name, rating, venue_name, created_at
+       FROM checkins WHERE ${clause} ORDER BY checkin_id DESC LIMIT 25`, params);
+        const count = Number(agg?.n ?? 0);
+        return {
+            had: count > 0,
+            count,
+            last_date: matches[0]?.created_at ?? null,
+            best_rating: num(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);
+        return this.db.all(`SELECT * FROM checkins WHERE ${where.join(' AND ')} ORDER BY ${order} LIMIT ?`, [...params, limit]);
+    }
+}
+/**
+ * Adapts a synchronous {@link CheckinStoreCore} to the async {@link CacheStore}
+ * interface. Used by the in-process node backend; the Durable Object backend
+ * implements CacheStore over a real RPC boundary instead.
+ */
+export class LocalCacheStore {
+    core;
+    constructor(core) {
+        this.core = core;
+    }
+    async upsertCheckins(username, rows) {
+        return this.core.upsertCheckins(username, rows);
+    }
+    async cachedCount(username) {
+        return this.core.cachedCount(username);
+    }
+    async distinctBeerCount(username) {
+        return this.core.distinctBeerCount(username);
+    }
+    async newestCachedId(username) {
+        return this.core.newestCachedId(username);
+    }
+    async getState(username) {
+        return this.core.getState(username);
+    }
+    async setState(username, patch) {
+        this.core.setState(username, patch);
+    }
+    async hasHad(username, opts) {
+        return this.core.hasHad(username, opts);
+    }
+    async query(username, filters) {
+        return this.core.query(username, filters);
+    }
+}
+// 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 simply strip the
+// specials rather than rely on a non-portable escape convention.
+function escapeLike(s) {
+    return s.replace(/[%_]/g, ' ');
+}

package/dist/cache/sync.js

@@ -0,0 +1,202 @@
+import { createHelpfulError, RateLimitError, messageOf } from '@chrischall/mcp-utils';
+import { mapCheckinRow } from './store.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 = await 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 += await 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.
+            await 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 = await cache.newestCachedId(rawUsername);
+            catchupMaxId = null;
+            catchupInProgress = false;
+            await 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 += await 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.
+            await 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 = await cache.cachedCount(rawUsername);
+    await 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: await 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,10 +13,17 @@ 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';
+import { logRegisteredTools } from './tools/diagnostics.js';
+import { CheckinCache, defaultCachePath } 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.
+let nodeCache;
+const nodeCacheProvider = () => (nodeCache ??= CheckinCache.open(defaultCachePath()));
 await runMcp({
     name: 'untappd-mcp',
     version: VERSION,
@@ -33,5 +40,11 @@ await runMcp({
         (s) => registerWishlistTools(s, client),
         (s) => registerCheckinTools(s, client),
         (s) => registerUtilityTools(s, client),
+        // The stdio server backs the cache with a local `node:sqlite` file; the
+        // remote Cloudflare connector (src/worker.ts) backs the same cache tools
+        // with a per-user Durable Object instead.
+        (s) => registerCacheTools(s, client, nodeCacheProvider),
+        // Keep last: logs the full registered toolset (count + names) at startup.
+        (s) => logRegisteredTools(s, 'stdio'),
     ],
 });