mcd-coupon-strategist

市面上的省钱工具都在回答「这一单怎么点最省」。 我们多回答一个问题：「你正在白扔多少钱？」

快速体验 · 真实例子 · 核心亮点 · 架构 · 设计原则

---

基于麦当劳中国 MCP 打造的点餐成本助手，做两件事：

短期 —— 这一单怎么点最省

• 拉取当前门店的实时菜单与价格
• 拉取你账户里当前门店可用的优惠券
• 枚举「单品 / 套餐 / 券组合 / 加购凑单」的候选方案
• 用 MCP 的 calculate-price 逐方案真实计价（而不是猜）
• 输出最省钱的方案，以及为什么不推荐更便宜但吃不饱的选项

长期 —— 你白扔了多少钱

• 券的沉默成本：你手里有几张券即将过期？那就是正在流失的钱
• 消费习惯画像：近 N 个月花了多少、客单价是否偏高、哪些单品该改成套餐
• 数据来自 order-list 历史订单 + query-my-coupons 券存量

---

快速体验（30 秒）

git clone https://github.com/Ayzzz123/mcd-coupon-strategist.git
cd mcd-coupon-strategist
python demo.py

零第三方依赖（只用标准库）、不需要 MCP Token、不联网。 demo.py 读取 fixtures/ 里录制的真实 MCP 响应，跑通两条链路：

链路 A · 单次省钱
门店：麦当劳南京东城汇餐厅(1990622)（到店自取）
需求：想吃「汉堡 + 薯条 + 可乐」，预算 40 元

推荐方案
  组合：套餐：麦辣鸡腿汉堡三件套
  实付 33.5 元

超预算（仅供对照）
  · 单点：麦辣鸡腿汉堡 + 薯条 + 可乐 —— 实付 46.5 元，比推荐方案贵 13.0 元

  → 这个价差来自套餐结构本身，不需要任何优惠券 —— 这是最稳的省法。

链路 B · 消费审计
券：当前门店可用 2 张，卡包里持有 9 张 —— 沉默成本按后者算

【一】券的沉默成本
  你的券有风险：9 张将在 7 天内陆续过期（面值 21.1 元）；
  另有 7 张的券面价值无法从菜单推算，未计入面值。

  优先处理这几张：
    · 大脆鸡扒堡早餐两件套  价值未知（菜单中无对应商品，未估算）  还剩 1 天
      仅 05:00-10:29 可用 · 到店专用
    · 中薯条买一送一  省 14.5 元  还剩 2 天
    · 王牌小食拼  省 6.6 元  还剩 2 天
    …… 另有 6 张（为控制篇幅未展开）

【二】消费习惯
  订单数：8 单（其中 2 笔 0 元）
  总支出：103.5 元
  客单价：17.25 元（按 6 笔有支出的订单计算）

  时段分布：
    早餐 · 4 单（2 笔有支出） · 支出 58.9 元 · 样本不足 3 笔，未估算客单价
    下午 · 1 单 · 支出 1.0 元 · 样本不足 3 笔，未估算客单价
    晚市 · 3 单 · 支出 43.6 元 · 客单价 14.53 元

本月最该做的事：先把 21.1 元的券用掉，
这笔钱不用就是纯损失。
另外 7 张券同样要过期，但券面价值还没算出来 —— 看清它们的时间和限制，别让它们悄悄走掉。

券包体检
  名义总额 ¥21.1（9 张） → 可实现 ¥21.1
【顺手可用】2 张 · 净省 ¥21.1
  · 中薯条买一送一    净省 14.5 元    还剩 2 天
  · 王牌小食拼    净省 6.6 元    还剩 2 天

【无法判断】7 张
  · 大脆鸡扒堡早餐两件套    菜单中无对应商品，未估算    还剩 1 天
  ……

用券排程
  窗口 2 天（券全部过期前） · 点单频率 0.089 单/天
  → 这期间你大概只会点 1 单，最多用掉 1 张券
    第 1 单 → 中薯条买一送一    净赚 14.5 元
  排不上（1 张 · 可实现 ¥6.6）
    · 王牌小食拼    净价值 6.6 元    还剩 2 天
  券包可实现 ¥21.1，但机会只够用掉 ¥14.5 —— 剩下 ¥6.6 注定随券过期浪费。

  麦麦省共 7 条券记录：已领取 4 条、可领取 3 条（同名去重后）

