myhotlunchbox-mcp 0.0.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "myhotlunchbox-mcp",
+  "owner": {
+    "name": "Chris Hall",
+    "email": "chris.c.hall@gmail.com"
+  },
+  "metadata": {
+    "description": "MCP server for My Hot Lunchbox — order school lunches, manage students, and track payments via natural language",
+    "version": "0.0.0"
+  },
+  "plugins": [
+    {
+      "name": "myhotlunchbox-mcp",
+      "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.0.0",
+      "author": {
+        "name": "Chris Hall"
+      },
+      "homepage": "https://github.com/chrischall/myhotlunchbox-mcp",
+      "repository": "https://github.com/chrischall/myhotlunchbox-mcp",
+      "license": "MIT",
+      "keywords": [
+        "myhotlunchbox",
+        "school-lunch",
+        "lunch-ordering",
+        "mcp",
+        "parent"
+      ],
+      "category": "productivity"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "myhotlunchbox-mcp",
+  "displayName": "My Hot Lunchbox",
+  "version": "0.0.0",
+  "description": "MCP server for My Hot Lunchbox — order school lunches, manage students, and track payments via natural language",
+  "author": {
+    "name": "Chris Hall",
+    "email": "chris.c.hall@gmail.com"
+  },
+  "homepage": "https://github.com/chrischall/myhotlunchbox-mcp",
+  "repository": "https://github.com/chrischall/myhotlunchbox-mcp",
+  "license": "MIT",
+  "keywords": [
+    "myhotlunchbox",
+    "school-lunch",
+    "lunch-ordering",
+    "mcp",
+    "parent"
+  ],
+  "skills": "./skills/",
+  "mcp": "./.mcp.json"
+}

package/.mcp.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "myhotlunchbox": {
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/dist/index.js"
+      ],
+      "env": {
+        "MYHOTLUNCHBOX_USERNAME": "${MYHOTLUNCHBOX_USERNAME}",
+        "MYHOTLUNCHBOX_PASSWORD": "${MYHOTLUNCHBOX_PASSWORD}"
+      }
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Hall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,113 @@
+# myhotlunchbox-mcp
+
+MCP server for [My Hot Lunchbox](https://www.myhotlunchbox.com) — read the
+school lunch calendar, manage students, place and change orders, and track
+deliveries and payments on a parent account.
+
+> Developed and maintained by AI (Claude Code). Use at your own discretion.
+
+## Install
+
+```sh
+npx myhotlunchbox-mcp
+```
+
+Or as a Claude Code plugin:
+
+```sh
+/plugin marketplace add chrischall/myhotlunchbox-mcp
+/plugin install myhotlunchbox-mcp
+```
+
+## Configure
+
+```sh
+MYHOTLUNCHBOX_USERNAME=you@example.com
+MYHOTLUNCHBOX_PASSWORD=…
+```
+
+That is the whole setup. The server performs a real server-side sign-in against
+`ordernow.myhotlunchbox.com` (OAuth2 password grant) and renews the session with
+the refresh token it receives — **no browser extension, no signed-in tab, no
+captured cookie**. Nothing is written to disk.
+
+`MYHOTLUNCHBOX_BASE_URL` overrides the app origin if it ever moves.
+
+The server boots without credentials so a host's install-time `tools/list` probe
+still works; the configuration error surfaces on the first tool call.
+
+## Tools
+
+38 tools, all prefixed `mhlb_`.
+
+**Account** — `mhlb_whoami`, `mhlb_session_reset`
+
+**Students** — `mhlb_list_students`, `mhlb_get_student_form`,
+`mhlb_new_student_form`, `mhlb_create_student`, `mhlb_update_student`,
+`mhlb_delete_student`
+
+**Calendar & deliveries** — `mhlb_get_calendar`, `mhlb_get_day`,
+`mhlb_next_delivery`, `mhlb_list_upcoming_deliveries`,
+`mhlb_list_past_deliveries`, `mhlb_list_vendors`
+
+**Ordering** — `mhlb_get_cart`, `mhlb_get_cart_tabs`, `mhlb_get_menu`,
+`mhlb_get_order_form`, `mhlb_get_order`, `mhlb_create_order`,
+`mhlb_update_order`, `mhlb_delete_order`
+
+**Billing** — `mhlb_list_transactions`, `mhlb_get_transaction`,
+`mhlb_list_subscriptions`, `mhlb_get_subscription_settings`,
+`mhlb_set_subscription_enabled`, `mhlb_unsubscribe_order`,
+`mhlb_list_gift_cards`, `mhlb_apply_gift_card`, `mhlb_get_coupon`,
+`mhlb_apply_coupon`, `mhlb_remove_coupon`
+
+**Checkout** — `mhlb_init_checkout`, `mhlb_checkout`
+
+**Reports** — `mhlb_print_orders`, `mhlb_print_calendar`,
+`mhlb_print_transactions`
+
+## Writes are confirm-gated
+
+Every mutating tool takes `confirm`. Without `confirm: true` it makes **no**
+network call and returns a dry-run preview of exactly what it would send.
+
+`mhlb_checkout` charges a real payment method, so it takes one extra safeguard:
+an `expectedTotal` that must match the total in the payment payload. Price the
+cart with `mhlb_init_checkout`, read the total it reports, and pass that figure.
+A stale cart fails closed instead of paying a different amount.
+
+### Unverified writes
+
+The write endpoints' paths, verbs and query parameters were extracted from the
+site's own compiled API client and are reliable. Their **request bodies have not
+been exercised against a live account** — every such tool says so in its
+description. Inspect the dry-run preview before confirming, and re-read the
+resource afterwards: a `200` is not proof a write persisted.
+
+## Ordering is read-modify-write
+
+There is no "add item X" call. Fetch the model, edit it, send it back whole:
+
+1. `mhlb_get_menu` — what is orderable for a student on a date
+2. `mhlb_get_order_form` — the order model to fill in
+3. `mhlb_create_order` — send it back (with `confirm: true`)
+4. `mhlb_init_checkout` → `mhlb_checkout` — price, then pay
+
+Fields omitted from the payload are **cleared**, not preserved.
+
+## Shell skill
+
+`skills/myhotlunchbox` covers the same account from a shell with `curl` — no MCP
+process needed. Useful in scripts, or on a machine where this server is not
+installed.
+
+## Notes
+
+- Only the parent role is wired. The same API also serves school-admin and
+  vendor roles; those endpoints return `403`, which the client reports as a role
+  mismatch rather than a broken session.
+- `docs/MYHOTLUNCHBOX-API.md` records how the API was mapped and exactly what is
+  verified. `docs/api-surface.txt` is the full 359-endpoint extraction.
+
+## Licence
+
+MIT

package/dist/auth.js

@@ -0,0 +1,192 @@
+import { McpToolError, truncateErrorMessage } from '@chrischall/mcp-utils';
+import { TokenManager } from '@chrischall/mcp-utils/session';
+import { API_PREFIX, OAUTH_SCOPE } from './config.js';
+/** Fallback lifetime when the server omits `expires_in`. */
+const DEFAULT_TOKEN_LIFETIME_S = 3600;
+/**
+ * Strip the caller's own secrets out of an upstream body before it is ever
+ * rendered to a user.
+ *
+ * `truncateErrorMessage`/`redactSecrets` match secret *shapes* (Bearer, JWT,
+ * `sk-`, …). A password has no shape, so it would survive them untouched — and
+ * this is the one error path that has just sent one. Splice out the literal
+ * values as well. The empty-needle guard matters: `split('')` would splice the
+ * placeholder between every character.
+ */
+export function scrubCredentials(text, secrets) {
+    let out = text;
+    for (const secret of secrets) {
+        if (!secret)
+            continue;
+        out = out.split(secret).join('[redacted]');
+    }
+    return truncateErrorMessage(out);
+}
+/**
+ * Owns the OAuth2 session against `/api/auth/login`.
+ *
+ * The web app uses a password grant with `offline_access`, so a real
+ * server-side login is possible — no browser bridge, no captured cookie. The
+ * refresh token renews the session; if the refresh grant itself fails (the
+ * refresh token expired or was revoked) we fall back to a full password login
+ * rather than dropping the caller into a re-auth loop.
+ */
+export class MhlbAuth {
+    config;
+    fetchImpl;
+    manager = null;
+    loginInFlight = null;
+    constructor(config, fetchImpl = fetch) {
+        this.config = config;
+        this.fetchImpl = fetchImpl;
+    }
+    /** Credentials are checked lazily so the server still boots without them. */
+    requireCredentials() {
+        const { username, password } = this.config;
+        if (!username || !password) {
+            throw new McpToolError('My Hot Lunchbox credentials are not configured.', {
+                hint: 'Set MYHOTLUNCHBOX_USERNAME and MYHOTLUNCHBOX_PASSWORD (the email and password you use at ' +
+                    'https://ordernow.myhotlunchbox.com) in your .env or MCP host config, then retry.',
+            });
+        }
+        return { username, password };
+    }
+    tokenUrl() {
+        return `${this.config.baseUrl}${API_PREFIX}/auth/login`;
+    }
+    /**
+     * POST a grant to the token endpoint. The web app sends
+     * `application/x-www-form-urlencoded` (it builds the body with `qs.stringify`).
+     */
+    async postGrant(form) {
+        const { password } = this.config;
+        let res;
+        try {
+            res = await this.fetchImpl(this.tokenUrl(), {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/x-www-form-urlencoded',
+                    accept: 'application/json',
+                },
+                body: new URLSearchParams(form).toString(),
+            });
+        }
+        catch (cause) {
+            throw new McpToolError(`Could not reach My Hot Lunchbox at ${this.config.baseUrl}.`, { hint: 'Check network connectivity, or override MYHOTLUNCHBOX_BASE_URL if the app has moved.', cause });
+        }
+        const raw = await res.text();
+        if (!res.ok) {
+            let parsed = null;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                /* non-JSON error body — fall through to the raw text */
+            }
+            const detail = parsed?.error_description ?? parsed?.error ?? raw;
+            // Never auto-retry a rejected credential: these servers count attempts.
+            throw new McpToolError(`My Hot Lunchbox rejected the sign-in (HTTP ${res.status}): ${scrubCredentials(detail, [password, form.password, form.refresh_token])}`, {
+                hint: parsed?.error === 'invalid_grant'
+                    ? 'Check MYHOTLUNCHBOX_USERNAME / MYHOTLUNCHBOX_PASSWORD. Do not retry with guesses — repeated failures can lock the account or force a CAPTCHA that blocks server-side sign-in entirely.'
+                    : 'Sign in once at https://ordernow.myhotlunchbox.com to confirm the account is active, then retry.',
+            });
+        }
+        try {
+            return JSON.parse(raw);
+        }
+        catch (cause) {
+            throw new McpToolError('My Hot Lunchbox returned a non-JSON token response.', {
+                hint: 'The sign-in endpoint may have changed. Re-capture the login request from the web app.',
+                cause,
+            });
+        }
+    }
+    static expiryOf(body) {
+        return Date.now() + (body.expires_in ?? DEFAULT_TOKEN_LIFETIME_S) * 1000;
+    }
+    assertAccessToken(body) {
+        if (!body.access_token) {
+            throw new McpToolError('My Hot Lunchbox returned no access token.', {
+                hint: 'The sign-in succeeded but carried no `access_token`. Re-capture the login request from the web app.',
+            });
+        }
+        return body.access_token;
+    }
+    /** Full password grant. */
+    async passwordLogin() {
+        const { username, password } = this.requireCredentials();
+        return this.postGrant({
+            grant_type: 'password',
+            username,
+            password,
+            scope: OAUTH_SCOPE,
+        });
+    }
+    /**
+     * Build (once) the TokenManager that fronts every authenticated call.
+     * Single-flight: concurrent first-callers share one login.
+     */
+    async ensureManager() {
+        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),
+                },
+                refresh: async (refreshToken) => {
+                    let next;
+                    try {
+                        next = await this.postGrant({ grant_type: 'refresh_token', refresh_token: refreshToken });
+                    }
+                    catch {
+                        // The refresh token expired or was revoked. We still hold the
+                        // password, so recover with a full login instead of surfacing a
+                        // re-auth error the caller cannot act on.
+                        next = await this.passwordLogin();
+                    }
+                    return {
+                        accessToken: this.assertAccessToken(next),
+                        refreshToken: next.refresh_token,
+                        expiresAt: MhlbAuth.expiryOf(next),
+                    };
+                },
+            });
+            this.manager = manager;
+            return manager;
+        })();
+        try {
+            return await this.loginInFlight;
+        }
+        finally {
+            this.loginInFlight = null;
+        }
+    }
+    /**
+     * Run an authenticated request. Delegates to {@link TokenManager.withAuth},
+     * which refreshes proactively inside the skew window and replays exactly once
+     * on a `401`.
+     */
+    async withAuth(call) {
+        const manager = await this.ensureManager();
+        return manager.withAuth(call);
+    }
+    /** Drop the cached session. Exposed for the `_signout` tool and for tests. */
+    reset() {
+        this.manager = null;
+        this.loginInFlight = null;
+    }
+    /** Raw fetch through the injected implementation (no auth attached). */
+    fetch(url, init) {
+        return this.fetchImpl(url, init);
+    }
+    /** Whether a session has been established in this process. */
+    get isAuthenticated() {
+        return this.manager !== null;
+    }
+}