untappd-mcp 2.1.3 → 2.2.1

package/dist/cache/db.js

@@ -1,5 +1,5 @@
 import { DatabaseSync } from 'node:sqlite';
-import { mkdirSync } from 'node:fs';
+import { chmodSync, closeSync, existsSync, mkdirSync, openSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 import { readEnvVar } from '@chrischall/mcp-utils';
@@ -46,16 +46,53 @@ export class CheckinCache extends LocalCacheStore {
         super(new CheckinStoreCore(new NodeSqlDriver(db)));
         this.db = db;
     }
-    /** Open (creating parent dirs) a file-backed cache, or `:memory:` for tests. */
+    /**
+     * Open (creating parent dirs) a file-backed cache, or `:memory:` for tests.
+     * The file holds other people's dated check-in and venue history, so it is
+     * kept owner-only: dirs 0700, the db (and any -wal/-shm/-journal) 0600.
+     */
     static open(path) {
         if (path !== ':memory:')
-            mkdirSync(dirname(path), { recursive: true });
-        return new CheckinCache(new DatabaseSync(path));
+            preparePrivateFile(path);
+        const cache = new CheckinCache(new DatabaseSync(path));
+        if (path !== ':memory:')
+            tightenSidecars(path);
+        return cache;
     }
     close() {
         this.db.close();
     }
 }
+/**
+ * Create the cache's directory (0700 — `mode` applies to every dir mkdir
+ * creates) and the db file itself (0600) BEFORE SQLite opens it, so the file is
+ * never briefly umask-readable. Pre-existing loose entries from older versions
+ * are tightened too; chmod failures (e.g. a shared dir the user doesn't own)
+ * are best-effort, never fatal.
+ */
+function preparePrivateFile(path) {
+    const dir = dirname(path);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    bestEffortChmod(dir, 0o700);
+    if (!existsSync(path))
+        closeSync(openSync(path, 'a', 0o600));
+    bestEffortChmod(path, 0o600);
+}
+/** SQLite side files inherit the db's mode, but re-assert in case a loose one lingers. */
+function tightenSidecars(path) {
+    for (const suffix of ['-wal', '-shm', '-journal']) {
+        if (existsSync(path + suffix))
+            bestEffortChmod(path + suffix, 0o600);
+    }
+}
+function bestEffortChmod(path, mode) {
+    try {
+        chmodSync(path, mode);
+    }
+    catch {
+        /* best-effort — not every filesystem supports POSIX modes */
+    }
+}
 /** Default on-disk cache path: `$UNTAPPD_CACHE_DB` or `~/.untappd-mcp/checkins.db`. */
 export function defaultCachePath() {
     return readEnvVar('UNTAPPD_CACHE_DB') ?? join(homedir(), '.untappd-mcp', 'checkins.db');

package/dist/cache/store.js

@@ -466,6 +466,22 @@ export class CheckinStoreCore {
         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]);
     }
+    /** Delete one user's cached rows (case-insensitive) in a single transaction. */
+    forgetUser(username) {
+        const key = username.toLowerCase();
+        const count = (table) => Number(this.db.get(`SELECT COUNT(*) AS n FROM ${table} WHERE username = ?`, [key])?.n ?? 0);
+        const removed = {
+            checkins: count('checkins'),
+            distinct_beers: count('distinct_beers'),
+            sync_state: count('sync_state'),
+        };
+        this.db.transaction(() => {
+            this.db.run('DELETE FROM checkins WHERE username = ?', [key]);
+            this.db.run('DELETE FROM distinct_beers WHERE username = ?', [key]);
+            this.db.run('DELETE FROM sync_state WHERE username = ?', [key]);
+        });
+        return removed;
+    }
     getBeerMeta(bids) {
         if (bids.length === 0)
             return [];
@@ -540,6 +556,9 @@ export class LocalCacheStore {
     async upsertBeerMeta(rows) {
         this.core.upsertBeerMeta(rows);
     }
+    async forgetUser(username) {
+        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

package/dist/tools/cache.js

@@ -1,8 +1,9 @@
 import { z } from 'zod';
-import { RateLimitError, createHelpfulError, minifiedResult, toolAnnotations } from '@chrischall/mcp-utils';
+import { RateLimitError, confirmTokenParam, createHelpfulError, minifiedResult, toolAnnotations } from '@chrischall/mcp-utils';
 import { beerMetaFrom } from '../cache/store.js';
 import { syncCheckins } from '../cache/sync.js';
 import { syncUserBeers } from '../cache/sync-beers.js';
+import { CONFIRM_FLOW, confirmWrite } from './confirm.js';
 // Re-fetch cached beer metadata at most this often; a hit newer than this skips
 // the beer/info API call.
 const BEER_META_TTL_MS = 30 * 24 * 60 * 60 * 1000;
@@ -386,4 +387,44 @@ export function registerCacheTools(server, client, cacheProvider) {
             freshness: await freshness(cache, user),
         });
     });
