untappd-mcp 0.0.0

package/dist/client.js

@@ -0,0 +1,252 @@
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { loadDotenvSafely, readEnvVar, buildQueryString, formatApiError, createHelpfulError, McpToolError, RateLimitError, UnreachableError, } from '@chrischall/mcp-utils';
+// Load .env for local dev; silently skip if dotenv is unavailable (e.g. the
+// mcpb bundle). `loadDotenvSafely` swallows a missing dotenv module and never
+// lets .env override a host-provided value.
+const __dirname = dirname(fileURLToPath(import.meta.url));
+await loadDotenvSafely({ path: join(__dirname, '..', '.env'), override: false });
+const BASE_URL = 'https://api.untappd.com/v4';
+const SERVICE = 'Untappd';
+const REQUEST_TIMEOUT_MS = 30_000;
+// Non-secret client constants that mimic the Untappd iPad app (v4.7.13). The
+// API accepts requests carrying these; NONE are user secrets (the secrets are
+// UNTAPPD_CLIENT_ID / UNTAPPD_CLIENT_SECRET / UNTAPPD_USERNAME / _PASSWORD,
+// which come from the environment). All overridable via env for forward-compat
+// when the app version bumps.
+const DEFAULTS = {
+    utv: '4.0.0',
+    appVersion: '4.7.13',
+    deviceName: 'iPad',
+    deviceVersion: '26.5',
+    devicePlatform: 'iPadOS',
+    userAgent: 'Untappd/4.7.13 (ios; iPadOS 26.5)',
+    // Untappd keys the returned access token to this device id; any stable UUID
+    // works. Override with UNTAPPD_DEVICE_ID to pin your own.
+    deviceUdid: 'A1B2C3D4-0000-4000-8000-0000000000AA',
+};
+function readCredentials() {
+    const username = readEnvVar('UNTAPPD_USERNAME');
+    const password = readEnvVar('UNTAPPD_PASSWORD');
+    const clientId = readEnvVar('UNTAPPD_CLIENT_ID');
+    const clientSecret = readEnvVar('UNTAPPD_CLIENT_SECRET');
+    if (username && password && clientId && clientSecret) {
+        return { username, password, clientId, clientSecret };
+    }
+    return null;
+}
+function missingCredsError() {
+    const missing = ['UNTAPPD_USERNAME', 'UNTAPPD_PASSWORD', 'UNTAPPD_CLIENT_ID', 'UNTAPPD_CLIENT_SECRET'].filter((k) => !readEnvVar(k));
+    return createHelpfulError(`Untappd credentials are not configured — missing ${missing.join(', ') || 'credentials'}.`, {
+        hint: 'Set UNTAPPD_USERNAME and UNTAPPD_PASSWORD (your Untappd login), plus UNTAPPD_CLIENT_ID and ' +
+            'UNTAPPD_CLIENT_SECRET (the Untappd mobile app client credentials). See the README for how to obtain them.',
+    });
+}
+export class UntappdClient {
+    fetchImpl;
+    creds;
+    configError;
+    utv = readEnvVar('UNTAPPD_UTV') ?? DEFAULTS.utv;
+    deviceUdid = readEnvVar('UNTAPPD_DEVICE_ID') ?? DEFAULTS.deviceUdid;
+    userAgent = readEnvVar('UNTAPPD_USER_AGENT') ?? DEFAULTS.userAgent;
+    token;
+    loginInFlight = null;
+    /**
+     * Defer the config error so the server can still start (and respond to the
+     * host's install-time tools/list smoke test) when credentials aren't set yet.
+     * Tool calls re-raise the error at request time.
+     */
+    constructor(opts = {}) {
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+        this.token = opts.token ?? null;
+        const creds = opts.credentials !== undefined ? opts.credentials : readCredentials();
+        if (creds) {
+            this.creds = creds;
+            this.configError = null;
+        }
+        else {
+            this.creds = null;
+            this.configError = missingCredsError();
+        }
+    }
+    /** Whether credentials are configured (used by the healthcheck tool). */
+    get configured() {
+        return this.configError === null;
+    }
+    /** The configured login name — the default `username` for user-scoped tools. */
+    get loginName() {
+        return this.creds?.username ?? null;
+    }
+    requireCreds() {
+        if (this.configError)
+            throw this.configError;
+        return this.creds;
+    }
+    baseHeaders() {
+        return {
+            'User-Agent': this.userAgent,
+            Accept: 'application/json',
+            'x-untappd-app': 'ios',
+            'x-untappd-app-version': DEFAULTS.appVersion,
+        };
+    }
+    // One HTTP attempt with a hard timeout. Network/timeout failures become an
+    // UnreachableError; HTTP status handling is left to the caller.
+    async send(method, url, init) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+        try {
+            return await this.fetchImpl(url, {
+                method,
+                headers: init.headers,
+                ...(init.body !== undefined ? { body: init.body } : {}),
+                signal: controller.signal,
+            });
+        }
+        catch {
+            throw new UnreachableError(SERVICE);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * Obtain an access token, logging in via xauth (username/password) on demand.
+     * A single shared in-flight promise coalesces concurrent tool calls so they
+     * never trigger duplicate logins.
+     */
+    async ensureToken() {
+        if (this.token)
+            return this.token;
+        if (!this.loginInFlight) {
+            this.loginInFlight = this.login().finally(() => {
+                this.loginInFlight = null;
+            });
+        }
+        return this.loginInFlight;
+    }
+    async login() {
+        const c = this.requireCreds();
+        const qs = buildQueryString({ client_id: c.clientId, client_secret: c.clientSecret, utv: this.utv });
+        const form = new URLSearchParams({
+            user_name: c.username,
+            user_password: c.password,
+            device_udid: this.deviceUdid,
+            device_name: DEFAULTS.deviceName,
+            device_version: DEFAULTS.deviceVersion,
+            device_platform: DEFAULTS.devicePlatform,
+            app_version: DEFAULTS.appVersion,
+            multi_account: 'true',
+        });
+        const res = await this.send('POST', `${BASE_URL}/xauth${qs}`, {
+            headers: { ...this.baseHeaders(), 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: form.toString(),
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            if (res.status === 401 || res.status === 400) {
+                throw createHelpfulError(`Untappd login failed (${res.status}).`, {
+                    hint: 'Check UNTAPPD_USERNAME / UNTAPPD_PASSWORD, and that UNTAPPD_CLIENT_ID / UNTAPPD_CLIENT_SECRET are the mobile app credentials.',
+                });
+            }
+            throw new McpToolError(formatApiError(res.status, 'POST', '/xauth', text, { service: SERVICE }));
+        }
+        let data;
+        try {
+            data = JSON.parse(text);
+        }
+        catch {
+            throw new McpToolError('Untappd login returned a non-JSON response.');
+        }
+        const token = data?.response?.access_token;
+        if (!token) {
+            throw createHelpfulError('Untappd login did not return an access token.', {
+                hint: data?.response?.two_factor_enabled
+                    ? 'This account has two-factor authentication enabled, which xauth login cannot satisfy.'
+                    : 'The credentials may be incorrect.',
+            });
+        }
+        this.token = token;
+        return token;
+    }
+    async parseJson(res, method, path) {
+        if (res.status === 429) {
+            const ra = Number(res.headers.get('retry-after'));
+            throw new RateLimitError(SERVICE, ra > 0 ? ra : undefined);
+        }
+        const text = await res.text();
+        let data;
+        if (text.length) {
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                /* leave undefined; handled below */
+            }
+        }
+        const meta = data?.meta;
+        if (!res.ok) {
+            const detail = meta?.error_detail || meta?.error_type;
+            throw new McpToolError(formatApiError(res.status, method, path, detail ?? text, { service: SERVICE }));
+        }
+        if (typeof meta?.code === 'number' && meta.code >= 400) {
+            const detail = meta.error_detail || meta.error_type || `code ${meta.code}`;
+            throw new McpToolError(`Untappd ${method} ${path} failed (${meta.code}): ${detail}`);
+        }
+        return (data?.response ?? data);
+    }
+    async request(method, path, opts, isRetry = false) {
+        const token = await this.ensureToken();
+        const headers = this.baseHeaders();
+        // The Untappd app carries the token as a query param on reads and as an
+        // `Authorization: Bearer` header on writes (with the client credentials in
+        // the query). We mirror that exactly — both shapes are the real captured
+        // requests the app itself makes.
+        let query;
+        if (opts.auth === 'bearer') {
+            const c = this.requireCreds();
+            headers['Authorization'] = `Bearer ${token}`;
+            query = { ...opts.query, client_id: c.clientId, client_secret: c.clientSecret, utv: this.utv };
+        }
+        else {
+            query = { ...opts.query, access_token: token, utv: this.utv };
+        }
+        const qs = buildQueryString(query);
+        let body;
+        if (opts.form) {
+            headers['Content-Type'] = 'application/x-www-form-urlencoded';
+            const f = new URLSearchParams();
+            for (const [k, v] of Object.entries(opts.form)) {
+                if (v !== undefined && v !== null)
+                    f.append(k, String(v));
+            }
+            body = f.toString();
+        }
+        const res = await this.send(method, `${BASE_URL}${path}${qs}`, { headers, body });
+        // A 401 means the cached token went stale — drop it and log in once more.
+        if (res.status === 401 && !isRetry) {
+            this.token = null;
+            return this.request(method, path, opts, true);
+        }
+        return this.parseJson(res, method, path);
+    }
+    /** Authenticated read (token in the query, as the app does for GETs). */
+    async get(path, query = {}) {
+        return this.request('GET', path, { query, auth: 'query' });
+    }
+    /**
+     * Authenticated write. Attaches the `Authorization: Bearer` token and client
+     * credentials centrally (the app's write shape); `form` is sent as
+     * application/x-www-form-urlencoded. Every mutating tool routes through here.
+     */
+    async write(method, path, opts = {}) {
+        return this.request(method, path, { ...opts, auth: 'bearer' });
+    }
+}
+/**
+ * Module-level singleton shared by every tool module. Constructing it here (not
+ * in `index.ts`) keeps the deferred-config-error pattern: the server boots and
+ * answers the host's install-time tools/list smoke test even when credentials
+ * are absent — the error only surfaces on the first tool call.
+ */
+export const client = new UntappdClient();

package/dist/index.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { runMcp } from '@chrischall/mcp-utils';
+import { VERSION } from './version.js';
+import { registerBeerTools } from './tools/beer.js';
+import { registerBreweryTools } from './tools/brewery.js';
+import { registerVenueTools } from './tools/venue.js';
+import { registerUserTools } from './tools/user.js';
+import { registerFeedTools } from './tools/feed.js';
+import { registerCheckinTools } from './tools/checkin.js';
+import { registerUtilityTools } from './tools/utilities.js';
+// The Untappd client is a module-level singleton (imported by each tool module)
+// that defers its config error to the first request. That preserves the
+// deferred-config-error pattern: the server boots and answers the host's
+// install-time tools/list smoke test even when credentials are absent — the
+// configuration error only surfaces on the first tool call.
+await runMcp({
+    name: 'untappd-mcp',
+    version: VERSION,
+    banner: '[untappd-mcp] This project was developed and is maintained by AI (Claude Opus 4.8). Use at your own discretion.',
+    tools: [
+        registerBeerTools,
+        registerBreweryTools,
+        registerVenueTools,
+        registerUserTools,
+        registerFeedTools,
+        registerCheckinTools,
+        registerUtilityTools,
+    ],
+});

package/dist/tools/beer.js

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import { textResult, toolAnnotations } from '@chrischall/mcp-utils';
+import { client } from '../client.js';
+const BidSchema = z.number().int().positive().describe('Untappd beer id (bid)');
+export function registerBeerTools(server) {
+    server.registerTool('untappd_search_beer', {
+        title: 'Search Untappd beers',
+        description: 'Search Untappd for beers by name (optionally "Brewery Beer"). Returns ranked matches with their ' +
+            'beer id (bid), brewery, style, ABV, IBU, and global rating. Feed a bid into untappd_beer_info for full ' +
+            'detail. Read-only.',
+        annotations: toolAnnotations({ title: 'Search Untappd beers', readOnly: true, idempotent: true, openWorld: true }),
+        inputSchema: {
+            query: z.string().min(1).describe('Beer name to search for'),
+            limit: z.number().int().min(1).max(50).optional().describe('Max results (1–50, default 25)'),
+            offset: z.number().int().min(0).optional().describe('Result offset for paging (default 0)'),
+            sort: z
+                .enum(['checkin', 'name', 'count'])
+                .optional()
+                .describe('Sort order: checkin (relevance, default), name, or count'),
+        },
+    }, async ({ query, limit, offset, sort }) => {
+        const data = await client.get('/search/beer', { q: query, limit, offset, sort });
+        return textResult(data);
+    });
+    server.registerTool('untappd_beer_info', {
+        title: 'Get Untappd beer detail',
+        description: 'Get full detail for a beer by its Untappd beer id (bid): description, style, ABV, IBU, brewery, rating, ' +
+            'total check-in count, and (unless compact) recent activity. Get a bid from untappd_search_beer. Read-only.',
+        annotations: toolAnnotations({ title: 'Get Untappd beer detail', readOnly: true, idempotent: true, openWorld: true }),
+        inputSchema: {
+            bid: BidSchema,
+            compact: z
+                .boolean()
+                .optional()
+                .describe('Return a slimmer record without the embedded recent-activity lists (default false)'),
+        },
+    }, async ({ bid, compact }) => {
+        const data = await client.get(`/beer/info/${bid}`, { compact: compact ? 'true' : undefined });
+        return textResult(data);
+    });
+}

package/dist/tools/brewery.js

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import { textResult, toolAnnotations } from '@chrischall/mcp-utils';
+import { client } from '../client.js';
+export function registerBreweryTools(server) {
+    server.registerTool('untappd_search_brewery', {
+        title: 'Search Untappd breweries',
+        description: 'Search Untappd for breweries by name. Returns matches with their brewery id, location, type, and beer ' +
+            'count. Feed a brewery id into untappd_brewery_info for full detail. Read-only.',
+        annotations: toolAnnotations({ title: 'Search Untappd breweries', readOnly: true, idempotent: true, openWorld: true }),
+        inputSchema: {
+            query: z.string().min(1).describe('Brewery name to search for'),
+            limit: z.number().int().min(1).max(50).optional().describe('Max results (1–50, default 25)'),
+            offset: z.number().int().min(0).optional().describe('Result offset for paging (default 0)'),
+        },
+    }, async ({ query, limit, offset }) => {
+        const data = await client.get('/search/brewery', { q: query, limit, offset });
+        return textResult(data);
+    });
+    server.registerTool('untappd_brewery_info', {
+        title: 'Get Untappd brewery detail',
+        description: 'Get full detail for a brewery by its Untappd brewery id: description, location, type, rating, total ' +
+            'check-ins, and popular beers. Get an id from untappd_search_brewery. Read-only.',
+        annotations: toolAnnotations({ title: 'Get Untappd brewery detail', readOnly: true, idempotent: true, openWorld: true }),
+        inputSchema: {
+            brewery_id: z.number().int().positive().describe('Untappd brewery id'),
+            compact: z.boolean().optional().describe('Return a slimmer record without embedded activity (default false)'),
+        },
+    }, async ({ brewery_id, compact }) => {
+        const data = await client.get(`/brewery/info/${brewery_id}`, { compact: compact ? 'true' : undefined });
+        return textResult(data);
+    });
+}

package/dist/tools/checkin.js

@@ -0,0 +1,110 @@
+import { z } from 'zod';
+import { textResult, toolAnnotations, schemaConfirm } from '@chrischall/mcp-utils';
+import { client } from '../client.js';
+const CheckinIdSchema = z.number().int().positive().describe('Untappd check-in id');
+// 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 };
+}
+export function registerCheckinTools(server) {
+    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.',
+        annotations: toolAnnotations({ title: 'Toast an Untappd check-in', readOnly: false, idempotent: false, openWorld: true }),
+        inputSchema: {
+            checkin_id: CheckinIdSchema,
+            confirm: schemaConfirm,
+        },
+    }, async ({ checkin_id, confirm }) => {
+        if (confirm !== true) {
+            return textResult({
+                dryRun: true,
+                action: 'toast',
+                checkin_id,
+                note: 'Dry run — re-run with confirm: true to toggle your toast on this check-in.',
+            });
+        }
+        const data = await client.write('POST', `/checkin/toast/${checkin_id}`);
+        return textResult({ toggled: true, checkin_id, result: data?.result, like_type: data?.like_type });
+    });
+    server.registerTool('untappd_add_comment', {
+        title: 'Comment on an Untappd check-in',
+        description: 'Post a comment on a check-in from YOUR account. Without confirm: true it returns a dry-run preview and ' +
+            'makes NO network call; with confirm: true it posts. Writes to your Untappd account and is visible to others.',
+        annotations: toolAnnotations({ title: 'Comment on an Untappd check-in', readOnly: false, idempotent: false, openWorld: true }),
+        inputSchema: {
+            checkin_id: CheckinIdSchema,
+            comment: z.string().min(1).max(2000).describe('Comment text to post'),
+            confirm: schemaConfirm,
+        },
+    }, async ({ checkin_id, comment, confirm }) => {
+        if (confirm !== true) {
+            return textResult({
+                dryRun: true,
+                action: 'add_comment',
+                checkin_id,
+                comment,
+                note: 'Dry run — re-run with confirm: true to post this comment to your Untappd account.',
+            });
+        }
+        const data = await client.write('POST', `/checkin/addcomment/${checkin_id}`, { form: { comment } });
+        return textResult({ posted: true, checkin_id, response: data });
+    });
+    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), and a venue via ' +
+            'foursquare_id (from a venue result). Without confirm: true it returns a dry-run preview of the exact fields ' +
+            'and makes NO network call; with confirm: true it posts. Photo attachment is not supported.',
+        annotations: toolAnnotations({ title: 'Check in a beer on Untappd', readOnly: false, idempotent: false, openWorld: true }),
+        inputSchema: {
+            bid: z.number().int().positive().describe('Untappd beer id to check in (from untappd_search_beer)'),
+            rating: RatingSchema.optional().describe('Rating 0–5 in 0.25 increments (omit for no rating)'),
+            shout: z.string().max(2000).optional().describe('Optional shout / comment text for the check-in'),
+            foursquare_id: z.string().optional().describe('Optional Foursquare venue id to tag the check-in location'),
+            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
+                .number()
+                .int()
+                .optional()
+                .describe('Optional serving container id (e.g. 1 = draft, 2 = bottle, 3 = can)'),
+            confirm: schemaConfirm,
+        },
+    }, async ({ bid, rating, shout, foursquare_id, geolat, geolng, container_id, confirm }) => {
+        const { timezone, gmt_offset } = localTimezone();
+        const form = {
+            bid,
+            rating: rating !== undefined ? rating.toFixed(2) : undefined,
+            shout: shout || undefined,
+            foursquare_id,
+            geolat,
+            geolng,
+            container_id,
+            timezone,
+            gmt_offset,
+            is_photo: 'false',
+            platform: 'ios',
+        };
+        if (confirm !== true) {
+            return textResult({
+                dryRun: true,
+                action: 'checkin',
+                form,
+                note: 'Dry run — re-run with confirm: true to POST this check-in to your public Untappd feed.',
+            });
+        }
+        const data = await client.write('POST', '/checkin/add', { form });
+        return textResult({ checked_in: true, checkin_id: data?.checkin_id, response: data });
+    });
+}

