untappd-mcp 1.8.7 → 1.9.0

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": "1.8.7"
+    "version": "1.9.0"
   },
   "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": "1.8.7",
+      "version": "1.9.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "untappd-mcp",
   "displayName": "Untappd",
-  "version": "1.8.7",
+  "version": "1.9.0",
   "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

@@ -26,8 +26,9 @@ it goes stale.
 
 | Variable | Required | Description |
 | --- | --- | --- |
-| `UNTAPPD_USERNAME` | yes | Your Untappd username or login email. |
-| `UNTAPPD_PASSWORD` | yes | Your Untappd password (used only for the xauth login). |
+| `UNTAPPD_ACCESS_TOKEN` | no | An access token you already hold. Supply this and **no password is needed** — the xauth login is skipped entirely. |
+| `UNTAPPD_USERNAME` | if no token | Your Untappd username or login email. |
+| `UNTAPPD_PASSWORD` | if no token | Your Untappd password (used only for the xauth login that mints a token). |
 | `UNTAPPD_CLIENT_ID` | yes | The Untappd mobile app client id (see below). |
 | `UNTAPPD_CLIENT_SECRET` | yes | The Untappd mobile app client secret. |
 | `UNTAPPD_DEVICE_ID` | no | Stable device UUID the token is keyed to (a default is provided). |

package/dist/bundle.js

@@ -31000,53 +31000,6 @@ var StdioServerTransport = class {
   }
 };
 
-// node_modules/@chrischall/mcp-utils/dist/server/index.js
-async function createMcpServer(opts) {
-  const server = new McpServer({ name: opts.name, version: opts.version });
-  if (opts.banner !== void 0) {
-    console.error(opts.banner);
-  }
-  const deps = opts.deps;
-  for (const register of opts.tools) {
-    await register(server, deps);
-  }
-  return server;
-}
-function withGracefulShutdown(server, opts = {}) {
-  const shouldExit = opts.exit ?? true;
-  let shuttingDown = false;
-  const handler = (signal) => {
-    if (shuttingDown)
-      return;
-    shuttingDown = true;
-    void (async () => {
-      try {
-        if (opts.onSignal)
-          await opts.onSignal(signal);
-        await server.close();
-      } catch (err) {
-        console.error(`[mcp-utils] error during graceful shutdown on ${signal}: ${err instanceof Error ? err.message : String(err)}`);
-      } finally {
-        if (shouldExit)
-          process.exit(0);
-      }
-    })();
-  };
-  process.on("SIGINT", () => handler("SIGINT"));
-  process.on("SIGTERM", () => handler("SIGTERM"));
-}
-async function runMcp(opts) {
-  const server = await createMcpServer(opts);
-  const shutdown = opts.shutdown ?? true;
-  if (shutdown !== false) {
-    withGracefulShutdown(server, shutdown === true ? {} : shutdown);
-  }
-  const spec = opts.transport ?? "stdio";
-  const transport = spec === "stdio" ? new StdioServerTransport() : spec;
-  await server.connect(transport);
-  return server;
-}
-
 // node_modules/@chrischall/mcp-utils/dist/errors/index.js
 var DEFAULT_ERROR_MESSAGE_MAX = 500;
 var McpToolError = class extends Error {
@@ -31133,6 +31086,81 @@ function textResult(data) {
     content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
   };
 }
