hujjun/mcd-saver-strategist

What it is

mcd‑saver‑strategist is a WorkBuddy skill that acts as a virtual “price‑calculator” for McDonald’s China. When a user asks something like “I want a Big Mac combo, how can I get it cheapest?” the skill:

1. Calls the McDonald’s China MCP API to fetch the current menu, prices, nutrition data and all coupons available to the user’s account.
2. Normalises that data into a JSON request.
3. Runs a deterministic combinatorial optimizer (scripts/optimizer.py) that enumerates every legal combination of items and coupons respecting the MCP’s stacking rules, budget or calorie limits.
4. Returns the top‑N lowest‑price, compliant combos and, if the user confirms, creates the order through MCP.

It is a contest entry (McDonald’s Programmer Creative Development Contest) and not an official McDonald’s product.

---

Quick install

# clone the repo
git clone https://github.com/hujjun/mcd-saver-strategist.git

# copy the skill into your WorkBuddy skill directory
cp -r mcd-saver-strategist/skills/mcd-saver-strategist ~/.workbuddy/skills/

Windows users copy to %USERPROFILE%\.workbuddy\skills\.

You also need a MCP token (see the README’s “申请麦当劳 MCP Token” section) and configure it via WorkBuddy’s 连接器 → 自定义连接器 → 配置 MCP using the provided mcp-config.example.json.

---

How to use

• In conversation: say something like “我想吃巨无霸套餐，怎么点最便宜”.
• The agent fetches the menu and the four‑way coupon pool, runs the optimizer and replies with the cheapest feasible combination (e.g. “1+1 随心配 ¥12.9 + 可乐 ¥9 = ¥21.90, saved ¥25.10”).
• You can add constraints:
  • budget=30 → shows the best meals under ¥30.
  • max_calories=800 → returns low‑calorie, cheap combos.
  • delivery mode → includes delivery fee and filters out coupons that are only for in‑store pickup.
• When you confirm, the skill calls MCP’s calculate-price to verify the final price and then create-order to place the order.

---

Command‑line demo (no token needed)

The repository ships a small offline data set so you can try the optimizer locally:

cd skills/mcd-saver-strategist/scripts
python optimizer.py                 # default in‑store scenario
python optimizer.py --json          # also output JSON
python optimizer.py --mode delivery --fee 9   # delivery fee included
python optimizer.py --budget 25
python optimizer.py --max-calories 800
python selftest.py                  # runs 19 built‑in tests

---

Technical highlights

Feature	Detail
Deterministic optimizer	Pure‑Python, standard‑library only; exhaustive search with pruning to respect MCP’s stacking rules (stackable:false means mutually exclusive).
Zero external dependencies	Works inside WorkBuddy’s sandbox and in the static web demo (docs/index.html).
MCP integration	Uses MCP endpoints for menu, coupons, nutrition, price verification and order creation.
Scenario awareness	Coupons carry a channel field (pickup, delivery, any). The optimizer automatically filters by the chosen scenario and adds delivery fees when needed.
Budget / calorie constraints	Simple linear constraints that the optimizer can honour while still finding the global minimum price.
Self‑test suite	selftest.py contains 19 assertions covering edge cases (empty coupon list, conflicting coupons, etc.).
Online interactive demo	A GitHub‑Pages page (docs/index.html) reproduces the same logic in the browser; users can drag sliders for budget and calories and see results instantly.

---

Who might find it useful

• Students or office workers who want the cheapest McDonald’s meal without manually juggling coupons.
• Fitness/weight‑loss enthusiasts needing low‑calorie options on a budget.
• Groups ordering multiple meals and needing to stay within a total spend.
• “Coupon hunters” who have many coupons and need the optimal combination.

---

License

MIT (see LICENSE).