可领取的券
  你还有 3 张券没领（领取免费）

【无法判断】3 张
  · 免费脆薯饼    菜单中无对应商品，未估算
  · 人气麦旋风买一送一    菜单中无对应商品，未估算
  · 9.9元中杯冰美式    菜单中无对应商品，未估算

  3 张的价值无法从券面推算 —— 我们不猜；领取后可以用「带券计价」实测出精确价值。
  另外别忘了机会有限：上面排程算出，窗口内的点单机会已被你手里的券占满 ——
  券不是越多越好，用得上才算数。

活动节奏
  10 月日历里有 14 天有活动：已过 2 天 · 今天 1 天 · 之后 11 天
  最近一次：10月15日（明天）
    · 麦当劳 X PEACEMINUSONE

  说明：「有活动」不等于「更便宜」。
       活动内容里的价格是营销文案，无法核实，本工具不拿它做计算。
       所以这里只给时间线，值不值得等要你结合活动内容自己判断。

  你手里的券撑得到 10月15日 吗（纯日期比较）：
    · 中薯条买一送一    10月16日到期（还剩 2 天）    → 等得到
    · 王牌小食拼    10月16日到期（还剩 2 天）    → 等得到

积分体检
  可用 376.3 积分 · 累计 581.3 · 已用 188
  ⚠️ 已过期 17 积分 —— 已发生的损失

  积分商城 24 个商品：9 个仍在兑换期内（其中 6 个换得起），15 个已过兑换期

【现在就能换】
  · 6.9元可乐麦炫酷    需 50 积分    还剩 77 天
  · 3.9元圆筒冰淇淋    需 100 积分    还剩 77 天
  · 16.9元2份麦辣鸡翅    需 200 积分    还剩 77 天

【同款不同价 · 换便宜的那个】
  · 10.9元指定小食任选 —— 一个要 200 积分，一个只要 100 积分，差 100

【已过兑换期】15 个
  这些商品的接口状态仍标着「上架」，但兑换截止日已经过去 ——
  只看状态会以为还能换。

上面那 3 张全是「价值未知」不是解析失败，是数据事实：这份菜单快照采集于 21:59，而脆薯饼、冰美式并不在该时段的菜单里。我们没有为了让 demo 好看 而往菜单里塞一个能匹配上的商品名 —— 原因与验证方式见 fixtures/README.md。

上面这段输出为便于阅读做了删减（省略了分隔线、以及「积分还不够」等重复项）， 完整输出请直接跑 python demo.py。

真实运行时，这些响应由 MCP 实时返回，业务逻辑一字未改 —— 所以这个 demo 同时也是整套数据流水线的端到端回归测试。 数据来源与采集时间见 fixtures/README.md。

---

一个真实例子

同一个账号，同一个门店，两种问法：

问「今天怎么点最省」 →

推荐方案
  组合：套餐：麦辣鸡腿汉堡三件套
  实付 33.5 元

超预算（仅供对照）
  · 单点：麦辣鸡腿汉堡 + 薯条 + 可乐 —— 实付 46.5 元，比推荐方案贵 13.0 元

同样吃到「汉堡 + 薯条 + 可乐」：套餐 33.5 元，单点 46.5 元，差 13 元 —— 而单点那条已经超出 40 元预算，所以它是对照，不是备选。

问「我最近在麦当劳花了多少」 →

【一】券的沉默成本
  你的券有风险：9 张将在 7 天内陆续过期（面值 21.1 元）；
  另有 7 张的券面价值无法从菜单推算，未计入面值。
  优先处理这几张：
    · 大脆鸡扒堡早餐两件套  价值未知  还剩 1 天
      仅 05:00-10:29 可用 · 到店专用
    · 中薯条买一送一  省 14.5 元  还剩 2 天
    · 王牌小食拼  省 6.6 元  还剩 2 天

