untappd-mcp 2.5.1 → 2.6.0

package/dist/cache/db.js

@@ -47,7 +47,9 @@ class NodeSqlDriver {
         // 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');
+        // BEGIN itself can still get a handler-less SQLITE_BUSY (e.g. while another
+        // process recovers the WAL), so it is retried too.
+        retryBusy(() => this.db.exec('BEGIN IMMEDIATE'));
         try {
             fn();
             this.db.exec('COMMIT');
@@ -78,23 +80,36 @@ export class CheckinCache extends LocalCacheStore {
         if (path !== ':memory:')
             preparePrivateFile(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');
+        try {
+            // 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:') {
+                // Switching a fresh file to WAL needs an exclusive lock, and when another
+                // process is opening it too SQLite answers SQLITE_BUSY WITHOUT calling
+                // the busy handler (#256) — so busy_timeout never applies and this has
+                // to retry itself. Once the file is WAL (the switch is persistent) a
+                // later open skips the switch entirely.
+                retryBusy(() => {
+                    if (journalModeOf(db) !== 'wal')
+                        db.exec('PRAGMA journal_mode = WAL');
+                });
+                db.exec('PRAGMA synchronous = NORMAL');
+            }
+            const cache = new CheckinCache(db, path);
+            if (path !== ':memory:')
+                tightenSidecars(path);
+            return cache;
+        }
+        catch (e) {
+            db.close();
+            throw e;
         }
-        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');
+        return journalModeOf(this.db);
     }
     /** On-disk footprint: the db file plus its -wal/-shm side files. */
     fileInfo() {
@@ -152,6 +167,39 @@ function bestEffortChmod(path, mode) {
 }
 // How long a write waits for another process's lock before failing.
 const BUSY_TIMEOUT_MS = 5000;
+function journalModeOf(db) {
+    const row = db.prepare('PRAGMA journal_mode').get();
+    return String(row?.journal_mode ?? 'unknown');
+}
+/** SQLITE_BUSY / SQLITE_LOCKED, including their extended codes (e.g. BUSY_RECOVERY). */
+function isBusy(e) {
+    const code = e?.errcode;
+    return typeof code === 'number' && ((code & 0xff) === 5 || (code & 0xff) === 6);
+}
+const sleepCell = new Int32Array(new SharedArrayBuffer(4));
+/**
+ * Run `fn`, retrying a SQLITE_BUSY that SQLite raised without consulting the
+ * busy handler, until {@link BUSY_TIMEOUT_MS} after the FIRST attempt. A BUSY
+ * that already waited out busy_timeout lands past that deadline and is thrown
+ * as-is, so the total wait never exceeds busy_timeout's. The driver is
+ * synchronous, so the backoff blocks (Atomics.wait) like busy_timeout does.
+ */
+export function retryBusy(fn, timeoutMs = BUSY_TIMEOUT_MS) {
+    const deadline = Date.now() + timeoutMs;
+    for (let attempt = 0;; attempt++) {
+        try {
+            return fn();
+        }
+        catch (e) {
+            const left = deadline - Date.now();
+            if (!isBusy(e) || left <= 0)
+                throw e;
+            // 5, 10, 20 … ms, capped at 100, plus jitter so colliding opens spread out.
+            const wait = Math.min(100, 5 * 2 ** Math.min(attempt, 5)) + Math.random() * 5;
+            Atomics.wait(sleepCell, 0, 0, Math.min(wait, left));
+        }
+    }
+}
 /**
  * The on-disk cache path, always ABSOLUTE: `$UNTAPPD_CACHE_DB` (a file), else
  * `$UNTAPPD_CACHE_DIR/checkins.db`, else `~/.untappd-mcp/checkins.db`.

package/dist/tools/beer.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { foodMeta } from './hints.js';
 import { resolveView, toolAnnotations, viewParam, viewResult } from '@chrischall/mcp-utils';
 import { compactBeerSearch, compactCheckins, UNTAPPD_VIEWS, upstreamCompact } from '../compact.js';
 import { beerMetaFrom } from '../cache/store.js';
@@ -33,6 +34,7 @@ export function registerBeerTools(server, client, cache) {
             'beer id (bid), brewery, style, ABV, IBU, and global rating. Feed a bid into untappd_beer_info for full ' +
             'detail. Read-only.',
         annotations: toolAnnotations({ title: 'Search Untappd beers', readOnly: true, idempotent: true, openWorld: true }),
+        _meta: foodMeta('lookup', { aliases: ['beer', 'ipa', 'stout', 'brew'] }),
         inputSchema: z.object({
             query: z.string().min(1).describe('Beer name to search for'),
             limit: z.number().int().min(1).max(50).optional().describe('Max results (1–50, default 25)'),
@@ -57,6 +59,7 @@ export function registerBeerTools(server, client, cache) {
         description: 'Get full detail for a beer by its Untappd beer id (bid): description, style, ABV, IBU, brewery, rating, ' +
             'total check-in count, and — on view:"full" — recent activity. Get a bid from untappd_search_beer. Read-only.',
         annotations: toolAnnotations({ title: 'Get Untappd beer detail', readOnly: true, idempotent: true, openWorld: true }),
+        _meta: foodMeta('lookup'),
         inputSchema: z.object({
             bid: BidSchema,
             // No local projection here: compact is forwarded to Untappd as its OWN
@@ -75,6 +78,7 @@ export function registerBeerTools(server, client, cache) {
         description: 'Get the recent public check-ins for a beer by its bid — who drank it, their rating, comment, and venue. ' +
             'Page backwards with max_id (the pagination.max_id from a prior call). Read-only.',
         annotations: toolAnnotations({ title: 'Get recent check-ins for a beer', readOnly: true, idempotent: false, openWorld: true }),
+        _meta: foodMeta('lookup'),
         inputSchema: z.object({
             bid: BidSchema,
             limit: z.number().int().min(1).max(50).optional().describe('Max check-ins (1–50, default 25)'),

package/dist/tools/brewery.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { foodMeta } from './hints.js';
 import { minifiedResult, resolveView, toolAnnotations, viewParam, viewResult } from '@chrischall/mcp-utils';
 import { UNTAPPD_VIEWS, compactBreweryBeerList, upstreamCompact } from '../compact.js';
 import { BREWERY_BEERS_DEFAULT_LIMIT, BREWERY_BEERS_TTL_MS, getBreweryBeers } from '../cache/brewery-beers.js';
@@ -11,6 +12,7 @@ export function registerBreweryTools(server, client, cacheProvider) {
         description: 'Search Untappd for breweries by name. Returns matches with their brewery id, location, type, and beer ' +
             'count. Feed a brewery id into untappd_brewery_info for full detail. Read-only.',
         annotations: toolAnnotations({ title: 'Search Untappd breweries', readOnly: true, idempotent: true, openWorld: true }),
+        _meta: foodMeta('lookup', { aliases: ['brewery', 'brewer'] }),
         inputSchema: z.object({
             query: z.string().min(1).describe('Brewery name to search for'),
             limit: z.number().int().min(1).max(50).optional().describe('Max results (1–50, default 25)'),
@@ -27,6 +29,7 @@ export function registerBreweryTools(server, client, cacheProvider) {
             'claimed_status.follow_status is whether the SIGNED-IN account follows/likes the brewery — never another ' +
             "user's; for theirs, run untappd_sync_brewery_likes and read untappd_favorites_list (source \"untappd\").",
         annotations: toolAnnotations({ title: 'Get Untappd brewery detail', readOnly: true, idempotent: true, openWorld: true }),
+        _meta: foodMeta('lookup'),
         inputSchema: z.object({
             brewery_id: z.number().int().positive().describe('Untappd brewery id'),
             view: viewParam(UNTAPPD_VIEWS, { note: 'compact also asks Untappd for its own slim record, dropping the embedded activity/list blocks; "full" returns everything.' }),
@@ -50,6 +53,7 @@ export function registerBreweryTools(server, client, cacheProvider) {
             'reason} for the brewery and on each favorite beer (derived from username\'s history or added with ' +
             'untappd_favorite_add; default your account). view:"full" always calls Untappd and returns its raw page. Read-only.',
         annotations: toolAnnotations({ title: "Get a brewery's beer list", readOnly: true, idempotent: true, openWorld: true }),
+        _meta: foodMeta('lookup'),
         inputSchema: z.object({
             brewery_id: z.number().int().positive().describe('Untappd brewery id'),
             limit: z.number().int().min(1).max(50).optional().describe('Max beers (1–50, default 25)'),

package/dist/tools/cache.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { foodMeta } from './hints.js';
 import { RateLimitError, confirmTokenParam, createHelpfulError, minifiedResult, toolAnnotations } from '@chrischall/mcp-utils';
 import { beerMetaFrom, DEFAULT_VISIT_RADIUS_M } from '../cache/store.js';
 import { syncCheckins } from '../cache/sync.js';
@@ -190,6 +191,7 @@ export function registerCacheTools(server, client, cacheProvider) {
             'is ignored until it reports a live value) and any 429 wait. Use it to confirm the cache persisted across ' +
             'restarts, to see how far a backfill has got, or to check whether a sync can run now.',
         annotations: toolAnnotations({ title: 'Show the local cache location, schema and per-user coverage', readOnly: true, idempotent: true, openWorld: false }),
+        _meta: foodMeta('lookup'),
         inputSchema: z.object({}),
     }, async () => {
         const cache = cacheProvider();
@@ -219,6 +221,7 @@ export function registerCacheTools(server, client, cacheProvider) {
             'with stopped_for_rate_limit and rate_limit.resume_at — progress is saved; re-run after that time. Omit ' +
             'username for your own account.',
         annotations: toolAnnotations({ title: "Sync a user's check-ins into the cache", readOnly: false, idempotent: false, openWorld: true, destructive: false }),
+        _meta: foodMeta('other'),
         inputSchema: z.object({
             username: UsernameArg,
             max_pages: z
@@ -255,6 +258,7 @@ export function registerCacheTools(server, client, cacheProvider) {
             'cleanly on a 429) with stopped_for_rate_limit and rate_limit.resume_at — progress is saved; re-run after ' +
             'that time. Omit username for your own account.',
         annotations: toolAnnotations({ title: "Sync a user's complete distinct-beers list into the cache", readOnly: false, idempotent: false, openWorld: true, destructive: false }),
+        _meta: foodMeta('other'),
         inputSchema: z.object({
             username: UsernameArg,
             max_pages: z
@@ -283,6 +287,7 @@ export function registerCacheTools(server, client, cacheProvider) {
             'stopped; another_run_needed stays true until it finishes). Stops BEFORE the ~100 calls/hour rate ' +
             'limit (or cleanly on a 429) with stopped_for_rate_limit and rate_limit.resume_at. Omit username for your own account.',
         annotations: toolAnnotations({ title: "Sync a user's complete venue history into the cache", readOnly: false, idempotent: false, openWorld: true, destructive: false }),
+        _meta: foodMeta('other'),
         inputSchema: z.object({
             username: UsernameArg,
             max_pages: z
@@ -309,6 +314,7 @@ export function registerCacheTools(server, client, cacheProvider) {
             'Only reads Untappd — never changes the wishlist (that is untappd_wishlist_add / _remove). Omit username for ' +
             'your own account; another user\'s wishlist needs a public account or friendship.',
         annotations: toolAnnotations({ title: "Sync a user's wishlist into the cache", readOnly: false, idempotent: false, openWorld: true, destructive: false }),
+        _meta: foodMeta('other'),
         inputSchema: z.object({
             username: UsernameArg,
             max_pages: z
@@ -344,6 +350,7 @@ export function registerCacheTools(server, client, cacheProvider) {
             openWorld: true,
             destructive: false,
         }),
+        _meta: foodMeta('other'),
         inputSchema: z.object({
             username: UsernameArg,
             max_pages: z
@@ -378,6 +385,7 @@ export function registerCacheTools(server, client, cacheProvider) {
             openWorld: true,
             destructive: false,
         }),
+        _meta: foodMeta('other'),
         inputSchema: z.object({
             username: UsernameArg,
             max_calls: z
@@ -438,6 +446,7 @@ export function registerCacheTools(server, client, cacheProvider) {
             'reason}: derived from the visit history or added with untappd_favorite_add), and total_visits; plus a freshness ' +
             'block (last_synced_at, coverage_complete, caveat). Run untappd_sync_user_venues first.',
         annotations: toolAnnotations({ title: 'Check if a user has been to a venue (from the cache)', readOnly: true, idempotent: true, openWorld: false }),
+        _meta: foodMeta('lookup'),
         inputSchema: z.object({
             username: UsernameArg,
             queries: z.array(VenueQueryArg).min(1).max(50).describe('Places to check (1–50); each needs venue_ids, name, or lat+lng'),
@@ -516,6 +525,7 @@ export function registerCacheTools(server, client, cacheProvider) {
             '≥4.25 / had ≥3 times, or added with untappd_favorite_add). Reports per-source freshness so you can ' +
             'caveat incomplete data. Requires bid or beer_name. Run untappd_sync_user_beers first for full coverage.',
         annotations: toolAnnotations({ title: 'Check if a user has had a beer (from the cache)', readOnly: true, idempotent: true, openWorld: false }),
+        _meta: foodMeta('lookup', { aliases: ['have i had', 'tried before'] }),
         inputSchema: z.object({
             username: UsernameArg,
             bid: z.number().int().positive().optional().describe('Exact Untappd beer id to look for'),
@@ -545,6 +555,7 @@ export function registerCacheTools(server, client, cacheProvider) {
             '"any_not_had" (at least one of them still needs it) — with qualifying_bids and a per-user freshness block. ' +
             'Run untappd_sync_user_beers first (for every user); the freshness block flags if coverage is incomplete.',
         annotations: toolAnnotations({ title: 'Batch-check many beers against the cache', readOnly: true, idempotent: true, openWorld: false }),
+        _meta: foodMeta('lookup'),
         inputSchema: z.object({
             username: UsernameArg,
             usernames: UsernamesArg,
@@ -606,6 +617,7 @@ export function registerCacheTools(server, client, cacheProvider) {
             'untappd_sync_user_beers first; if coverage is incomplete the freshness caveat flags that a "not had" may be ' +
             'a false negative.',
         annotations: toolAnnotations({ title: 'From a list of beers, return the ones a user has NOT had', readOnly: true, idempotent: true, openWorld: false }),
+        _meta: foodMeta('lookup'),
         inputSchema: z.object({
             username: UsernameArg,
             bids: z.array(z.number().int().positive()).min(1).max(500).describe('Candidate beer ids to filter (1–500)'),
@@ -635,6 +647,7 @@ export function registerCacheTools(server, client, cacheProvider) {
             'for non-self accounts is only the recent window; for full coverage of which beers a user has had, use ' +
             'untappd_cache_has_had / not_had instead. Run untappd_sync_checkins first.',
         annotations: toolAnnotations({ title: 'Query cached check-ins with filters', readOnly: true, idempotent: true, openWorld: false }),
+        _meta: foodMeta('lookup'),
         inputSchema: z.object({
             username: UsernameArg,
             brewery_id: z.number().int().positive().optional().describe('Exact brewery id'),
@@ -673,6 +686,7 @@ export function registerCacheTools(server, client, cacheProvider) {
             'untappd_sync_wishlist and Untappd likes untappd_sync_brewery_likes — ' +
             'and says so per beer (score, boosted_by, wishlisted, brewery_favorite/favorite).',
         annotations: toolAnnotations({ title: 'Top-rated beers a user has NOT had, from a candidate list', readOnly: false, idempotent: false, openWorld: true, destructive: false }),
+        _meta: foodMeta('other', { aliases: ['what should i order', 'beers i have not had'] }),
         inputSchema: z.object({
             username: UsernameArg,
             usernames: UsernamesArg,
@@ -855,6 +869,7 @@ export function registerCacheTools(server, client, cacheProvider) {
             'cannot be re-fetched). Shared beer, venue and brewery facts are kept. The preview shows the username and exactly how many rows will be removed. Omit username ' +
             `for your own account. ${CONFIRM_FLOW}`,
         annotations: toolAnnotations({ title: "Forget a user's cached check-ins", readOnly: false, idempotent: true, openWorld: false, destructive: true }),
+        _meta: foodMeta('change'),
         inputSchema: z.object({
             username: UsernameArg,
             confirmToken: confirmTokenParam,

package/dist/tools/checkin.js

@@ -4,6 +4,7 @@ import { pipeline } from 'node:stream/promises';
 import { homedir } from 'node:os';
 import { delimiter, extname, join } from 'node:path';
 import { z } from 'zod';
+import { foodMeta } from './hints.js';
 import { confirmTokenParam, McpToolError, assertPathWithinRoots, createHelpfulError, fileBlob, messageOf, minifiedResult, readEnvVar, readFileHead, sniffMimeBytes, toolAnnotations, UnreachableError, } from '@chrischall/mcp-utils';
 import { CONFIRM_FLOW, confirmWrite } from './confirm.js';
 const CheckinIdSchema = z.number().int().positive().describe('Untappd check-in id');
@@ -192,6 +193,7 @@ export function registerCheckinTools(server, client) {
             `already toasted removes the toast. Writes to your Untappd account and is visible to others. ${CONFIRM_FLOW}`,
         // Destructive: a toast lands in the check-in owner's notifications, and toggling it back off cannot un-notify them.
         annotations: toolAnnotations({ title: 'Toast an Untappd check-in', readOnly: false, idempotent: false, openWorld: true, destructive: true }),
+        _meta: foodMeta('send', { aliases: ['toast', 'cheers'] }),
         inputSchema: z.object({
             checkin_id: CheckinIdSchema,
             confirmToken: confirmTokenParam,
@@ -227,6 +229,7 @@ export function registerCheckinTools(server, client) {
             CONFIRM_FLOW,
         // Destructive: the comment reaches the check-in owner (and other readers); untappd_delete_comment removes it but cannot un-notify anyone.
         annotations: toolAnnotations({ title: 'Comment on an Untappd check-in', readOnly: false, idempotent: false, openWorld: true, destructive: true }),
+        _meta: foodMeta('send', { aliases: ['comment'] }),
         inputSchema: z.object({
             checkin_id: CheckinIdSchema,
             comment: z.string().min(1).max(2000).describe('Comment text to post'),
@@ -261,6 +264,7 @@ export function registerCheckinTools(server, client) {
         title: 'Delete a comment from an Untappd check-in',
         description: `Delete one of YOUR comments by its comment id (the id from a check-in's comments list). ${CONFIRM_FLOW}`,
         annotations: toolAnnotations({ title: 'Delete a comment from an Untappd check-in', readOnly: false, idempotent: true, openWorld: true, destructive: true }),
+        _meta: foodMeta('change'),
         inputSchema: z.object({
             comment_id: z.number().int().positive().describe('Untappd comment id (from a check-in\'s comments.items)'),
             confirmToken: confirmTokenParam,
@@ -287,6 +291,7 @@ export function registerCheckinTools(server, client) {
         title: 'Delete an Untappd check-in',
         description: `Permanently delete one of YOUR check-ins by its id. This is destructive and cannot be undone. ${CONFIRM_FLOW}`,
         annotations: toolAnnotations({ title: 'Delete an Untappd check-in', readOnly: false, idempotent: true, openWorld: true, destructive: true }),
+        _meta: foodMeta('change'),
         inputSchema: z.object({
             checkin_id: CheckinIdSchema,
             confirmToken: confirmTokenParam,
@@ -322,6 +327,7 @@ export function registerCheckinTools(server, client) {
             `that will be posted. ${CONFIRM_FLOW}`,
         // Destructive: it publishes to your public feed, where friends see it; untappd_delete_checkin cannot unpublish what they saw.
         annotations: toolAnnotations({ title: 'Check in a beer on Untappd', readOnly: false, idempotent: false, openWorld: true, destructive: true }),
+        _meta: foodMeta('change', { aliases: ['check in', 'log a beer', 'rate a beer', 'drinking'] }),
         inputSchema: z.object({
             bid: z.number().int().positive().describe('Untappd beer id to check in (from untappd_search_beer)'),
             rating: RatingSchema.optional().describe('Rating 0–5 in 0.25 increments (omit for no rating)'),

package/dist/tools/discover.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { foodMeta } from './hints.js';
 import { minifiedResult, resolveView, toolAnnotations, viewParam, viewResult } from '@chrischall/mcp-utils';
 import { compactCheckins, UNTAPPD_VIEWS } from '../compact.js';
 export function registerDiscoverTools(server, client) {
@@ -7,6 +8,7 @@ export function registerDiscoverTools(server, client) {
         description: 'Get the beers trending on Untappd right now, split into macro (big/widely-available) and micro ' +
             '(craft/independent) lists. Read-only.',
         annotations: toolAnnotations({ title: 'Get trending beers', readOnly: true, idempotent: false, openWorld: true }),
+        _meta: foodMeta('lookup', { aliases: ['popular beers', 'trending beers'] }),
         inputSchema: z.object({}),
     }, async () => {
         const data = await client.get('/beer/trending');
@@ -17,6 +19,7 @@ export function registerDiscoverTools(server, client) {
         description: 'Get your Untappd notifications — toasts, comments, friend requests, and badges earned on YOUR account, ' +
             'plus news items. Read-only.',
         annotations: toolAnnotations({ title: 'Get your Untappd notifications', readOnly: true, idempotent: false, openWorld: true }),
+        _meta: foodMeta('whats-new', { aliases: ['toasts', 'badges', 'friend requests', 'beer notifications'] }),
         inputSchema: z.object({
             limit: z.number().int().min(1).max(50).optional().describe('Max notifications (1–50, default 25)'),
             offset: z.number().int().min(0).optional().describe('Result offset for paging (default 0)'),
@@ -30,6 +33,7 @@ export function registerDiscoverTools(server, client) {
         description: 'Get recent check-ins near a location (lat/lng) — what people are drinking nearby right now. Optionally ' +
             'widen the search radius. Read-only.',
         annotations: toolAnnotations({ title: 'Get nearby Untappd check-ins', readOnly: true, idempotent: false, openWorld: true }),
+        _meta: foodMeta('lookup', { aliases: ['drinking nearby'] }),
         inputSchema: z.object({
             lat: z.number().min(-90).max(90).describe('Latitude of the location'),
             lng: z.number().min(-180).max(180).describe('Longitude of the location'),

package/dist/tools/favorites.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { foodMeta } from './hints.js';
 import { minifiedResult, toolAnnotations } from '@chrischall/mcp-utils';
 import { FAVORITE_KINDS } from '../cache/store.js';
 import { DEFAULT_FAVORITE_THRESHOLDS, FAVORITE_SOURCES, listFavorites } from '../cache/favorites.js';
@@ -30,6 +31,7 @@ export function registerFavoriteTools(server, client, cacheProvider) {
             'has_had, has_had_many, has_visited, brewery_beers, venue_menu, top_not_had and trip_check results; a favorite brewery also boosts its ' +
             'beers in untappd_top_not_had. Omit username for your own account.',
         annotations: toolAnnotations({ title: 'Mark a beer, brewery or venue as a favorite (local)', readOnly: false, idempotent: true, openWorld: false, destructive: false }),
+        _meta: foodMeta('change'),
         inputSchema: z.object({
             username: UsernameArg,
             kind: KindArg,
@@ -49,6 +51,7 @@ export function registerFavoriteTools(server, client, cacheProvider) {
             'when there was none. A DERIVED favorite (from the user\'s history) cannot be removed — it is computed from ' +
             'the thresholds; change them in untappd_favorites_list instead. Omit username for your own account.',
         annotations: toolAnnotations({ title: 'Remove a manual favorite (local)', readOnly: false, idempotent: true, openWorld: false, destructive: false }),
+        _meta: foodMeta('change'),
         inputSchema: z.object({ username: UsernameArg, kind: KindArg, id: IdArg }),
     }, async ({ username, kind, id }) => {
         const user = resolveUser(username, client.loginName);
@@ -70,6 +73,7 @@ export function registerFavoriteTools(server, client, cacheProvider) {
             '(untappd_sync_user_venues, untappd_sync_user_beers); "untappd" ones as the last untappd_sync_brewery_likes ' +
             '(freshness.brewery_likes). Filter by kind and source. Omit username for your own account.',
         annotations: toolAnnotations({ title: "List a user's favorite beers, breweries and venues", readOnly: true, idempotent: true, openWorld: false }),
+        _meta: foodMeta('lookup'),
         inputSchema: z.object({
             username: UsernameArg,
             kind: z.enum(FAVORITE_KINDS).optional().describe('Only this kind (default all three)'),

package/dist/tools/feed.js

@@ -1,19 +1,33 @@
 import { z } from 'zod';
-import { minifiedResult, resolveView, toolAnnotations, viewParam, viewResult } from '@chrischall/mcp-utils';
+import { minifiedResult, resolveView, toolAnnotations, viewResult } from '@chrischall/mcp-utils';
 import { compactCheckins, UNTAPPD_VIEWS } from '../compact.js';
+import { briefCheckins, foodMeta } from './hints.js';
+/**
+ * The feed's `view`: the fleet's compact/full rungs plus `brief`, the one-line-per-item
+ * answer a context-group host reads aloud (the feed is this server's canonical whats-new).
+ */
+const FEED_VIEW = z
+    .enum(['compact', 'full', 'brief'])
+    .optional()
+    .describe('Response shape: "compact" (default) projects each check-in to {id, user, beer, brewery, venue, rating, comment, ' +
+    'toast/comment counts}; "full" returns Untappd\'s whole ~5 KB record; "brief" returns one line per check-in: ' +
+    '<user>: <beer> (<brewery>) at <venue> — <ISO date or "no date"> — <rated N|not rated>.');
 export function registerFeedTools(server, client) {
     server.registerTool('untappd_activity_feed', {
         title: 'Get Untappd friend activity feed',
         description: 'Get your Untappd friend activity feed — the recent check-ins from people you follow, newest first. Page ' +
             'backwards with max_id (the pagination.max_id from a prior call). Read-only.',
         annotations: toolAnnotations({ title: 'Get Untappd friend activity feed', readOnly: true, idempotent: false, openWorld: true }),
+        _meta: foodMeta('whats-new', { canonical: true, aliases: ['beer', 'check-ins', 'friends drinking', 'what are my friends drinking', 'craft beer'] }),
         inputSchema: z.object({
             limit: z.number().int().min(1).max(50).optional().describe('Max check-ins (1–50, default 25)'),
             max_id: z.number().int().positive().optional().describe('Return check-ins older than this id (for paging)'),
-            view: viewParam(UNTAPPD_VIEWS, { note: 'compact projects each check-in to {id, user, beer, brewery, venue, rating, comment, toast/comment counts}; "full" returns Untappd\'s whole ~5 KB record.' }),
+            view: FEED_VIEW,
         }),
     }, async ({ limit, max_id, view }) => {
         const data = await client.get('/checkin/recent', { limit, max_id });
+        if (view === 'brief')
+            return { content: [{ type: 'text', text: briefCheckins(data) }] };
         const v = resolveView(view, UNTAPPD_VIEWS);
         return viewResult(v, v === 'compact' ? compactCheckins(data) : data);
     });
@@ -22,6 +36,7 @@ export function registerFeedTools(server, client) {
         description: 'Get full detail for a single check-in by its id: the beer, rating, comment, photos, venue, badges earned, ' +
             'toasts, and comments. Get a check-in id from a feed or user-checkins result. Read-only.',
         annotations: toolAnnotations({ title: 'Get Untappd check-in detail', readOnly: true, idempotent: true, openWorld: true }),
+        _meta: foodMeta('lookup'),
         inputSchema: z.object({
             checkin_id: z.number().int().positive().describe('Untappd check-in id'),
         }),

package/dist/tools/friends.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { confirmTokenParam, minifiedResult, toolAnnotations } from '@chrischall/mcp-utils';
 import { CONFIRM_FLOW, confirmWrite } from './confirm.js';
+import { foodMeta } from './hints.js';
 // The endpoint PATHS below are confirmed from the Untappd app's own JS bundle
 // (`friend/request`, `friend/accept`, `friend/reject`, `friend/remove`). The
 // HTTP method (POST) mirrors the other captured action-writes (toast/comment),
@@ -20,6 +21,7 @@ const ACTIONS = [
         title: 'Send an Untappd friend request',
         verb: 'send a friend request to',
         detail: 'Sends a friend request to another user, who will be notified.',
+        intent: 'send',
     },
     {
         tool: 'untappd_accept_friend',
@@ -27,6 +29,7 @@ const ACTIONS = [
         title: 'Accept an Untappd friend request',
         verb: 'accept the incoming friend request from',
         detail: 'Accepts an incoming friend request (see untappd_pending_friends for pending uids).',
+        intent: 'change',
     },
     {
         tool: 'untappd_reject_friend',
@@ -34,6 +37,7 @@ const ACTIONS = [
         title: 'Reject an Untappd friend request',
         verb: 'reject the incoming friend request from',
         detail: 'Rejects/ignores an incoming friend request (see untappd_pending_friends for pending uids).',
+        intent: 'change',
     },
     {
         tool: 'untappd_remove_friend',
@@ -41,6 +45,7 @@ const ACTIONS = [
         title: 'Remove an Untappd friend',
         verb: 'remove your friendship with',
         detail: 'Removes an existing friend, or cancels a friend request you sent.',
+        intent: 'change',
     },
 ];
 export function registerFriendActionTools(server, client) {
@@ -55,6 +60,7 @@ export function registerFriendActionTools(server, client) {
             // un-sent, and a rejection cannot be un-rejected, so none of them has an
             // inverse in this tool set.
             annotations: toolAnnotations({ title: action.title, readOnly: false, idempotent: true, openWorld: true, destructive: true }),
+            _meta: foodMeta(action.intent, action.intent === 'send' ? { aliases: ['friend request', 'add a friend'] } : {}),
             inputSchema: z.object({
                 target_uid: TargetUidSchema,
                 confirmToken: confirmTokenParam,

package/dist/tools/hints.js

@@ -0,0 +1,42 @@
+/** `_meta` for an Untappd tool: every tool here is in the `food` domain. */
+export function foodMeta(intent, extra = {}) {
+    return { mint: { domain: 'food', intent, ...extra } };
+}
+const BRIEF_MAX = 120;
+function str(v) {
+    return typeof v === 'string' && v.trim() !== '' ? v.trim() : undefined;
+}
+function dict(v) {
+    return v && typeof v === 'object' ? v : {};
+}
+/** Untappd's RFC 2822 `created_at` as an ISO instant (to the second), or undefined when unparseable. */
+function isoInstant(v) {
+    const s = str(v);
+    if (!s)
+        return undefined;
+    const t = Date.parse(s);
+    return Number.isNaN(t) ? undefined : new Date(t).toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+/**
+ * One check-in as one line, `<user>: <beer> (<brewery>) at <venue> — <ISO date | no date> — <rated N | not rated>`,
+ * at most 120 characters (the title is shortened). Read only from the fields a
+ * check-in record carries; a rating of 0 is Untappd's "no rating".
+ */
+export function briefCheckinLine(item) {
+    const c = dict(item);
+    const who = str(dict(c.user).user_name) ?? 'someone';
+    const beer = str(dict(c.beer).beer_name) ?? 'a beer';
+    const brewery = str(dict(c.brewery).brewery_name);
+    const venue = str(dict(c.venue).venue_name);
+    const title = `${who}: ${beer}${brewery ? ` (${brewery})` : ''}${venue ? ` at ${venue}` : ''}`;
+    const rating = typeof c.rating_score === 'number' && c.rating_score > 0 ? `rated ${c.rating_score}` : 'not rated';
+    const tail = ` — ${isoInstant(c.created_at) ?? 'no date'} — ${rating}`;
+    const room = BRIEF_MAX - tail.length;
+    const shown = title.length > room ? `${title.slice(0, Math.max(room - 1, 0))}…` : title;
+    return `${shown}${tail}`;
+}
+/** A `{ checkins: { items } }` response as brief lines, one per check-in (none for an empty or unexpected page). */
+export function briefCheckins(resp) {
+    const items = dict(dict(resp).checkins).items;
+    return Array.isArray(items) ? items.map(briefCheckinLine).join('\n') : '';
+}

package/dist/tools/menu.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { foodMeta } from './hints.js';
 import { createHelpfulError, minifiedResult, toolAnnotations } from '@chrischall/mcp-utils';
 import { menuPick, venuePick } from '../menu/pick.js';
 import { freshness, quotaFields, resolveUser, UsernameArg } from './cache.js';
@@ -47,6 +48,7 @@ export function registerMenuTools(server, client, cacheProvider, deps = {}) {
             'a false negative and another_run_needed is true. api_budget is also capped to the quota Untappd reports, ' +
             'when it reports one. Omit username for your own account.',
         annotations: toolAnnotations({ title: "Pick beers off a tap list that a user hasn't had", readOnly: false, idempotent: false, openWorld: true, destructive: false }),
+        _meta: foodMeta('other', { aliases: ['what should i order', 'tap list', 'beer menu'] }),
         inputSchema: z.object({
             username: UsernameArg,
             items: z
@@ -84,6 +86,7 @@ export function registerMenuTools(server, client, cacheProvider, deps = {}) {
             '(menu_complete is false only if the budget ran out mid-menu). A venue with no verified menu comes back ' +
             'unresolved — use untappd_menu_pick with the tap list instead. Omit username for your own account.',
         annotations: toolAnnotations({ title: "Pick beers off a venue's Untappd menu that a user hasn't had", readOnly: false, idempotent: false, openWorld: true, destructive: false }),
+        _meta: foodMeta('other', { aliases: ['what should i order', 'on tap'] }),
         inputSchema: z.object({
             venue: z
                 .union([z.string().min(1), z.number().int().positive()])

package/dist/tools/resolve.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { foodMeta } from './hints.js';
 import { createHelpfulError, minifiedResult, toolAnnotations } from '@chrischall/mcp-utils';
 /**
  * Parse an untappd.com URL into its entity type and id. Path shapes (confirmed
@@ -49,6 +50,7 @@ export function registerResolveTools(server, client) {
         description: 'Parse an untappd.com URL (a beer /b/, brewery /w/, venue /v/, user /user/, or check-in link) into its ' +
             'entity type and id, and name the tool to call next. Pure local parsing — no network. Read-only.',
         annotations: toolAnnotations({ title: 'Resolve an Untappd URL', readOnly: true, idempotent: true, openWorld: false }),
+        _meta: foodMeta('lookup'),
         inputSchema: z.object({
             url: z.string().min(1).describe('An untappd.com URL to resolve'),
         }),
@@ -66,6 +68,7 @@ export function registerResolveTools(server, client) {
         description: 'Resolve an untappd.com URL AND fetch the entity detail in one call — the convenience combination of ' +
             'untappd_resolve + the matching info tool. Returns { resolved, detail }. Read-only.',
         annotations: toolAnnotations({ title: 'Open an Untappd URL', readOnly: true, idempotent: true, openWorld: true }),
+        _meta: foodMeta('lookup'),
         inputSchema: z.object({
             url: z.string().min(1).describe('An untappd.com URL to resolve and fetch'),
         }),

package/dist/tools/trip.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { foodMeta } from './hints.js';
 import { RateLimitError, createHelpfulError, messageOf, minifiedResult, toolAnnotations } from '@chrischall/mcp-utils';
 import { DEFAULT_VISIT_RADIUS_M, haversineM } from '../cache/store.js';
 import { BREWERY_BEERS_TTL_MS, getBreweryBeers } from '../cache/brewery-beers.js';
@@ -64,6 +65,7 @@ export function registerTripTools(server, client, cacheProvider) {
             idempotent: true,
             openWorld: true,
         }),
+        _meta: foodMeta('lookup', { aliases: ['brewery crawl', 'bar crawl', 'beer trip'] }),
         inputSchema: z.object({
             username: UsernameArg,
             usernames: z