package/dist/tools/feed.js

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import { textResult, toolAnnotations } from '@chrischall/mcp-utils';
+import { client } from '../client.js';
+export function registerFeedTools(server) {
+    server.registerTool('untappd_activity_feed', {
+        title: 'Get Untappd friend activity feed',
+        description: 'Get your Untappd friend activity feed — the recent check-ins from people you follow, newest first. Page ' +
+            'backwards with max_id (the pagination.max_id from a prior call). Read-only.',
+        annotations: toolAnnotations({ title: 'Get Untappd friend activity feed', readOnly: true, idempotent: false, openWorld: true }),
+        inputSchema: {
+            limit: z.number().int().min(1).max(50).optional().describe('Max check-ins (1–50, default 25)'),
+            max_id: z.number().int().positive().optional().describe('Return check-ins older than this id (for paging)'),
+        },
+    }, async ({ limit, max_id }) => {
+        const data = await client.get('/checkin/recent', { limit, max_id });
+        return textResult(data);
+    });
+    server.registerTool('untappd_checkin_info', {
+        title: 'Get Untappd check-in detail',
+        description: 'Get full detail for a single check-in by its id: the beer, rating, comment, photos, venue, badges earned, ' +
+            'toasts, and comments. Get a check-in id from a feed or user-checkins result. Read-only.',
+        annotations: toolAnnotations({ title: 'Get Untappd check-in detail', readOnly: true, idempotent: true, openWorld: true }),
+        inputSchema: {
+            checkin_id: z.number().int().positive().describe('Untappd check-in id'),
+        },
+    }, async ({ checkin_id }) => {
+        const data = await client.get(`/checkin/view/${checkin_id}`);
+        return textResult(data);
+    });
+}

