myhotlunchbox-mcp 0.3.0 → 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.3.0"
+    "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.3.0",
+      "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.3.0",
+  "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/bundle.js

@@ -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) {
@@ -32240,7 +32245,7 @@ var MhlbClient = class {
 };
 
 // src/version.ts
-var VERSION = "0.3.0";
+var VERSION = "0.4.0";
 
 // src/tools/_shared.ts
 function preview(action, request, notes) {
@@ -32919,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();
@@ -32934,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/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.3.0'; // x-release-please-version
+export const VERSION = '0.4.0'; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "myhotlunchbox-mcp",
-  "version": "0.3.0",
+  "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>",
@@ -45,7 +45,7 @@
     "capture:writes": "node scripts/capture-writes.mjs"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.17.1",
+    "@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.3.0",
+  "version": "0.4.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "myhotlunchbox-mcp",
-      "version": "0.3.0",
+      "version": "0.4.0",
       "transport": {
         "type": "stdio"
       },