+    server.registerTool('untappd_cache_forget', {
+        title: "Forget a user's cached check-ins",
+        description: "Delete everything the LOCAL cache holds for one user — their cached check-ins (beer, rating, comment, venue, " +
+            'date), distinct-beers list and sync state — e.g. after syncing a friend you no longer want a history of. Only ' +
+            'the local cache is touched; nothing on Untappd changes, and a later sync can re-fetch it. Shared beer ' +
+            'metadata is 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 }),
+        inputSchema: z.object({
+            username: UsernameArg,
+            confirmToken: confirmTokenParam,
+        }),
+    }, async ({ username, confirmToken }, ctx) => {
+        const user = resolveUser(username, client.loginName);
+        const cache = cacheProvider();
+        // Bound into the token: if a sync adds rows after the preview, the
+        // token no longer matches and the user re-confirms the real counts.
+        const counts = {
+            checkins: await cache.cachedCount(user),
+            distinct_beers: await cache.distinctBeersCount(user),
+        };
+        const gate = await confirmWrite(ctx, {
+            tool: 'untappd_cache_forget',
+            action: 'untappd.cache_forget',
+            message: `Review and confirm deleting ${user}'s data from the local Untappd cache:`,
+            confirmToken,
+            target: user.toLowerCase(),
+            payload: { username: user.toLowerCase(), ...counts },
+            preview: {
+                action: 'cache_forget',
+                username: user,
+                ...counts,
+                note: 'Deletes these rows from the LOCAL cache only; Untappd itself is unchanged and a re-sync can restore them.',
+            },
+        });
+        if (gate)
+            return gate;
+        const removed = await cache.forgetUser(user);
+        return minifiedResult({ forgotten: true, username: user, removed });
+    });
 }

package/dist/tools/checkin.js

@@ -1,7 +1,10 @@
-import { realpathSync, statSync } from 'node:fs';
+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 { z } from 'zod';
-import { McpToolError, assertPathWithinRoots, createHelpfulError, fileBlob, messageOf, minifiedResult, readEnvVar, readFileHead, schemaConfirm, sniffMimeBytes, toolAnnotations, UnreachableError, } from '@chrischall/mcp-utils';
+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');
 // Keyed by the NORMALISED extension that photoExt() returns (jpeg → jpg), so
 // there is no dead `jpeg` entry.
@@ -23,7 +26,7 @@ function photoRoots() {
  * 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 dry run shows a human
+ * allow-list, 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) {
@@ -61,7 +64,15 @@ async function checkPhoto(photoPath) {
             hint: 'Attach a normal-sized JPEG or PNG photo.',
         });
     }
