untappd-mcp 2.1.3 → 2.2.0

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) {
@@ -69,6 +72,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 +172,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 +203,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 +291,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 +303,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 +318,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 +341,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.0'; // x-release-please-version

package/package.json

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

package/server.json

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

package/skills/untappd-mcp/SKILL.md

@@ -109,9 +109,9 @@ one that exists.
 Each for its own reason — and none of them will tell you it ignored the
 parameter, because an undeclared key is dropped by zod without a warning:
 
-- **The 11 confirm-gated writes** (`untappd_checkin`, `untappd_toast`,
+- **The 11 confirmation-gated writes** (`untappd_checkin`, `untappd_toast`,
   `untappd_add_comment`, the two deletes, the wishlist pair, the four friend
-  actions) answer with a dry-run preview or a receipt. Nothing in a receipt is
+  actions) answer with a confirmation preview or a receipt. Nothing in a receipt is
   decoration.
 - **`untappd_sync_checkins` / `untappd_sync_user_beers`** answer with sync
   PROGRESS — pages walked, `another_run_needed`, `backfill_complete`. Slimming
@@ -140,10 +140,15 @@ parameter, because an undeclared key is dropped by zod without a warning:
   (#161) — it takes a `view` now, and its field shape is documented with the
   other projections above.
 
-## Write tools (confirm-gated — these post to your public account)
+## Write tools (confirmation-gated — these post to your public account)
 
-Each returns a dry-run preview and makes NO network call unless called with
-`confirm: true`:
+Each asks the user to confirm first. Where the client can show a confirmation
+prompt, it does. Otherwise the first call makes NO network call and returns
+`status: "confirmation-required"` with a `preview` of the exact request and a
+`confirmToken`; show the preview to the user, and only after they approve call
+the tool again with the same arguments plus `confirmToken`. A token works once
+and only for those arguments (a change returns `DRAFT_CHANGED` with a fresh
+preview). `MCP_CONFIRM_MODE` on the server can make this `auto` or `refuse`.
 
 - `untappd_toast` — toast/like a check-in (this endpoint is a toggle).
 - `untappd_add_comment` — comment on a check-in.