package/dist/tools/user.js

@@ -0,0 +1,108 @@
+import { z } from 'zod';
+import { textResult, toolAnnotations, createHelpfulError } from '@chrischall/mcp-utils';
+import { client } from '../client.js';
+const UsernameArg = z
+    .string()
+    .min(1)
+    .optional()
+    .describe('Untappd username. Omit to use your own configured account (UNTAPPD_USERNAME).');
+/** Resolve the target username: explicit arg, else the configured login name. */
+function resolveUser(username) {
+    const u = username ?? client.loginName;
+    if (!u) {
+        throw createHelpfulError('No username given and no configured account to fall back to.', {
+            hint: 'Pass `username`, or set UNTAPPD_USERNAME so user tools default to your own account.',
+        });
+    }
+    return encodeURIComponent(u);
+}
+export function registerUserTools(server) {
+    server.registerTool('untappd_user_info', {
+        title: 'Get Untappd user profile',
+        description: "Get an Untappd user's profile: bio, location, total check-ins, distinct beers, badges, and stats. " +
+            'Omit username for your own account. Read-only.',
+        annotations: toolAnnotations({ title: 'Get Untappd user profile', readOnly: true, idempotent: true, openWorld: true }),
+        inputSchema: {
+            username: UsernameArg,
+            compact: z.boolean().optional().describe('Return a slimmer record without embedded lists (default false)'),
+        },
+    }, async ({ username, compact }) => {
+        const data = await client.get(`/user/info/${resolveUser(username)}`, { compact: compact ? 'true' : undefined });
+        return textResult(data);
+    });
+    server.registerTool('untappd_user_checkins', {
+        title: 'Get Untappd user check-ins',
+        description: "Get a user's recent check-ins (most recent first): the beer, rating, comment, venue, and toasts/comments. " +
+            'Page backwards with max_id (the pagination.max_id from a prior call). Omit username for your own. Read-only.',
+        annotations: toolAnnotations({ title: 'Get Untappd user check-ins', readOnly: true, idempotent: true, openWorld: true }),
+        inputSchema: {
+            username: UsernameArg,
+            limit: z.number().int().min(1).max(50).optional().describe('Max check-ins (1–50, default 25)'),
+            max_id: z.number().int().positive().optional().describe('Return check-ins older than this id (for paging)'),
+        },
+    }, async ({ username, limit, max_id }) => {
+        const data = await client.get(`/user/checkins/${resolveUser(username)}`, { limit, max_id });
+        return textResult(data);
+    });
+    server.registerTool('untappd_user_wishlist', {
+        title: 'Get Untappd user wishlist',
+        description: "Get the beers on a user's wishlist. Supports sorting and paging. Omit username for your own account. Read-only.",
+        annotations: toolAnnotations({ title: 'Get Untappd user wishlist', readOnly: true, idempotent: true, openWorld: true }),
+        inputSchema: {
+            username: UsernameArg,
+            limit: z.number().int().min(1).max(50).optional().describe('Max beers (1–50, default 25)'),
+            offset: z.number().int().min(0).optional().describe('Result offset for paging (default 0)'),
+            sort: z
+                .enum(['date', 'name', 'brewery', 'style', 'rating', 'abv'])
+                .optional()
+                .describe('Sort order (default date added, newest first)'),
+        },
+    }, async ({ username, limit, offset, sort }) => {
+        const data = await client.get(`/user/wishlist/${resolveUser(username)}`, { limit, offset, sort });
+        return textResult(data);
+    });
+    server.registerTool('untappd_user_beers', {
+        title: 'Get Untappd distinct beers',
+        description: "Get the distinct (unique) beers a user has ever checked in, with their rating and check-in count per beer. " +
+            'Supports sorting and paging. Omit username for your own account. Read-only.',
+        annotations: toolAnnotations({ title: 'Get Untappd distinct beers', readOnly: true, idempotent: true, openWorld: true }),
+        inputSchema: {
+            username: UsernameArg,
+            limit: z.number().int().min(1).max(50).optional().describe('Max beers (1–50, default 25)'),
+            offset: z.number().int().min(0).optional().describe('Result offset for paging (default 0)'),
+            sort: z
+                .enum(['date', 'checkin', 'highest_rated', 'lowest_rated', 'name', 'this_month', 'highest_abv'])
+                .optional()
+                .describe('Sort order (default date, most recent first)'),
+        },
+    }, async ({ username, limit, offset, sort }) => {
+        const data = await client.get(`/user/beers/${resolveUser(username)}`, { limit, offset, sort });
+        return textResult(data);
+    });
+    server.registerTool('untappd_user_badges', {
+        title: 'Get Untappd user badges',
+        description: "Get the badges a user has earned, most recent first. Omit username for your own account. Read-only.",
+        annotations: toolAnnotations({ title: 'Get Untappd user badges', readOnly: true, idempotent: true, openWorld: true }),
+        inputSchema: {
+            username: UsernameArg,
+            limit: z.number().int().min(1).max(50).optional().describe('Max badges (1–50, default 25)'),
+            offset: z.number().int().min(0).optional().describe('Result offset for paging (default 0)'),
+        },
+    }, async ({ username, limit, offset }) => {
+        const data = await client.get(`/user/badges/${resolveUser(username)}`, { limit, offset });
+        return textResult(data);
+    });
+    server.registerTool('untappd_user_friends', {
+        title: 'Get Untappd user friends',
+        description: "Get a user's friend list. Omit username for your own account. Read-only.",
+        annotations: toolAnnotations({ title: 'Get Untappd user friends', readOnly: true, idempotent: true, openWorld: true }),
+        inputSchema: {
+            username: UsernameArg,
+            limit: z.number().int().min(1).max(50).optional().describe('Max friends (1–50, default 25)'),
+            offset: z.number().int().min(0).optional().describe('Result offset for paging (default 0)'),
+        },
+    }, async ({ username, limit, offset }) => {
+        const data = await client.get(`/user/friends/${resolveUser(username)}`, { limit, offset });
+        return textResult(data);
+    });
+}

