untappd-mcp 2.6.0 → 2.7.0

package/dist/tools/checkin.js

@@ -6,6 +6,7 @@ import { delimiter, extname, join } from 'node:path';
 import { z } from 'zod';
 import { foodMeta } from './hints.js';
 import { confirmTokenParam, McpToolError, assertPathWithinRoots, createHelpfulError, fileBlob, messageOf, minifiedResult, readEnvVar, readFileHead, sniffMimeBytes, toolAnnotations, UnreachableError, } from '@chrischall/mcp-utils';
+import { blobStoreFromEnv, inlineFileSchema, isHostedEnv, MAX_UPLOAD_FILES, mintUploadSlot, resolveUploadMime, resolveUploadSource, sanitizeUploadFilename, uploadSlotRequestSchema, } from '@chrischall/mcp-utils/export';
 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
@@ -98,6 +99,38 @@ async function photoSha256(path) {
     await pipeline(createReadStream(path), hash);
     return hash.digest('hex');
 }
+/** The parameter names the photo routes are spelled with here, for resolveUploadSource's messages. */
+const PHOTO_PARAM_NAMES = {
+    path: 'photo_path',
+    inline: 'photo_inline',
+    blobKey: 'photo_blob_key',
+    slotTool: 'untappd_upload_slots',
+};
+/** The image types Untappd takes for a check-in photo, as bare MIME types. */
+const PHOTO_MIME_TYPES = Object.values(PHOTO_CONTENT_TYPES);
+/** Untappd's `photo_file_ext` for an accepted photo MIME type. */
+function extForMime(mime) {
+    return Object.entries(PHOTO_CONTENT_TYPES).find(([, m]) => m === mime)[0];
+}
+/**
+ * A photo that arrived as bytes — inline base64 or an upload-slot blob —
+ * through {@link resolveUploadSource}: exactly one source, image types only,
+ * the same cap as a local path, the bytes sniffed against the type. Called on
+ * EVERY phase, so the confirmed call re-reads the blob and a changed one no
+ * longer matches the sha256 bound into the token. Reading never deletes.
+ *
+ * A local `photo_path` does NOT come through here (it keeps {@link checkPhoto}
+ * and its photo-directory rules) — except on a hosted deployment, where
+ * resolveUploadSource is what refuses it, and when it was combined with
+ * another source, which resolveUploadSource refuses as "exactly one".
+ */
+function resolvePhotoSource(input) {
+    return resolveUploadSource(input, {
+        maxBytes: MAX_PHOTO_BYTES,
+        allowedMimeTypes: PHOTO_MIME_TYPES,
+        names: PHOTO_PARAM_NAMES,
+    });
+}
 // Untappd ratings are 0–5 in 0.25 increments; 0 (or omitted) means no rating.
 const RatingSchema = z
     .number()
@@ -319,12 +352,54 @@ export function registerCheckinTools(server, client) {
         const data = await client.write('POST', `/checkin/delete/${checkin_id}`);
         return minifiedResult({ deleted: true, checkin_id, result: data?.result });
     });
