myhotlunchbox-mcp 0.2.0 → 0.2.1

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.0"
+    "version": "0.2.1"
   },
   "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.0",
+      "version": "0.2.1",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "myhotlunchbox-mcp",
   "displayName": "My Hot Lunchbox",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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

@@ -71,18 +71,38 @@ directory); existing files are never overwritten.
 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.
+`mhlb_checkout` charges a real payment method. The server prices the charge from
+`orderIds`, so nothing client-side can bind the amount — there is no total in the
+request to check against. `expectedTotal` is therefore **attribution, not a
+guard**: you state what you expected, and it is recorded in the dry run and in
+the result so an unexpected charge is traceable to the call that made it. What
+the tool does refuse outright is paying a non-zero total with no `orderIds`.
+
+### Writes: shapes captured, acceptance unverified
+
+`npm run capture:writes` runs every mutating tool against a local proxy that
+forwards reads to the real service but answers writes itself, so the payloads
+are built from genuine server models and nothing happens upstream. It also
+proves all 13 refuse to send anything without `confirm: true`.
+
+What that established, and corrected: `mhlb_delete_order` and
+`mhlb_unsubscribe_order` take `{orderId, eventDate, studentId, isRepeated,
+isSubscribed}` — not the order model — and checkout takes
+`{orderIds, checkoutType, couponCode, giftCardCode, schoolDonations}`.
+
+**What is still unverified is whether the server accepts these bodies.** Shape
+is not acceptance; only a real write shows that, and none has been made. Inspect
+the dry-run preview before confirming, and re-read afterwards — a `200` is not
+proof a write persisted.
+
+Two limits on `mhlb_checkout` specifically:
+
+- It can only pay with a card **already saved** on the account. Paying with a
+  new card needs a Stripe token minted by Stripe.js in a browser, which no
+  server-side client can produce.
+- It generates an idempotency key and returns it. If a checkout fails
+  ambiguously, retry with that same `idempotencyKey` rather than a fresh call —
+  that is what stops a retry becoming a second charge.
 
 ## Ordering is read-modify-write
 

package/dist/bundle.js

@@ -31891,7 +31891,7 @@ var MhlbClient = class {
 };
 
 // src/version.ts