package/dist/tools/utilities.js

@@ -0,0 +1,27 @@
+import { textResult, toolAnnotations } from '@chrischall/mcp-utils';
+import { client } from '../client.js';
+export function registerUtilityTools(server) {
+    server.registerTool('untappd_healthcheck', {
+        title: 'Untappd healthcheck',
+        description: 'Verify Untappd connectivity and that credentials are configured and can log in. Performs a lightweight ' +
+            'authenticated request (your recent feed) and reports whether it succeeded. Read-only.',
+        annotations: toolAnnotations({ title: 'Untappd healthcheck', readOnly: true, idempotent: true, openWorld: true }),
+        inputSchema: {},
+    }, async () => {
+        if (!client.configured) {
+            return textResult({
+                ok: false,
+                configured: false,
+                note: 'Untappd credentials are not set. Configure UNTAPPD_USERNAME, UNTAPPD_PASSWORD, UNTAPPD_CLIENT_ID, and UNTAPPD_CLIENT_SECRET.',
+            });
+        }
+        const feed = await client.get('/checkin/recent', { limit: 1 });
+        return textResult({
+            ok: true,
+            configured: true,
+            account: client.loginName,
+            feed_reachable: feed?.checkins !== undefined,
+            note: 'Logged in to Untappd and fetched the friend feed successfully.',
+        });
+    });
+}