untappd-mcp 1.0.0 → 1.2.0

package/dist/client.js

@@ -1,11 +1,15 @@
 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 });
+// Load .env for local (Node) 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. Guard on `import.meta.url`:
+// in a non-Node runtime (Cloudflare Workers) it is undefined and there is no
+// local .env — secrets arrive via the platform's env bindings instead.
+if (import.meta.url) {
+    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;
@@ -25,15 +29,87 @@ const DEFAULTS = {
     // 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 };
+// One HTTP attempt with a hard timeout, shared by the instance `send()` method
+// and the standalone `xauthLogin()` helper below. Network/timeout failures
+// become an UnreachableError; HTTP status handling is left to the caller.
+async function sendRequest(fetchImpl, method, url, init) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    try {
+        return await fetchImpl(url, {
+            method,
+            headers: init.headers,
+            ...(init.body !== undefined ? { body: init.body } : {}),
+            signal: controller.signal,
+        });
+    }
+    catch {
+        throw new UnreachableError(SERVICE);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function xauthHeaders(userAgent) {
+    return {
+        'User-Agent': userAgent,
+        Accept: 'application/json',
+        'x-untappd-app': 'ios',
+        'x-untappd-app-version': DEFAULTS.appVersion,
+    };
+}
+/**
+ * Performs the one-shot Untappd xauth login POST (username/password →
+ * access token). Standalone so it can be reused both by `UntappdClient`'s
+ * own on-demand login and by the Cloudflare-connector login flow
+ * (`src/untappd-auth.ts`), which authenticates a user before a client even
+ * exists — without duplicating the request/parsing logic.
+ */
+export async function xauthLogin(creds, opts = {}) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const utv = opts.utv ?? readEnvVar('UNTAPPD_UTV') ?? DEFAULTS.utv;
+    const deviceUdid = opts.deviceUdid ?? readEnvVar('UNTAPPD_DEVICE_ID') ?? DEFAULTS.deviceUdid;
+    const userAgent = opts.userAgent ?? readEnvVar('UNTAPPD_USER_AGENT') ?? DEFAULTS.userAgent;
+    const qs = buildQueryString({ client_id: creds.clientId, client_secret: creds.clientSecret, utv });
+    const form = new URLSearchParams({
+        user_name: creds.username,
+        user_password: creds.password,
+        device_udid: deviceUdid,
+        device_name: DEFAULTS.deviceName,
+        device_version: DEFAULTS.deviceVersion,
+        device_platform: DEFAULTS.devicePlatform,
+        app_version: DEFAULTS.appVersion,
+        multi_account: 'true',
+    });
+    const res = await sendRequest(fetchImpl, 'POST', `${BASE_URL}/xauth${qs}`, {
+        headers: { ...xauthHeaders(userAgent), '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.');
     }
-    return null;
+    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.',
+        });
+    }
+    return token;
 }
 function missingCredsError() {
     const missing = ['UNTAPPD_USERNAME', 'UNTAPPD_PASSWORD', 'UNTAPPD_CLIENT_ID', 'UNTAPPD_CLIENT_SECRET'].filter((k) => !readEnvVar(k));
@@ -44,8 +120,11 @@ function missingCredsError() {
 }
 export class UntappdClient {
     fetchImpl;
-    creds;
-    configError;
+    clientId;
+    clientSecret;
+    username;
+    password;
+    _loginName;
     utv = readEnvVar('UNTAPPD_UTV') ?? DEFAULTS.utv;
     deviceUdid = readEnvVar('UNTAPPD_DEVICE_ID') ?? DEFAULTS.deviceUdid;
     userAgent = readEnvVar('UNTAPPD_USER_AGENT') ?? DEFAULTS.userAgent;
@@ -59,28 +138,34 @@ export class UntappdClient {
     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();
-        }
+        this.clientId = opts.clientId ?? readEnvVar('UNTAPPD_CLIENT_ID') ?? null;
+        this.clientSecret = opts.clientSecret ?? readEnvVar('UNTAPPD_CLIENT_SECRET') ?? null;
+        this.username = opts.username ?? readEnvVar('UNTAPPD_USERNAME') ?? null;
+        this.password = opts.password ?? readEnvVar('UNTAPPD_PASSWORD') ?? null;
+        this._loginName = opts.loginName ?? this.username;
     }
-    /** Whether credentials are configured (used by the healthcheck tool). */
+    /** True when enough is configured to make authenticated calls. */
     get configured() {
-        return this.configError === null;
+        // A pre-seeded token needs only app creds (for writes); otherwise a full login is required.
+        if (this.token)
+            return Boolean(this.clientId && this.clientSecret);
+        return Boolean(this.clientId && this.clientSecret && this.username && this.password);
     }
     /** The configured login name — the default `username` for user-scoped tools. */
     get loginName() {
-        return this.creds?.username ?? null;
+        return this._loginName;
+    }
+    requireAppCreds() {
+        if (!this.clientId || !this.clientSecret) {
+            throw missingCredsError();
+        }
+        return { clientId: this.clientId, clientSecret: this.clientSecret };
     }
-    requireCreds() {
-        if (this.configError)
-            throw this.configError;
-        return this.creds;
+    requireLogin() {
+        const app = this.requireAppCreds();
+        if (!this.username || !this.password)
+            throw missingCredsError();
+        return { ...app, username: this.username, password: this.password };
     }
     baseHeaders() {
         return {
@@ -90,25 +175,10 @@ export class UntappdClient {
             '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.
+    // One HTTP attempt with a hard timeout, delegating to the module-level
+    // helper shared with `xauthLogin()`.
     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);
-        }
+        return sendRequest(this.fetchImpl, method, url, init);
     }
     /**
      * Obtain an access token, logging in via xauth (username/password) on demand.
@@ -126,46 +196,13 @@ export class UntappdClient {
         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 c = this.requireLogin();
+        const token = await xauthLogin(c, {
+            fetchImpl: this.fetchImpl,
+            utv: this.utv,
+            deviceUdid: this.deviceUdid,
+            userAgent: this.userAgent,
         });
-        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;
     }
@@ -204,7 +241,7 @@ export class UntappdClient {
         // requests the app itself makes.
         let query;
         if (opts.auth === 'bearer') {
-            const c = this.requireCreds();
+            const c = this.requireAppCreds();
             headers['Authorization'] = `Bearer ${token}`;
             query = { ...opts.query, client_id: c.clientId, client_secret: c.clientSecret, utv: this.utv };
         }
@@ -255,10 +292,3 @@ export class UntappdClient {
         }
     }
 }
-/**
- * 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/compact.js

@@ -0,0 +1,90 @@
+// Opt-in slim projections for the fat reverse-engineered list responses. A
+// single check-in record is ~5 KB and a beer search item ~1.2 KB, so a page of
+// 25 is a lot of agent context. These project each item down to the fields an
+// agent usually needs, keyed off DOCUMENTED fields only, and derive nothing it
+// can't. Every projector degrades safely: if the expected `<container>.items`
+// array isn't present (the undocumented API drifted), it warns to stderr and
+// returns the RAW response rather than an empty/wrong projection.
+function asDict(v) {
+    return v && typeof v === 'object' ? v : undefined;
+}
+function count(v) {
+    const d = asDict(v);
+    if (!d)
+        return undefined;
+    return (d.count ?? d.total_count);
+}
+/** Slim a single check-in record. */
+export function compactCheckin(item) {
+    const c = asDict(item) ?? {};
+    const beer = asDict(c.beer);
+    const brewery = asDict(c.brewery);
+    const venue = asDict(c.venue);
+    const user = asDict(c.user);
+    return {
+        checkin_id: c.checkin_id,
+        created_at: c.created_at,
+        user: user?.user_name,
+        rating: c.rating_score,
+        comment: c.checkin_comment || undefined,
+        beer: beer && { bid: beer.bid, name: beer.beer_name, style: beer.beer_style, abv: beer.beer_abv },
+        brewery: brewery?.brewery_name,
+        venue: venue?.venue_name || undefined,
+        toasts: count(c.toasts),
+        comments: count(c.comments),
+        has_photo: (count(c.media) ?? 0) > 0,
+    };
+}
+/** The beer fields common to every beer-list item (search, wishlist, distinct). */
+function beerCore(item) {
+    const beer = asDict(item.beer) ?? {};
+    const brewery = asDict(item.brewery);
+    return {
+        bid: beer.bid,
+        name: beer.beer_name,
+        style: beer.beer_style,
+        abv: beer.beer_abv,
+        ibu: beer.beer_ibu,
+        brewery: brewery?.brewery_name,
+    };
+}
+/** Slim a single beer-search result item. */
+export function compactBeerResult(item) {
+    const i = asDict(item) ?? {};
+    return { ...beerCore(i), checkin_count: i.checkin_count, have_had: i.have_had };
+}
+/** Slim a single wishlist item (adds when it was wishlisted). */
+export function compactWishlistBeer(item) {
+    const i = asDict(item) ?? {};
+    return { ...beerCore(i), added_at: i.created_at };
+}
+/** Slim a single distinct-beers (user/beers) item — your count, ratings, last had. */
+export function compactUserBeer(item) {
+    const i = asDict(item) ?? {};
+    return {
+        ...beerCore(i),
+        your_count: i.count,
+        your_rating: i.user_auth_rating_score || undefined,
+        global_rating: i.rating_score || undefined,
+        last_had: i.recent_created_at,
+    };
+}
+/**
+ * Project `<container>.items` in a response with `mapFn`, preserving the rest of
+ * the container (pagination etc.). Drift-safe: returns the raw response
+ * unchanged (with a stderr warning) when the array isn't where expected.
+ */
+export function projectItems(resp, container, mapFn) {
+    const r = asDict(resp);
+    const box = asDict(r?.[container]);
+    const items = box?.items;
+    if (!r || !box || !Array.isArray(items)) {
+        process.stderr.write(`[untappd-mcp] compact: expected ${container}.items array; returning raw response\n`);
+        return resp;
+    }
+    return { ...r, [container]: { ...box, items: items.map(mapFn) } };
+}
+export const compactCheckins = (resp) => projectItems(resp, 'checkins', compactCheckin);
+export const compactBeerSearch = (resp) => projectItems(resp, 'beers', compactBeerResult);
+export const compactWishlist = (resp) => projectItems(resp, 'beers', compactWishlistBeer);
+export const compactUserBeers = (resp) => projectItems(resp, 'beers', compactUserBeer);

package/dist/index.js

@@ -1,33 +1,37 @@
 #!/usr/bin/env node
 import { runMcp } from '@chrischall/mcp-utils';
 import { VERSION } from './version.js';
+import { UntappdClient } from './client.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 { registerResolveTools } from './tools/resolve.js';
 import { registerDiscoverTools } from './tools/discover.js';
+import { registerFriendActionTools } from './tools/friends.js';
 import { registerWishlistTools } from './tools/wishlist.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.
+// Build the env-based client once and inject it into each registrar. The
+// constructor defers its config error, so the server still boots (and answers
+// the host's install-time tools/list probe) when credentials are absent.
+const client = new UntappdClient();
 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,
-        registerDiscoverTools,
-        registerWishlistTools,
-        registerCheckinTools,
-        registerUtilityTools,
+        (s) => registerBeerTools(s, client),
+        (s) => registerBreweryTools(s, client),
+        (s) => registerVenueTools(s, client),
+        (s) => registerUserTools(s, client),
+        (s) => registerFeedTools(s, client),
+        (s) => registerResolveTools(s, client),
+        (s) => registerDiscoverTools(s, client),
+        (s) => registerFriendActionTools(s, client),
+        (s) => registerWishlistTools(s, client),
+        (s) => registerCheckinTools(s, client),
+        (s) => registerUtilityTools(s, client),
     ],
 });