【二】消费习惯
  订单数：8 单（其中 2 笔 0 元）
  总支出：103.5 元
  客单价：17.25 元（按 6 笔有支出的订单计算）
  洞察：
    · 近 3 个月你在麦当劳共消费 103.5 元，其中 6 笔有实际支出，平均每单 17.25 元。
    · 另有 2 笔 0 元订单（多为券核销或积分兑换）—— 不计入客单价，但算作一次点单机会。
    · 还有 2 笔「部分退款」订单 —— 接口不返回退款金额，无法确认 realTotalAmount 是退款前还是退款后的口径，上面的支出可能略偏高。

本月最该做的事：先把 21.1 元的券用掉，这笔钱不用就是纯损失。

第二个问题的价值不在这一次的数字大小，而在于它是持续性的： 第一个问题每单只影响一次；第二个问题每次都会告诉你又有什么在悄悄过期 —— 而这是一次性工具永远给不出的答案。

注意「王牌小食拼」那个 6.6 元：这张券的标题里没有数字，菜单里也没有对应商品， 靠反查原价这条路根本走不通。它的价值是把券的商品码传给 calculate-price 实测出来的 —— 而不是估一个「差不多」的数。

这两段输出与 python demo.py 的结果逐字一致 —— 你可以自己跑一遍验证。

---

我们做对了什么别人没做的

省钱类工具已经很多了，多到这次比赛报名里就有好几支在做同一件事。所以先说清楚我们的不同点到底在哪：

差异化内核：别处都在帮用户花钱，我们在帮用户止损。 下单前省的那几块钱是「收益」，快过期的券是「损失」—— 人对损失的敏感度是对收益的两倍，而这个数字从来没人给他算过。

关键实现：怎么知道一张券真值多少钱

「券的沉默成本」要成立，前提是得知道每张券真实值多少钱。而 MCP 返回的券通常只有名字，没有面值：

「中薯条买一送一」  →  值多少钱？
「9.9元中杯冰美式」 →  值多少钱？
「王牌小食拼」      →  值多少钱？

首选：直接问收银台。 把券自带的商品码连同 couponId 传给 calculate-price， 返回的 discount 就是这张券的精确价值，price 就是用券实付：

兜底：从菜单反查原价（拿不到券的商品码时用）：

为什么首选实测：「王牌小食拼」标题里没有数字、菜单里也没有对应商品 —— 反查只能返回 0（价值未知），而它实际值 6.6 元。 反查不只是可能低估，还会把真实存在的价值报成 0。

两条路都走不通时，一律取 0 并在报告中标注「价值未知」， 绝不估一个「看起来合理」的数。宁可少报，不可编造。

前提：把「客单价」的口径搞对

后面的券包体检和用券排程都依赖同一个数：你的「自然消费基准」 —— 不看券的话，你本来会花多少钱。它取自历史订单的客单价。

而这个数很容易算错。真实订单里有两类订单不该按「一单消费」来算：

最后一条是关键：0 元订单只在有券时才会出现，拿它当「不看券时你会花多少」是 循环论证；而且它会把基准往下拉，让所有券都显得更难用上。

真实数据里，仅这一处口径修正就让客单价从 12.94 元变成 17.25 元， 结论随之从「两张券都得凑单」变成「两张都顺手可用」， 可实现金额从 ¥17.58 变成 ¥21.1。

于是本项目区分两个口径 —— 混用会让结论系统性失真：

• 消费口径（算钱、当基准）：只算有实际支出的订单 → avg_per_order
• 点单口径（算机会）：全部订单都算 → 推算「券过期前你还会点几单」

更进一步：券包体检

知道「你正在白扔多少钱」之后，下一个问题自然是：这笔钱该怎么不白扔？

答案取决于一个反直觉的事实 —— 券的名义面值，从来不是它对你的真实价值：

净价值 = 券面价值 − 为用这张券、你本来不会花的那部分钱

一张「满50减12」的券，如果客单价是 13 元 —— 为了用它得点到 50 元， 名义省 12，实际多花 37，净亏 25。

按这个公式，券包会被切成四类：