untappd-mcp 2.1.2 → 2.2.0

package/dist/tools/checkin.js

@@ -1,7 +1,10 @@
-import { existsSync } from 'node:fs';
-import { extname } from 'node:path';
+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, createHelpfulError, fileBlob, messageOf, minifiedResult, schemaConfirm, toolAnnotations } 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.
@@ -10,103 +13,277 @@ function photoExt(path) {
     const ext = extname(path).slice(1).toLowerCase();
     return ext === 'jpeg' ? 'jpg' : ext;
 }
+// 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). */
+function photoRoots() {
+    const raw = readEnvVar('UNTAPPD_PHOTO_DIR');
+    const roots = raw?.split(delimiter).filter(Boolean);
+    return roots && roots.length > 0 ? roots : undefined;
+}
+/**
+ * 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
+ * exactly which file would be uploaded. Errors never echo the path back.
+ */
+async function checkPhoto(photoPath) {
+    const ext = photoExt(photoPath);
+    if (!(ext in PHOTO_CONTENT_TYPES)) {
+        throw createHelpfulError(`Unsupported photo type "${ext || '(none)'}".`, {
+            hint: 'Attach a .jpg, .jpeg, or .png file.',
+        });
+    }
+    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.',
+            });
+        }
+    }
+    let real;
+    let size;
+    try {
+        real = realpathSync(photoPath);
+        const st = statSync(real);
+        if (!st.isFile())
+            throw new Error('not a file');
+        size = st.size;
+    }
+    catch {
+        throw new McpToolError('Photo file not found or not readable.');
+    }
+    if (size > MAX_PHOTO_BYTES) {
+        throw createHelpfulError(`Photo is too large (${size} bytes; the limit is ${MAX_PHOTO_BYTES}).`, {
+            hint: 'Attach a normal-sized JPEG or PNG photo.',
+        });
+    }
+    const sniffed = sniffMimeBytes(await readFileHead(real, 16));
+    if (sniffed !== PHOTO_CONTENT_TYPES[ext]) {
+        throw createHelpfulError(sniffed === 'image/jpeg' || sniffed === 'image/png'
+            ? `Photo content (${sniffed}) does not match its .${ext} extension.`
+            : 'The file is not a JPEG or PNG image.', { hint: 'Attach a real .jpg/.jpeg or .png photo.' });
+    }
+    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()
     .min(0)
     .max(5)
     .refine((r) => Math.round(r * 4) === r * 4, { message: 'rating must be a multiple of 0.25' });
