untappd-mcp 2.1.2 → 2.1.3

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "MCP server for Untappd — beers, breweries, venues, check-ins, wishlists, and your friend feed",
-    "version": "2.1.2"
+    "version": "2.1.3"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "Untappd",
       "source": "./",
       "description": "MCP server for Untappd — search beers/breweries/venues, read profiles/check-ins/wishlists, and post check-ins, toasts, and comments",
-      "version": "2.1.2",
+      "version": "2.1.3",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "untappd-mcp",
   "displayName": "Untappd",
-  "version": "2.1.2",
+  "version": "2.1.3",
   "description": "MCP server for Untappd — search beers/breweries/venues, read check-ins and wishlists, and post check-ins, toasts, and comments",
   "author": {
     "name": "Chris Hall",

package/README.md

@@ -34,6 +34,8 @@ it goes stale.
 | `UNTAPPD_DEVICE_ID` | no | Stable device UUID the token is keyed to (a default is provided). |
 | `UNTAPPD_UTV` | no | API version param (default `4.0.0`). |
 | `UNTAPPD_USER_AGENT` | no | Override the User-Agent (default mimics the app). |
+| `UNTAPPD_TIMEZONE` | no | IANA timezone (e.g. `America/New_York`) that check-ins are stamped with when the call doesn't pass `timezone`. Set it when the server runs somewhere other than the drinker's zone (e.g. a hosted connector, usually UTC). Defaults to the server process's zone. |
+| `UNTAPPD_PHOTO_DIR` | no | Restrict `untappd_checkin`'s `photo_path` to files inside this directory (several allowed, separated by `:`). Recommended wherever the model can be steered by untrusted content. |
 | `UNTAPPD_CACHE_DB` | no | Path to the local check-in cache SQLite file (default `~/.untappd-mcp/checkins.db`). Local/stdio only. |
 
 Copy `.env.example` to `.env` and fill it in for local use.

package/dist/bundle.js

@@ -1585,8 +1585,8 @@ var require_regexes = __commonJS({
     }
     exports.ipv4 = /^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$/;
     exports.ipv6 = /^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:))$/;
