untappd-mcp 1.3.1 → 1.4.0

package/dist/cache/sync.js

@@ -1,5 +1,5 @@
 import { createHelpfulError, RateLimitError, messageOf } from '@chrischall/mcp-utils';
-import { mapCheckinRow } from './db.js';
+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) {
@@ -46,7 +46,7 @@ async function fetchTotalCheckins(client, encodedUser) {
  */
 export async function syncCheckins(client, cache, rawUsername, maxPages = 10) {
     const encodedUser = encodeURIComponent(rawUsername);
-    const prior = cache.getState(rawUsername);
+    const prior = await cache.getState(rawUsername);
     const priorNewest = prior?.newest_checkin_id ?? null;
     let pages = 0;
     let added = 0;
@@ -92,7 +92,7 @@ export async function syncCheckins(client, cache, rawUsername, maxPages = 10) {
                 break;
             }
             const rows = rowsOf(rawUsername, page.items);
-            added += cache.upsertCheckins(rawUsername, rows);
+            added += await cache.upsertCheckins(rawUsername, rows);
             const oldestOnPage = rows[rows.length - 1].checkin_id;
             if (oldestOnPage <= priorNewest) {
                 caughtUp = true; // reconnected to the cached block
@@ -108,16 +108,16 @@ export async function syncCheckins(client, cache, rawUsername, maxPages = 10) {
             }
             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() });
+            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 = cache.newestCachedId(rawUsername);
+            newest = await cache.newestCachedId(rawUsername);
             catchupMaxId = null;
             catchupInProgress = false;
-            cache.setState(rawUsername, {
+            await cache.setState(rawUsername, {
                 newest_checkin_id: newest,
                 catchup_max_id: null,
                 backfill_complete: backfillComplete,
@@ -144,14 +144,14 @@ export async function syncCheckins(client, cache, rawUsername, maxPages = 10) {
                 break;
             }
             const rows = rowsOf(rawUsername, page.items);
-            added += cache.upsertCheckins(rawUsername, rows);
+            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.
-            cache.setState(rawUsername, {
+            await cache.setState(rawUsername, {
                 newest_checkin_id: newest,
                 oldest_max_id: oldestMaxId,
                 backfill_complete: backfillComplete,
@@ -163,8 +163,8 @@ export async function syncCheckins(client, cache, rawUsername, maxPages = 10) {
         }
     }
     const total = await fetchTotalCheckins(client, encodedUser);
-    const cached = cache.cachedCount(rawUsername);
-    cache.setState(rawUsername, {
+    const cached = await cache.cachedCount(rawUsername);
+    await cache.setState(rawUsername, {
         newest_checkin_id: newest,
         oldest_max_id: oldestMaxId,
         catchup_max_id: catchupMaxId,
@@ -190,7 +190,7 @@ export async function syncCheckins(client, cache, rawUsername, maxPages = 10) {
         rows_added: added,
         pages_fetched: pages,
         cached_checkins: cached,
-        distinct_beers: cache.distinctBeerCount(rawUsername),
+        distinct_beers: await cache.distinctBeerCount(rawUsername),
         total_checkins: total,
         backfill_percent: backfillPercent,
         backfill_complete: backfillComplete,

package/dist/index.js

@@ -14,10 +14,16 @@ 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,
@@ -34,9 +40,11 @@ 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),
+        // 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'),
     ],
 });

package/dist/tools/cache.js

@@ -1,6 +1,5 @@
 import { z } from 'zod';
 import { textResult, toolAnnotations, createHelpfulError } from '@chrischall/mcp-utils';
-import { CheckinCache, defaultCachePath } from '../cache/db.js';
 import { syncCheckins } from '../cache/sync.js';
 const UsernameArg = z
     .string()
@@ -23,9 +22,9 @@ function resolveUser(username, loginName) {
  * is, and a plain-language warning when a "not had" answer might be a false
  * negative.
  */
-function freshness(cache, username) {
-    const state = cache.getState(username);
-    const cached = cache.cachedCount(username);
+async function freshness(cache, username) {
+    const state = await cache.getState(username);
+    const cached = await cache.cachedCount(username);
     const backfillComplete = state?.backfill_complete ?? false;
     const percent = state?.total_checkins && state.total_checkins > 0
         ? Math.min(100, Math.round((cached / state.total_checkins) * 100))
@@ -49,24 +48,24 @@ function freshness(cache, username) {
         catchup_in_progress: catchupInProgress,
         backfill_percent: percent,
         cached_checkins: cached,
-        distinct_beers: cache.distinctBeerCount(username),
+        distinct_beers: await cache.distinctBeerCount(username),
         ...(caveat ? { caveat } : {}),
     };
 }
 /**
- * Register the local check-in cache tools. `cacheProvider` is injectable for
- * tests; in production it lazily opens the env-configured on-disk SQLite file on
- * first use (so the server still boots when no cache path/credentials are set).
+ * Register the check-in cache tools. `cacheProvider` supplies the backing store
+ * (a `node:sqlite` file on the stdio server, a Durable Object on the remote
+ * connector) and is required so this module imports no platform-specific code.
  */
-export function registerCacheTools(server, client, cacheProvider = defaultCacheProvider()) {
+export function registerCacheTools(server, client, cacheProvider) {
     server.registerTool('untappd_sync_checkins', {
-        title: 'Sync Untappd check-ins into the local cache',
-        description: "Fetch a user's check-ins into a local SQLite cache so history can be queried without paging the API. " +
+        title: 'Sync Untappd check-ins into the cache',
+        description: "Fetch a user's check-ins into a persistent cache so history can be queried without paging the API. " +
             'Incremental (stops once it reaches already-cached check-ins) and resumable: if the backfill is not yet ' +
             'complete it pages backwards up to max_pages per call and persists progress after every page, so run it ' +
-            'repeatedly until backfill_complete is true. Syncing another user requires their account be public or a ' +
+            'repeatedly until another_run_needed is false. Syncing another user requires their account be public or a ' +
             'friend. Omit username for your own account.',
-        annotations: toolAnnotations({ title: 'Sync Untappd check-ins into the local cache', readOnly: false, idempotent: false, openWorld: true }),
+        annotations: toolAnnotations({ title: 'Sync Untappd check-ins into the cache', readOnly: false, idempotent: false, openWorld: true }),
         inputSchema: {
             username: UsernameArg,
             max_pages: z
@@ -83,12 +82,12 @@ export function registerCacheTools(server, client, cacheProvider = defaultCacheP
         return textResult(summary);
     });
     server.registerTool('untappd_cache_has_had', {
-        title: 'Check if a user has had a beer (from local cache)',
-        description: 'Answer "has this user ever checked in this beer?" from the LOCAL cache only — NO API call. Match by exact ' +
+        title: 'Check if a user has had a beer (from the cache)',
+        description: 'Answer "has this user ever checked in this beer?" from the cache only — NO API call. Match by exact ' +
             'bid, or by a case-insensitive substring of the beer name. Returns whether they had it, how many times, the ' +
             "best rating, the last date, and the matching check-ins. Always reports cache freshness so you can caveat " +
             'incomplete data. Requires bid or beer_name. Run untappd_sync_checkins first.',
-        annotations: toolAnnotations({ title: 'Check if a user has had a beer (from local cache)', readOnly: true, idempotent: true, openWorld: false }),
+        annotations: toolAnnotations({ title: 'Check if a user has had a beer (from the cache)', readOnly: true, idempotent: true, openWorld: false }),
         inputSchema: {
             username: UsernameArg,
             bid: z.number().int().positive().optional().describe('Exact Untappd beer id to look for'),
@@ -100,15 +99,15 @@ export function registerCacheTools(server, client, cacheProvider = defaultCacheP
         }
         const user = resolveUser(username, client.loginName);
         const cache = cacheProvider();
-        const result = cache.hasHad(user, { bid, beerName: beer_name });
-        return textResult({ username: user, query: { bid, beer_name }, ...result, freshness: freshness(cache, user) });
+        const result = await cache.hasHad(user, { bid, beerName: beer_name });
+        return textResult({ username: user, query: { bid, beer_name }, ...result, freshness: await freshness(cache, user) });
     });
     server.registerTool('untappd_cache_has_had_many', {
-        title: 'Batch-check many beers against the local cache',
+        title: 'Batch-check many beers against the cache',
         description: 'Cross-check a list of beer ids against a user\'s cached history in ONE call — NO API call. Returns had/not-had ' +
             'per bid (with count and last date when had). Ideal for checking a whole venue menu at once. Run ' +
             'untappd_sync_checkins first; the freshness block flags if the cache is incomplete.',
-        annotations: toolAnnotations({ title: 'Batch-check many beers against the local cache', readOnly: true, idempotent: true, openWorld: false }),
+        annotations: toolAnnotations({ title: 'Batch-check many beers against the cache', readOnly: true, idempotent: true, openWorld: false }),
         inputSchema: {
             username: UsernameArg,
             bids: z.array(z.number().int().positive()).min(1).max(500).describe('Beer ids to check (1–500)'),
@@ -124,7 +123,7 @@ export function registerCacheTools(server, client, cacheProvider = defaultCacheP
             if (seen.has(bid))
                 continue;
             seen.add(bid);
-            const r = cache.hasHad(user, { bid });
+            const r = await cache.hasHad(user, { bid });
             if (r.had)
                 hadCount++;
             results.push({ bid, had: r.had, count: r.count, last_date: r.last_date, best_rating: r.best_rating });
@@ -135,13 +134,13 @@ export function registerCacheTools(server, client, cacheProvider = defaultCacheP
             had: hadCount,
             not_had: seen.size - hadCount,
             results,
-            freshness: freshness(cache, user),
+            freshness: await freshness(cache, user),
         });
     });
     server.registerTool('untappd_cache_query', {
         title: 'Query cached check-ins with filters',
         description: "Query a user's cached check-ins by brewery, style, minimum rating, venue, and/or date range, with sorting " +
-            'and a limit — from the LOCAL cache only, NO API call. Returns the matching check-ins plus cache freshness. ' +
+            'and a limit — from the cache only, NO API call. Returns the matching check-ins plus cache freshness. ' +
             'Run untappd_sync_checkins first.',
         annotations: toolAnnotations({ title: 'Query cached check-ins with filters', readOnly: true, idempotent: true, openWorld: false }),
         inputSchema: {
@@ -163,12 +162,7 @@ export function registerCacheTools(server, client, cacheProvider = defaultCacheP
     }, async ({ username, ...filters }) => {
         const user = resolveUser(username, client.loginName);
         const cache = cacheProvider();
-        const rows = cache.query(user, filters);
-        return textResult({ username: user, count: rows.length, filters, results: rows, freshness: freshness(cache, user) });
+        const rows = await cache.query(user, filters);
+        return textResult({ username: user, count: rows.length, filters, results: rows, freshness: await freshness(cache, user) });
     });
 }
-/** Lazily open (once) the env-configured on-disk cache. */
-function defaultCacheProvider() {
-    let cache;
-    return () => (cache ??= CheckinCache.open(defaultCachePath()));
-}

package/dist/tools/diagnostics.js

@@ -0,0 +1,33 @@
+// Small helpers so the live build's exact toolset is visible from the client
+// (via untappd_healthcheck) and from server logs (a startup line). This is how
+// you confirm a deploy actually shipped the tools you expect — e.g. that the
+// remote connector is exposing the cache tools, not a stale 37-tool build.
+/** The names of every tool registered on `server`, sorted. Defensive if the SDK internal shape drifts. */
+export function registeredToolNames(server) {
+    const reg = server._registeredTools;
+    return reg ? Object.keys(reg).sort() : [];
+}
+/**
+ * FNV-1a 32-bit hash of the sorted tool-name list — a stable, dependency-free
+ * fingerprint of the exposed toolset (works in both Node and Workers), so two
+ * builds can be compared at a glance without diffing the full list.
+ */
+export function toolsHash(names) {
+    let h = 0x811c9dc5;
+    const s = names.join(',');
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return (h >>> 0).toString(16).padStart(8, '0');
+}
+/** Version + tool count + tool-name-hash + names, for the healthcheck payload. */
+export function toolInventory(server) {
+    const names = registeredToolNames(server);
+    return { tool_count: names.length, tools_hash: toolsHash(names), tools: names };
+}
+/** Emit a one-line startup log of the registered tools (stderr on Node, logs on Workers). */
+export function logRegisteredTools(server, context) {
+    const names = registeredToolNames(server);
+    console.error(`[untappd-mcp] ${context}: ${names.length} tools registered [${toolsHash(names)}]: ${names.join(', ')}`);
+}

package/dist/tools/utilities.js

@@ -1,16 +1,24 @@
 import { textResult, toolAnnotations } from '@chrischall/mcp-utils';
+import { VERSION } from '../version.js';
+import { toolInventory } from './diagnostics.js';
 export function registerUtilityTools(server, client) {
     server.registerTool('untappd_healthcheck', {
         title: 'Untappd healthcheck',
         description: 'Verify Untappd connectivity and that credentials are configured and can log in. Performs a lightweight ' +
-            'authenticated request (your recent feed) and reports whether it succeeded. Read-only.',
+            'authenticated request (your recent feed) and reports whether it succeeded, plus the running server version ' +
+            'and the exact set of tools this build exposes (count, a stable hash, and their names) so you can confirm ' +
+            'which build is live. Read-only.',
         annotations: toolAnnotations({ title: 'Untappd healthcheck', readOnly: true, idempotent: true, openWorld: true }),
         inputSchema: {},
     }, async () => {
+        // Always report build/tool diagnostics, even when credentials are absent,
+        // so the live build and its toolset can be confirmed from the client.
+        const build = { server_version: VERSION, ...toolInventory(server) };
         if (!client.configured) {
             return textResult({
                 ok: false,
                 configured: false,
+                ...build,
                 note: 'Untappd credentials are not set. Configure UNTAPPD_USERNAME, UNTAPPD_PASSWORD, UNTAPPD_CLIENT_ID, and UNTAPPD_CLIENT_SECRET.',
             });
         }
@@ -20,6 +28,7 @@ export function registerUtilityTools(server, client) {
             configured: true,
             account: client.loginName,
             feed_reachable: feed?.checkins !== undefined,
+            ...build,
             note: 'Logged in to Untappd and fetched the friend feed successfully.',
         });
     });

package/dist/version.js

@@ -3,4 +3,4 @@
 // json's `extra-files`), and `versionSyncTest` guards that it stays equal to
 // package.json. Import VERSION wherever the version is needed rather than
 // re-declaring it.
-export const VERSION = '1.3.1'; // x-release-please-version
+export const VERSION = '1.4.0'; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "untappd-mcp",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "mcpName": "io.github.chrischall/untappd-mcp",
   "description": "Untappd MCP server for Claude — developed and maintained by AI (Claude Code)",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/untappd-mcp",
     "source": "github"
   },
-  "version": "1.3.1",
+  "version": "1.4.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "untappd-mcp",
-      "version": "1.3.1",
+      "version": "1.4.0",
       "transport": {
         "type": "stdio"
       },