-function localTimezone() {
-    const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
-    // getTimezoneOffset is minutes behind UTC (positive = behind), so negate for GMT offset in hours.
-    const gmt_offset = -new Date().getTimezoneOffset() / 60;
-    return { timezone, gmt_offset };
+/** GMT offset in hours of an IANA zone at `at` (DST-aware), e.g. 5.5 for Asia/Kolkata. */
+function gmtOffsetHours(timeZone, at) {
+    const name = new Intl.DateTimeFormat('en-US', { timeZone, timeZoneName: 'longOffset' })
+        .formatToParts(at)
+        .find((p) => p.type === 'timeZoneName')?.value;
+    const m = /GMT([+-])(\d{1,2})(?::(\d{2}))?/.exec(name ?? '');
+    if (!m)
+        return 0; // plain "GMT"
+    const hours = Number(m[2]) + Number(m[3] ?? 0) / 60;
+    return m[1] === '-' ? -hours : hours;
+}
+/**
+ * The zone the check-in is stamped with: the caller's `timezone`, else
+ * UNTAPPD_TIMEZONE, else the server process's own zone. The process zone is
+ * only right when the server runs on the drinker's own machine — a hosted
+ * connector's process is typically UTC, which would stamp an evening check-in
+ * into the next day.
+ */
+function checkinTimezone(requested) {
+    const timezone = requested ?? readEnvVar('UNTAPPD_TIMEZONE') ?? (Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC');
+    try {
+        return { timezone, gmt_offset: gmtOffsetHours(timezone, new Date()) };
+    }
+    catch {
+        throw createHelpfulError(`Unknown timezone "${timezone}".`, {
+            hint: 'Pass an IANA timezone name such as "America/New_York" or "Europe/London".',
+        });
+    }
+}
+// How far before the POST a recovered check-in's created_at may fall and still
+// count as the one this call made. Only a small allowance for Untappd's
+// whole-second created_at and modest clock skew: a wider window would match an
+// earlier same-beer check-in (e.g. a prior timed-out attempt) and wrongly report
+// it as this call's — telling the caller not to retry a check-in that never landed.
+const RECOVERY_WINDOW_MS = 30_000;
+/**
+ * Run a NON-idempotent write. A transport failure or timeout (UnreachableError)
+ * may fire after Untappd already received and applied the request, so it is
+ * reported as "outcome unknown" — with how to check — rather than "unreachable",
+ * which invites a blind retry that double-posts (or, for a toggle, undoes it).
+ */
+async function nonIdempotentWrite(run, unknownOutcome) {
+    try {
+        return await run();
+    }
+    catch (e) {
+        if (e instanceof UnreachableError)
+            throw new McpToolError(unknownOutcome);
+        throw e;
+    }
+}
+/**
+ * After an outcome-unknown /checkin/add, look for the check-in it may have made:
+ * the caller's own most recent check-ins, same beer, created since just before
+ * the POST. Returns its id only when exactly one matches; null when none does,
+ * when more than one does (it can't tell which is this call's), or when the
+ * lookup fails — each of which the caller reports as an unknown outcome.
+ */
+async function findRecentCheckin(client, bid, sentAt) {
+    const self = client.loginName;
+    if (!self)
+        return null;
+    try {
+        const data = await client.get(`/user/checkins/${encodeURIComponent(self)}`, { limit: 5 });
+        const matches = [];
+        for (const it of data?.checkins?.items ?? []) {
+            const c = it;
+            const at = Date.parse(c.created_at ?? '');
+            if (c.beer?.bid === bid && typeof c.checkin_id === 'number' && at >= sentAt - RECOVERY_WINDOW_MS) {
+                matches.push(c.checkin_id);
+            }
+        }
+        if (matches.length === 1)
+            return matches[0];
+    }
+    catch {
+        /* can't verify — the caller reports the outcome as unknown */
+    }
+    return null;
 }
 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.',
-            });
-        }
-        const data = await client.write('POST', `/checkin/toast/${checkin_id}`);
+                ...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.`);
         return minifiedResult({ toggled: true, checkin_id, result: data?.result, like_type: data?.like_type });
     });
     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.',
-            });
-        }
-        const data = await client.write('POST', `/checkin/addcomment/${checkin_id}`, { form: { comment } });
+                ...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 });
     });
@@ -114,15 +291,19 @@ 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)'),
             rating: RatingSchema.optional().describe('Rating 0–5 in 0.25 increments (omit for no rating)'),
             shout: z.string().max(2000).optional().describe('Optional shout / comment text for the check-in'),
             foursquare_id: z.string().optional().describe('Optional Foursquare venue id to tag the check-in location'),
-            photo_path: z.string().optional().describe('Optional path to a local JPEG/PNG photo to attach to the check-in'),
+            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.'),
             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
@@ -130,19 +311,22 @@ export function registerCheckinTools(server, client) {
                 .int()
                 .optional()
                 .describe('Optional serving container id (e.g. 1 = draft, 2 = bottle, 3 = can)'),
-            confirm: schemaConfirm,
+            timezone: z
+                .string()
+                .min(1)
+                .optional()
+                .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.'),
+            confirmToken: confirmTokenParam,
         }),
-    }, async ({ bid, rating, shout, foursquare_id, photo_path, geolat, geolng, container_id, confirm }) => {
-        const { timezone, gmt_offset } = localTimezone();
-        let ext;
-        if (photo_path !== undefined) {
-            ext = photoExt(photo_path);
-            if (!(ext in PHOTO_CONTENT_TYPES)) {
-                throw createHelpfulError(`Unsupported photo type "${ext || '(none)'}".`, {
-                    hint: 'Attach a .jpg, .jpeg, or .png file.',
-                });
-            }
-        }
+    }, async ({ bid, rating, shout, foursquare_id, photo_path, geolat, geolng, container_id, timezone: requestedTz, confirmToken }, ctx) => {
+        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
+        // 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,
@@ -153,38 +337,72 @@ export function registerCheckinTools(server, client) {
             container_id,
             timezone,
             gmt_offset,
-            is_photo: photo_path !== undefined ? 'true' : 'false',
-            photo_file_ext: photo_path !== undefined ? ext : undefined,
+            is_photo: photo ? 'true' : 'false',
+            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,
-                photo: photo_path !== undefined ? { path: photo_path, note: 'will be uploaded 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.',
-            });
-        }
+                ...request,
+                photo: photo ? { ...photo, note: 'this exact file will be uploaded PUBLICLY after the check-in is created' } : undefined,
+                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;
-        if (photo_path !== undefined) {
-            if (!existsSync(photo_path))
-                throw new McpToolError(`Photo file not found: ${photo_path}`);
-            blob = await fileBlob(photo_path); // file-backed, streamed — not heap-buffered
+        if (photo) {
+            // file-backed, streamed — not heap-buffered; re-checks the size cap/roots at open.
+            blob = await fileBlob(photo.path, { maxBytes: MAX_PHOTO_BYTES, label: 'Photo', allowedRoots: photoRoots() });
+        }
+        const sentAt = Date.now();
+        let data;
+        try {
+            data = await client.write('POST', '/checkin/add', { form });
+        }
+        catch (e) {
+            if (!(e instanceof UnreachableError))
+                throw e;
+            // The POST may have landed before the connection failed. Look before
+            // reporting failure: a retry of a check-in that DID land double-posts it
+            // to the public feed (and double-counts stats and badges).
+            const found = await findRecentCheckin(client, bid, sentAt);
+            if (found === null) {
+                throw new McpToolError('Untappd did not answer the check-in request in time, so the check-in may have been created anyway ' +
+                    '(it could not be confirmed either way). Look at your latest check-ins with untappd_user_checkins ' +
+                    'before retrying — retrying a check-in that did land posts it twice.');
+            }
+            return minifiedResult({
+                checked_in: true,
+                checkin_id: found,
+                recovered: true,
+                photo_attached: false,
+                ...(photo
+                    ? { photo_error: `Check-in ${found} was created, but its photo upload URL was lost with the timed-out response, so no photo was attached.` }
+                    : {}),
+                note: 'Untappd did not answer in time, but the check-in was found on your account — it was created. Do not retry.',
+            });
         }
-        const data = await client.write('POST', '/checkin/add', { form });
         // Photo is a follow-up S3 upload keyed to the returned checkin_id, then an
         // uploadComplete call. The check-in already exists at this point, so a
         // photo failure is surfaced explicitly (photo_error) rather than thrown —
         // never silently dropped.
         let photo_attached = false;
         let photo_error;
-        if (photo_path !== undefined) {
+        if (photo) {
             if (data?.photo_upload?.url && data.checkin_id) {
                 try {
-                    await client.putBinary(data.photo_upload.url, blob, PHOTO_CONTENT_TYPES[ext]);
+                    await client.putBinary(data.photo_upload.url, blob, photo.content_type);
                     await client.write('POST', '/photo/uploadComplete', {
                         form: { checkin_id: data.checkin_id, destination_url: data.photo_upload.destination_url },
                     });

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 });
         });