+    server.registerTool('untappd_upload_slots', {
+        title: 'Get upload URLs for Untappd check-in photos',
+        description: 'Get signed upload URLs for check-in photos — the way to attach a photo on the HOSTED connector, which cannot ' +
+            'read files on your machine. For each photo (JPEG or PNG, max 15 MB) it returns a blobKey and a ready curl ' +
+            'command: run the curl with the path to the photo (it must send exactly the returned Content-Type), then pass ' +
+            'the blobKey to untappd_checkin as photo_blob_key. URLs expire after 30 minutes. Posts nothing to Untappd. ' +
+            'Only available where the deployment provides a blob store; on a local install use photo_path or photo_inline.',
+        annotations: toolAnnotations({ title: 'Get upload URLs for Untappd check-in photos', readOnly: true, openWorld: false }),
+        _meta: foodMeta('lookup', { aliases: ['upload photo', 'beer photo'] }),
+        inputSchema: z.object({
+            slots: z
+                .array(uploadSlotRequestSchema)
+                .min(1)
+                .max(MAX_UPLOAD_FILES)
+                .describe(`One entry per photo to upload (at most ${MAX_UPLOAD_FILES}): {filename, mimeType?}. JPEG or PNG only.`),
+        }),
+    }, async ({ slots }) => {
+        const store = blobStoreFromEnv();
+        if (!store) {
+            throw createHelpfulError('Upload slots need the blob store a hosted deployment provides, and this server has no blob store.', {
+                hint: 'On a local install attach the photo with untappd_checkin photo_path (a file in UNTAPPD_PHOTO_DIR) or photo_inline (base64).',
+            });
+        }
+        // Refuse a non-photo before minting a URL the check-in would only reject later.
+        for (const req of slots) {
+            const mime = resolveUploadMime(sanitizeUploadFilename(req.filename), req.mimeType);
+            if (!PHOTO_MIME_TYPES.includes(mime)) {
+                throw createHelpfulError(`${req.filename}: ${mime} is not a check-in photo type.`, {
+                    hint: 'Untappd check-in photos must be JPEG or PNG (.jpg, .jpeg or .png).',
+                });
+            }
+        }
+        return minifiedResult({
+            slots: slots.map((req) => mintUploadSlot(store, req)),
+            next: 'PUT each photo to its uploadUrl (the curl command, with the placeholder replaced by the file path), then ' +
+                'call untappd_checkin with photo_blob_key set to that slot\'s blobKey. The upload is deleted once the ' +
+                'check-in and its photo succeed.',
+        });
+    });
     server.registerTool('untappd_checkin', {
         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). The preview shows the exact fields and photo ' +
-            `that will be posted. ${CONFIRM_FLOW}`,
+            'foursquare_id, and ONE photo (JPEG/PNG, max 15 MB) via exactly one of photo_path (a local file), ' +
+            'photo_inline (base64, for a small photo) or photo_blob_key. On the hosted connector, use the slot flow: call ' +
+            'untappd_upload_slots, PUT the photo with the returned curl, then pass its blobKey as photo_blob_key (a path ' +
+            'cannot work there). The preview shows the exact fields and photo that will be posted. ' +
+            `${CONFIRM_FLOW}`,
         // Destructive: it publishes to your public feed, where friends see it; untappd_delete_checkin cannot unpublish what they saw.
         annotations: toolAnnotations({ title: 'Check in a beer on Untappd', readOnly: false, idempotent: false, openWorld: true, destructive: true }),
         _meta: foodMeta('change', { aliases: ['check in', 'log a beer', 'rate a beer', 'drinking'] }),
@@ -338,7 +413,18 @@ export function registerCheckinTools(server, client) {
                 .optional()
                 .describe('Optional path to a local JPEG/PNG photo (max 15 MB) to attach — it is published publicly. It must be ' +
                 'inside the photo directory (UNTAPPD_PHOTO_DIR, default ~/Downloads/untappd-mcp). Only use a file the ' +
-                'user explicitly chose; the preview shows the resolved path and size for them to confirm.'),
+                'user explicitly chose; the preview shows the resolved path and size for them to confirm. Local installs ' +
+                'only — refused on the hosted connector (use photo_blob_key).'),
+            photo_inline: inlineFileSchema
+                .optional()
+                .describe('Optional photo as base64: {filename, contentBase64, mimeType?}, JPEG or PNG, max 15 MB — it is published ' +
+                'publicly. Works on any deployment; for anything but a small photo prefer the upload slot flow ' +
+                '(photo_blob_key). Only use a photo the user explicitly chose.'),
+            photo_blob_key: z
+                .string()
+                .optional()
+                .describe('Optional blobKey of a photo PUT to a slot from untappd_upload_slots (hosted connector) — it is published ' +
+                'publicly. Deleted from the upload store once the check-in and its photo succeed; kept if they fail.'),
             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
@@ -356,13 +442,37 @@ export function registerCheckinTools(server, client) {
             confirmToken: confirmTokenParam,
         }),
     }, async (args, ctx) => {
-        const { bid, rating, shout, foursquare_id, photo_path, geolat, geolng, container_id, timezone: requestedTz, confirmToken } = args;
+        const { bid, rating, shout, foursquare_id, photo_path, photo_inline, photo_blob_key, geolat, geolng, container_id, timezone: requestedTz, confirmToken, } = args;
         const { timezone, gmt_offset } = checkinTimezone(requestedTz);
-        // Vetted on every call, so the preview names the exact file (resolved path
-        // + size) that will be published — and a file whose bytes change between
-        // 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;
+        // Vetted on every call, so the preview names the exact photo that will be
+        // published — and one whose bytes change between the preview and the
+        // confirmed call no longer matches the token. A lone local photo_path keeps
+        // its own checks; every other route (and a path on a hosted deployment,
+        // which is refused there) goes through resolveUploadSource.
+        const localPath = photo_path !== undefined && photo_inline === undefined && photo_blob_key === undefined && !isHostedEnv();
+        const anyPhoto = photo_path !== undefined || photo_inline !== undefined || photo_blob_key !== undefined;
+        const source = anyPhoto && !localPath
+            ? await resolvePhotoSource({ path: photo_path, inline: photo_inline, blobKey: photo_blob_key })
+            : undefined;
+        const photo = localPath ? await checkPhoto(photo_path) : undefined;
+        const photo_sha256 = photo ? await photoSha256(photo.path) : source?.sha256;
+        const photo_ext = photo?.ext ?? (source ? extForMime(source.mimeType) : undefined);
+        const photo_content_type = photo?.content_type ?? source?.mimeType;
+        const hasPhoto = photo !== undefined || source !== undefined;
+        // What the preview (and the token) names: a local file by its resolved
+        // path; bytes by name, type, size and hash (never the signed URL).
+        const photoPreview = photo
+            ? photo
+            : source
+                ? {
+                    origin: source.origin,
+                    file_name: source.fileName,
+                    content_type: source.mimeType,
+                    size_bytes: source.sizeBytes,
+                    sha256: source.sha256,
+                    ...(source.blobKey !== undefined ? { blob_key: source.blobKey } : {}),
+                }
+                : undefined;
         const form = {
             bid,
             rating: rating !== undefined ? rating.toFixed(2) : undefined,
@@ -373,8 +483,8 @@ export function registerCheckinTools(server, client) {
             container_id,
             timezone,
             gmt_offset,
-            is_photo: photo ? 'true' : 'false',
-            photo_file_ext: photo?.ext,
+            is_photo: hasPhoto ? 'true' : 'false',
+            photo_file_ext: photo_ext,
             platform: 'ios',
         };
         const request = { method: 'POST', path: '/checkin/add', form };
@@ -385,11 +495,13 @@ export function registerCheckinTools(server, client) {
             confirmToken,
             args,
             target: bid,
-            payload: { ...request, photo, photo_sha256 },
+            payload: { ...request, photo: photoPreview, photo_sha256 },
             preview: {
                 action: 'checkin',
                 ...request,
-                photo: photo ? { ...photo, note: 'this exact file will be uploaded PUBLICLY after the check-in is created' } : undefined,
+                photo: photoPreview
+                    ? { ...photoPreview, note: 'this exact photo will be uploaded PUBLICLY after the check-in is created' }
+                    : undefined,
                 note: 'POSTs this check-in to your public Untappd feed.',
             },
         });
@@ -402,6 +514,17 @@ export function registerCheckinTools(server, client) {
             // 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() });
         }
+        else if (source) {
+            // Already read and hashed above; copied so the Blob owns a plain ArrayBuffer.
+            blob = new Blob([new Uint8Array(source.bytes)], { type: source.mimeType });
+        }
+        // An uploaded blob is deleted only after the check-in AND its photo
+        // succeed; on any other outcome it is kept (and said so), so the caller
+        // can delete the check-in and retry with the same photo_blob_key. The
+        // blob store's retention prune reclaims it otherwise.
+        const keptBlob = source?.origin === 'blob'
+            ? { photo_blob: { deleted: false, kept: true, blob_key: source.blobKey, note: 'The uploaded photo was kept because it was not attached.' } }
+            : {};
         const sentAt = Date.now();
         let data;
         try {
@@ -424,8 +547,8 @@ export function registerCheckinTools(server, client) {
                 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.` }
+                ...(hasPhoto
+                    ? { photo_error: `Check-in ${found} was created, but its photo upload URL was lost with the timed-out response, so no photo was attached.`, ...keptBlob }
                     : {}),
                 note: 'Untappd did not answer in time, but the check-in was found on your account — it was created. Do not retry.',
             });
@@ -436,10 +559,10 @@ export function registerCheckinTools(server, client) {
         // never silently dropped.
         let photo_attached = false;
         let photo_error;
-        if (photo) {
+        if (hasPhoto) {
             if (data?.photo_upload?.url && data.checkin_id) {
                 try {
-                    await client.putBinary(data.photo_upload.url, blob, photo.content_type);
+                    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 },
                     });
@@ -453,11 +576,15 @@ export function registerCheckinTools(server, client) {
                 photo_error = `Check-in ${data?.checkin_id} was created, but Untappd returned no photo upload URL, so no photo was attached.`;
             }
         }
+        // Release (delete) an uploaded blob only now that the photo is attached; a
+        // failed delete is reported, never thrown — the check-in already exists.
+        const blobOutcome = source?.origin === 'blob' ? (photo_attached ? { photo_blob: await source.release() } : keptBlob) : {};
         return minifiedResult({
             checked_in: true,
             checkin_id: data?.checkin_id,
             photo_attached,
             ...(photo_error ? { photo_error } : {}),
+            ...blobOutcome,
             response: data,
         });
     });

package/dist/tools/feed.js

@@ -11,7 +11,8 @@ const FEED_VIEW = z
     .optional()
     .describe('Response shape: "compact" (default) projects each check-in to {id, user, beer, brewery, venue, rating, comment, ' +
     'toast/comment counts}; "full" returns Untappd\'s whole ~5 KB record; "brief" returns one line per check-in: ' +
-    '<user>: <beer> (<brewery>) at <venue> — <ISO date or "no date"> — <rated N|not rated>.');
+    '<user>: <beer> (<brewery>) at <venue> — <ISO date or "no date"> — <rated N|not rated>, inside the untrusted-data ' +
+    'envelope as data: string[], with "-- " note lines ("-- none", "-- more").');
 export function registerFeedTools(server, client) {
     server.registerTool('untappd_activity_feed', {
         title: 'Get Untappd friend activity feed',

package/dist/tools/hints.js

@@ -1,3 +1,4 @@
+import { UNTRUSTED_CONTENT_RULE, untrustedEnvelope } from '@chrischall/mcp-utils';
 /** `_meta` for an Untappd tool: every tool here is in the `food` domain. */
 export function foodMeta(intent, extra = {}) {
     return { mint: { domain: 'food', intent, ...extra } };
@@ -19,8 +20,10 @@ function isoInstant(v) {
 }
 /**
  * One check-in as one line, `<user>: <beer> (<brewery>) at <venue> — <ISO date | no date> — <rated N | not rated>`,
- * at most 120 characters (the title is shortened). Read only from the fields a
- * check-in record carries; a rating of 0 is Untappd's "no rating".
+ * cut to at most 120 characters as a whole, title first. A title starting with
+ * `-- ` or `\\` is escaped with one leading `\\`, so an item never reads as a
+ * note. Read only from the fields a check-in record carries; a rating of 0 is
+ * Untappd's "no rating".
  */
 export function briefCheckinLine(item) {
     const c = dict(item);
@@ -28,15 +31,40 @@ export function briefCheckinLine(item) {
     const beer = str(dict(c.beer).beer_name) ?? 'a beer';
     const brewery = str(dict(c.brewery).brewery_name);
     const venue = str(dict(c.venue).venue_name);
-    const title = `${who}: ${beer}${brewery ? ` (${brewery})` : ''}${venue ? ` at ${venue}` : ''}`;
+    const raw = `${who}: ${beer}${brewery ? ` (${brewery})` : ''}${venue ? ` at ${venue}` : ''}`;
+    // A title that could read as a note (`-- `) or lose a character to the host's one-backslash strip is escaped.
+    const title = raw.startsWith('-- ') || raw.startsWith('\\') ? `\\${raw}` : raw;
     const rating = typeof c.rating_score === 'number' && c.rating_score > 0 ? `rated ${c.rating_score}` : 'not rated';
     const tail = ` — ${isoInstant(c.created_at) ?? 'no date'} — ${rating}`;
     const room = BRIEF_MAX - tail.length;
     const shown = title.length > room ? `${title.slice(0, Math.max(room - 1, 0))}…` : title;
     return `${shown}${tail}`;
 }
-/** A `{ checkins: { items } }` response as brief lines, one per check-in (none for an empty or unexpected page). */
+/** Who writes the brief lines' text — the head of the untrusted-data envelope's note. */
+const BRIEF_WHO_WROTE = 'Check-in user names and beer, brewery and venue names are written by other Untappd users and breweries.';
+/**
+ * A `{ checkins: { items, pagination } }` response as brief lines, one per
+ * check-in, plus `-- ` notes: `-- none` for an empty page, `-- more` when
+ * Untappd returned an older-page cursor (`pagination.max_id`), and
+ * `-- error: …` for a shape this view does not read.
+ */
+export function briefCheckinLines(resp) {
+    const box = dict(dict(resp).checkins);
+    if (!Array.isArray(box.items)) {
+        return ['-- error: Untappd answered in a shape this brief view does not read; ask with view "full"'];
+    }
+    if (box.items.length === 0)
+        return ['-- none'];
+    const lines = box.items.map(briefCheckinLine);
+    const next = dict(box.pagination).max_id;
+    if (typeof next === 'number' && next > 0)
+        lines.push('-- more');
+    return lines;
+}
+/**
+ * The brief answer: the lines inside the fleet's untrusted-data envelope as
+ * `data: string[]`, minified, note first — the text in them is other people's.
+ */
 export function briefCheckins(resp) {
-    const items = dict(dict(resp).checkins).items;
-    return Array.isArray(items) ? items.map(briefCheckinLine).join('\n') : '';
+    return JSON.stringify(untrustedEnvelope(briefCheckinLines(resp), { note: `${BRIEF_WHO_WROTE} ${UNTRUSTED_CONTENT_RULE}` }));
 }

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

package/mint.yaml

@@ -92,3 +92,8 @@ egress:
     #   - a signed upload URL returned by the API (often storage.googleapis.com / s3)
     # Confirm the concrete host(s) against a live run and add them, or
     # the isolated tier will block the call.
+    #
+    # Not listed: mcp-host's own blob store (MCP_BLOB_BASE_URL, the gateway
+    # serving this connector — its host differs per deployment). The server
+    # GETs + DELETEs check-in photos the caller uploaded through
+    # untappd_upload_slots. Signed requests only; no Untappd credential is sent.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "untappd-mcp",
-  "version": "2.6.0",
+  "version": "2.7.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": "^3.0.3",
+    "@chrischall/mcp-utils": "^3.7.2",
     "@modelcontextprotocol/server": "^2.3.0",
     "dotenv": "^18.0.1",
     "zod": "^4.6.5"

package/server.json

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

package/skills/untappd-mcp/SKILL.md

@@ -25,9 +25,13 @@ client credentials):
 
 Two things the server enforces that you should plan around:
 
-- **Photos:** `untappd_checkin`'s `photo_path` must be a file inside
-  `UNTAPPD_PHOTO_DIR` (default `~/Downloads/untappd-mcp`); anything else (e.g.
-  `~/Pictures/beer.jpg`) is refused. Ask the user to move the photo there first.
+- **Photos:** pass exactly one of `photo_path`, `photo_inline` or
+  `photo_blob_key` (JPEG/PNG, max 15 MB). Locally, `photo_path` must be a file
+  inside `UNTAPPD_PHOTO_DIR` (default `~/Downloads/untappd-mcp`); anything else
+  (e.g. `~/Pictures/beer.jpg`) is refused — ask the user to move the photo there
+  first. On the **hosted connector** a path cannot work: call
+  `untappd_upload_slots`, PUT the photo with the returned `curl`, then pass its
+  `blobKey` as `photo_blob_key` (or, for a small photo, `photo_inline` base64).
 - **Time zone:** on a hosted connector the server usually runs in UTC, so pass
   `timezone` (the drinker's IANA zone, e.g. `America/New_York`) on
   `untappd_checkin` unless `UNTAPPD_TIMEZONE` is set — otherwise the check-in is
@@ -75,7 +79,11 @@ and you still get compact. `view: "full"` is the only way back.
 
 `untappd_activity_feed` also takes a third rung, `view: "brief"`: one line per
 check-in, `<user>: <beer> (<brewery>) at <venue> — <ISO date | no date> —
-<rated N | not rated>`, each at most 120 characters. It is the shape a
+<rated N | not rated>`, each at most 120 characters, answered inside the
+untrusted-data envelope as `data: string[]` (the names are other Untappd
+users'). A line starting `-- ` is a note, not a check-in: `-- none` for an
+empty feed, `-- more` when an older page exists; a name that itself starts
+with `-- ` or `\` is escaped with one leading `\`. It is the shape a
 context-group host reads aloud (below); use it when you only need to say what
 friends have been drinking.
 
@@ -175,9 +183,8 @@ 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.
 - `untappd_checkin` — post a new beer check-in to your feed (needs a `bid` from
-  `untappd_search_beer`; optional `rating` 0–5 in 0.25 steps, `shout`, venue).
-
-Photo attachment and wishlist add/remove are not yet supported.
+  `untappd_search_beer`; optional `rating` 0–5 in 0.25 steps, `shout`, venue,
+  one photo — see **Photos** above).
 
 ## Check-in cache