package/dist/tools/beer.js

@@ -1,8 +1,12 @@
 import { z } from 'zod';
 import { textResult, toolAnnotations } from '@chrischall/mcp-utils';
-import { client } from '../client.js';
+import { compactBeerSearch, compactCheckins } from '../compact.js';
 const BidSchema = z.number().int().positive().describe('Untappd beer id (bid)');
-export function registerBeerTools(server) {
+const CompactCheckins = z
+    .boolean()
+    .optional()
+    .describe('Project each check-in to a slim summary (id, user, beer, rating, comment, venue, toast/comment counts) to save context (default false)');
+export function registerBeerTools(server, client) {
     server.registerTool('untappd_search_beer', {
         title: 'Search Untappd beers',
         description: 'Search Untappd for beers by name (optionally "Brewery Beer"). Returns ranked matches with their ' +
@@ -17,10 +21,14 @@ export function registerBeerTools(server) {
                 .enum(['checkin', 'name', 'count'])
                 .optional()
                 .describe('Sort order: checkin (relevance, default), name, or count'),
+            compact: z
+                .boolean()
+                .optional()
+                .describe('Project each result to a slim summary (bid, name, brewery, style, abv, ibu, counts) to save context (default false)'),
         },
-    }, async ({ query, limit, offset, sort }) => {
+    }, async ({ query, limit, offset, sort, compact }) => {
         const data = await client.get('/search/beer', { q: query, limit, offset, sort });
-        return textResult(data);
+        return textResult(compact ? compactBeerSearch(data) : data);
     });
     server.registerTool('untappd_beer_info', {
         title: 'Get Untappd beer detail',
@@ -47,9 +55,10 @@ export function registerBeerTools(server) {
             bid: BidSchema,
             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)'),
+            compact: CompactCheckins,
         },
-    }, async ({ bid, limit, max_id }) => {
+    }, async ({ bid, limit, max_id, compact }) => {
         const data = await client.get(`/beer/checkins/${bid}`, { limit, max_id });
-        return textResult(data);
+        return textResult(compact ? compactCheckins(data) : data);
     });
 }