-    var mac3 = (delimiter) => {
-      const escapedDelim = util.escapeRegex(delimiter ?? ":");
+    var mac3 = (delimiter2) => {
+      const escapedDelim = util.escapeRegex(delimiter2 ?? ":");
       return new RegExp(`^(?:[0-9A-F]{2}${escapedDelim}){5}[0-9A-F]{2}$|^(?:[0-9a-f]{2}${escapedDelim}){5}[0-9a-f]{2}$`);
     };
     exports.mac = mac3;
@@ -5000,7 +5000,7 @@ var require_memoizer = __commonJS({
       return bucket;
     }
     var handoff2;
-    var open2 = [];
+    var open3 = [];
     var memo3 = {
       alloc(_inst, payload, empty) {
         const bucket = handoff2;
@@ -5009,7 +5009,7 @@ var require_memoizer = __commonJS({
         handoff2 = void 0;
         const entry = { value: empty, issues: null };
         bucket.set(payload.value, entry);
-        open2.push(entry);
+        open3.push(entry);
         return empty;
       },
       guard(inst) {
@@ -5080,10 +5080,10 @@ var require_memoizer = __commonJS({
               return payload;
             }
             handoff2 = bucket;
-            const depth = open2.length;
+            const depth = open3.length;
             const result = base(payload, ctx);
             handoff2 = void 0;
-            const entry = open2.length > depth ? open2.pop() : void 0;
+            const entry = open3.length > depth ? open3.pop() : void 0;
             if (result instanceof Promise) {
               return result.then((r) => {
                 if (entry)
@@ -40052,8 +40052,8 @@ function emoji() {
 }
 var ipv4 = /^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$/;
 var ipv6 = /^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:))$/;
-var mac = (delimiter) => {
-  const escapedDelim = escapeRegex(delimiter ?? ":");
+var mac = (delimiter2) => {
+  const escapedDelim = escapeRegex(delimiter2 ?? ":");
   return new RegExp(`^(?:[0-9A-F]{2}${escapedDelim}){5}[0-9A-F]{2}$|^(?:[0-9a-f]{2}${escapedDelim}){5}[0-9a-f]{2}$`);
 };
 var cidrv4 = /^((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\/([0-9]|[1-2][0-9]|3[0-2])$/;
@@ -57983,6 +57983,7 @@ async function loadDotenvSafely(opts = {}) {
 
 // node_modules/@chrischall/mcp-utils/dist/fs/index.js
 import { openAsBlob } from "node:fs";
+import { open as open2 } from "node:fs/promises";
 
 // node_modules/@chrischall/mcp-utils/dist/fs/confine.js
 import { existsSync, realpathSync } from "node:fs";
@@ -58019,6 +58020,24 @@ function assertPathWithinRoots(path, roots) {
   throw new Error(`Path is outside the allowed directories: ${path}`);
 }
 
+// node_modules/@chrischall/mcp-utils/dist/fs/output.js
+function sniffMimeBytes(bytes) {
+  const buf = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (buf.length >= 8 && buf.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) {
+    return "image/png";
+  }
+  if (buf.length >= 3 && buf[0] === 255 && buf[1] === 216 && buf[2] === 255) {
+    return "image/jpeg";
+  }
+  if (buf.length >= 12 && buf.subarray(0, 4).toString("latin1") === "RIFF" && buf.subarray(8, 12).toString("latin1") === "WEBP") {
+    return "image/webp";
+  }
+  if (buf.length >= 4 && buf.subarray(0, 4).toString("latin1") === "GIF8") {
+    return "image/gif";
+  }
+  return void 0;
+}
+
 // node_modules/@chrischall/mcp-utils/dist/fs/index.js
 async function fileBlob(path, opts = {}) {
   const target = opts.allowedRoots ? assertPathWithinRoots(path, opts.allowedRoots) : path;
@@ -58033,6 +58052,22 @@ async function fileBlob(path, opts = {}) {
   }
   return blob;
 }
+async function readFileHead(path, bytes, opts = {}) {
+  const target = opts.allowedRoots ? assertPathWithinRoots(path, opts.allowedRoots) : path;
+  let fh;
+  try {
+    fh = await open2(target, "r");
+  } catch {
+    throw new Error(`Cannot read file: ${path}`);
+  }
+  try {
+    const buf = Buffer.alloc(bytes);
+    const { bytesRead } = await fh.read(buf, 0, bytes, 0);
+    return buf.subarray(0, bytesRead);
+  } finally {
+    await fh.close();
+  }
+}
 
 // node_modules/@chrischall/mcp-utils/dist/http/index.js
 function buildQueryString(params) {
@@ -58091,7 +58126,7 @@ function toolAnnotations(opts = {}) {
 }
 
 // src/version.ts
-var VERSION = "2.1.2";
+var VERSION = "2.1.3";
 
 // src/client.ts
 import { dirname as dirname2, join as join2 } from "path";
@@ -58598,7 +58633,9 @@ var SCHEMA_STATEMENTS = [
      beers_offset       INTEGER,
      beers_total        INTEGER,
      beers_complete     INTEGER NOT NULL DEFAULT 0,
-     served_backfill_last INTEGER NOT NULL DEFAULT 0
+     served_backfill_last INTEGER NOT NULL DEFAULT 0,
+     beers_accepted_gap INTEGER NOT NULL DEFAULT 0,
+     beers_rescan_target INTEGER
    )`
 ];
 var MIGRATIONS = [
@@ -58607,7 +58644,9 @@ var MIGRATIONS = [
   "ALTER TABLE sync_state ADD COLUMN beers_offset INTEGER",
   "ALTER TABLE sync_state ADD COLUMN beers_total INTEGER",
   "ALTER TABLE sync_state ADD COLUMN beers_complete INTEGER NOT NULL DEFAULT 0",
-  "ALTER TABLE sync_state ADD COLUMN served_backfill_last INTEGER NOT NULL DEFAULT 0"
+  "ALTER TABLE sync_state ADD COLUMN served_backfill_last INTEGER NOT NULL DEFAULT 0",
+  "ALTER TABLE sync_state ADD COLUMN beers_accepted_gap INTEGER NOT NULL DEFAULT 0",
+  "ALTER TABLE sync_state ADD COLUMN beers_rescan_target INTEGER"
 ];
 var CheckinStoreCore = class {
   constructor(db) {
@@ -58729,7 +58768,9 @@ var CheckinStoreCore = class {
       beers_offset: num(row.beers_offset),
       beers_total: num(row.beers_total),
       beers_complete: Number(row.beers_complete) === 1,
-      served_backfill_last: Number(row.served_backfill_last) === 1
+      served_backfill_last: Number(row.served_backfill_last) === 1,
+      beers_accepted_gap: num(row.beers_accepted_gap) ?? 0,
+      beers_rescan_target: num(row.beers_rescan_target)
     };
   }
   /**
@@ -58753,19 +58794,22 @@ var CheckinStoreCore = class {
       beers_offset: pick2("beers_offset", null),
       beers_total: pick2("beers_total", null),
       beers_complete: pick2("beers_complete", false),
-      served_backfill_last: pick2("served_backfill_last", false)
+      served_backfill_last: pick2("served_backfill_last", false),
+      beers_accepted_gap: pick2("beers_accepted_gap", 0),
+      beers_rescan_target: pick2("beers_rescan_target", null)
     };
     this.db.run(
       `INSERT INTO sync_state
-         (username, oldest_max_id, newest_checkin_id, catchup_max_id, last_synced_at, backfill_complete, total_checkins, checkins_truncated, beers_offset, beers_total, beers_complete, served_backfill_last)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+         (username, oldest_max_id, newest_checkin_id, catchup_max_id, last_synced_at, backfill_complete, total_checkins, checkins_truncated, beers_offset, beers_total, beers_complete, served_backfill_last, beers_accepted_gap, beers_rescan_target)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
        ON CONFLICT(username) DO UPDATE SET
          oldest_max_id=excluded.oldest_max_id, newest_checkin_id=excluded.newest_checkin_id,
          catchup_max_id=excluded.catchup_max_id, last_synced_at=excluded.last_synced_at,
          backfill_complete=excluded.backfill_complete, total_checkins=excluded.total_checkins,
          checkins_truncated=excluded.checkins_truncated, beers_offset=excluded.beers_offset,
          beers_total=excluded.beers_total, beers_complete=excluded.beers_complete,
-         served_backfill_last=excluded.served_backfill_last`,
+         served_backfill_last=excluded.served_backfill_last, beers_accepted_gap=excluded.beers_accepted_gap,
+         beers_rescan_target=excluded.beers_rescan_target`,
       [
         key,
         next.oldest_max_id,
@@ -58778,7 +58822,9 @@ var CheckinStoreCore = class {
         next.beers_offset,
         next.beers_total,
         next.beers_complete ? 1 : 0,
-        next.served_backfill_last ? 1 : 0
+        next.served_backfill_last ? 1 : 0,
+        next.beers_accepted_gap,
+        next.beers_rescan_target
       ]
     );
   }
@@ -59740,19 +59786,108 @@ function registerWishlistTools(server, client2) {
 }
 
 // src/tools/checkin.ts
-import { existsSync as existsSync2 } from "node:fs";
-import { extname } from "node:path";
+import { realpathSync as realpathSync2, statSync } from "node:fs";
+import { delimiter, extname } from "node:path";
 var CheckinIdSchema = external_exports.number().int().positive().describe("Untappd check-in id");
 var PHOTO_CONTENT_TYPES = { jpg: "image/jpeg", png: "image/png" };
 function photoExt(path) {
   const ext = extname(path).slice(1).toLowerCase();
   return ext === "jpeg" ? "jpg" : ext;
 }
+var MAX_PHOTO_BYTES = 15 * 1024 * 1024;
+function photoRoots() {
+  const raw = readEnvVar("UNTAPPD_PHOTO_DIR");
+  const roots = raw?.split(delimiter).filter(Boolean);
+  return roots && roots.length > 0 ? roots : void 0;
+}
+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 = realpathSync2(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 };
+}
 var RatingSchema = external_exports.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";
-  const gmt_offset = -(/* @__PURE__ */ new Date()).getTimezoneOffset() / 60;
-  return { timezone, gmt_offset };
+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;
+  const hours = Number(m[2]) + Number(m[3] ?? 0) / 60;
+  return m[1] === "-" ? -hours : hours;
+}
+function checkinTimezone(requested) {
+  const timezone = requested ?? readEnvVar("UNTAPPD_TIMEZONE") ?? (Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC");
+  try {
+    return { timezone, gmt_offset: gmtOffsetHours(timezone, /* @__PURE__ */ new Date()) };
+  } catch {
+    throw createHelpfulError(`Unknown timezone "${timezone}".`, {
+      hint: 'Pass an IANA timezone name such as "America/New_York" or "Europe/London".'
+    });
+  }
+}
+var RECOVERY_WINDOW_MS = 3e4;
+async function nonIdempotentWrite(run, unknownOutcome) {
+  try {
+    return await run();
+  } catch (e) {
+    if (e instanceof UnreachableError) throw new McpToolError(unknownOutcome);
+    throw e;
+  }
+}
+async function findRecentCheckin(client2, bid, sentAt) {
+  const self = client2.loginName;
+  if (!self) return null;
+  try {
+    const data = await client2.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 {
+  }
+  return null;
 }
 function registerCheckinTools(server, client2) {
   server.registerTool(
@@ -59775,7 +59910,10 @@ function registerCheckinTools(server, client2) {
           note: "Dry run \u2014 re-run with confirm: true to toggle your toast on this check-in."
         });
       }
-      const data = await client2.write("POST", `/checkin/toast/${checkin_id}`);
+      const data = await nonIdempotentWrite(
+        () => client2.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 });
     }
   );
@@ -59801,7 +59939,10 @@ function registerCheckinTools(server, client2) {
           note: "Dry run \u2014 re-run with confirm: true to post this comment to your Untappd account."
         });
       }
-      const data = await client2.write("POST", `/checkin/addcomment/${checkin_id}`, { form: { comment } });
+      const data = await nonIdempotentWrite(
+        () => client2.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 });
     }
   );
@@ -59864,24 +60005,21 @@ function registerCheckinTools(server, client2) {
         rating: RatingSchema.optional().describe("Rating 0\u20135 in 0.25 increments (omit for no rating)"),
         shout: external_exports.string().max(2e3).optional().describe("Optional shout / comment text for the check-in"),
         foursquare_id: external_exports.string().optional().describe("Optional Foursquare venue id to tag the check-in location"),
-        photo_path: external_exports.string().optional().describe("Optional path to a local JPEG/PNG photo to attach to the check-in"),
+        photo_path: external_exports.string().optional().describe(
+          "Optional path to a local JPEG/PNG photo (max 15 MB) to attach \u2014 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."
+        ),
         geolat: external_exports.number().optional().describe("Optional latitude of the check-in"),
         geolng: external_exports.number().optional().describe("Optional longitude of the check-in"),
         container_id: external_exports.number().int().optional().describe("Optional serving container id (e.g. 1 = draft, 2 = bottle, 3 = can)"),
+        timezone: external_exports.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 \u2014 which on a hosted connector is usually UTC, so pass it when you know where the user is."
+        ),
         confirm: schemaConfirm
       })
     },
-    async ({ bid, rating, shout, foursquare_id, photo_path, geolat, geolng, container_id, confirm }) => {
-      const { timezone, gmt_offset } = localTimezone();
-      let ext;
-      if (photo_path !== void 0) {
-        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, confirm }) => {
+      const { timezone, gmt_offset } = checkinTimezone(requestedTz);
+      const photo = photo_path !== void 0 ? await checkPhoto(photo_path) : void 0;
       const form = {
         bid,
         rating: rating !== void 0 ? rating.toFixed(2) : void 0,
@@ -59892,8 +60030,8 @@ function registerCheckinTools(server, client2) {
         container_id,
         timezone,
         gmt_offset,
-        is_photo: photo_path !== void 0 ? "true" : "false",
-        photo_file_ext: photo_path !== void 0 ? ext : void 0,
+        is_photo: photo ? "true" : "false",
+        photo_file_ext: photo?.ext,
         platform: "ios"
       };
       if (confirm !== true) {
@@ -59901,22 +60039,41 @@ function registerCheckinTools(server, client2) {
           dryRun: true,
           action: "checkin",
           form,
-          photo: photo_path !== void 0 ? { path: photo_path, note: "will be uploaded after the check-in is created" } : void 0,
+          photo: photo ? { ...photo, note: "this exact file will be uploaded PUBLICLY after the check-in is created" } : void 0,
           note: "Dry run \u2014 re-run with confirm: true to POST this check-in to your public Untappd feed."
         });
       }
       let blob;
-      if (photo_path !== void 0) {
-        if (!existsSync2(photo_path)) throw new McpToolError(`Photo file not found: ${photo_path}`);
-        blob = await fileBlob(photo_path);
+      if (photo) {
+        blob = await fileBlob(photo.path, { maxBytes: MAX_PHOTO_BYTES, label: "Photo", allowedRoots: photoRoots() });
+      }
+      const sentAt = Date.now();
+      let data;
+      try {
+        data = await client2.write("POST", "/checkin/add", { form });
+      } catch (e) {
+        if (!(e instanceof UnreachableError)) throw e;
+        const found = await findRecentCheckin(client2, 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 \u2014 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 \u2014 it was created. Do not retry."
+        });
       }
-      const data = await client2.write("POST", "/checkin/add", { form });
       let photo_attached = false;
       let photo_error;
-      if (photo_path !== void 0) {
+      if (photo) {
         if (data?.photo_upload?.url && data.checkin_id) {
           try {
-            await client2.putBinary(data.photo_upload.url, blob, PHOTO_CONTENT_TYPES[ext]);
+            await client2.putBinary(data.photo_upload.url, blob, photo.content_type);
             await client2.write("POST", "/photo/uploadComplete", {
               form: { checkin_id: data.checkin_id, destination_url: data.photo_upload.destination_url }
             });
@@ -60226,6 +60383,7 @@ async function syncCheckins(client2, cache, rawUsername, options = {}) {
 
 // src/cache/sync-beers.ts
 var PAGE_LIMIT2 = 50;
+var RESUME_OVERLAP = 10;
 async function fetchBeersPage(client2, encodedUser, offset) {
   const data = await client2.get(
     `/user/beers/${encodedUser}`,
@@ -60248,8 +60406,11 @@ async function syncUserBeers(client2, cache, rawUsername, maxPages = 10) {
   const now = () => (/* @__PURE__ */ new Date()).toISOString();
   const prior = await cache.getState(rawUsername);
   const incremental = (prior?.beers_complete ?? false) && !!prior?.last_synced_at;
-  let offset = incremental ? 0 : prior?.beers_offset ?? 0;
+  let refreshing = incremental;
+  let offset = incremental ? 0 : Math.max(0, (prior?.beers_offset ?? 0) - RESUME_OVERLAP);
   let total = prior?.beers_total ?? null;
+  let acceptedGap = prior?.beers_accepted_gap ?? 0;
+  let rescanTarget = incremental ? null : prior?.beers_rescan_target ?? null;
   let complete = false;
   let pages = 0;
   let added = 0;
@@ -60263,31 +60424,41 @@ async function syncUserBeers(client2, cache, rawUsername, maxPages = 10) {
       });
     }
   };
+  const gapNow = async () => total === null ? 0 : total - await cache.distinctBeersCount(rawUsername);
   for (; pages < maxPages && !complete; ) {
     const page = pages === 0 ? await firstFetch(offset) : await fetchBeersPage(client2, encodedUser, offset);
     pages++;
     if (page.total !== null) total = page.total;
-    if (page.items.length === 0) {
-      complete = true;
-      await cache.setState(rawUsername, {
-        beers_offset: incremental ? total ?? offset : offset,
-        beers_total: total,
-        beers_complete: true,
-        last_synced_at: now()
-      });
-      break;
+    let atEnd = page.items.length === 0;
+    if (!atEnd) {
+      const rows = rowsOf2(rawUsername, page.items);
+      const netNew = await cache.upsertDistinctBeers(rawUsername, rows);
+      added += netNew;
+      offset += page.items.length;
+      if (total !== null && offset >= total) atEnd = true;
+      else if (page.items.length < PAGE_LIMIT2) atEnd = true;
+      else if (refreshing && netNew === 0) atEnd = true;
+      else if (rescanTarget !== null && await gapNow() <= rescanTarget) atEnd = true;
+    }
+    if (atEnd) {
+      const gap = await gapNow();
+      if (gap > acceptedGap && rescanTarget === null) {
+        rescanTarget = acceptedGap;
+        acceptedGap = gap;
+        refreshing = false;
+        offset = 0;
+      } else {
+        complete = true;
+        rescanTarget = null;
+        acceptedGap = Math.max(0, gap);
+      }
     }
-    const rows = rowsOf2(rawUsername, page.items);
-    const netNew = await cache.upsertDistinctBeers(rawUsername, rows);
-    added += netNew;
-    offset += page.items.length;
-    if (total !== null && offset >= total) complete = true;
-    else if (page.items.length < PAGE_LIMIT2) complete = true;
-    else if (incremental && netNew === 0) complete = true;
     await cache.setState(rawUsername, {
-      beers_offset: incremental ? total ?? offset : offset,
+      beers_offset: refreshing ? total ?? offset : offset,
       beers_total: total,
       beers_complete: complete,
+      beers_accepted_gap: acceptedGap,
+      beers_rescan_target: rescanTarget,
       last_synced_at: now()
     });
   }

package/dist/cache/store.js

@@ -175,7 +175,9 @@ export const SCHEMA_STATEMENTS = [
      beers_offset       INTEGER,
      beers_total        INTEGER,
      beers_complete     INTEGER NOT NULL DEFAULT 0,
-     served_backfill_last INTEGER NOT NULL DEFAULT 0
+     served_backfill_last INTEGER NOT NULL DEFAULT 0,
+     beers_accepted_gap INTEGER NOT NULL DEFAULT 0,
+     beers_rescan_target INTEGER
    )`,
 ];
 /** Columns added after the initial release, each applied idempotently on open. */
@@ -186,6 +188,8 @@ export const MIGRATIONS = [
     'ALTER TABLE sync_state ADD COLUMN beers_total INTEGER',
     'ALTER TABLE sync_state ADD COLUMN beers_complete INTEGER NOT NULL DEFAULT 0',
     'ALTER TABLE sync_state ADD COLUMN served_backfill_last INTEGER NOT NULL DEFAULT 0',
+    'ALTER TABLE sync_state ADD COLUMN beers_accepted_gap INTEGER NOT NULL DEFAULT 0',
+    'ALTER TABLE sync_state ADD COLUMN beers_rescan_target INTEGER',
 ];
 /**
  * The cache logic over a synchronous {@link SqlDriver}. Usernames are keyed
@@ -298,6 +302,8 @@ export class CheckinStoreCore {
             beers_total: num(row.beers_total),
             beers_complete: Number(row.beers_complete) === 1,
             served_backfill_last: Number(row.served_backfill_last) === 1,
+            beers_accepted_gap: num(row.beers_accepted_gap) ?? 0,
+            beers_rescan_target: num(row.beers_rescan_target),
         };
     }
     /**
@@ -322,20 +328,24 @@ export class CheckinStoreCore {
             beers_total: pick('beers_total', null),
             beers_complete: pick('beers_complete', false),
             served_backfill_last: pick('served_backfill_last', false),
+            beers_accepted_gap: pick('beers_accepted_gap', 0),
+            beers_rescan_target: pick('beers_rescan_target', null),
         };
         this.db.run(`INSERT INTO sync_state
-         (username, oldest_max_id, newest_checkin_id, catchup_max_id, last_synced_at, backfill_complete, total_checkins, checkins_truncated, beers_offset, beers_total, beers_complete, served_backfill_last)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+         (username, oldest_max_id, newest_checkin_id, catchup_max_id, last_synced_at, backfill_complete, total_checkins, checkins_truncated, beers_offset, beers_total, beers_complete, served_backfill_last, beers_accepted_gap, beers_rescan_target)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
        ON CONFLICT(username) DO UPDATE SET
          oldest_max_id=excluded.oldest_max_id, newest_checkin_id=excluded.newest_checkin_id,
          catchup_max_id=excluded.catchup_max_id, last_synced_at=excluded.last_synced_at,
          backfill_complete=excluded.backfill_complete, total_checkins=excluded.total_checkins,
          checkins_truncated=excluded.checkins_truncated, beers_offset=excluded.beers_offset,
          beers_total=excluded.beers_total, beers_complete=excluded.beers_complete,
-         served_backfill_last=excluded.served_backfill_last`, [
+         served_backfill_last=excluded.served_backfill_last, beers_accepted_gap=excluded.beers_accepted_gap,
+         beers_rescan_target=excluded.beers_rescan_target`, [
             key, next.oldest_max_id, next.newest_checkin_id, next.catchup_max_id, next.last_synced_at,
             next.backfill_complete ? 1 : 0, next.total_checkins, next.checkins_truncated ? 1 : 0,
             next.beers_offset, next.beers_total, next.beers_complete ? 1 : 0, next.served_backfill_last ? 1 : 0,
+            next.beers_accepted_gap, next.beers_rescan_target,
         ]);
     }
     /**

package/dist/cache/sync-beers.js

@@ -1,6 +1,10 @@
 import { createHelpfulError, RateLimitError, messageOf } from '@chrischall/mcp-utils';
 import { mapBeerRow } from './store.js';
 const PAGE_LIMIT = 50; // Untappd's max page size for /user/beers.
+// A resumed backfill re-reads this many already-fetched items: if beers dropped
+// out of the list between runs, everything below shifted UP past the stored
+// offset, and without the overlap the beers that crossed it would be skipped.
+const RESUME_OVERLAP = 10;
 /** One `/user/beers` page fetch (offset-paged), tolerant of the fat shape. */
 async function fetchBeersPage(client, encodedUser, offset) {
     const data = await client.get(`/user/beers/${encodedUser}`, { limit: PAGE_LIMIT, offset, sort: 'date' });
@@ -35,8 +39,15 @@ export async function syncUserBeers(client, cache, rawUsername, maxPages = 10) {
     // An already-complete cache re-scans from the top to pick up newly-had beers,
     // stopping on the first page with nothing new. Otherwise resume the backfill.
     const incremental = (prior?.beers_complete ?? false) && !!prior?.last_synced_at;
-    let offset = incremental ? 0 : (prior?.beers_offset ?? 0);
+    // `refreshing` is the live mode: it starts as `incremental` and is cleared when
+    // a shortfall forces a rescan (which must page past "nothing new" pages).
+    let refreshing = incremental;
+    let offset = incremental ? 0 : Math.max(0, (prior?.beers_offset ?? 0) - RESUME_OVERLAP);
     let total = prior?.beers_total ?? null;
+    let acceptedGap = prior?.beers_accepted_gap ?? 0;
+    // Non-null while a coverage rescan is walking down from the top (possibly
+    // across runs): it stops as soon as the shortfall is back within this target.
+    let rescanTarget = incremental ? null : (prior?.beers_rescan_target ?? null);
     let complete = false;
     let pages = 0;
     let added = 0;
@@ -52,42 +63,60 @@ export async function syncUserBeers(client, cache, rawUsername, maxPages = 10) {
             });
         }
     };
+    const gapNow = async () => total === null ? 0 : total - (await cache.distinctBeersCount(rawUsername));
     for (; pages < maxPages && !complete;) {
         const page = pages === 0 ? await firstFetch(offset) : await fetchBeersPage(client, encodedUser, offset);
         pages++;
         if (page.total !== null)
             total = page.total;
-        if (page.items.length === 0) {
-            // An empty (e.g. first) page still means the list is fully paged — persist
-            // completion so a subsequent call doesn't re-run the same empty fetch.
-            complete = true;
-            await cache.setState(rawUsername, {
-                beers_offset: incremental ? (total ?? offset) : offset,
-                beers_total: total,
-                beers_complete: true,
-                last_synced_at: now(),
-            });
-            break;
+        // An empty (e.g. first) page still means the list is fully paged.
+        let atEnd = page.items.length === 0;
+        if (!atEnd) {
+            const rows = rowsOf(rawUsername, page.items);
+            const netNew = await cache.upsertDistinctBeers(rawUsername, rows);
+            added += netNew;
+            offset += page.items.length;
+            // End conditions: caught the whole list, a short (final) page, or — during an
+            // incremental top refresh — a page that added nothing new.
+            if (total !== null && offset >= total)
+                atEnd = true;
+            else if (page.items.length < PAGE_LIMIT)
+                atEnd = true;
+            else if (refreshing && netNew === 0)
+                atEnd = true;
+            else if (rescanTarget !== null && (await gapNow()) <= rescanTarget)
+                atEnd = true;
+        }
+        if (atEnd) {
+            // Offset paging across runs is not a snapshot: when the list churns between
+            // runs (a beer drops out, or is re-sorted) a beer can slip behind the resumed
+            // offset and never be fetched. Reaching the end is therefore only "complete"
+            // if the cache actually holds total_count beers — less whatever shortfall a
+            // previous full pass already proved the list can never close (a count Untappd
+            // reports but never lists). A NEW shortfall means skipped beers: rescan from
+            // the top (upserts are idempotent) instead of reporting false coverage.
+            const gap = await gapNow();
+            if (gap > acceptedGap && rescanTarget === null) {
+                rescanTarget = acceptedGap;
+                acceptedGap = gap; // a rescan that finds nothing new accepts this gap
+                refreshing = false;
+                offset = 0;
+            }
+            else {
+                complete = true;
+                rescanTarget = null;
+                acceptedGap = Math.max(0, gap);
+            }
         }
-        const rows = rowsOf(rawUsername, page.items);
-        const netNew = await cache.upsertDistinctBeers(rawUsername, rows);
-        added += netNew;
-        offset += page.items.length;
-        // End conditions: caught the whole list, a short (final) page, or — during an
-        // incremental top refresh — a page that added nothing new.
-        if (total !== null && offset >= total)
-            complete = true;
-        else if (page.items.length < PAGE_LIMIT)
-            complete = true;
-        else if (incremental && netNew === 0)
-            complete = true;
         // Persist progress after EVERY page. During an incremental refresh the stored
         // offset stays at the completed total so the next run refreshes from the top
         // again rather than resuming a stale cursor.
         await cache.setState(rawUsername, {
-            beers_offset: incremental ? (total ?? offset) : offset,
+            beers_offset: refreshing ? (total ?? offset) : offset,
             beers_total: total,
             beers_complete: complete,
+            beers_accepted_gap: acceptedGap,
+            beers_rescan_target: rescanTarget,
             last_synced_at: now(),
         });
     }

package/dist/tools/checkin.js

@@ -1,7 +1,7 @@
-import { existsSync } from 'node:fs';
-import { extname } from 'node:path';
+import { realpathSync, statSync } from 'node:fs';
+import { delimiter, extname } from 'node:path';
 import { z } from 'zod';
-import { McpToolError, createHelpfulError, fileBlob, messageOf, minifiedResult, schemaConfirm, toolAnnotations } from '@chrischall/mcp-utils';
+import { McpToolError, assertPathWithinRoots, createHelpfulError, fileBlob, messageOf, minifiedResult, readEnvVar, readFileHead, schemaConfirm, sniffMimeBytes, toolAnnotations, UnreachableError, } from '@chrischall/mcp-utils';
 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,17 +10,150 @@ 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 dry run 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 };
+}
 // 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', {
@@ -42,7 +175,9 @@ export function registerCheckinTools(server, client) {
                 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}`);
+        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', {
@@ -65,7 +200,8 @@ export function registerCheckinTools(server, client) {
                 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 } });
+        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', {
@@ -122,7 +258,11 @@ export function registerCheckinTools(server, client) {
             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 dry run 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 +270,20 @@ export function registerCheckinTools(server, client) {
                 .int()
                 .optional()
                 .describe('Optional serving container id (e.g. 1 = draft, 2 = bottle, 3 = can)'),
+            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.'),
             confirm: schemaConfirm,
         }),
-    }, 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, confirm }) => {
+        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.
+        const photo = photo_path !== undefined ? await checkPhoto(photo_path) : undefined;
         const form = {
             bid,
             rating: rating !== undefined ? rating.toFixed(2) : undefined,
@@ -153,8 +294,8 @@ 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) {
@@ -162,29 +303,55 @@ export function registerCheckinTools(server, client) {
                 dryRun: true,
                 action: 'checkin',
                 form,
-                photo: photo_path !== undefined ? { path: photo_path, note: 'will be uploaded after the check-in is created' } : undefined,
+                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.',
             });
         }
         // 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/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.2'; // x-release-please-version
+export const VERSION = '2.1.3'; // x-release-please-version

package/mint.yaml

@@ -26,6 +26,15 @@ env:
     required: true
     help: >-
       Untappd mobile app client secret.
+  - name: UNTAPPD_TIMEZONE
+    required: false
+    help: >-
+      IANA timezone (e.g. America/New_York) that check-ins are stamped with
+      when a call passes no timezone. Defaults to the server's own zone.
+  - name: UNTAPPD_PHOTO_DIR
+    required: false
+    help: >-
+      Restrict check-in photo uploads to files inside this directory.
   - name: UNTAPPD_CACHE_DB
     required: false
     help: >-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "untappd-mcp",
-  "version": "2.1.2",
+  "version": "2.1.3",
   "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>",

package/server.json

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