+function errorResult(message) {
+  return {
+    content: [{ type: "text", text: redactSecrets(message) }],
+    isError: true
+  };
+}
+
+// node_modules/@chrischall/mcp-utils/dist/server/index.js
+function hintResultOrRethrow(err) {
+  if (err instanceof McpToolError && err.hint) {
+    return errorResult(`${err.message}
+
+Hint: ${err.hint}`);
+  }
+  throw err;
+}
+function surfaceToolHints(server) {
+  const register = server.registerTool.bind(server);
+  server.registerTool = (name, config2, cb) => register(name, config2, (...args) => {
+    let result;
+    try {
+      result = cb(...args);
+    } catch (err) {
+      return hintResultOrRethrow(err);
+    }
+    return result instanceof Promise ? result.catch(hintResultOrRethrow) : result;
+  });
+}
+async function createMcpServer(opts) {
+  const server = new McpServer({ name: opts.name, version: opts.version });
+  if (opts.surfaceHints !== false)
+    surfaceToolHints(server);
+  if (opts.banner !== void 0) {
+    console.error(opts.banner);
+  }
+  const deps = opts.deps;
+  for (const register of opts.tools) {
+    await register(server, deps);
+  }
+  return server;
+}
+function withGracefulShutdown(server, opts = {}) {
+  const shouldExit = opts.exit ?? true;
+  let shuttingDown = false;
+  const handler = (signal) => {
+    if (shuttingDown)
+      return;
+    shuttingDown = true;
+    void (async () => {
+      try {
+        if (opts.onSignal)
+          await opts.onSignal(signal);
+        await server.close();
+      } catch (err) {
+        console.error(`[mcp-utils] error during graceful shutdown on ${signal}: ${err instanceof Error ? err.message : String(err)}`);
+      } finally {
+        if (shouldExit)
+          process.exit(0);
+      }
+    })();
+  };
+  process.on("SIGINT", () => handler("SIGINT"));
+  process.on("SIGTERM", () => handler("SIGTERM"));
+}
+async function runMcp(opts) {
+  const server = await createMcpServer(opts);
+  const shutdown = opts.shutdown ?? true;
+  if (shutdown !== false) {
+    withGracefulShutdown(server, shutdown === true ? {} : shutdown);
+  }
+  const spec = opts.transport ?? "stdio";
+  const transport = spec === "stdio" ? new StdioServerTransport() : spec;
+  await server.connect(transport);
+  return server;
+}
 
 // node_modules/@chrischall/mcp-utils/dist/config/index.js
 var PLACEHOLDER_RE = /^\$\{[^}]*\}$/;
@@ -31232,7 +31260,7 @@ function toolAnnotations(opts = {}) {
 }
 
 // src/version.ts
-var VERSION = "1.8.7";
+var VERSION = "1.9.0";
 
 // src/client.ts
 import { dirname, join } from "path";