package/dist/tools/brewery.js

@@ -1,7 +1,6 @@
 import { z } from 'zod';
 import { textResult, toolAnnotations } from '@chrischall/mcp-utils';
-import { client } from '../client.js';
-export function registerBreweryTools(server) {
+export function registerBreweryTools(server, client) {
     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 ' +

package/dist/tools/checkin.js

@@ -2,7 +2,6 @@ import { existsSync } from 'node:fs';
 import { extname } from 'node:path';
 import { z } from 'zod';
 import { textResult, toolAnnotations, schemaConfirm, fileBlob, McpToolError, createHelpfulError, messageOf } from '@chrischall/mcp-utils';
-import { client } from '../client.js';
 const CheckinIdSchema = z.number().int().positive().describe('Untappd check-in id');
 // Keyed by the NORMALISED extension that photoExt() returns (jpeg → jpg), so
 // there is no dead `jpeg` entry.
@@ -23,7 +22,7 @@ function localTimezone() {
     const gmt_offset = -new Date().getTimezoneOffset() / 60;
     return { timezone, gmt_offset };
 }
-export function registerCheckinTools(server) {
+export function registerCheckinTools(server, client) {
     server.registerTool('untappd_toast', {
         title: 'Toast an Untappd check-in',
         description: "Toast (like) a check-in on YOUR account. This endpoint is a TOGGLE: calling it on a check-in you have " +

package/dist/tools/discover.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { textResult, toolAnnotations } from '@chrischall/mcp-utils';
-import { client } from '../client.js';
-export function registerDiscoverTools(server) {
+import { compactCheckins } from '../compact.js';
+export function registerDiscoverTools(server, client) {
     server.registerTool('untappd_trending', {
         title: 'Get trending beers',
         description: 'Get the beers trending on Untappd right now, split into macro (big/widely-available) and micro ' +
@@ -35,9 +35,13 @@ export function registerDiscoverTools(server) {
             lng: z.number().min(-180).max(180).describe('Longitude of the location'),
             limit: z.number().int().min(1).max(50).optional().describe('Max check-ins (1–50, default 25)'),
             radius: z.number().int().min(1).max(25).optional().describe('Search radius (default per Untappd)'),
+            compact: z
+                .boolean()
+                .optional()
+                .describe('Project each check-in to a slim summary to save context (default false)'),
         },
-    }, async ({ lat, lng, limit, radius }) => {
+    }, async ({ lat, lng, limit, radius, compact }) => {
         const data = await client.get('/thepub/local', { lat, lng, limit, radius });
-        return textResult(data);
+        return textResult(compact ? compactCheckins(data) : data);
     });
 }

package/dist/tools/feed.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { textResult, toolAnnotations } from '@chrischall/mcp-utils';
-import { client } from '../client.js';
-export function registerFeedTools(server) {
+import { compactCheckins } from '../compact.js';
+export function registerFeedTools(server, client) {
     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 ' +
@@ -10,10 +10,14 @@ export function registerFeedTools(server) {
         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)'),
+            compact: z
+                .boolean()
+                .optional()
+                .describe('Project each check-in to a slim summary to save context (default false)'),
         },
-    }, async ({ limit, max_id }) => {
+    }, async ({ limit, max_id, compact }) => {
         const data = await client.get('/checkin/recent', { limit, max_id });
-        return textResult(data);
+        return textResult(compact ? compactCheckins(data) : data);
     });
     server.registerTool('untappd_checkin_info', {
         title: 'Get Untappd check-in detail',

package/dist/tools/friends.js

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+import { textResult, toolAnnotations, schemaConfirm } from '@chrischall/mcp-utils';
+// The endpoint PATHS below are confirmed from the Untappd app's own JS bundle
+// (`friend/request`, `friend/accept`, `friend/reject`, `friend/remove`). The
+// HTTP method (POST) mirrors the other captured action-writes (toast/comment),
+// but — unlike the rest of this server's writes — these were NOT live-verified
+// against the API, because doing so would send real friend requests to / alter
+// real relationships with other people. They are confirm-gated so nothing fires
+// without an explicit confirm: true.
+const TargetUidSchema = z
+    .number()
+    .int()
+    .positive()
+    .describe('The target user id (uid) — from a user profile (response.user.uid) or a friends-list item');
+const ACTIONS = [
+    {
+        tool: 'untappd_add_friend',
+        path: 'request',
+        title: 'Send an Untappd friend request',
+        verb: 'send a friend request to',
+        detail: 'Sends a friend request to another user, who will be notified.',
+    },
+    {
+        tool: 'untappd_accept_friend',
+        path: 'accept',
+        title: 'Accept an Untappd friend request',
+        verb: 'accept the incoming friend request from',
+        detail: 'Accepts an incoming friend request (see untappd_pending_friends for pending uids).',
+    },
+    {
+        tool: 'untappd_reject_friend',
+        path: 'reject',
+        title: 'Reject an Untappd friend request',
+        verb: 'reject the incoming friend request from',
+        detail: 'Rejects/ignores an incoming friend request (see untappd_pending_friends for pending uids).',
+    },
+    {
+        tool: 'untappd_remove_friend',
+        path: 'remove',
+        title: 'Remove an Untappd friend',
+        verb: 'remove your friendship with',
+        detail: 'Removes an existing friend, or cancels a friend request you sent.',
+    },
+];
+export function registerFriendActionTools(server, client) {
+    for (const action of ACTIONS) {
+        server.registerTool(action.tool, {
+            title: action.title,
+            description: `${action.detail} Acts on YOUR account and affects a real relationship with another person. ` +
+                'Without confirm: true it returns a dry-run preview and makes NO network call; with confirm: true it ' +
+                'performs the action. Note: this endpoint path is taken from the Untappd app but is not otherwise ' +
+                'independently verified.',
+            annotations: toolAnnotations({ title: action.title, readOnly: false, idempotent: true, openWorld: true }),
+            inputSchema: {
+                target_uid: TargetUidSchema,
+                confirm: schemaConfirm,
+            },
+        }, async ({ target_uid, confirm }) => {
+            if (confirm !== true) {
+                return textResult({
+                    dryRun: true,
+                    action: action.path,
+                    target_uid,
+                    note: `Dry run — re-run with confirm: true to ${action.verb} user ${target_uid}.`,
+                });
+            }
+            const data = await client.write('POST', `/friend/${action.path}/${target_uid}`);
+            return textResult({ done: true, action: action.path, target_uid, result: data?.result });
+        });
+    }
+}