myhotlunchbox-mcp 0.2.1 → 0.4.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "MCP server for My Hot Lunchbox — order school lunches, manage students, and track payments via natural language",
-    "version": "0.2.1"
+    "version": "0.4.0"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "My Hot Lunchbox",
       "source": "./",
       "description": "MCP server for My Hot Lunchbox — school lunch calendar, ordering, and payments. Signs in server-side with the parent account credentials.",
-      "version": "0.2.1",
+      "version": "0.4.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "myhotlunchbox-mcp",
   "displayName": "My Hot Lunchbox",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "MCP server for My Hot Lunchbox — order school lunches, manage students, and track payments via natural language",
   "author": {
     "name": "Chris Hall",

package/README.md

@@ -38,10 +38,12 @@ still works; the configuration error surfaces on the first tool call.
 
 ## Tools
 
-34 tools, all prefixed `mhlb_`. All 20 read tools are verified live against a real parent account (`node scripts/verify-reads.mjs`); the 14 write tools are not — see below.
+35 tools, all prefixed `mhlb_`. All 20 read tools are verified live against a real parent account (`node scripts/verify-reads.mjs`); the 14 write tools are not — see below.
 
 **Account** — `mhlb_whoami`, `mhlb_session_reset`
 
+**Health** — `mhlb_healthcheck` (is this connector working? reports whether the credential resolved, whether My Hot Lunchbox accepted it, and what to fix — unlike `mhlb_whoami`, which throws instead of answering)
+
 **Students** — `mhlb_list_students`, `mhlb_get_student_form`,
 `mhlb_new_student_form`, `mhlb_create_student`, `mhlb_update_student`,
 `mhlb_delete_student`

package/dist/auth.js

@@ -1,6 +1,7 @@
 import { McpToolError, truncateErrorMessage } from '@chrischall/mcp-utils';
 import { TokenManager } from '@chrischall/mcp-utils/session';
 import { API_PREFIX, OAUTH_SCOPE } from './config.js';
+import { createTokenCache, reportCacheWriteFailure } from './token-cache.js';
 /** Fallback lifetime when the server omits `expires_in`. */
 const DEFAULT_TOKEN_LIFETIME_S = 3600;
 /**
@@ -132,13 +133,24 @@ export class MhlbAuth {
         if (this.loginInFlight)
             return this.loginInFlight;
         this.loginInFlight = (async () => {
-            const body = await this.passwordLogin();
             const manager = new TokenManager({
-                initial: {
-                    accessToken: this.assertAccessToken(body),
-                    refreshToken: body.refresh_token,
-                    expiresAt: MhlbAuth.expiryOf(body),
+                // The FUNCTION form, so the cache is consulted before the password
+                // grant runs at all — the eager object form skips persistence, which
+                // would mean a cache that is written and never read.
+                initial: async () => {
+                    const body = await this.passwordLogin();
+                    return {
+                        accessToken: this.assertAccessToken(body),
+                        refreshToken: body.refresh_token,
+                        expiresAt: MhlbAuth.expiryOf(body),
+                    };
                 },
+                persistence: createTokenCache() ?? undefined,
+                onPersistError: reportCacheWriteFailure,
+                // `refresh` below already recovers from a revoked refresh token by
+                // falling back to a full login, so the library's own re-mint-on-revoked
+                // recovery would only add a third attempt after both have failed.
+                isRefreshRevoked: () => false,
                 refresh: async (refreshToken) => {
                     let next;
                     try {

package/dist/bundle.js

@@ -2984,7 +2984,7 @@ var require_compile = __commonJS({
       const schOrFunc = root.refs[ref];
       if (schOrFunc)
         return schOrFunc;
-      let _sch = resolve2.call(this, root, ref);
+      let _sch = resolve3.call(this, root, ref);
       if (_sch === void 0) {
         const schema = (_a3 = root.localRefs) === null || _a3 === void 0 ? void 0 : _a3[ref];
         const { schemaId } = this.opts;
@@ -3011,7 +3011,7 @@ var require_compile = __commonJS({
     function sameSchemaEnv(s1, s2) {
       return s1.schema === s2.schema && s1.root === s2.root && s1.baseId === s2.baseId;
     }
-    function resolve2(root, ref) {
+    function resolve3(root, ref) {
       let sch;
       while (typeof (sch = this.refs[ref]) == "string")
         ref = sch;
@@ -3836,7 +3836,7 @@ var require_fast_uri = __commonJS({
       }
       return uri;
     }
-    function resolve2(baseURI, relativeURI, options) {
+    function resolve3(baseURI, relativeURI, options) {
       const schemelessOptions = options ? Object.assign({ scheme: "null" }, options) : { scheme: "null" };
       const {
         parsed: baseParsed,
@@ -4198,7 +4198,7 @@ var require_fast_uri = __commonJS({
     var fastUri = {
       SCHEMES,
       normalize,
-      resolve: resolve2,
+      resolve: resolve3,
       resolveComponent,
       equal,
       serialize,
@@ -29145,7 +29145,7 @@ var Protocol = class {
           return;
         }
         const pollInterval = task2.pollInterval ?? this._options?.defaultTaskPollInterval ?? 1e3;
-        await new Promise((resolve2) => setTimeout(resolve2, pollInterval));
+        await new Promise((resolve3) => setTimeout(resolve3, pollInterval));
         options?.signal?.throwIfAborted();
       }
     } catch (error51) {
@@ -29162,7 +29162,7 @@ var Protocol = class {
    */
   request(request, resultSchema, options) {
     const { relatedRequestId, resumptionToken, onresumptiontoken, task, relatedTask } = options ?? {};
-    return new Promise((resolve2, reject) => {
+    return new Promise((resolve3, reject) => {
       const earlyReject = (error51) => {
         reject(error51);
       };
@@ -29240,7 +29240,7 @@ var Protocol = class {
           if (!parseResult.success) {
             reject(parseResult.error);
           } else {
-            resolve2(parseResult.data);
+            resolve3(parseResult.data);
           }
         } catch (error51) {
           reject(error51);
@@ -29501,12 +29501,12 @@ var Protocol = class {
       }
     } catch {
     }
-    return new Promise((resolve2, reject) => {
+    return new Promise((resolve3, reject) => {
       if (signal.aborted) {
         reject(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
         return;
       }
-      const timeoutId = setTimeout(resolve2, interval);
+      const timeoutId = setTimeout(resolve3, interval);
       signal.addEventListener("abort", () => {
         clearTimeout(timeoutId);
         reject(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
@@ -30597,7 +30597,7 @@ var McpServer = class {
     let task = createTaskResult.task;
     const pollInterval = task.pollInterval ?? 5e3;
     while (task.status !== "completed" && task.status !== "failed" && task.status !== "cancelled") {
-      await new Promise((resolve2) => setTimeout(resolve2, pollInterval));
+      await new Promise((resolve3) => setTimeout(resolve3, pollInterval));
       const updatedTask = await extra.taskStore.getTask(taskId);
       if (!updatedTask) {
         throw new McpError(ErrorCode.InternalError, `Task ${taskId} not found during polling`);
@@ -31261,12 +31261,12 @@ var StdioServerTransport = class {
     this.onclose?.();
   }
   send(message) {
-    return new Promise((resolve2) => {
+    return new Promise((resolve3) => {
       const json2 = serializeMessage(message);
       if (this._stdout.write(json2)) {
-        resolve2();
+        resolve3();
       } else {
-        this._stdout.once("drain", resolve2);
+        this._stdout.once("drain", resolve3);
       }
     });
   }
@@ -31343,6 +31343,11 @@ function truncateErrorMessage(text, max = DEFAULT_ERROR_MESSAGE_MAX) {
     return redacted;
   return `${redacted.slice(0, max)}\u2026 [truncated]`;
 }
+function messageOf(err) {
+  if (err instanceof Error)
+    return err.message;
+  return String(err);
+}
 
 // node_modules/@chrischall/mcp-utils/dist/response/index.js
 function textResult(data) {
@@ -31440,6 +31445,20 @@ function readEnvVar(key, opts = {}) {
   }
   return opts.default;
 }
+var TRUE_TOKENS = /* @__PURE__ */ new Set(["1", "true", "yes", "on"]);
+var FALSE_TOKENS = /* @__PURE__ */ new Set(["0", "false", "no", "off"]);
+function parseBoolEnv(key, opts = {}) {
+  const fallback = opts.default ?? false;
+  const raw = readEnvVar(key, { env: opts.env });
+  if (raw === void 0)
+    return fallback;
+  const token = raw.toLowerCase();
+  if (TRUE_TOKENS.has(token))
+    return true;
+  if (FALSE_TOKENS.has(token))
+    return false;
+  return fallback;
+}
 async function loadDotenvSafely(opts = {}) {
   try {
     const mod = await import(
@@ -31457,6 +31476,34 @@ async function loadDotenvSafely(opts = {}) {
   }
 }
 
+// node_modules/@chrischall/mcp-utils/dist/http/index.js
+var RateLimitedError = class extends Error {
+  status = 429;
+  constructor(service) {
+    super(`Rate limited (429) by ${service} after retries.`);
+    this.name = "RateLimitedError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var RequestTimeoutError = class extends Error {
+  timeoutMs;
+  constructor(service, timeoutMs) {
+    super(`Request to ${service} timed out after ${timeoutMs}ms.`);
+    this.name = "RequestTimeoutError";
+    this.timeoutMs = timeoutMs;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var ApiError = class extends Error {
+  status;
+  constructor(status, message) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
 // node_modules/@chrischall/mcp-utils/dist/zod/index.js
 var PositiveInt = external_exports.number().int().positive();
 var NonNegInt = external_exports.number().int().nonnegative();
@@ -31485,57 +31532,313 @@ function toolAnnotations(opts = {}) {
 }
 
 // node_modules/@chrischall/mcp-utils/dist/session/index.js
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, renameSync, unlinkSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { randomBytes, createHmac } from "node:crypto";
+function bindingDigest(secret, salt) {
+  return createHmac("sha256", salt).update(secret).digest("hex").slice(0, 32);
+}
+function isEnvelope(raw) {
+  return raw !== null && typeof raw === "object" && raw.v === 1 && "state" in raw;
+}
+var StatePersistenceError = class extends Error {
+  cause;
+  constructor(cause) {
+    super(cause instanceof Error ? cause.message : String(cause));
+    this.name = "StatePersistenceError";
+    this.cause = cause;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+function createFileStatePersistence(opts) {
+  const { filePath, validate } = opts;
+  const secret = opts.boundTo;
+  return {
+    load() {
+      if (!existsSync(filePath))
+        return null;
+      try {
+        const raw = JSON.parse(readFileSync(filePath, "utf8"));
+        let state;
+        if (isEnvelope(raw)) {
+          const b = raw.boundTo;
+          if (secret === void 0) {
+            if (b !== void 0)
+              return null;
+          } else {
+            if (b === void 0)
+              return null;
+            if (bindingDigest(secret, b.salt) !== b.digest)
+              return null;
+          }
+          state = raw.state;
+        } else {
+          if (secret !== void 0)
+            return null;
+          state = raw;
+        }
+        if (validate !== void 0)
+          return validate(state);
+        return state;
+      } catch {
+        return null;
+      }
+    },
+    save(state) {
+      const dir = dirname(filePath);
+      const tmp = `${filePath}.tmp-${randomBytes(6).toString("hex")}`;
+      const dirExisted = existsSync(dir);
+      try {
+        mkdirSync(dir, { recursive: true, mode: 448 });
+        if (!dirExisted)
+          chmodSync(dir, 448);
+        let boundTo;
+        if (secret !== void 0) {
+          const salt = randomBytes(16).toString("hex");
+          boundTo = { salt, digest: bindingDigest(secret, salt) };
+        }
+        const envelope = { v: 1, ...boundTo !== void 0 ? { boundTo } : {}, state };
+        writeFileSync(tmp, JSON.stringify(envelope, null, 2), { mode: 384 });
+        chmodSync(tmp, 384);
+        renameSync(tmp, filePath);
+        chmodSync(filePath, 384);
+      } catch (err) {
+        try {
+          if (existsSync(tmp))
+            unlinkSync(tmp);
+        } catch {
+        }
+        throw err;
+      }
+    },
+    clear() {
+      try {
+        if (existsSync(filePath))
+          unlinkSync(filePath);
+      } catch {
+      }
+    }
+  };
+}
+function homeOf(env) {
+  return readEnvVar("HOME", { env }) ?? homedir();
+}
+function resolveStateDir(opts = {}) {
+  const env = opts.env;
+  return join(readEnvVar("MCP_DATA_DIR", { env }) ?? homeOf(env), opts.subdir ?? "");
+}
+function resolveStateFile(opts) {
+  const override = opts.envVar !== void 0 ? readEnvVar(opts.envVar, { env: opts.env }) : void 0;
+  if (override !== void 0) {
+    if (override === "~")
+      return homeOf(opts.env);
+    if (override.startsWith("~/"))
+      return join(homeOf(opts.env), override.slice(2));
+    return resolve(override);
+  }
+  const dirOpts = { env: opts.env };
+  if (opts.subdir !== void 0)
+    dirOpts.subdir = opts.subdir;
+  return join(resolveStateDir(dirOpts), opts.fileName);
+}
 var TOKEN_REFRESH_SKEW_MS = 5 * 60 * 1e3;
+function defaultIsRefreshRevoked(err) {
+  if (err instanceof RateLimitedError || err instanceof RequestTimeoutError)
+    return false;
+  if (err instanceof ApiError && err.status >= 500)
+    return false;
+  return true;
+}
+function isBearerTokens(raw) {
+  if (raw === null || typeof raw !== "object")
+    return false;
+  const t = raw;
+  if (typeof t.accessToken !== "string" || t.accessToken === "")
+    return false;
+  if (typeof t.expiresAt !== "number" || !Number.isFinite(t.expiresAt))
+    return false;
+  return t.refreshToken === void 0 || typeof t.refreshToken === "string";
+}
 var TokenManager = class {
-  accessToken;
-  refreshToken;
-  expiresAt;
+  tokens;
+  bootstrapFn;
   refreshFn;
   skewMs;
+  persistence;
+  now;
+  isRefreshRevokedFn;
+  onPersistErrorFn;
   inFlight;
+  bootstrapInFlight;
+  /**
+   * Persistence is consulted at most once per process. Without this the
+   * revoked-token recovery below re-reads the SAME rejected record — `clear()`
+   * is optional on {@link StatePersistence} and its failures are swallowed, so
+   * recovery must not depend on it. After the first read the in-memory tokens
+   * (or their deliberate absence) are the truth.
+   */
+  persistenceRead = false;
   constructor(opts) {
-    this.accessToken = opts.initial.accessToken;
-    this.refreshToken = opts.initial.refreshToken;
-    this.expiresAt = opts.initial.expiresAt;
+    if (typeof opts.initial === "function") {
+      this.bootstrapFn = opts.initial;
+    } else {
+      this.tokens = { ...opts.initial };
+    }
     this.refreshFn = opts.refresh;
     this.skewMs = opts.skewMs ?? TOKEN_REFRESH_SKEW_MS;
+    this.persistence = opts.persistence;
+    this.now = opts.now ?? Date.now;
+    this.isRefreshRevokedFn = opts.isRefreshRevoked ?? defaultIsRefreshRevoked;
+    this.onPersistErrorFn = opts.onPersistError;
   }
   /** Whether the token is within the skew window of (or past) expiry. */
   needsRefresh() {
-    return Date.now() >= this.expiresAt - this.skewMs;
+    if (this.tokens === void 0)
+      return false;
+    return this.now() >= this.tokens.expiresAt - this.skewMs;
+  }
+  /**
+   * A stored token is worth using when it is still valid, OR when it carries a
+   * refresh token — an expired-but-refreshable token still saves the login,
+   * which is the expensive half.
+   */
+  isUsable(t) {
+    return this.now() < t.expiresAt - this.skewMs || t.refreshToken !== void 0;
+  }
+  /** Read persisted tokens, guarding shape and usability. Never throws. */
+  async loadPersisted() {
+    if (this.persistence === void 0 || this.persistenceRead)
+      return null;
+    this.persistenceRead = true;
+    try {
+      const raw = await this.persistence.load();
+      if (!isBearerTokens(raw) || !this.isUsable(raw))
+        return null;
+      return raw;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Write tokens. Silent by default (a lost write costs a future login, not this
+   * request); throws a {@link StatePersistenceError} when `onPersistError` does.
+   */
+  async persist(t) {
+    if (this.persistence === void 0)
+      return;
+    try {
+      await this.persistence.save(t);
+    } catch (err) {
+      if (this.onPersistErrorFn === void 0)
+        return;
+      try {
+        this.onPersistErrorFn(err);
+      } catch (hookErr) {
+        throw new StatePersistenceError(hookErr);
+      }
+    }
+  }
+  /** Discard persisted tokens (a refresh they could not satisfy). Never throws. */
+  async clearPersisted() {
+    if (this.persistence?.clear === void 0)
+      return;
+    try {
+      await this.persistence.clear();
+    } catch {
+    }
+  }
+  /** The current tokens, single-flighting the bootstrap if there are none. */
+  ensureTokens() {
+    if (this.tokens !== void 0)
+      return Promise.resolve(this.tokens);
+    if (this.bootstrapInFlight === void 0) {
+      this.bootstrapInFlight = this.runBootstrap().finally(() => {
+        this.bootstrapInFlight = void 0;
+      });
+    }
+    return this.bootstrapInFlight;
+  }
+  /** One bootstrap attempt: persisted tokens if usable, else the login. */
+  async runBootstrap() {
+    const stored = await this.loadPersisted();
+    if (stored !== null) {
+      this.tokens = stored;
+      return stored;
+    }
+    if (this.bootstrapFn === void 0) {
+      throw new Error("TokenManager: no tokens and no bootstrap function to mint them.");
+    }
+    const fresh = await this.bootstrapFn();
+    this.tokens = fresh;
+    try {
+      await this.persist(fresh);
+    } catch (err) {
+      throw err instanceof StatePersistenceError ? err.cause : err;
+    }
+    return fresh;
   }
   /**
    * Single-flight refresh. Concurrent callers share one in-flight promise; it is
    * cleared on settle (success or failure) so a subsequent refresh can proceed.
    */
   refreshNow() {
-    if (!this.inFlight) {
-      const rt = this.refreshToken;
-      if (rt === void 0) {
-        return Promise.reject(new Error("TokenManager: cannot refresh \u2014 no refresh token is available."));
-      }
-      this.inFlight = (async () => {
-        const tok = await this.refreshFn(rt);
-        this.accessToken = tok.accessToken;
-        if (tok.refreshToken !== void 0 && tok.refreshToken !== "") {
-          this.refreshToken = tok.refreshToken;
-        }
-        this.expiresAt = tok.expiresAt;
-      })().finally(() => {
+    if (this.inFlight === void 0) {
+      this.inFlight = this.runRefresh().finally(() => {
         this.inFlight = void 0;
       });
     }
     return this.inFlight;
   }
+  /** One refresh attempt against the current refresh token. */
+  async runRefresh() {
+    const current = this.tokens ?? await this.ensureTokens();
+    const rt = current.refreshToken;
+    if (rt === void 0) {
+      throw new Error("TokenManager: cannot refresh \u2014 no refresh token is available.");
+    }
+    const tok = await this.refreshFn(rt);
+    this.tokens = {
+      accessToken: tok.accessToken,
+      // Rotation is optional: keep the current refresh token when none comes back.
+      refreshToken: tok.refreshToken !== void 0 && tok.refreshToken !== "" ? tok.refreshToken : rt,
+      expiresAt: tok.expiresAt
+    };
+    await this.persist(this.tokens);
+  }
+  /**
+   * Recover from a refresh the current credential could not satisfy — commonly
+   * a refresh token restored from a previous process and revoked since. Without
+   * a bootstrap to fall back on this is terminal; with one, re-minting beats
+   * staying broken forever. Shared so the two entry points cannot diverge.
+   */
+  async reBootstrap(err) {
+    if (err instanceof StatePersistenceError)
+      throw err.cause;
+    if (this.bootstrapFn === void 0)
+      throw err;
+    if (!this.isRefreshRevokedFn(err))
+      throw err;
+    this.tokens = void 0;
+    await this.clearPersisted();
+    return this.ensureTokens();
+  }
   /** Get a valid access token, refreshing proactively inside the skew window. */
   async getAccessToken() {
-    if (this.needsRefresh())
-      await this.refreshNow();
-    return this.accessToken;
+    let tokens = this.tokens ?? await this.ensureTokens();
+    if (this.needsRefresh()) {
+      try {
+        await this.refreshNow();
+      } catch (err) {
+        return (await this.reBootstrap(err)).accessToken;
+      }
+      tokens = this.tokens ?? tokens;
+    }
+    return tokens.accessToken;
   }
-  /** Current absolute expiry (epoch ms). */
+  /** Current absolute expiry (epoch ms), or `0` before the first bootstrap. */
   getExpiresAt() {
-    return this.expiresAt;
+    return this.tokens?.expiresAt ?? 0;
   }
   /**
    * Run an authenticated request with reactive 401-replay. `call` receives a
@@ -31553,9 +31856,14 @@ var TokenManager = class {
     const usedToken = await this.getAccessToken();
     let res = await call(usedToken);
     if (res.status === 401) {
-      if (this.accessToken === usedToken)
-        await this.refreshNow();
-      res = await call(this.accessToken);
+      if (this.tokens?.accessToken === usedToken) {
+        try {
+          await this.refreshNow();
+        } catch (err) {
+          await this.reBootstrap(err);
+        }
+      }
+      res = await call(this.tokens?.accessToken ?? usedToken);
     }
     return res;
   }
@@ -31574,6 +31882,41 @@ function loadConfig(env = process.env) {
   };
 }
 
+// src/token-cache.ts
+function tokenCachePath(env = process.env) {
+  return resolveStateFile({
+    env,
+    envVar: "MYHOTLUNCHBOX_TOKEN_FILE",
+    subdir: ".myhotlunchbox-mcp",
+    fileName: "token.json"
+  });
+}
+function isTokens(raw) {
+  if (raw === null || typeof raw !== "object") return false;
+  const t = raw;
+  return typeof t.accessToken === "string" && t.accessToken !== "" && typeof t.expiresAt === "number" && (t.refreshToken === void 0 || typeof t.refreshToken === "string");
+}
+function createTokenCache(env = process.env) {
+  if (!parseBoolEnv("MYHOTLUNCHBOX_TOKEN_CACHE", { env, default: true })) return null;
+  const username = readEnvVar("MYHOTLUNCHBOX_USERNAME", { env });
+  const password = readEnvVar("MYHOTLUNCHBOX_PASSWORD", { env });
+  if (username === void 0 || password === void 0) return null;
+  return createFileStatePersistence({
+    filePath: tokenCachePath(env),
+    // Joined on a NUL, written as an escape rather than a literal byte: a
+    // password may contain spaces, so a space-joined pair could collide with a
+    // different pair by shifting the boundary between the two halves.
+    boundTo: [username.trim().toLowerCase(), password].join("\0"),
+    validate: (raw) => isTokens(raw) ? raw : null
+  });
+}
+function reportCacheWriteFailure(err) {
+  const detail = err instanceof Error ? err.message : String(err);
+  console.error(
+    `[myhotlunchbox-mcp] could not cache the OAuth tokens (${detail}); continuing without the cache \u2014 every restart will log in again until this is fixed.`
+  );
+}
+
 // src/auth.ts
 var DEFAULT_TOKEN_LIFETIME_S = 3600;
 function scrubCredentials(text, secrets) {
@@ -31681,13 +32024,24 @@ var MhlbAuth = class _MhlbAuth {
     if (this.manager) return this.manager;
     if (this.loginInFlight) return this.loginInFlight;
     this.loginInFlight = (async () => {
-      const body = await this.passwordLogin();
       const manager = new TokenManager({
-        initial: {
-          accessToken: this.assertAccessToken(body),
-          refreshToken: body.refresh_token,
-          expiresAt: _MhlbAuth.expiryOf(body)
+        // The FUNCTION form, so the cache is consulted before the password
+        // grant runs at all — the eager object form skips persistence, which
+        // would mean a cache that is written and never read.
+        initial: async () => {
+          const body = await this.passwordLogin();
+          return {
+            accessToken: this.assertAccessToken(body),
+            refreshToken: body.refresh_token,
+            expiresAt: _MhlbAuth.expiryOf(body)
+          };
         },
+        persistence: createTokenCache() ?? void 0,
+        onPersistError: reportCacheWriteFailure,
+        // `refresh` below already recovers from a revoked refresh token by
+        // falling back to a full login, so the library's own re-mint-on-revoked
+        // recovery would only add a third attempt after both have failed.
+        isRefreshRevoked: () => false,
         refresh: async (refreshToken) => {
           let next;
           try {
@@ -31891,7 +32245,7 @@ var MhlbClient = class {
 };
 
 // src/version.ts
-var VERSION = "0.2.1";
+var VERSION = "0.4.0";
 
 // src/tools/_shared.ts
 function preview(action, request, notes) {
@@ -32420,12 +32774,12 @@ function checkoutBody(args) {
 }
 
 // src/tools/reports.ts
-import { mkdirSync, writeFileSync } from "node:fs";
-import { isAbsolute, join, resolve } from "node:path";
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { isAbsolute, join as join2, resolve as resolve2 } from "node:path";
 var MAX_INLINE_BYTES = 75e4;
 function outputDir(env = process.env) {
   const configured = readEnvVar("MYHOTLUNCHBOX_OUTPUT_DIR", { env });
-  return configured ? resolve(configured) : process.cwd();
+  return configured ? resolve2(configured) : process.cwd();
 }
 function* candidateNames(filename) {
   const dot = filename.lastIndexOf(".");
@@ -32440,9 +32794,9 @@ function writeWithoutClobbering(dir, filename, bytes) {
   for (const name of candidateNames(filename)) {
     if (attempts >= MAX_NAME_ATTEMPTS) break;
     attempts += 1;
-    const candidate = join(dir, name);
+    const candidate = join2(dir, name);
     try {
-      writeFileSync(candidate, bytes, { flag: "wx" });
+      writeFileSync2(candidate, bytes, { flag: "wx" });
       return candidate;
     } catch (err) {
       if (err.code !== "EEXIST") throw err;
@@ -32484,7 +32838,7 @@ function deliver(bytes, contentType, filename, inline) {
   const dir = outputDir();
   let path;
   try {
-    mkdirSync(dir, { recursive: true });
+    mkdirSync2(dir, { recursive: true });
     path = writeWithoutClobbering(dir, filename, bytes);
   } catch (cause) {
     if (cause instanceof McpToolError) throw cause;
@@ -32570,6 +32924,181 @@ function registerReportTools(server, client2) {
   );
 }
 
+// node_modules/@chrischall/mcp-utils/dist/healthcheck/index.js
+function statusOf(err) {
+  if (typeof err !== "object" || err === null)
+    return void 0;
+  const s = err.status ?? err.statusCode;
+  return typeof s === "number" ? s : void 0;
+}
+var CREDENTIAL_ARMS = /* @__PURE__ */ new Set([
+  "ok",
+  "no_credential",
+  "credential_rejected",
+  "timeout",
+  "http",
+  "transport",
+  "unknown"
+]);
+function isArm(kind) {
+  return kind !== void 0 && CREDENTIAL_ARMS.has(kind);
+}
+function credentialHint(arm, prefix, hostLabel, source) {
+  switch (arm) {
+    case "ok":
+      return `Credential from '${source}' works: ${hostLabel} accepted an authenticated request. If a real tool still fails, the problem is that tool, not auth.`;
+    case "no_credential":
+      return `No credential resolved. Nothing was available to authenticate with \u2014 sign in and reconnect the connector so ${prefix} receives a token, or set the documented environment variable.`;
+    case "credential_rejected":
+      return `${hostLabel} rejected the credential from '${source}'. It is present but no longer valid \u2014 most often expired or revoked upstream. Re-authenticate and reconnect; retrying will not fix it.`;
+    case "timeout":
+      return `The credential from '${source}' resolved, but ${hostLabel} did not answer in time. Usually transient \u2014 retry. If it persists, ${hostLabel} is slow or unreachable from here.`;
+    case "http":
+      return `${hostLabel} answered with an error status that is not an auth rejection. That is USUALLY a ${hostLabel}-side problem rather than an auth one \u2014 but a 404 here more often means the probe path is wrong than that ${hostLabel} is broken, so check error.message and probe.url before concluding anything about the credential.`;
+    case "transport":
+      return `Could not reach ${hostLabel} at all. Check network egress; the credential itself was never judged.`;
+    default:
+      return `Unexpected failure \u2014 see error.message.`;
+  }
+}
+function registerCredentialHealthcheckTool(args) {
+  const { server, prefix, hostLabel, probePath, resolveCredential, probeFn, classifyThrown, hints } = args;
+  const probeUrl = probePath ? `https://${hostLabel}${probePath}` : void 0;
+  server.registerTool(`${prefix}_healthcheck`, {
+    title: "Verify credentials and upstream reachability",
+    description: `Resolves the credential the way real tools do, then makes one authenticated request to ${hostLabel}. Reports which source supplied the credential, whether ${hostLabel} accepted it, the round-trip time, and a plain-English hint distinguishing 'no credential' from 'credential rejected' from 'a ${hostLabel}-side problem'. Call this when a real tool fails and you want to know which hop broke. Read-only; never returns the credential itself.`,
+    annotations: {
+      title: "Verify credentials and upstream reachability",
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: {}
+  }, async () => {
+    let probeStarted = 0;
+    let state;
+    try {
+      state = await resolveCredential();
+    } catch (e) {
+      const classified = classifyThrown?.(e);
+      const result2 = {
+        ok: false,
+        // Still false, and still no source: a classification explains WHY
+        // nothing resolved, it does not invent a credential that did.
+        credential: { source: null, resolved: false },
+        // No `url`: nothing was probed, and naming one implies it was tried.
+        probe: { elapsed_ms: 0 },
+        error: {
+          kind: classified?.kind ?? "no_credential",
+          message: truncateErrorMessage(messageOf(e)),
+          ...classified?.detail !== void 0 ? { detail: classified.detail } : {}
+        },
+        // The hint must follow the KIND beside it. Falling back to
+        // `no_credential`'s copy under a classified kind would state a cause
+        // the kind contradicts — the same disagreement this path exists to
+        // remove. So: an inline hint wins; else the classified arm's own
+        // copy (consumer override first); else, for a kind this module has
+        // no copy for, the neutral `unknown` text rather than one that
+        // asserts a cause; else the unclassified `no_credential` default.
+        hint: classified?.hint ?? (isArm(classified?.kind) ? hints?.[classified.kind] ?? credentialHint(classified.kind, prefix, hostLabel, null) : classified !== void 0 ? credentialHint("unknown", prefix, hostLabel, null) : hints?.no_credential ?? credentialHint("no_credential", prefix, hostLabel, null))
+      };
+      return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
+    }
+    const credential = {
+      source: state.source,
+      resolved: state.source !== null,
+      ...state.detail !== void 0 ? { detail: state.detail } : {}
+    };
+    if (!credential.resolved) {
+      const result2 = {
+        ok: false,
+        credential,
+        probe: { elapsed_ms: 0 },
+        error: { kind: "no_credential", message: "no credential source resolved" },
+        hint: hints?.no_credential ?? credentialHint("no_credential", prefix, hostLabel, null)
+      };
+      return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
+    }
+    let arm = "ok";
+    let error51;
+    let status;
+    let customHint;
+    probeStarted = Date.now();
+    try {
+      await probeFn();
+    } catch (e) {
+      status = statusOf(e);
+      const aborted2 = e instanceof Error && e.name === "AbortError";
+      arm = status === 401 || status === 403 ? "credential_rejected" : status !== void 0 ? "http" : aborted2 || /timeout|timed out|ETIMEDOUT/i.test(messageOf(e)) ? "timeout" : /fetch failed|ENOTFOUND|ECONNREFUSED|ECONNRESET|network/i.test(messageOf(e)) ? "transport" : "unknown";
+      let kind = arm;
+      let detail;
+      const custom2 = classifyThrown?.(e);
+      if (custom2) {
+        kind = custom2.kind;
+        customHint = custom2.hint;
+        detail = custom2.detail;
+      }
+      error51 = {
+        kind,
+        // Redacted AND bounded before it reaches the result: an upstream
+        // failure routinely quotes what it was sent, and a healthcheck is
+        // the tool people paste into a chat when something is broken.
+        message: truncateErrorMessage(messageOf(e)),
+        ...detail !== void 0 ? { detail } : {}
+      };
+    }
+    const result = {
+      ok: error51 === void 0,
+      credential,
+      probe: {
+        ...probeUrl ? { url: probeUrl } : {},
+        elapsed_ms: Date.now() - probeStarted,
+        ...status !== void 0 ? { status } : {}
+      },
+      ...error51 ? { error: error51 } : {},
+      hint: customHint ?? hints?.[arm] ?? credentialHint(arm, prefix, hostLabel, state.source)
+    };
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  });
+}
+
+// src/tools/health.ts
+var NOT_CONFIGURED = "credentials are not configured";
+function classifyMhlbError(err) {
+  const msg = err instanceof Error ? err.message : String(err);
+  if (msg.includes(NOT_CONFIGURED)) return { kind: "no_credential" };
+  if (msg.includes("Could not reach My Hot Lunchbox")) {
+    return {
+      kind: "unreachable",
+      hint: "Could not reach My Hot Lunchbox at all, so the credential was never tested. Check network connectivity, or MYHOTLUNCHBOX_BASE_URL if the app has moved."
+    };
+  }
+  if (msg.includes("rejected the sign-in")) {
+    return {
+      kind: "credential_rejected",
+      hint: "My Hot Lunchbox rejected the sign-in. Check MYHOTLUNCHBOX_USERNAME / MYHOTLUNCHBOX_PASSWORD against https://ordernow.myhotlunchbox.com \u2014 but do NOT re-run this with guesses: repeated failures can lock the account or force a CAPTCHA that blocks server-side sign-in entirely."
+    };
+  }
+  return void 0;
+}
+function registerHealthcheckTools(server, client2, readConfig = () => loadConfig()) {
+  registerCredentialHealthcheckTool({
+    server,
+    prefix: "mhlb",
+    hostLabel: "ordernow.myhotlunchbox.com",
+    probePath: "/api/auth/userinfo",
+    resolveCredential: async () => {
+      const { username, password, baseUrl } = readConfig();
+      const source = username && password ? "MYHOTLUNCHBOX_USERNAME+MYHOTLUNCHBOX_PASSWORD" : null;
+      return { source, detail: { base_url: baseUrl } };
+    },
+    // The same authenticated read `mhlb_whoami` makes: cheap, and it changes
+    // nothing — no order is placed, no balance moved.
+    probeFn: () => client2.get("/auth/userinfo"),
+    classifyThrown: classifyMhlbError
+  });
+}
+
 // src/index.ts
 await loadDotenvSafely();
 var client = new MhlbClient();
@@ -32585,6 +33114,7 @@ await runMcp({
     registerOrderTools,
     registerBillingTools,
     registerCheckoutTools,
-    registerReportTools
+    registerReportTools,
+    registerHealthcheckTools
   ]
 });

package/dist/index.js

@@ -9,6 +9,7 @@ import { registerOrderTools } from './tools/orders.js';
 import { registerBillingTools } from './tools/billing.js';
 import { registerCheckoutTools } from './tools/checkout.js';
 import { registerReportTools } from './tools/reports.js';
+import { registerHealthcheckTools } from './tools/health.js';
 await loadDotenvSafely();
 // Built here, in the caller, so the deferred-config-error pattern holds: the
 // server still boots (and answers the host's install-time tools/list probe)
@@ -27,5 +28,6 @@ await runMcp({
         registerBillingTools,
         registerCheckoutTools,
         registerReportTools,
+        registerHealthcheckTools,
     ],
 });

package/dist/token-cache.js

@@ -0,0 +1,63 @@
+import { createFileStatePersistence, resolveStateFile, } from '@chrischall/mcp-utils/session';
+import { readEnvVar, parseBoolEnv } from '@chrischall/mcp-utils';
+/** Where the OAuth token pair is cached between runs. */
+export function tokenCachePath(env = process.env) {
+    return resolveStateFile({
+        env,
+        envVar: 'MYHOTLUNCHBOX_TOKEN_FILE',
+        subdir: '.myhotlunchbox-mcp',
+        fileName: 'token.json',
+    });
+}
+/** Only a token pair is ever stored — never the username or password. */
+function isTokens(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return false;
+    const t = raw;
+    return (typeof t.accessToken === 'string' &&
+        t.accessToken !== '' &&
+        typeof t.expiresAt === 'number' &&
+        (t.refreshToken === undefined || typeof t.refreshToken === 'string'));
+}
+/**
+ * The token cache, or `null` when it is off or there are no credentials to
+ * bind a record to.
+ *
+ * A restart currently spends a full password grant for a token that is usually
+ * still valid — and, when it is not, a refresh would have done. Caching turns
+ * the first case into nothing and the second into one refresh, which matters on
+ * a host where a child idles out after ten minutes and every start is cold.
+ *
+ * The record is bound to the credentials that minted it, so rotating either
+ * discards it rather than leaving a token from the old password in play. Only a
+ * salted digest is written; neither value reaches the file.
+ */
+export function createTokenCache(env = process.env) {
+    if (!parseBoolEnv('MYHOTLUNCHBOX_TOKEN_CACHE', { env, default: true }))
+        return null;
+    const username = readEnvVar('MYHOTLUNCHBOX_USERNAME', { env });
+    const password = readEnvVar('MYHOTLUNCHBOX_PASSWORD', { env });
+    if (username === undefined || password === undefined)
+        return null;
+    return createFileStatePersistence({
+        filePath: tokenCachePath(env),
+        // Joined on a NUL, written as an escape rather than a literal byte: a
+        // password may contain spaces, so a space-joined pair could collide with a
+        // different pair by shifting the boundary between the two halves.
+        boundTo: [username.trim().toLowerCase(), password].join('\u0000'),
+        validate: (raw) => (isTokens(raw) ? raw : null),
+    });
+}
+/**
+ * Report a cache write that failed. Not fatal: the tokens are re-mintable from
+ * the credentials in the environment, so a lost write costs the next start a
+ * login rather than access. Worth saying, though — a read-only data dir
+ * otherwise looks exactly like a server that never caches.
+ *
+ * stderr only; stdout is the JSON-RPC channel.
+ */
+export function reportCacheWriteFailure(err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    console.error(`[myhotlunchbox-mcp] could not cache the OAuth tokens (${detail}); continuing ` +
+        'without the cache — every restart will log in again until this is fixed.');
+}

package/dist/tools/health.js

@@ -0,0 +1,65 @@
+import { registerCredentialHealthcheckTool } from '@chrischall/mcp-utils/healthcheck';
+import { loadConfig } from '../config.js';
+/**
+ * `mhlb_healthcheck` — the one call that answers "is this connector
+ * working?", and the only tool here that reports a failure as DATA rather
+ * than throwing.
+ *
+ * My Hot Lunchbox had none. `mhlb_whoami` looks like one — its own
+ * description says "Start here to confirm the session works" — and is not: it
+ * is a plain data read that THROWS when auth fails, so the caller gets an
+ * exception, not an answer, and cannot tell a bad password from an
+ * unreachable host from a lockout.
+ *
+ * The lockout is why this matters more here than elsewhere. This account
+ * counts failed sign-ins and will lock or force a CAPTCHA that blocks
+ * server-side sign-in entirely, so a `credential_rejected` hint that invites
+ * retrying is actively harmful. {@link classifyMhlbError} carries that
+ * warning instead.
+ */
+const NOT_CONFIGURED = 'credentials are not configured';
+export function classifyMhlbError(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes(NOT_CONFIGURED))
+        return { kind: 'no_credential' };
+    // The host is unreachable, or MYHOTLUNCHBOX_BASE_URL points somewhere wrong.
+    // Nothing here says the credential is bad — do not send anyone to change it.
+    if (msg.includes('Could not reach My Hot Lunchbox')) {
+        return {
+            kind: 'unreachable',
+            hint: 'Could not reach My Hot Lunchbox at all, so the credential was never tested. ' +
+                'Check network connectivity, or MYHOTLUNCHBOX_BASE_URL if the app has moved.',
+        };
+    }
+    if (msg.includes('rejected the sign-in')) {
+        return {
+            kind: 'credential_rejected',
+            hint: 'My Hot Lunchbox rejected the sign-in. Check MYHOTLUNCHBOX_USERNAME / MYHOTLUNCHBOX_PASSWORD against ' +
+                'https://ordernow.myhotlunchbox.com — but do NOT re-run this with guesses: repeated failures can lock ' +
+                'the account or force a CAPTCHA that blocks server-side sign-in entirely.',
+        };
+    }
+    return undefined;
+}
+export function registerHealthcheckTools(server, client, 
+/** Seam: injectable so tests need no process env. */
+readConfig = () => loadConfig()) {
+    registerCredentialHealthcheckTool({
+        server,
+        prefix: 'mhlb',
+        hostLabel: 'ordernow.myhotlunchbox.com',
+        probePath: '/api/auth/userinfo',
+        resolveCredential: async () => {
+            const { username, password, baseUrl } = readConfig();
+            // Both halves or nothing: a username with no password cannot sign in,
+            // and sending it to the API would spend a failed attempt against an
+            // account that locks.
+            const source = username && password ? 'MYHOTLUNCHBOX_USERNAME+MYHOTLUNCHBOX_PASSWORD' : null;
+            return { source, detail: { base_url: baseUrl } };
+        },
+        // The same authenticated read `mhlb_whoami` makes: cheap, and it changes
+        // nothing — no order is placed, no balance moved.
+        probeFn: () => client.get('/auth/userinfo'),
+        classifyThrown: classifyMhlbError,
+    });
+}

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Single source of truth for the server version; release-please rewrites it. */
-export const VERSION = '0.2.1'; // x-release-please-version
+export const VERSION = '0.4.0'; // x-release-please-version

package/mint.yaml

@@ -33,7 +33,10 @@ env:
     help: >-
       Password for that account. Used for a server-side OAuth2 password grant;
       the refresh token it returns renews the session, so no browser or
-      extension is involved and nothing is written to disk.
+      extension is involved. The password itself is never written to disk — the
+      token pair it mints is cached at
+      $MCP_DATA_DIR/.myhotlunchbox-mcp/token.json (0600), bound to a salted
+      digest of these credentials so rotating either discards it.
 
   - name: MYHOTLUNCHBOX_BASE_URL
     secret: false
@@ -52,10 +55,27 @@ env:
       the filesystem belongs to the runner, so prefer calling those tools with
       inline: true and taking the bytes back in the result.
 
+  - name: MYHOTLUNCHBOX_TOKEN_CACHE
+    secret: false
+    required: false
+    help: >-
+      Set to false to disable the on-disk token cache and log in on every
+      process start. Defaults to enabled.
+  - name: MYHOTLUNCHBOX_TOKEN_FILE
+    secret: false
+    required: false
+    help: >-
+      Absolute path for the token cache file. Defaults to
+      $MCP_DATA_DIR/.myhotlunchbox-mcp/token.json.
 state:
-  # Sessions live in memory for the life of the child and are re-established by
-  # signing in again, so a cold start costs one login and loses nothing.
-  dataDir: false
+  dataDir: true
+  reason: >-
+    Caches the OAuth token pair at $MCP_DATA_DIR/.myhotlunchbox-mcp/token.json
+    (0600). This was dataDir:false while sessions lived only in memory, on the
+    reasoning that a cold start cost one login and lost nothing — true then, and
+    no longer: the cache is what turns those starts into nothing, and without a
+    persistent dir it is written to a rootfs the next idle-stop discards, so it
+    would never be read back.
 
 identity:
   # Credentials are per-registration secrets, not per-caller, so one shared

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "myhotlunchbox-mcp",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "mcpName": "io.github.chrischall/myhotlunchbox-mcp",
   "description": "My Hot Lunchbox MCP server for Claude — developed and maintained by AI (Claude Code)",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -38,14 +38,14 @@
     "bundle": "esbuild src/index.ts --bundle --platform=node --format=esm --external:dotenv --outfile=dist/bundle.js",
     "dev": "node dist/index.js",
     "typecheck": "tsc --noEmit",
-    "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",
     "verify:reads": "node scripts/verify-reads.mjs",
     "capture:writes": "node scripts/capture-writes.mjs"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.15.0",
+    "@chrischall/mcp-utils": "^0.19.3",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.0",
     "zod": "^4.4.2"

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/myhotlunchbox-mcp",
     "source": "github"
   },
-  "version": "0.2.1",
+  "version": "0.4.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "myhotlunchbox-mcp",
-      "version": "0.2.1",
+      "version": "0.4.0",
       "transport": {
         "type": "stdio"
       },
@@ -43,6 +43,20 @@
           "isRequired": false,
           "format": "string",
           "isSecret": false
+        },
+        {
+          "name": "MYHOTLUNCHBOX_TOKEN_CACHE",
+          "description": "Set to false to disable the on-disk token cache and re-authenticate on every process start. Defaults to enabled.",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": false
+        },
+        {
+          "name": "MYHOTLUNCHBOX_TOKEN_FILE",
+          "description": "Absolute path for the token cache file. Defaults to $MCP_DATA_DIR/.myhotlunchbox-mcp/token.json.",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": false
         }
       ]
     }