@@ -31324,11 +31352,10 @@ async function xauthLogin(creds, opts = {}) {
 }
 function missingCredsError() {
   const missing = ["UNTAPPD_USERNAME", "UNTAPPD_PASSWORD", "UNTAPPD_CLIENT_ID", "UNTAPPD_CLIENT_SECRET"].filter((k) => !readEnvVar(k));
+  const remedy = "Either set UNTAPPD_ACCESS_TOKEN (an access token you already hold \u2014 no password needed), or set UNTAPPD_USERNAME and UNTAPPD_PASSWORD to log in for one. Either way UNTAPPD_CLIENT_ID and UNTAPPD_CLIENT_SECRET (the Untappd mobile app client credentials) are required. See the README.";
   return createHelpfulError(
-    `Untappd credentials are not configured \u2014 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."
-    }
+    `Untappd credentials are not configured \u2014 missing ${missing.join(", ") || "credentials"}. ${remedy}`,
+    { hint: remedy }
   );
 }
 var UntappdClient = class {
@@ -31343,6 +31370,7 @@ var UntappdClient = class {
   userAgent = readEnvVar("UNTAPPD_USER_AGENT") ?? DEFAULTS.userAgent;
   token;
   loginInFlight = null;
+  tokenIsSupplied;
   /**
    * 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.
@@ -31350,7 +31378,8 @@ var UntappdClient = class {
    */
   constructor(opts = {}) {
     this.fetchImpl = opts.fetchImpl ?? fetch;
-    this.token = opts.token ?? null;
+    this.token = opts.token ?? readEnvVar("UNTAPPD_ACCESS_TOKEN") ?? null;
+    this.tokenIsSupplied = this.token !== null;
     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;
@@ -31413,6 +31442,7 @@ var UntappdClient = class {
       userAgent: this.userAgent
     });
     this.token = token;
+    this.tokenIsSupplied = false;
     return token;
   }
   async parseJson(res, method, path) {
@@ -31462,6 +31492,14 @@ var UntappdClient = class {
     }
     const res = await this.send(method, `${BASE_URL}${path}${qs}`, { headers, body });
     if (res.status === 401 && !isRetry) {
+      if (this.tokenIsSupplied && !(this.username && this.password)) {
+        throw createHelpfulError(
+          "Untappd rejected the access token (401) \u2014 UNTAPPD_ACCESS_TOKEN has expired or been revoked. Supply a fresh token, or set UNTAPPD_USERNAME and UNTAPPD_PASSWORD so a new one can be minted automatically.",
+          {
+            hint: "The token is stale, not missing. A pre-seeded token cannot be refreshed without a login."
+          }
+        );
+      }
       this.token = null;
       return this.request(method, path, opts, true);
     }

package/dist/client.js

@@ -112,10 +112,13 @@ export async function xauthLogin(creds, opts = {}) {
 }
 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.',
-    });
+    // Both paths in the MESSAGE, not only `hint`: MCP serialization surfaces the
+    // message and drops the hint, so a token path mentioned only there is
+    // invisible exactly when someone is deciding what to configure.
+    const remedy = 'Either set UNTAPPD_ACCESS_TOKEN (an access token you already hold — no password needed), or set ' +
+        'UNTAPPD_USERNAME and UNTAPPD_PASSWORD to log in for one. Either way UNTAPPD_CLIENT_ID and ' +
+        'UNTAPPD_CLIENT_SECRET (the Untappd mobile app client credentials) are required. See the README.';
+    return createHelpfulError(`Untappd credentials are not configured — missing ${missing.join(', ') || 'credentials'}. ${remedy}`, { hint: remedy });
 }
 export class UntappdClient {
     fetchImpl;
@@ -129,6 +132,7 @@ export class UntappdClient {
     userAgent = readEnvVar('UNTAPPD_USER_AGENT') ?? DEFAULTS.userAgent;
     token;
     loginInFlight = null;
+    tokenIsSupplied;
     /**
      * 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.
@@ -136,7 +140,15 @@ export class UntappdClient {
      */
     constructor(opts = {}) {
         this.fetchImpl = opts.fetchImpl ?? fetch;
-        this.token = opts.token ?? null;
+        // Path 1 of the ladder: a token the consumer already holds. Reachable from
+        // the environment, not just from code — otherwise the only configuration a
+        // deployment can express is "hand over the password", which is the shape
+        // this exists to avoid.
+        this.token = opts.token ?? readEnvVar('UNTAPPD_ACCESS_TOKEN') ?? null;
+        // Whether that token was GIVEN to us rather than minted by a login. It
+        // decides what a later 401 means: a minted token can simply be re-minted,
+        // a supplied one can only be replaced by whoever supplied it.
+        this.tokenIsSupplied = this.token !== null;
         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;
@@ -203,6 +215,7 @@ export class UntappdClient {
             userAgent: this.userAgent,
         });
         this.token = token;
+        this.tokenIsSupplied = false;
         return token;
     }
     async parseJson(res, method, path) {
@@ -259,8 +272,19 @@ export class UntappdClient {
             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.
+        // A 401 means the token went stale. Re-minting one needs a login, and a
+        // deployment that SUPPLIED the token may have no username/password to log
+        // in with — that fell through to `missingCredsError()` and told the
+        // operator to set the very variable they had set (CLAUDE.md, "a pre-seeded
+        // token is one-way"). Name what actually happened instead, and don't spend
+        // a second request discovering there is nothing to retry with.
         if (res.status === 401 && !isRetry) {
+            if (this.tokenIsSupplied && !(this.username && this.password)) {
+                throw createHelpfulError('Untappd rejected the access token (401) — UNTAPPD_ACCESS_TOKEN has expired or been revoked. ' +
+                    'Supply a fresh token, or set UNTAPPD_USERNAME and UNTAPPD_PASSWORD so a new one can be minted automatically.', {
+                    hint: 'The token is stale, not missing. A pre-seeded token cannot be refreshed without a login.',
+                });
+            }
             this.token = null;
             return this.request(method, path, opts, true);
         }

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

package/mint.yaml

@@ -0,0 +1,68 @@
+version: 1
+name: Untappd
+slug: untappd
+summary: >-
+  Search Untappd beers, breweries, and venues; read profiles, check-ins,
+  wishlists, and your friend feed; and post check-ins, toasts, and comments
+  to your account
+env:
+  - name: UNTAPPD_USERNAME
+    required: true
+    help: >-
+      Your Untappd username or login email.
+  - name: UNTAPPD_PASSWORD
+    secret: true
+    required: true
+    help: >-
+      Your Untappd account password (used only for xauth login).
+  - name: UNTAPPD_CLIENT_ID
+    secret: true
+    required: true
+    help: >-
+      Untappd mobile app client id (obtained by intercepting the app; see
+      README).
+  - name: UNTAPPD_CLIENT_SECRET
+    secret: true
+    required: true
+    help: >-
+      Untappd mobile app client secret.
+  - name: UNTAPPD_CACHE_DB
+    required: false
+    help: >-
+      Path to the on-disk check-in cache (defaults to
+      ~/.untappd-mcp/checkins.db). Relates to state.dataDir below.
+  - name: UNTAPPD_DEVICE_ID
+    required: false
+    help: >-
+      A stable UUID that Untappd keys the returned access token to. Any stable
+      value works; set it to pin your own instead of the built-in default.
+  - name: UNTAPPD_USER_AGENT
+    required: false
+    help: >-
+      Overrides the User-Agent sent upstream. Leave unset unless the service
+      requires a specific one.
+  - name: UNTAPPD_UTV
+    required: false
+    help: >-
+      Overrides the Untappd app version string, which is sent on every request
+      (not only at login). Leave unset unless a version bump is needed to keep
+      the API accepting requests.
+state:
+  dataDir: true
+  reason: >-
+    Persists the check-in cache SQLite database (UNTAPPD_CACHE_DB, default
+    ~/.untappd-mcp/checkins.db) under $HOME. Without it every cold start begins
+    with an empty cache and has to re-sync from the API. The access token is
+    NOT persisted — it is held in memory only — so this is about avoiding
+    repeated syncs, not about surviving authentication.
+egress:
+  allow:
+    # Only hosts the SERVER process actually fetches. Hosts that appear
+    # solely in a URL this server BUILDS and returns are excluded.
+    - api.untappd.com
+    #
+    # NOTE — this server also reaches at least one host determined at
+    # RUNTIME, which cannot appear as a literal here:
+    #   - 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "untappd-mcp",
-  "version": "1.8.7",
+  "version": "1.9.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>",
@@ -29,18 +29,20 @@
     ".claude-plugin",
     "skills/",
     ".mcp.json",
-    "server.json"
+    "server.json",
+    "mint.yaml"
   ],
   "scripts": {
     "build": "tsc && npm run bundle",
     "bundle": "esbuild src/index.ts --bundle --platform=node --format=esm --external:dotenv --outfile=dist/bundle.js",
     "dev": "node dist/index.js",
-    "test": "vitest run",
+    "test": "npm run typecheck && vitest run",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage"
+    "test:coverage": "npm run typecheck && vitest run --coverage",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.14.0",
+    "@chrischall/mcp-utils": "^0.15.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "ai": "^7.0.19",
     "dotenv": "^17.4.0",

package/server.json

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