-var VERSION = "0.2.0";
+var VERSION = "0.2.1";
 
 // src/tools/_shared.ts
 function preview(action, request, notes) {
@@ -32047,6 +32047,24 @@ function registerCalendarTools(server, client2) {
 
 // src/tools/orders.ts
 var OrderModel = external_exports.record(external_exports.string(), external_exports.unknown()).describe("The order model, as returned by mhlb_get_order_form / mhlb_get_order, with quantities and options edited.");
+var OrderRefShape = {
+  orderId: PositiveInt.describe("Order id, from mhlb_get_calendar or mhlb_get_cart."),
+  eventDate: IsoDate.describe("The lunch date of that order (YYYY-MM-DD)."),
+  studentId: PositiveInt.describe("Student the order belongs to."),
+  isRepeated: external_exports.boolean().optional().describe("true acts on the whole recurring series, not just this date. Defaults to false."),
+  isSubscribed: external_exports.boolean().optional().describe(
+    "Whether the order is a subscription. Defaults to false for mhlb_delete_order and true for mhlb_unsubscribe_order, matching what each is for."
+  )
+};
+function orderRefBody(ref) {
+  return {
+    orderId: ref.orderId,
+    eventDate: ref.eventDate,
+    studentId: ref.studentId,
+    isRepeated: ref.isRepeated ?? false,
+    isSubscribed: ref.isSubscribed ?? false
+  };
+}
 function registerOrderTools(server, client2) {
   server.registerTool(
     "mhlb_get_cart",
@@ -32160,18 +32178,17 @@ function registerOrderTools(server, client2) {
     {
       description: "Cancel a lunch order. If it was already paid for, the refund behaviour is whatever My Hot Lunchbox applies \u2014 this tool does not control it." + UNVERIFIED,
       annotations: toolAnnotations({ title: "Delete order", readOnly: false, openWorld: true }),
-      inputSchema: {
-        order: external_exports.record(external_exports.string(), external_exports.unknown()).describe("The order identifier payload, as returned by mhlb_get_order or listed in mhlb_get_cart."),
-        confirm: schemaConfirm
-      }
+      inputSchema: { ...OrderRefShape, confirm: schemaConfirm }
     },
-    async ({ order, confirm }) => {
+    async ({ confirm, ...ref }) => {
+      const body = orderRefBody(ref);
       if (!confirm) {
-        return preview("Delete order", { method: "POST", path: "/event/deleteOrder", body: order }, [
-          "Cancelling a paid order may or may not refund it \u2014 verify on the site afterwards."
+        return preview("Delete order", { method: "POST", path: "/event/deleteOrder", body }, [
+          "Cancelling a paid order may or may not refund it \u2014 verify on the site afterwards.",
+          "isRepeated: true removes the whole recurring series, not just this date."
         ]);
       }
-      return jsonResult(await client2.write("/event/deleteOrder", order));
+      return jsonResult(await client2.write("/event/deleteOrder", body));
     }
   );
 }
@@ -32246,15 +32263,19 @@ function registerBillingTools(server, client2) {
     {
       description: "Stop a recurring subscription for a specific lunch order." + UNVERIFIED,
       annotations: toolAnnotations({ title: "Unsubscribe an order", readOnly: false, openWorld: true }),
-      inputSchema: {
-        order: external_exports.record(external_exports.string(), external_exports.unknown()).describe("The subscription identifier payload, from mhlb_list_subscriptions."),
-        confirm: schemaConfirm
-      }
+      // Same identifier payload as mhlb_delete_order — the site's order-mixin
+      // routes to whichever endpoint by `isSubscribed`, with one body shape.
+      inputSchema: { ...OrderRefShape, confirm: schemaConfirm }
     },
     // The upstream route really is spelled `unsubcribeOrder`.
-    async ({ order, confirm }) => {
-      if (!confirm) return preview("Unsubscribe order", { method: "POST", path: "/event/unsubcribeOrder", body: order });
-      return jsonResult(await client2.write("/event/unsubcribeOrder", order));
+    async ({ confirm, ...ref }) => {
+      const body = orderRefBody({ ...ref, isSubscribed: ref.isSubscribed ?? true });
+      if (!confirm) {
+        return preview("Unsubscribe order", { method: "POST", path: "/event/unsubcribeOrder", body }, [
+          "isRepeated: true stops the whole recurring series, not just this date."
+        ]);
+      }
+      return jsonResult(await client2.write("/event/unsubcribeOrder", body));
     }
   );
   server.registerTool(
@@ -32318,6 +32339,7 @@ function registerBillingTools(server, client2) {
 }
 
 // src/tools/checkout.ts
+import { randomUUID } from "node:crypto";
 function registerCheckoutTools(server, client2) {
   server.registerTool(
     "mhlb_init_checkout",
@@ -32325,62 +32347,76 @@ function registerCheckoutTools(server, client2) {
       description: "Start checkout for the cart: returns the order summary, totals, taxes, applied credits and the available payment methods. This does NOT charge anything \u2014 it is the read step before mhlb_checkout." + UNVERIFIED,
       annotations: toolAnnotations({ title: "Initialise checkout", readOnly: false, openWorld: true }),
       inputSchema: {
-        cart: external_exports.record(external_exports.string(), external_exports.unknown()).describe("The checkout request payload \u2014 the orders to pay for, from mhlb_get_cart."),
+        ...CheckoutShape,
         confirm: schemaConfirm
       }
     },
-    async ({ cart, confirm }) => {
+    async ({ confirm, ...args }) => {
+      const body = checkoutBody(args);
       if (!confirm) {
-        return preview("Initialise checkout", { method: "POST", path: "/payment/initCheckout", body: cart }, [
+        return preview("Initialise checkout", { method: "POST", path: "/payment/initCheckout", body }, [
           "This step prices the cart and returns payment options. It does not charge a card."
         ]);
       }
-      return jsonResult(await client2.write("/payment/initCheckout", cart));
+      return jsonResult(await client2.write("/payment/initCheckout", body));
     }
   );
   server.registerTool(
     "mhlb_checkout",
     {
-      description: "PAY for the lunches in the cart. This charges a real payment method on the My Hot Lunchbox account. Run mhlb_init_checkout first, read the total it returns, and pass that same total as expectedTotal \u2014 the call is refused if it does not match, so a stale cart cannot be paid by accident." + UNVERIFIED,
+      description: "PAY for the lunches in the cart. This charges a real payment method on the My Hot Lunchbox account. Run mhlb_init_checkout first, read the total it returns, and pass that figure as expectedTotal. Only a card ALREADY SAVED on the account can be used: paying with a new card needs a Stripe token minted by Stripe.js in a browser, which no server-side client can produce." + UNVERIFIED,
       annotations: toolAnnotations({ title: "Pay for cart", readOnly: false, openWorld: true }),
       inputSchema: {
-        payment: external_exports.record(external_exports.string(), external_exports.unknown()).describe("The payment payload returned/derived from mhlb_init_checkout."),
-        expectedTotal: external_exports.number().nonnegative().describe("The amount you expect to be charged, exactly as mhlb_init_checkout reported it."),
+        ...CheckoutShape,
+        availableCredits: external_exports.number().nonnegative().optional().describe("Account credit to apply, as parent_credit_value from mhlb_whoami."),
+        idempotencyKey: external_exports.string().min(1).optional().describe(
+          "Reuse the SAME key when retrying a checkout that may already have gone through \u2014 that is what stops a retry becoming a second charge. Generated automatically when omitted."
+        ),
+        expectedTotal: external_exports.number().nonnegative().describe(
+          "The amount you expect to be charged, as mhlb_init_checkout reported it. The server prices the charge from orderIds, so no client-side check can bind the amount \u2014 this is recorded in the dry run and in the result so an unexpected charge is at least attributable."
+        ),
         confirm: schemaConfirm
       }
     },
-    async ({ payment, expectedTotal, confirm }) => {
-      const stated = findTotal(payment);
+    async ({ availableCredits, idempotencyKey, expectedTotal, confirm, ...args }) => {
+      const key = idempotencyKey ?? `${randomUUID()}-${Date.now()}`;
+      const body = {
+        ...checkoutBody(args),
+        ...availableCredits !== void 0 ? { availableCredits } : {},
+        idempotencyKey: key
+      };
       if (!confirm) {
-        return preview("Pay for cart", { method: "POST", path: "/payment/checkout", body: payment }, [
+        return preview("Pay for cart", { method: "POST", path: "/payment/checkout", body }, [
           `This CHARGES a payment method. Expected total: ${expectedTotal}.`,
-          stated === null ? "No total field was found in the payload, so the amount cannot be cross-checked before sending." : `Total found in the payload: ${stated}.`
+          "No stripeToken is sent, so this can only pay with a card already saved on the account. Paying with a NEW card needs a Stripe token minted by Stripe.js in a browser, which no server-side client can produce \u2014 do that on the site.",
+          `Idempotency key for this attempt: ${key}. Reuse it if you retry.`
         ]);
       }
-      if (stated !== null && !nearlyEqual(stated, expectedTotal)) {
-        return jsonResult({
-          charged: false,
-          reason: "expectedTotal does not match the total in the payment payload.",
-          expectedTotal,
-          payloadTotal: stated,
-          hint: "Re-run mhlb_init_checkout to reprice the cart, then retry with the total it reports."
+      if (expectedTotal > 0 && args.orderIds.length === 0) {
+        throw new McpToolError("Refusing to pay: no orderIds were given.", {
+          hint: "Pass the orderIds mhlb_init_checkout priced, so the charge is bound to specific orders."
         });
       }
-      return jsonResult(await client2.write("/payment/checkout", payment));
+      const result = await client2.write("/payment/checkout", body);
+      return jsonResult({ result, expectedTotal, idempotencyKey: key });
     }
   );
 }
-function nearlyEqual(a, b) {
-  return Math.abs(a - b) < 5e-3;
-}
-function findTotal(payload) {
-  const candidates = ["totalPrice", "total", "amount", "grandTotal", "totalAmount", "amountToPay"];
-  for (const key of candidates) {
-    const value = payload[key];
-    if (typeof value === "number" && Number.isFinite(value)) return value;
-    if (typeof value === "string" && value.trim() !== "" && Number.isFinite(Number(value))) return Number(value);
-  }
-  return null;
+var CheckoutShape = {
+  orderIds: external_exports.array(PositiveInt).describe("Ids of the orders to pay for, from mhlb_get_cart."),
+  checkoutType: external_exports.union([external_exports.number().int(), external_exports.string()]).optional().describe("Payment method type, as mhlb_init_checkout reports it. Omit to let the server default."),
+  couponCode: external_exports.string().optional().describe("Coupon code to apply to this checkout."),
+  giftCardCode: external_exports.string().optional().describe("Gift card code to apply to this checkout."),
+  schoolDonations: external_exports.unknown().optional().describe("School donation selections, as returned by mhlb_init_checkout.")
+};
+function checkoutBody(args) {
+  return {
+    orderIds: args.orderIds,
+    checkoutType: args.checkoutType ?? null,
+    couponCode: args.couponCode ?? null,
+    giftCardCode: args.giftCardCode ?? null,
+    schoolDonations: args.schoolDonations ?? null
+  };
 }
 
 // src/tools/reports.ts

package/dist/tools/billing.js

@@ -1,6 +1,7 @@
 import { toolAnnotations, PositiveInt, NonEmptyString, schemaConfirm } from '@chrischall/mcp-utils';
 import { z } from 'zod';
 import { jsonResult, preview, UNVERIFIED } from './_shared.js';
+import { OrderRefShape, orderRefBody } from './orders.js';
 export function registerBillingTools(server, client) {
     server.registerTool('mhlb_list_transactions', {
         description: 'List payment transactions on the account — date, amount, and what was paid for.',
@@ -44,18 +45,19 @@ export function registerBillingTools(server, client) {
     server.registerTool('mhlb_unsubscribe_order', {
         description: 'Stop a recurring subscription for a specific lunch order.' + UNVERIFIED,
         annotations: toolAnnotations({ title: 'Unsubscribe an order', readOnly: false, openWorld: true }),
-        inputSchema: {
-            order: z
-                .record(z.string(), z.unknown())
-                .describe('The subscription identifier payload, from mhlb_list_subscriptions.'),
-            confirm: schemaConfirm,
-        },
+        // Same identifier payload as mhlb_delete_order — the site's order-mixin
+        // routes to whichever endpoint by `isSubscribed`, with one body shape.
+        inputSchema: { ...OrderRefShape, confirm: schemaConfirm },
     }, 
     // The upstream route really is spelled `unsubcribeOrder`.
-    async ({ order, confirm }) => {
-        if (!confirm)
-            return preview('Unsubscribe order', { method: 'POST', path: '/event/unsubcribeOrder', body: order });
-        return jsonResult(await client.write('/event/unsubcribeOrder', order));
+    async ({ confirm, ...ref }) => {
+        const body = orderRefBody({ ...ref, isSubscribed: ref.isSubscribed ?? true });
+        if (!confirm) {
+            return preview('Unsubscribe order', { method: 'POST', path: '/event/unsubcribeOrder', body }, [
+                'isRepeated: true stops the whole recurring series, not just this date.',
+            ]);
+        }
+        return jsonResult(await client.write('/event/unsubcribeOrder', body));
     });
     server.registerTool('mhlb_list_gift_cards', {
         description: 'List gift cards on the account — codes, balances and status.',

package/dist/tools/checkout.js

@@ -1,12 +1,17 @@
-import { toolAnnotations, schemaConfirm } from '@chrischall/mcp-utils';
+import { randomUUID } from 'node:crypto';
+import { McpToolError, toolAnnotations, PositiveInt, schemaConfirm } from '@chrischall/mcp-utils';
 import { z } from 'zod';
 import { jsonResult, preview, UNVERIFIED } from './_shared.js';
 /**
  * Checkout is the only pair of tools that moves money. Both are confirm-gated
- * like every other write, and `mhlb_checkout` additionally requires the caller
- * to restate the amount it believes it is paying: a stale cart read that no
- * longer matches the server's total fails closed instead of silently charging
- * a different figure.
+ * like every other write.
+ *
+ * There is deliberately no amount check. The server prices the charge from
+ * `orderIds`; the request carries no total, so anything compared here would be
+ * the caller's own input against itself. `expectedTotal` is attribution — it is
+ * echoed in the dry run and returned with the result, so a surprising charge is
+ * traceable to the call that made it. The one real refusal is paying a non-zero
+ * total with no `orderIds`.
  */
 export function registerCheckoutTools(server, client) {
     server.registerTool('mhlb_init_checkout', {
@@ -15,73 +20,105 @@ export function registerCheckoutTools(server, client) {
             UNVERIFIED,
         annotations: toolAnnotations({ title: 'Initialise checkout', readOnly: false, openWorld: true }),
         inputSchema: {
-            cart: z
-                .record(z.string(), z.unknown())
-                .describe('The checkout request payload — the orders to pay for, from mhlb_get_cart.'),
+            ...CheckoutShape,
             confirm: schemaConfirm,
         },
-    }, async ({ cart, confirm }) => {
+    }, async ({ confirm, ...args }) => {
+        const body = checkoutBody(args);
         if (!confirm) {
-            return preview('Initialise checkout', { method: 'POST', path: '/payment/initCheckout', body: cart }, [
+            return preview('Initialise checkout', { method: 'POST', path: '/payment/initCheckout', body }, [
                 'This step prices the cart and returns payment options. It does not charge a card.',
             ]);
         }
-        return jsonResult(await client.write('/payment/initCheckout', cart));
+        return jsonResult(await client.write('/payment/initCheckout', body));
     });
     server.registerTool('mhlb_checkout', {
         description: 'PAY for the lunches in the cart. This charges a real payment method on the My Hot Lunchbox account. ' +
-            'Run mhlb_init_checkout first, read the total it returns, and pass that same total as expectedTotal — ' +
-            'the call is refused if it does not match, so a stale cart cannot be paid by accident.' + UNVERIFIED,
+            'Run mhlb_init_checkout first, read the total it returns, and pass that figure as expectedTotal. ' +
+            'Only a card ALREADY SAVED on the account can be used: paying with a new card needs a Stripe token ' +
+            'minted by Stripe.js in a browser, which no server-side client can produce.' + UNVERIFIED,
         annotations: toolAnnotations({ title: 'Pay for cart', readOnly: false, openWorld: true }),
         inputSchema: {
-            payment: z
-                .record(z.string(), z.unknown())
-                .describe('The payment payload returned/derived from mhlb_init_checkout.'),
+            ...CheckoutShape,
+            availableCredits: z
+                .number()
+                .nonnegative()
+                .optional()
+                .describe('Account credit to apply, as parent_credit_value from mhlb_whoami.'),
+            idempotencyKey: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('Reuse the SAME key when retrying a checkout that may already have gone through — that is what ' +
+                'stops a retry becoming a second charge. Generated automatically when omitted.'),
             expectedTotal: z
                 .number()
                 .nonnegative()
-                .describe('The amount you expect to be charged, exactly as mhlb_init_checkout reported it.'),
+                .describe('The amount you expect to be charged, as mhlb_init_checkout reported it. The server prices the ' +
+                'charge from orderIds, so no client-side check can bind the amount — this is recorded in the ' +
+                'dry run and in the result so an unexpected charge is at least attributable.'),
             confirm: schemaConfirm,
         },
-    }, async ({ payment, expectedTotal, confirm }) => {
-        const stated = findTotal(payment);
+    }, async ({ availableCredits, idempotencyKey, expectedTotal, confirm, ...args }) => {
+        // The site generates this client-side as `${randomUUID()}-${Date.now()}`
+        // (form-mixin's getKey) and holds it in session storage across retries.
+        const key = idempotencyKey ?? `${randomUUID()}-${Date.now()}`;
+        const body = {
+            ...checkoutBody(args),
+            ...(availableCredits !== undefined ? { availableCredits } : {}),
+            idempotencyKey: key,
+        };
         if (!confirm) {
-            return preview('Pay for cart', { method: 'POST', path: '/payment/checkout', body: payment }, [
+            return preview('Pay for cart', { method: 'POST', path: '/payment/checkout', body }, [
                 `This CHARGES a payment method. Expected total: ${expectedTotal}.`,
-                stated === null
-                    ? 'No total field was found in the payload, so the amount cannot be cross-checked before sending.'
-                    : `Total found in the payload: ${stated}.`,
+                'No stripeToken is sent, so this can only pay with a card already saved on the account. ' +
+                    'Paying with a NEW card needs a Stripe token minted by Stripe.js in a browser, which no ' +
+                    'server-side client can produce — do that on the site.',
+                `Idempotency key for this attempt: ${key}. Reuse it if you retry.`,
             ]);
         }
-        if (stated !== null && !nearlyEqual(stated, expectedTotal)) {
-            return jsonResult({
-                charged: false,
-                reason: 'expectedTotal does not match the total in the payment payload.',
-                expectedTotal,
-                payloadTotal: stated,
-                hint: 'Re-run mhlb_init_checkout to reprice the cart, then retry with the total it reports.',
+        if (expectedTotal > 0 && args.orderIds.length === 0) {
+            throw new McpToolError('Refusing to pay: no orderIds were given.', {
+                hint: 'Pass the orderIds mhlb_init_checkout priced, so the charge is bound to specific orders.',
             });
         }
-        return jsonResult(await client.write('/payment/checkout', payment));
+        // Nested, not spread: the response shape is unverified, so spreading it
+        // would mangle a non-object and would let `expectedTotal`/`idempotencyKey`
+        // silently shadow same-named server fields.
+        const result = await client.write('/payment/checkout', body);
+        return jsonResult({ result, expectedTotal, idempotencyKey: key });
     });
 }
-/** Amounts within a cent are equal — the API and the caller may round differently. */
-function nearlyEqual(a, b) {
-    return Math.abs(a - b) < 0.005;
-}
 /**
- * Find the payable amount in a checkout payload. Field naming is not verified
- * against a live checkout, so several plausible spellings are accepted; when
- * none is present the cross-check is skipped rather than guessed at.
+ * The checkout payload the site actually sends, captured from its own
+ * `checkout` route chunk:
+ *   initCheckout {orderIds, checkoutType, couponCode, giftCardCode, schoolDonations}
+ *   checkout     … the same, plus {availableCredits, idempotencyKey, stripeToken}
+ *
+ * `stripeToken` is deliberately absent here: the site only sets it when paying
+ * by a NEW card, and it comes from `Stripe.createToken` in the browser. With a
+ * card already saved on the account it is left undefined, which is the only
+ * case a server-side client can serve.
  */
-export function findTotal(payload) {
-    const candidates = ['totalPrice', 'total', 'amount', 'grandTotal', 'totalAmount', 'amountToPay'];
-    for (const key of candidates) {
-        const value = payload[key];
-        if (typeof value === 'number' && Number.isFinite(value))
-            return value;
-        if (typeof value === 'string' && value.trim() !== '' && Number.isFinite(Number(value)))
-            return Number(value);
-    }
-    return null;
+const CheckoutShape = {
+    orderIds: z
+        .array(PositiveInt)
+        .describe('Ids of the orders to pay for, from mhlb_get_cart.'),
+    checkoutType: z
+        .union([z.number().int(), z.string()])
+        .optional()
+        .describe('Payment method type, as mhlb_init_checkout reports it. Omit to let the server default.'),
+    couponCode: z.string().optional().describe('Coupon code to apply to this checkout.'),
+    giftCardCode: z.string().optional().describe('Gift card code to apply to this checkout.'),
+    schoolDonations: z.unknown().optional().describe('School donation selections, as returned by mhlb_init_checkout.'),
+};
+function checkoutBody(args) {
+    // The site sends these keys explicitly with null rather than omitting them.
+    return {
+        orderIds: args.orderIds,
+        checkoutType: args.checkoutType ?? null,
+        couponCode: args.couponCode ?? null,
+        giftCardCode: args.giftCardCode ?? null,
+        schoolDonations: args.schoolDonations ?? null,
+    };
 }

package/dist/tools/orders.js

@@ -11,6 +11,39 @@ import { jsonResult, preview, UNVERIFIED } from './_shared.js';
 const OrderModel = z
     .record(z.string(), z.unknown())
     .describe('The order model, as returned by mhlb_get_order_form / mhlb_get_order, with quantities and options edited.');
+/**
+ * Cancelling and unsubscribing take a small identifier payload — NOT the order
+ * model the create/edit pair round-trips. Captured from the site's own
+ * `order-mixin`, which builds exactly
+ * `{orderId, isRepeated, eventDate, studentId, isSubscribed}`.
+ *
+ * Spelling this out rather than accepting an opaque record is the point: an
+ * agent handed "the order payload" sends the 40-field model, which is not what
+ * these endpoints read.
+ */
+export const OrderRefShape = {
+    orderId: PositiveInt.describe('Order id, from mhlb_get_calendar or mhlb_get_cart.'),
+    eventDate: IsoDate.describe('The lunch date of that order (YYYY-MM-DD).'),
+    studentId: PositiveInt.describe('Student the order belongs to.'),
+    isRepeated: z
+        .boolean()
+        .optional()
+        .describe('true acts on the whole recurring series, not just this date. Defaults to false.'),
+    isSubscribed: z
+        .boolean()
+        .optional()
+        .describe('Whether the order is a subscription. Defaults to false for mhlb_delete_order and true for ' +
+        'mhlb_unsubscribe_order, matching what each is for.'),
+};
+export function orderRefBody(ref) {
+    return {
+        orderId: ref.orderId,
+        eventDate: ref.eventDate,
+        studentId: ref.studentId,
+        isRepeated: ref.isRepeated ?? false,
+        isSubscribed: ref.isSubscribed ?? false,
+    };
+}
 export function registerOrderTools(server, client) {
     server.registerTool('mhlb_get_cart', {
         description: 'Get the shopping cart — lunches added but not yet paid for. Filter by order status and ordering period, ' +
@@ -97,18 +130,15 @@ export function registerOrderTools(server, client) {
         description: 'Cancel a lunch order. If it was already paid for, the refund behaviour is whatever My Hot Lunchbox ' +
             'applies — this tool does not control it.' + UNVERIFIED,
         annotations: toolAnnotations({ title: 'Delete order', readOnly: false, openWorld: true }),
-        inputSchema: {
-            order: z
-                .record(z.string(), z.unknown())
-                .describe('The order identifier payload, as returned by mhlb_get_order or listed in mhlb_get_cart.'),
-            confirm: schemaConfirm,
-        },
-    }, async ({ order, confirm }) => {
+        inputSchema: { ...OrderRefShape, confirm: schemaConfirm },
+    }, async ({ confirm, ...ref }) => {
+        const body = orderRefBody(ref);
         if (!confirm) {
-            return preview('Delete order', { method: 'POST', path: '/event/deleteOrder', body: order }, [
+            return preview('Delete order', { method: 'POST', path: '/event/deleteOrder', body }, [
                 'Cancelling a paid order may or may not refund it — verify on the site afterwards.',
+                'isRepeated: true removes the whole recurring series, not just this date.',
             ]);
         }
-        return jsonResult(await client.write('/event/deleteOrder', order));
+        return jsonResult(await client.write('/event/deleteOrder', body));
     });
 }

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

package/mint.yaml

@@ -1,10 +1,13 @@
-# How this MCP wants to be hosted on mcp-host (see mcp-host/docs/HOSTING-MANIFEST.md).
+# How this MCP wants to be hosted on mcp-host — the file its registration
+# preview reads to fill the wizard in, instead of someone guessing from the
+# README (mcp-host's own docs describe the format).
 #
-# The FILENAME is load-bearing: mcp-host matches it exactly, against
-# HOSTING_MANIFEST_FILE in packages/core/src/hosting-manifest-schema.ts. A name
-# the reader does not expect is not an error — it is simply never found, and the
-# registration preview falls back to inference with nothing to notice. If this
-# file ever looks ignored, check that constant first.
+# The FILENAME is load-bearing: the reader matches it exactly, and a name it
+# does not expect is not an error — it is simply never found, and the preview
+# falls back to inference with nothing to notice. The reader accepts the older
+# `mcp-host.yaml` as well, so the two names coexist. If this file ever looks
+# ignored, check the manifest-filename constant in mcp-host's core package
+# before looking anywhere else.
 #
 # This file is a PROPOSAL, never an application. It is read at the resolved pin
 # by the registration preview and rendered for a human; nothing here changes a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "myhotlunchbox-mcp",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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>",
@@ -40,7 +40,9 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage"
+    "test:coverage": "vitest run --coverage",
+    "verify:reads": "node scripts/verify-reads.mjs",
+    "capture:writes": "node scripts/capture-writes.mjs"
   },
   "dependencies": {
     "@chrischall/mcp-utils": "^0.15.0",

package/server.json

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

package/skills/myhotlunchbox/references/endpoints.md

@@ -128,7 +128,7 @@ model, edit it, post it back whole, then re-read to confirm.
 |---|---|---|
 | Place an order | `GET /event/createOrder?eventId=&studentId=` | `POST /event/createOrder` |
 | Change an order | `GET /event/editOrder?orderId=` | `POST /event/editOrder` |
-| Cancel an order | — | `POST /event/deleteOrder` |
+| Cancel an order | — | `POST /event/deleteOrder` — body below, **not** the order model |
 | Add a student | `GET /parent/createChild` | `POST /parent/createChild` |
 | Edit a student | `GET /parent/editChild?childId=` | `POST /parent/editChild` |
 | Remove a student | — | `POST /parent/deleteChild?id=` |
@@ -136,12 +136,39 @@ model, edit it, post it back whole, then re-read to confirm.
 | Apply a coupon | — | `POST /parent/applyCoupon?couponCode=` |
 | Remove the coupon | — | `POST /parent/removeCoupon` |
 | Toggle subscriptions | `GET /event/subscription` | `POST /parent/changeSubscriptionStatus?isEnableSubscription=` |
-| Stop one subscription | `GET /event/upcomingSubscriptions` | `POST /event/unsubcribeOrder` |
+| Stop one subscription | `GET /event/upcomingSubscriptions` | `POST /event/unsubcribeOrder` — same body as deleteOrder |
 | Price the cart | — | `POST /payment/initCheckout` |
 | **Pay** | — | `POST /payment/checkout` |
 
 `POST /event/unsubcribeOrder` is spelled that way upstream — the typo is theirs.
 
+Cancelling and unsubscribing take a small identifier payload, **not** the order
+model that create/edit round-trip. Captured from the site's own `order-mixin`:
+
+```sh
+# isRepeated: true acts on the whole recurring series, not just this date.
+mhlb_post /event/deleteOrder \
+  '{"orderId":17284377,"eventDate":"2026-08-26","studentId":111627,"isRepeated":false,"isSubscribed":false}'
+```
+
+Checkout takes `{orderIds, checkoutType, couponCode, giftCardCode, schoolDonations}`,
+with the nulls sent explicitly, plus `{availableCredits, idempotencyKey, stripeToken}`
+on `/payment/checkout`:
+
+```sh
+mhlb_post /payment/initCheckout \
+  '{"orderIds":[123],"checkoutType":null,"couponCode":null,"giftCardCode":null,"schoolDonations":null}'
+```
+
+Two things about paying:
+
+- **`stripeToken` cannot be produced outside a browser.** The site mints it with
+  Stripe.js, and only when paying by a NEW card. Server-side you can only pay
+  with a card already saved on the account.
+- **`idempotencyKey` is yours to generate** — the site uses
+  `"$(uuidgen | tr A-Z a-z)-$(date +%s000)"`. Reuse the SAME key when retrying an
+  ambiguous checkout; a fresh one risks a second charge.
+
 `POST /payment/checkout` charges a real payment method. Price with
 `initCheckout` first, read the total it returns, and confirm that figure before
 paying.