myhotlunchbox-mcp: Instructions file for Claude Code

myhotlunchbox-mcp

Repo-specific notes. Fleet-wide conventions live in ~/.claude/CLAUDE.md and are deliberately not restated here.

Archetype

Server-side OAuth2 password grant — not a browser bridge, not a captured cookie. ordernow.myhotlunchbox.com has no bot wall and no CAPTCHA, so MYHOTLUNCHBOX_USERNAME + MYHOTLUNCHBOX_PASSWORD are the whole configuration. Do not add a @fetchproxy/server dependency; nothing here needs one.

offline_access in the scope is load-bearing — it is what yields the refresh token. Drop it and every session needs the password again.

Never retry a rejected credential

/api/auth/login is OpenIddict. A failed attempt is counted, and repeated failures can escalate to a CAPTCHA that removes server-side sign-in for the account permanently. MhlbAuth.postGrant throws on the first rejection by design — do not add a retry loop around it.

The password has no shape

redactSecrets matches secret shapes (Bearer, JWT, sk-). A password matches none of them. Every error path that renders an upstream body goes through truncateErrorMessage(text, max, { values: [password] }), which splices the literal value out (raw and JSON-escaped) before it cuts, so no half of it survives at the boundary. tests/auth.test.ts and tests/client.test.ts assert the outcome (the password is absent from the message), not that the wrapper was called — the wrapper alone would have passed while still leaking.

Ordering is read-modify-write

GET /event/createOrder returns a model; POST /event/createOrder takes it back. Same for editOrder, createChild, editChild. The site's own compiled client passes these through opaquely and never names the fields, so the tools do the same rather than inventing a schema. These are whole-record replaces.

Field names the extraction got wrong

Four things the compiled-client extraction could not tell us, all found by running against a real account. Do not "simplify" any of them back:

• /calendar/studentSchoolData takes start/end, not startDate/endDate. Wrong names return 200 with an empty events array — a silent wrong answer. tests/tools.test.ts pins this.
• /parentReports/print* return binary PDF, not JSON — hence MhlbClient.writeBinary. Their payloads are not date ranges: printCalendar needs middle (the midpoint date), printOrders takes a single eventDate plus a non-empty studentIds, and printTransactions takes a whole transaction record.
• printOrders answers 500, not 4xx, for an empty studentIds or a date with no matching order. writeBinary words its 500 hint accordingly — do not replace it with a generic UnreachableError.
• Order status enum: Pending: 0, Paid: 1, Credited: 2.