untappd-mcp 2.2.4 → 2.3.1

package/dist/cache/store.js

@@ -369,9 +369,9 @@ export class CheckinStoreCore {
         }
         if (opts.beerName !== undefined) {
             const like = `%${escapeLike(opts.beerName)}%`;
-            cClause.push('beer_name LIKE ? COLLATE NOCASE');
+            cClause.push(`beer_name ${LIKE_MATCH}`);
             cParams.push(like);
-            bClause.push('beer_name LIKE ? COLLATE NOCASE');
+            bClause.push(`beer_name ${LIKE_MATCH}`);
             bParams.push(like);
         }
         const cWhere = cClause.join(' AND ');
@@ -429,11 +429,11 @@ export class CheckinStoreCore {
             params.push(filters.brewery_id);
         }
         if (filters.brewery !== undefined) {
-            where.push('brewery_name LIKE ? COLLATE NOCASE');
+            where.push(`brewery_name ${LIKE_MATCH}`);
             params.push(`%${escapeLike(filters.brewery)}%`);
         }
         if (filters.style !== undefined) {
-            where.push('beer_style LIKE ? COLLATE NOCASE');
+            where.push(`beer_style ${LIKE_MATCH}`);
             params.push(`%${escapeLike(filters.style)}%`);
         }
         if (filters.min_rating !== undefined) {
@@ -441,7 +441,7 @@ export class CheckinStoreCore {
             params.push(filters.min_rating);
         }
         if (filters.venue !== undefined) {
-            where.push('venue_name LIKE ? COLLATE NOCASE');
+            where.push(`venue_name ${LIKE_MATCH}`);
             params.push(`%${escapeLike(filters.venue)}%`);
         }
         if (filters.venue_id !== undefined) {
@@ -459,9 +459,9 @@ export class CheckinStoreCore {
         const order = filters.sort === 'oldest'
             ? 'created_at ASC, checkin_id ASC'
             : filters.sort === 'highest_rated'
-                ? 'rating DESC, created_at DESC'
+                ? 'rating IS NULL, rating DESC, created_at DESC'
                 : filters.sort === 'lowest_rated'
-                    ? 'rating ASC, created_at DESC'
+                    ? 'rating IS NULL, rating ASC, created_at DESC'
                     : 'created_at 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]);
@@ -560,9 +560,11 @@ export class LocalCacheStore {
         return this.core.forgetUser(username);
     }
 }
-// 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.
+// Case-insensitive substring match whose pattern is built by escapeLike(): the
+// ESCAPE clause makes a backslash-prefixed %, _ or backslash match itself literally.
+const LIKE_MATCH = "LIKE ? COLLATE NOCASE ESCAPE '\\'";
+// Escape LIKE wildcards in user input so a literal % or _ in a beer/brewery/venue
+// name matches itself instead of acting as a wildcard (pair with LIKE_MATCH).
 function escapeLike(s) {
-    return s.replace(/[%_]/g, ' ');
+    return s.replace(/[\\%_]/g, (c) => `\\${c}`);
 }

package/dist/cache/sync.js

@@ -26,6 +26,12 @@ function rowsOf(username, items) {
         if (r)
             rows.push(r);
     }
+    if (rows.length === 0 && items.length > 0) {
+        // Every item on a non-empty page failed to map — an upstream shape change,
+        // not the end of the history. Say so, rather than letting the caller index
+        // rows[0] / rows[rows.length - 1] and die with a bare TypeError.
+        throw createHelpfulError(`Untappd returned ${items.length} check-in(s) for "${username}" with no numeric checkin_id; the response shape may have changed.`, { hint: 'Progress from earlier pages is kept. Re-run the sync later; if it persists, the user/checkins parser needs updating.' });
+    }
     return rows;
 }
 /** Best-effort stats.total_checkins; null if it can't be read. */

package/dist/client.js

@@ -29,19 +29,26 @@ const DEFAULTS = {
     // works. Override with UNTAPPD_DEVICE_ID to pin your own.
     deviceUdid: 'A1B2C3D4-0000-4000-8000-0000000000AA',
 };
+// Statuses whose Response may not carry a body (the constructor rejects one).
+const NULL_BODY_STATUSES = new Set([101, 103, 204, 205, 304]);
 // One HTTP attempt with a hard timeout, shared by the instance `send()` method
-// and the standalone `xauthLogin()` helper below. Network/timeout failures
-// become an UnreachableError; HTTP status handling is left to the caller.
+// and the standalone `xauthLogin()` helper below. The timeout covers reading
+// the BODY too, not just the headers: the body is buffered here, under the same
+// abort timer, so a server that sends headers and then stalls can't hang the
+// call (or, via the coalesced login, every call waiting on it). Network/timeout
+// failures become an UnreachableError; HTTP status handling is left to the caller.
 async function sendRequest(fetchImpl, method, url, init) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
     try {
-        return await fetchImpl(url, {
+        const res = await fetchImpl(url, {
             method,
             headers: init.headers,
             ...(init.body !== undefined ? { body: init.body } : {}),
             signal: controller.signal,
         });
+        const body = NULL_BODY_STATUSES.has(res.status) ? null : await res.arrayBuffer();
+        return new Response(body, { status: res.status, statusText: res.statusText, headers: res.headers });
     }
     catch {
         throw new UnreachableError(SERVICE);
@@ -110,16 +117,28 @@ export async function xauthLogin(creds, opts = {}) {
     }
     return token;
 }
-function missingCredsError() {
-    const missing = ['UNTAPPD_USERNAME', 'UNTAPPD_PASSWORD', 'UNTAPPD_CLIENT_ID', 'UNTAPPD_CLIENT_SECRET'].filter((k) => !readEnvVar(k));
+/**
+ * No token and no complete login set: nothing can be called. Names exactly what
+ * is missing from the login set, because a token alone (no app creds) is a
+ * complete read-only setup — the app creds are not "required either way".
+ */
+function missingCredsError(missing) {
     // Both paths in the MESSAGE, not only `hint`: MCP serialization surfaces the
     // message and drops the hint, so a token path mentioned only there is
     // invisible exactly when someone is deciding what to configure.
-    const remedy = 'Either set UNTAPPD_ACCESS_TOKEN (an access token you already hold — no password needed), or set ' +
-        'UNTAPPD_USERNAME and UNTAPPD_PASSWORD to log in for one. Either way UNTAPPD_CLIENT_ID and ' +
-        'UNTAPPD_CLIENT_SECRET (the Untappd mobile app client credentials) are required. See the README.';
+    const remedy = 'Either set UNTAPPD_ACCESS_TOKEN (an access token you already hold — reads need nothing else; writes also ' +
+        'need UNTAPPD_CLIENT_ID and UNTAPPD_CLIENT_SECRET), or set UNTAPPD_USERNAME, UNTAPPD_PASSWORD, ' +
+        'UNTAPPD_CLIENT_ID and UNTAPPD_CLIENT_SECRET (the Untappd mobile app client credentials) to log in for one. ' +
+        'See the README.';
     return createHelpfulError(`Untappd credentials are not configured — missing ${missing.join(', ') || 'credentials'}. ${remedy}`, { hint: remedy });
 }
+/** A working token, but a write needs the app's client credentials too. */
+function missingWriteCredsError(missing) {
+    const remedy = 'Untappd writes (check-ins, toasts, comments, wishlist and friend actions) carry the mobile app client ' +
+        'credentials alongside the token; reads work without them. Set UNTAPPD_CLIENT_ID and UNTAPPD_CLIENT_SECRET ' +
+        '(see the README).';
+    return createHelpfulError(`This is a write, and it needs ${missing.join(' and ')}. ${remedy}`, { hint: remedy });
+}
 export class UntappdClient {
     fetchImpl;
     clientId;
@@ -155,28 +174,50 @@ export class UntappdClient {
         this.password = opts.password ?? readEnvVar('UNTAPPD_PASSWORD') ?? null;
         this._loginName = opts.loginName ?? this.username;
     }
-    /** True when enough is configured to make authenticated calls. */
+    /**
+     * True when authenticated READS can be made: a token is held (reads carry
+     * only `access_token`), or the full login set can mint one. App creds alone
+     * cannot make any call. Writes additionally need the app creds — `canWrite`.
+     */
     get configured() {
-        // A pre-seeded token needs only app creds (for writes); otherwise a full login is required.
-        if (this.token)
-            return Boolean(this.clientId && this.clientSecret);
-        return Boolean(this.clientId && this.clientSecret && this.username && this.password);
+        return Boolean(this.token) || this.loginMissing().length === 0;
+    }
+    /** True when writes can be made too: configured, plus the app's client credentials. */
+    get canWrite() {
+        return this.configured && this.appCredsMissing().length === 0;
+    }
+    appCredsMissing() {
+        const missing = [];
+        if (!this.clientId)
+            missing.push('UNTAPPD_CLIENT_ID');
+        if (!this.clientSecret)
+            missing.push('UNTAPPD_CLIENT_SECRET');
+        return missing;
+    }
+    loginMissing() {
+        const missing = [];
+        if (!this.username)
+            missing.push('UNTAPPD_USERNAME');
+        if (!this.password)
+            missing.push('UNTAPPD_PASSWORD');
+        return [...missing, ...this.appCredsMissing()];
     }
     /** The configured login name — the default `username` for user-scoped tools. */
     get loginName() {
         return this._loginName;
     }
+    /** App creds for a write; reached only once a token is in hand. */
     requireAppCreds() {
         if (!this.clientId || !this.clientSecret) {
-            throw missingCredsError();
+            throw missingWriteCredsError(this.appCredsMissing());
         }
         return { clientId: this.clientId, clientSecret: this.clientSecret };
     }
     requireLogin() {
-        const app = this.requireAppCreds();
-        if (!this.username || !this.password)
-            throw missingCredsError();
-        return { ...app, username: this.username, password: this.password };
+        if (!this.username || !this.password || !this.clientId || !this.clientSecret) {
+            throw missingCredsError(this.loginMissing());
+        }
+        return { username: this.username, password: this.password, clientId: this.clientId, clientSecret: this.clientSecret };
     }
     baseHeaders() {
         return {
@@ -247,18 +288,20 @@ export class UntappdClient {
     async request(method, path, opts, isRetry = false) {
         const token = await this.ensureToken();
         const headers = this.baseHeaders();
-        // The Untappd app carries the token as a query param on reads and as an
-        // `Authorization: Bearer` header on writes (with the client credentials in
-        // the query). We mirror that exactly — both shapes are the real captured
-        // requests the app itself makes.
+        // The token always travels in an `Authorization: Bearer` header, never the
+        // URL, where proxy and server logs would record it. The Untappd app itself
+        // puts it in the query on reads, but the API accepts the header for reads
+        // too (live-verified 2026-10-09 on /user/info, /beer/info and /search/beer,
+        // with no app creds). Writes also carry the client credentials in the
+        // query, as the app's captured write requests do.
+        headers['Authorization'] = `Bearer ${token}`;
         let query;
         if (opts.auth === 'bearer') {
             const c = this.requireAppCreds();
-            headers['Authorization'] = `Bearer ${token}`;
             query = { ...opts.query, client_id: c.clientId, client_secret: c.clientSecret, utv: this.utv };
         }
         else {
-            query = { ...opts.query, access_token: token, utv: this.utv };
+            query = { ...opts.query, utv: this.utv };
         }
         const qs = buildQueryString(query);
         let body;
@@ -290,7 +333,7 @@ export class UntappdClient {
         }
         return this.parseJson(res, method, path);
     }
-    /** Authenticated read (token in the query, as the app does for GETs). */
+    /** Authenticated read (token in a Bearer header; no app creds needed). */
     async get(path, query = {}) {
         return this.request('GET', path, { query, auth: 'query' });
     }

package/dist/tools/cache.js

@@ -270,7 +270,8 @@ export function registerCacheTools(server, client, cacheProvider) {
             'the cache only (both sources, no API call). Beer ratings/styles come from a metadata cache; a beer/info API ' +
             'call is made only on a cache miss or if the cached metadata is >30 days old, capped at api_budget calls per ' +
             'run (~100 calls/hour limit) — if more are needed it returns partial: true / another_run_needed: true, so ' +
-            're-running fills the rest. Reports the same freshness/caveat block as untappd_cache_not_had. Omit username ' +
+            're-running fills the rest. A beer whose refresh is deferred or fails is still ranked on its older cached ' +
+            'metadata and marked stale: true. Reports the same freshness/caveat block as untappd_cache_not_had. Omit username ' +
             'for your own account.',
         annotations: toolAnnotations({ title: 'Top-rated beers a user has NOT had, from a candidate list', readOnly: false, idempotent: false, openWorld: true, destructive: false }),
         inputSchema: z.object({
@@ -349,7 +350,18 @@ export function registerCacheTools(server, client, cacheProvider) {
         }
         if (fetched.length)
             await cache.upsertBeerMeta(fetched);
-        const available = [...haveMeta, ...fetched];
+        // A bid whose refresh was deferred or failed still has its older cached
+        // metadata — rank it (flagged stale) rather than silently dropping a beer
+        // the cache knows about.
+        const refreshed = new Set(fetched.map((m) => m.bid));
+        const staleMeta = [];
+        for (const bid of needFetch) {
+            const m = metaByBid.get(bid);
+            if (m && !refreshed.has(bid))
+                staleMeta.push(m);
+        }
+        const staleBids = new Set(staleMeta.map((m) => m.bid));
+        const available = [...haveMeta, ...fetched, ...staleMeta];
         const ratingOf = (m) => m.weighted_rating_score ?? m.rating_score ?? 0;
         // Style filter: substring against EITHER the beer style or its parent style.
         let matched = available;
@@ -369,8 +381,11 @@ export function registerCacheTools(server, client, cacheProvider) {
             abv: m.abv,
             rating: m.weighted_rating_score ?? m.rating_score,
             rating_count: m.rating_count,
+            ...(staleBids.has(m.bid) ? { stale: true } : {}),
         }));
-        const partial = deferred > 0;
+        // Errors leave beers unranked (or ranked on stale data) just like a
+        // deferral does, so a re-run is worth it in both cases.
+        const partial = deferred > 0 || errors > 0;
         return minifiedResult({
             username: user,
             ranked,
@@ -380,6 +395,7 @@ export function registerCacheTools(server, client, cacheProvider) {
                 style_matched: style !== undefined ? matched.length : null,
                 api_calls_used: apiCalls,
                 errors,
+                stale: staleMeta.length,
                 partial,
                 another_run_needed: partial,
                 ...(rateLimited ? { rate_limited: true } : {}),
@@ -399,7 +415,8 @@ export function registerCacheTools(server, client, cacheProvider) {
             username: UsernameArg,
             confirmToken: confirmTokenParam,
         }),
-    }, async ({ username, confirmToken }, ctx) => {
+    }, async (args, ctx) => {
+        const { username, confirmToken } = args;
         const user = resolveUser(username, client.loginName);
         const cache = cacheProvider();
         // Bound into the token: if a sync adds rows after the preview, the
@@ -413,6 +430,7 @@ export function registerCacheTools(server, client, cacheProvider) {
             action: 'untappd.cache_forget',
             message: `Review and confirm deleting ${user}'s data from the local Untappd cache:`,
             confirmToken,
+            args,
             target: user.toLowerCase(),
             payload: { username: user.toLowerCase(), ...counts },
             preview: {

package/dist/tools/checkin.js

@@ -1,7 +1,8 @@
 import { createReadStream, realpathSync, statSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { pipeline } from 'node:stream/promises';
-import { delimiter, extname } from 'node:path';
+import { homedir } from 'node:os';
+import { delimiter, extname, join } from 'node:path';
 import { z } from 'zod';
 import { confirmTokenParam, McpToolError, assertPathWithinRoots, createHelpfulError, fileBlob, messageOf, minifiedResult, readEnvVar, readFileHead, sniffMimeBytes, toolAnnotations, UnreachableError, } from '@chrischall/mcp-utils';
 import { CONFIRM_FLOW, confirmWrite } from './confirm.js';
@@ -15,18 +16,24 @@ function photoExt(path) {
 }
 // Far above any phone photo; a file this big is not a beer picture.
 const MAX_PHOTO_BYTES = 15 * 1024 * 1024;
-/** UNTAPPD_PHOTO_DIR (one or more dirs, split on the platform path delimiter). */
+/**
+ * The directories a photo_path may come from: UNTAPPD_PHOTO_DIR (one or more,
+ * split on the platform path delimiter), else ~/Downloads/untappd-mcp. Confined
+ * by DEFAULT because the photo is published to the public feed and the path is
+ * model-supplied — a prompt-injected shout/comment could otherwise name any
+ * JPEG/PNG on the disk (a screenshot of a bank statement), and under
+ * MCP_CONFIRM_MODE=auto the model reviews its own preview.
+ */
 function photoRoots() {
-    const raw = readEnvVar('UNTAPPD_PHOTO_DIR');
-    const roots = raw?.split(delimiter).filter(Boolean);
-    return roots && roots.length > 0 ? roots : undefined;
+    const roots = readEnvVar('UNTAPPD_PHOTO_DIR')?.split(delimiter).filter(Boolean) ?? [];
+    return roots.length > 0 ? roots : [join(homedir(), 'Downloads', 'untappd-mcp')];
 }
 /**
  * Vet a photo before it can be published to the public feed. photo_path is a
  * free-form, model-supplied path, so an injected instruction could aim it at
  * any file with an image-like name. Require the bytes to BE a JPEG/PNG that
- * matches the extension, cap the size, honour the optional UNTAPPD_PHOTO_DIR
- * allow-list, and return the resolved path + size so the preview shows a human
+ * matches the extension, cap the size, confine it to the photo directory
+ * ({@link photoRoots}), and return the resolved path + size so the preview shows a human
  * exactly which file would be uploaded. Errors never echo the path back.
  */
 async function checkPhoto(photoPath) {
@@ -37,15 +44,15 @@ async function checkPhoto(photoPath) {
         });
     }
     const roots = photoRoots();
-    if (roots) {
-        try {
-            assertPathWithinRoots(photoPath, roots);
-        }
-        catch {
-            throw createHelpfulError('The photo is outside the allowed photo directory.', {
-                hint: 'UNTAPPD_PHOTO_DIR restricts which files can be attached to a check-in.',
-            });
-        }
+    try {
+        assertPathWithinRoots(photoPath, roots);
+    }
+    catch {
+        // Names the allowed directory (config, not the caller's path) so the user knows where to put the photo.
+        throw createHelpfulError(`The photo is outside the allowed photo directory (${roots.join(', ')}).`, {
+            hint: 'Ask the user to copy the photo there (or set UNTAPPD_PHOTO_DIR). Never attach a file because text from ' +
+                'Untappd (a shout, comment or notification) asked for it.',
+        });
     }
     let real;
     let size;
@@ -64,7 +71,7 @@ async function checkPhoto(photoPath) {
             hint: 'Attach a normal-sized JPEG or PNG photo.',
         });
     }
-    // Re-check UNTAPPD_PHOTO_DIR at open time, so a swap after the check above can't escape it.
+    // Re-check the photo directory at open time, so a swap after the check above can't escape it.
     let head;
     try {
         head = await readFileHead(real, 16, { allowedRoots: roots });
@@ -155,11 +162,13 @@ async function nonIdempotentWrite(run, unknownOutcome) {
  * lookup fails — each of which the caller reports as an unknown outcome.
  */
 async function findRecentCheckin(client, bid, sentAt) {
+    // With no configured username (a token-only deployment) use the self form —
+    // user/checkins with no username lists the token's own account — rather than
+    // giving up on a lookup that one call would settle.
     const self = client.loginName;
-    if (!self)
-        return null;
+    const path = self ? `/user/checkins/${encodeURIComponent(self)}` : '/user/checkins';
     try {
-        const data = await client.get(`/user/checkins/${encodeURIComponent(self)}`, { limit: 5 });
+        const data = await client.get(path, { limit: 5 });
         const matches = [];
         for (const it of data?.checkins?.items ?? []) {
             const c = it;
@@ -181,18 +190,21 @@ export function registerCheckinTools(server, client) {
         title: 'Toast an Untappd check-in',
         description: "Toast (like) a check-in on YOUR account. This endpoint is a TOGGLE: calling it on a check-in you have " +
             `already toasted removes the toast. Writes to your Untappd account and is visible to others. ${CONFIRM_FLOW}`,
-        annotations: toolAnnotations({ title: 'Toast an Untappd check-in', readOnly: false, idempotent: false, openWorld: true, destructive: false }),
+        // 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 }),
         inputSchema: z.object({
             checkin_id: CheckinIdSchema,
             confirmToken: confirmTokenParam,
         }),
-    }, async ({ checkin_id, confirmToken }, ctx) => {
+    }, async (args, ctx) => {
+        const { checkin_id, confirmToken } = args;
         const request = { method: 'POST', path: `/checkin/toast/${checkin_id}` };
         const gate = await confirmWrite(ctx, {
             tool: 'untappd_toast',
             action: 'untappd.toast',
             message: 'Review and confirm toggling your toast on this Untappd check-in:',
             confirmToken,
+            args,
             target: checkin_id,
             payload: request,
             preview: {
@@ -213,19 +225,22 @@ export function registerCheckinTools(server, client) {
         title: 'Comment on an Untappd check-in',
         description: 'Post a comment on a check-in from YOUR account. Writes to your Untappd account and is visible to others. ' +
             CONFIRM_FLOW,
-        annotations: toolAnnotations({ title: 'Comment on an Untappd check-in', readOnly: false, idempotent: false, openWorld: true, destructive: false }),
+        // 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 }),
         inputSchema: z.object({
             checkin_id: CheckinIdSchema,
             comment: z.string().min(1).max(2000).describe('Comment text to post'),
             confirmToken: confirmTokenParam,
         }),
-    }, async ({ checkin_id, comment, confirmToken }, ctx) => {
+    }, async (args, ctx) => {
+        const { checkin_id, comment, confirmToken } = args;
         const request = { method: 'POST', path: `/checkin/addcomment/${checkin_id}`, form: { comment } };
         const gate = await confirmWrite(ctx, {
             tool: 'untappd_add_comment',
             action: 'untappd.add_comment',
             message: 'Review and confirm posting this comment from your Untappd account:',
             confirmToken,
+            args,
             target: checkin_id,
             payload: request,
             preview: {
@@ -250,13 +265,15 @@ export function registerCheckinTools(server, client) {
             comment_id: z.number().int().positive().describe('Untappd comment id (from a check-in\'s comments.items)'),
             confirmToken: confirmTokenParam,
         }),
-    }, async ({ comment_id, confirmToken }, ctx) => {
+    }, async (args, ctx) => {
+        const { comment_id, confirmToken } = args;
         const request = { method: 'POST', path: `/checkin/deletecomment/${comment_id}` };
         const gate = await confirmWrite(ctx, {
             tool: 'untappd_delete_comment',
             action: 'untappd.delete_comment',
             message: 'Review and confirm deleting this comment from your Untappd account:',
             confirmToken,
+            args,
             target: comment_id,
             payload: request,
             preview: { action: 'delete_comment', comment_id, ...request, note: 'Deletes this comment from your Untappd account.' },
@@ -274,13 +291,15 @@ export function registerCheckinTools(server, client) {
             checkin_id: CheckinIdSchema,
             confirmToken: confirmTokenParam,
         }),
-    }, async ({ checkin_id, confirmToken }, ctx) => {
+    }, async (args, ctx) => {
+        const { checkin_id, confirmToken } = args;
         const request = { method: 'POST', path: `/checkin/delete/${checkin_id}` };
         const gate = await confirmWrite(ctx, {
             tool: 'untappd_delete_checkin',
             action: 'untappd.delete_checkin',
             message: 'Review and confirm PERMANENTLY deleting this Untappd check-in:',
             confirmToken,
+            args,
             target: checkin_id,
             payload: request,
             preview: {
@@ -301,7 +320,8 @@ export function registerCheckinTools(server, client) {
             '(bid) from untappd_search_beer; optionally a rating (0–5 in 0.25 steps), a shout (comment), a venue via ' +
             'foursquare_id, and a local photo via photo_path (JPEG/PNG). The preview shows the exact fields and photo ' +
             `that will be posted. ${CONFIRM_FLOW}`,
-        annotations: toolAnnotations({ title: 'Check in a beer on Untappd', readOnly: false, idempotent: false, openWorld: true, destructive: false }),
+        // 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 }),
         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)'),
@@ -310,8 +330,9 @@ export function registerCheckinTools(server, client) {
             photo_path: z
                 .string()
                 .optional()
-                .describe('Optional path to a local JPEG/PNG photo (max 15 MB) to attach — it is published publicly. Only use a ' +
-                'file the user explicitly chose; the preview shows the resolved path and size for them to confirm.'),
+                .describe('Optional path to a local JPEG/PNG photo (max 15 MB) to attach — it is published publicly. It must be ' +
+                'inside the photo directory (UNTAPPD_PHOTO_DIR, default ~/Downloads/untappd-mcp). Only use a file the ' +
+                'user explicitly chose; the preview shows the resolved path and size for them to confirm.'),
             geolat: z.number().optional().describe('Optional latitude of the check-in'),
             geolng: z.number().optional().describe('Optional longitude of the check-in'),
             container_id: z
@@ -328,7 +349,8 @@ export function registerCheckinTools(server, client) {
                 'when you know where the user is.'),
             confirmToken: confirmTokenParam,
         }),
-    }, async ({ bid, rating, shout, foursquare_id, photo_path, geolat, geolng, container_id, timezone: requestedTz, confirmToken }, ctx) => {
+    }, async (args, ctx) => {
+        const { bid, rating, shout, foursquare_id, photo_path, geolat, geolng, container_id, timezone: requestedTz, confirmToken } = args;
         const { timezone, gmt_offset } = checkinTimezone(requestedTz);
         // Vetted on every call, so the preview names the exact file (resolved path
         // + size) that will be published — and a file whose bytes change between
@@ -355,6 +377,7 @@ export function registerCheckinTools(server, client) {
             action: 'untappd.checkin',
             message: 'Review and confirm posting this check-in to your public Untappd feed:',
             confirmToken,
+            args,
             target: bid,
             payload: { ...request, photo, photo_sha256 },
             preview: {

package/dist/tools/confirm.js

@@ -15,6 +15,9 @@ export function confirmWrite(ctx, c) {
         details: c.preview,
         tool: c.tool,
         confirmToken: c.confirmToken,
+        // One process acts with one Untappd access token: a single-account server.
+        account: undefined,
+        args: c.args,
         subject: () => ({ target: String(c.target), payload: c.payload, preview: c.preview }),
     }));
 }

package/dist/tools/friends.js

@@ -59,13 +59,15 @@ export function registerFriendActionTools(server, client) {
                 target_uid: TargetUidSchema,
                 confirmToken: confirmTokenParam,
             }),
-        }, async ({ target_uid, confirmToken }, ctx) => {
+        }, async (args, ctx) => {
+            const { target_uid, confirmToken } = args;
             const request = { method: 'POST', path: `/friend/${action.path}/${target_uid}` };
             const gate = await confirmWrite(ctx, {
                 tool: action.tool,
                 action: `untappd.friend_${action.path}`,
                 message: `Review and confirm: ${action.verb} Untappd user ${target_uid}.`,
                 confirmToken,
+                args,
                 target: target_uid,
                 payload: request,
                 preview: { action: action.path, target_uid, ...request, note: `Will ${action.verb} user ${target_uid}.` },

package/dist/tools/utilities.js

@@ -20,7 +20,9 @@ export function registerUtilityTools(server, client) {
                 ok: false,
                 configured: false,
                 ...build,
-                note: 'Untappd credentials are not set. Configure UNTAPPD_USERNAME, UNTAPPD_PASSWORD, UNTAPPD_CLIENT_ID, and UNTAPPD_CLIENT_SECRET.',
+                note: 'Untappd credentials are not set. Configure either UNTAPPD_ACCESS_TOKEN (a token you already hold — no ' +
+                    'password needed; enough for reads) or UNTAPPD_USERNAME, UNTAPPD_PASSWORD, UNTAPPD_CLIENT_ID and ' +
+                    'UNTAPPD_CLIENT_SECRET to log in. Writes also need UNTAPPD_CLIENT_ID and UNTAPPD_CLIENT_SECRET.',
             });
         }
         const feed = await client.get('/checkin/recent', { limit: 1 });
@@ -29,8 +31,12 @@ export function registerUtilityTools(server, client) {
             configured: true,
             account: client.loginName,
             feed_reachable: feed?.checkins !== undefined,
+            writes_enabled: client.canWrite,
             ...build,
-            note: 'Logged in to Untappd and fetched the friend feed successfully.',
+            note: client.canWrite
+                ? 'Logged in to Untappd and fetched the friend feed successfully.'
+                : 'Fetched the friend feed successfully with the access token. Reads work; writes (check-in, toast, ' +
+                    'comment, wishlist, friend actions) need UNTAPPD_CLIENT_ID and UNTAPPD_CLIENT_SECRET as well.',
         });
     });
 }

package/dist/tools/wishlist.js

@@ -11,13 +11,15 @@ export function registerWishlistTools(server, client) {
             bid: BidSchema,
             confirmToken: confirmTokenParam,
         }),
-    }, async ({ bid, confirmToken }, ctx) => {
+    }, async (args, ctx) => {
+        const { bid, confirmToken } = args;
         const request = { method: 'GET', path: '/user/wishlist/add', query: { bid } };
         const gate = await confirmWrite(ctx, {
             tool: 'untappd_wishlist_add',
             action: 'untappd.wishlist_add',
             message: 'Review and confirm adding this beer to your Untappd wishlist:',
             confirmToken,
+            args,
             target: bid,
             payload: request,
             preview: { action: 'wishlist_add', bid, ...request, note: 'Adds this beer to your Untappd wishlist.' },
@@ -35,13 +37,15 @@ export function registerWishlistTools(server, client) {
             bid: BidSchema,
             confirmToken: confirmTokenParam,
         }),
-    }, async ({ bid, confirmToken }, ctx) => {
+    }, async (args, ctx) => {
+        const { bid, confirmToken } = args;
         const request = { method: 'GET', path: '/user/wishlist/delete', query: { bid } };
         const gate = await confirmWrite(ctx, {
             tool: 'untappd_wishlist_remove',
             action: 'untappd.wishlist_remove',
             message: 'Review and confirm removing this beer from your Untappd wishlist:',
             confirmToken,
+            args,
             target: bid,
             payload: request,
             preview: { action: 'wishlist_remove', bid, ...request, note: 'Removes this beer from your Untappd wishlist.' },

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 = '2.2.4'; // x-release-please-version
+export const VERSION = '2.3.1'; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "untappd-mcp",
-  "version": "2.2.4",
+  "version": "2.3.1",
   "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>",
@@ -45,9 +45,8 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^2.14.0",
+    "@chrischall/mcp-utils": "^3.0.0",
     "@modelcontextprotocol/server": "^2.3.0",
-    "ai": "^7.0.19",
     "dotenv": "^18.0.1",
     "zod": "^4.6.5"
   },