-    const sniffed = sniffMimeBytes(await readFileHead(real, 16));
+    // Re-check UNTAPPD_PHOTO_DIR at open time, so a swap after the check above can't escape it.
+    let head;
+    try {
+        head = await readFileHead(real, 16, { allowedRoots: roots });
+    }
+    catch {
+        throw new McpToolError('Photo file not found or not readable.');
+    }
+    const sniffed = sniffMimeBytes(head);
     if (sniffed !== PHOTO_CONTENT_TYPES[ext]) {
         throw createHelpfulError(sniffed === 'image/jpeg' || sniffed === 'image/png'
             ? `Photo content (${sniffed}) does not match its .${ext} extension.`
@@ -69,6 +80,16 @@ async function checkPhoto(photoPath) {
     }
     return { path: real, size_bytes: size, ext, content_type: sniffed };
 }
+/**
+ * sha256 of the photo's bytes, streamed. Bound into the confirm token so a
+ * different image swapped in at the same path — even one of identical size and
+ * type — no longer matches the preview the user approved.
+ */
+async function photoSha256(path) {
+    const hash = createHash('sha256');
+    await pipeline(createReadStream(path), hash);
+    return hash.digest('hex');
+}
 // Untappd ratings are 0–5 in 0.25 increments; 0 (or omitted) means no rating.
 const RatingSchema = z
     .number()
@@ -159,22 +180,30 @@ export function registerCheckinTools(server, client) {
     server.registerTool('untappd_toast', {
         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. Without confirm: true it returns a dry-run preview and makes NO network ' +
-            'call; with confirm: true it posts. Writes to your Untappd account and is visible to others.',
+            `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 }),
         inputSchema: z.object({
             checkin_id: CheckinIdSchema,
-            confirm: schemaConfirm,
+            confirmToken: confirmTokenParam,
         }),
-    }, async ({ checkin_id, confirm }) => {
-        if (confirm !== true) {
-            return minifiedResult({
-                dryRun: true,
+    }, async ({ checkin_id, confirmToken }, ctx) => {
+        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,
+            target: checkin_id,
+            payload: request,
+            preview: {
                 action: 'toast',
                 checkin_id,
-                note: 'Dry run — re-run with confirm: true to toggle your toast on this check-in.',
-            });
-        }
+                ...request,
+                note: 'Toggles your toast on this check-in (removes it if you have already toasted).',
+            },
+        });
+        if (gate)
+            return gate;
         const data = await nonIdempotentWrite(() => client.write('POST', `/checkin/toast/${checkin_id}`), `Untappd did not answer the toast request for check-in ${checkin_id} in time, so it may or may not have ` +
             'been applied. Toast is a TOGGLE: retrying could remove a toast that did land. Check with ' +
             `untappd_checkin_info (checkin_id ${checkin_id}) before retrying.`);
@@ -182,67 +211,87 @@ export function registerCheckinTools(server, client) {
     });
     server.registerTool('untappd_add_comment', {
         title: 'Comment on an Untappd check-in',
-        description: 'Post a comment on a check-in from YOUR account. Without confirm: true it returns a dry-run preview and ' +
-            'makes NO network call; with confirm: true it posts. Writes to your Untappd account and is visible to others.',
+        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 }),
         inputSchema: z.object({
             checkin_id: CheckinIdSchema,
             comment: z.string().min(1).max(2000).describe('Comment text to post'),
-            confirm: schemaConfirm,
+            confirmToken: confirmTokenParam,
         }),
-    }, async ({ checkin_id, comment, confirm }) => {
-        if (confirm !== true) {
-            return minifiedResult({
-                dryRun: true,
+    }, async ({ checkin_id, comment, confirmToken }, ctx) => {
+        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,
+            target: checkin_id,
+            payload: request,
+            preview: {
                 action: 'add_comment',
                 checkin_id,
                 comment,
-                note: 'Dry run — re-run with confirm: true to post this comment to your Untappd account.',
-            });
-        }
+                ...request,
+                note: 'Posts this comment to the check-in from your Untappd account, visible to others.',
+            },
+        });
+        if (gate)
+            return gate;
         const data = await nonIdempotentWrite(() => client.write('POST', `/checkin/addcomment/${checkin_id}`, { form: { comment } }), `Untappd did not answer in time, so the comment may have been posted already. Check the comments with ` +
             `untappd_checkin_info (checkin_id ${checkin_id}) before retrying, or it may be posted twice.`);
         return minifiedResult({ posted: true, checkin_id, response: data });
     });
     server.registerTool('untappd_delete_comment', {
         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). Without ' +
-            'confirm: true it returns a dry-run preview and makes NO network call; with confirm: true it deletes.',
+        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 }),
         inputSchema: z.object({
             comment_id: z.number().int().positive().describe('Untappd comment id (from a check-in\'s comments.items)'),
-            confirm: schemaConfirm,
+            confirmToken: confirmTokenParam,
         }),
-    }, async ({ comment_id, confirm }) => {
-        if (confirm !== true) {
-            return minifiedResult({
-                dryRun: true,
-                action: 'delete_comment',
-                comment_id,
-                note: 'Dry run — re-run with confirm: true to delete this comment from your Untappd account.',
-            });
-        }
+    }, async ({ comment_id, confirmToken }, ctx) => {
+        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,
+            target: comment_id,
+            payload: request,
+            preview: { action: 'delete_comment', comment_id, ...request, note: 'Deletes this comment from your Untappd account.' },
+        });
+        if (gate)
+            return gate;
         const data = await client.write('POST', `/checkin/deletecomment/${comment_id}`);
         return minifiedResult({ deleted: true, comment_id, result: data?.result });
     });
     server.registerTool('untappd_delete_checkin', {
         title: 'Delete an Untappd check-in',
-        description: 'Permanently delete one of YOUR check-ins by its id. This is destructive and cannot be undone. Without ' +
-            'confirm: true it returns a dry-run preview and makes NO network call; with confirm: true it deletes.',
+        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 }),
         inputSchema: z.object({
             checkin_id: CheckinIdSchema,
-            confirm: schemaConfirm,
+            confirmToken: confirmTokenParam,
         }),
-    }, async ({ checkin_id, confirm }) => {
-        if (confirm !== true) {
-            return minifiedResult({
-                dryRun: true,
+    }, async ({ checkin_id, confirmToken }, ctx) => {
+        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,
+            target: checkin_id,
+            payload: request,
+            preview: {
                 action: 'delete_checkin',
                 checkin_id,
-                note: 'Dry run — re-run with confirm: true to PERMANENTLY delete this check-in. This cannot be undone.',
-            });
-        }
+                ...request,
+                note: 'PERMANENTLY deletes this check-in. This cannot be undone.',
+            },
+        });
+        if (gate)
+            return gate;
         const data = await client.write('POST', `/checkin/delete/${checkin_id}`);
         return minifiedResult({ deleted: true, checkin_id, result: data?.result });
     });
@@ -250,8 +299,8 @@ export function registerCheckinTools(server, client) {
         title: 'Check in a beer on Untappd',
         description: 'Post a NEW beer check-in to YOUR Untappd account — this publishes to your public feed. Provide the beer id ' +
             '(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). Without confirm: true it returns a dry-run ' +
-            'preview of the exact fields and makes NO network call; with confirm: true it posts.',
+            '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 }),
         inputSchema: z.object({
             bid: z.number().int().positive().describe('Untappd beer id to check in (from untappd_search_beer)'),
@@ -262,7 +311,7 @@ export function registerCheckinTools(server, client) {
                 .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 dry run shows the resolved path and size for them to confirm.'),
+                '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
@@ -277,13 +326,15 @@ export function registerCheckinTools(server, client) {
                 .describe("The drinker's IANA timezone (e.g. America/New_York), which sets the check-in's local time. Defaults to " +
                 "UNTAPPD_TIMEZONE, else the server's own zone — which on a hosted connector is usually UTC, so pass it " +
                 'when you know where the user is.'),
-            confirm: schemaConfirm,
+            confirmToken: confirmTokenParam,
         }),
-    }, async ({ bid, rating, shout, foursquare_id, photo_path, geolat, geolng, container_id, timezone: requestedTz, confirm }) => {
+    }, async ({ bid, rating, shout, foursquare_id, photo_path, geolat, geolng, container_id, timezone: requestedTz, confirmToken }, ctx) => {
         const { timezone, gmt_offset } = checkinTimezone(requestedTz);
-        // Vetted on the dry run too, so the preview names the exact file (resolved
-        // path + size) that confirm: true would publish.
+        // 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
+        // the preview and the confirmed call no longer matches the token.
         const photo = photo_path !== undefined ? await checkPhoto(photo_path) : undefined;
+        const photo_sha256 = photo ? await photoSha256(photo.path) : undefined;
         const form = {
             bid,
             rating: rating !== undefined ? rating.toFixed(2) : undefined,
@@ -298,15 +349,23 @@ export function registerCheckinTools(server, client) {
             photo_file_ext: photo?.ext,
             platform: 'ios',
         };
-        if (confirm !== true) {
-            return minifiedResult({
-                dryRun: true,
+        const request = { method: 'POST', path: '/checkin/add', form };
+        const gate = await confirmWrite(ctx, {
+            tool: 'untappd_checkin',
+            action: 'untappd.checkin',
+            message: 'Review and confirm posting this check-in to your public Untappd feed:',
+            confirmToken,
+            target: bid,
+            payload: { ...request, photo, photo_sha256 },
+            preview: {
                 action: 'checkin',
-                form,
+                ...request,
                 photo: photo ? { ...photo, note: 'this exact file will be uploaded PUBLICLY after the check-in is created' } : undefined,
-                note: 'Dry run — re-run with confirm: true to POST this check-in to your public Untappd feed.',
-            });
-        }
+                note: 'POSTs this check-in to your public Untappd feed.',
+            },
+        });
+        if (gate)
+            return gate;
         // Open the photo BEFORE creating the check-in, so a missing/unreadable
         // file fails fast without leaving an orphaned photo-less check-in behind.
         let blob;

package/dist/tools/confirm.js

@@ -0,0 +1,20 @@
+import { confirmationFromEnv, requireConfirmationWithFallback } from '@chrischall/mcp-utils';
+/** The sentence every gated write's description carries. */
+export const CONFIRM_FLOW = 'Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call ' +
+    'returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).';
+/**
+ * Gate a write behind the fleet confirmation flow. `undefined` means proceed;
+ * anything else is the result to return unchanged. Callers rebuild `payload`
+ * and `preview` from the arguments on every call, so a token only authorises
+ * the exact request its preview showed.
+ */
+export function confirmWrite(ctx, c) {
+    return requireConfirmationWithFallback(ctx, confirmationFromEnv({
+        action: c.action,
+        message: c.message,
+        details: c.preview,
+        tool: c.tool,
+        confirmToken: c.confirmToken,
+        subject: () => ({ target: String(c.target), payload: c.payload, preview: c.preview }),
+    }));
+}

package/dist/tools/friends.js

@@ -1,12 +1,13 @@
 import { z } from 'zod';
-import { minifiedResult, schemaConfirm, toolAnnotations } from '@chrischall/mcp-utils';
+import { confirmTokenParam, minifiedResult, toolAnnotations } from '@chrischall/mcp-utils';
+import { CONFIRM_FLOW, confirmWrite } from './confirm.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),
 // but — unlike the rest of this server's writes — these were NOT live-verified
 // against the API, because doing so would send real friend requests to / alter
-// real relationships with other people. They are confirm-gated so nothing fires
-// without an explicit confirm: true.
+// real relationships with other people. They are confirmation-gated so nothing
+// fires without the user approving the exact request first.
 const TargetUidSchema = z
     .number()
     .int()
@@ -47,8 +48,7 @@ export function registerFriendActionTools(server, client) {
         server.registerTool(action.tool, {
             title: action.title,
             description: `${action.detail} Acts on YOUR account and affects a real relationship with another person. ` +
-                'Without confirm: true it returns a dry-run preview and makes NO network call; with confirm: true it ' +
-                'performs the action. Note: this endpoint path is taken from the Untappd app but is not otherwise ' +
+                `${CONFIRM_FLOW} Note: this endpoint path is taken from the Untappd app but is not otherwise ` +
                 'independently verified.',
             // All four reach ANOTHER PERSON — the description says so itself: "affects
             // a real relationship with another person". A friend request cannot be
@@ -57,17 +57,21 @@ export function registerFriendActionTools(server, client) {
             annotations: toolAnnotations({ title: action.title, readOnly: false, idempotent: true, openWorld: true, destructive: true }),
             inputSchema: z.object({
                 target_uid: TargetUidSchema,
-                confirm: schemaConfirm,
+                confirmToken: confirmTokenParam,
             }),
-        }, async ({ target_uid, confirm }) => {
-            if (confirm !== true) {
-                return minifiedResult({
-                    dryRun: true,
-                    action: action.path,
-                    target_uid,
-                    note: `Dry run — re-run with confirm: true to ${action.verb} user ${target_uid}.`,
-                });
-            }
+        }, async ({ target_uid, confirmToken }, ctx) => {
+            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,
+                target: target_uid,
+                payload: request,
+                preview: { action: action.path, target_uid, ...request, note: `Will ${action.verb} user ${target_uid}.` },
+            });
+            if (gate)
+                return gate;
             const data = await client.write('POST', `/friend/${action.path}/${target_uid}`);
             return minifiedResult({ done: true, action: action.path, target_uid, result: data?.result });
         });

package/dist/tools/wishlist.js

@@ -1,46 +1,53 @@
 import { z } from 'zod';
-import { minifiedResult, schemaConfirm, toolAnnotations } from '@chrischall/mcp-utils';
+import { confirmTokenParam, minifiedResult, toolAnnotations } from '@chrischall/mcp-utils';
+import { CONFIRM_FLOW, confirmWrite } from './confirm.js';
 const BidSchema = z.number().int().positive().describe('Untappd beer id (bid) — from untappd_search_beer');
 export function registerWishlistTools(server, client) {
     server.registerTool('untappd_wishlist_add', {
         title: 'Add a beer to your wishlist',
-        description: 'Add a beer to YOUR Untappd wishlist by its bid. Without confirm: true it returns a dry-run preview and ' +
-            'makes NO network call; with confirm: true it adds. Writes to your account.',
+        description: `Add a beer to YOUR Untappd wishlist by its bid. Writes to your account. ${CONFIRM_FLOW}`,
         annotations: toolAnnotations({ title: 'Add a beer to your wishlist', readOnly: false, idempotent: true, openWorld: true, destructive: false }),
         inputSchema: z.object({
             bid: BidSchema,
-            confirm: schemaConfirm,
+            confirmToken: confirmTokenParam,
         }),
-    }, async ({ bid, confirm }) => {
-        if (confirm !== true) {
-            return minifiedResult({
-                dryRun: true,
-                action: 'wishlist_add',
-                bid,
-                note: 'Dry run — re-run with confirm: true to add this beer to your wishlist.',
-            });
-        }
+    }, async ({ bid, confirmToken }, ctx) => {
+        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,
+            target: bid,
+            payload: request,
+            preview: { action: 'wishlist_add', bid, ...request, note: 'Adds this beer to your Untappd wishlist.' },
+        });
+        if (gate)
+            return gate;
         const data = await client.write('GET', '/user/wishlist/add', { query: { bid } });
         return minifiedResult({ added: true, bid, result: data?.result });
     });
     server.registerTool('untappd_wishlist_remove', {
         title: 'Remove a beer from your wishlist',
-        description: 'Remove a beer from YOUR Untappd wishlist by its bid. Without confirm: true it returns a dry-run preview ' +
-            'and makes NO network call; with confirm: true it removes. Writes to your account.',
+        description: `Remove a beer from YOUR Untappd wishlist by its bid. Writes to your account. ${CONFIRM_FLOW}`,
         annotations: toolAnnotations({ title: 'Remove a beer from your wishlist', readOnly: false, idempotent: true, openWorld: true, destructive: false }),
         inputSchema: z.object({
             bid: BidSchema,
-            confirm: schemaConfirm,
+            confirmToken: confirmTokenParam,
         }),
-    }, async ({ bid, confirm }) => {
-        if (confirm !== true) {
-            return minifiedResult({
-                dryRun: true,
-                action: 'wishlist_remove',
-                bid,
-                note: 'Dry run — re-run with confirm: true to remove this beer from your wishlist.',
-            });
-        }
+    }, async ({ bid, confirmToken }, ctx) => {
+        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,
+            target: bid,
+            payload: request,
+            preview: { action: 'wishlist_remove', bid, ...request, note: 'Removes this beer from your Untappd wishlist.' },
+        });
+        if (gate)
+            return gate;
         const data = await client.write('GET', '/user/wishlist/delete', { query: { bid } });
         return minifiedResult({ removed: true, bid, result: data?.result });
     });

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "untappd-mcp",
-  "version": "2.1.3",
+  "version": "2.2.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,7 +45,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^2.4.0",
+    "@chrischall/mcp-utils": "^2.6.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "ai": "^7.0.19",
     "dotenv": "^18.0.1",