Ayzzz123/mcd-coupon-strategist

---

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

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

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

长期 —— 你白扔了多少钱

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

---

一个真实例子

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

问「今天怎么点最省」 →

推荐方案
  组合：麦辣鸡腿堡三件套（汉堡 + 中薯条 + 可乐）
  实付 33.5 元
备选方案
  · 单点：麦辣鸡腿堡 + 中薯条 —— 实付 37.0 元

三件套 33.5 元买三样，比单点买两样还便宜 3.5 元。

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

【一】券的沉默成本
  你有 3 张券将在 1 天内陆续过期（面值 33.1 元）。
  优先处理这几张：
    · 满50减12        省 12.0 元  还剩 1 天（满 50 元可用）
    · 免费脆薯饼       省  8.0 元  还剩 2 天
    · 9.9元中杯冰美式  省 13.1 元  还剩 5 天
【二】消费习惯
  订单数：4 单      总支出：144.5 元      客单价：36.12 元
  洞察：
    · 你点过 4 次「麦辣鸡腿汉堡」。如果给它配上套餐，
      每次通常能省 5~13 元，4 次下来就是一笔不小的数。

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

第二个问题的价值，远大于第一个。因为第一个问题每次只省几块钱，而第二个问题一次就能指出几十块的流失 —— 而且它是一次性工具永远给不出的答案。

---

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

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

| 常见做法 | 我们的做法 | 差别 | |---|---|---| | 让模型估算价格 | 所有金额由 MCP calculate-price 回填 | 模型给不出真实价格，只能猜 | | 只说「推荐买这个」 | 说清省在哪：哪张券、哪个套餐、加了什么 | 用户才能学会，而不是依赖工具 | | 为用券鼓励凑单 | 主动检测凑单陷阱并劝退 | 凑单常常反而更贵 | | 只看这一单 | 同时看历史订单 + 券存量 | 一次性工具看不到长期结构 | | 券是「可用资源」 | 券是有保质期的钱 | 过期即损失，这是本项目独有的视角 | | —— | 券的沉默成本 | 别处见不到这个指标 |

关键实现：券面价值反查

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

「中薯条买一送一」  →  值多少钱？
「9.9元中杯冰美式」 →  值多少钱？
「满50减12」        →  值多少钱？

答案是从门店菜单反查原价：

| 券形态 | 价值推算 | 本例结果 | |---|---|---| | 满减券 满50减12 | 直接取减免额 | 12.0 元 | | 买一送一 中薯条买一送一 | 取该商品菜单单价 | 14.5 元 | | 固定价券 9.9元中杯冰美式 | 菜单原价 − 固定价 | 23.0 − 9.9 = 13.1 元 |

若菜单里查不到对应商品，一律取 0 并在报告中标注，绝不估一个「看起来合理」的数。宁可少报，不可编造。

---

目标用户

• 学生党 / 打工人：预算固定，希望同样吃饱的前提下花得更少
• 持券用户：手里攒了一堆券，但不知道哪张快过期、哪张该用
• 选择困难用户：不想在菜单里反复横跳，希望直接得到一个明确答案
• 想知道自己花了多少钱的人：从没算过在麦当劳的月度开销

---

核心能力

| 能力 | 说明 | |---|---| | 门店菜单感知 | 价格与供应状态随门店实时变化，不写死菜单 | | 券面价值解析 | 从菜单反查原价，算出这张券真实值多少钱（买一送一 = 商品单价；9.9元券 = 原价 − 9.9） | | 方案枚举计价 | 所有候选方案都经 MCP 真实计价，不复用历史价格 | | 省钱归因 | 明确告诉用户「省在哪」：用了哪张券、换成了哪个套餐、加了什么凑单品 | | 反凑单陷阱 | 当「为用券而加购」反而更贵时，主动指出并给出更优解 | | 券的沉默成本 | 量化即将过期的券面值 —— 那是正在流失的钱 | | 消费习惯画像 | 从历史订单还原月度支出、客单价、高频单品，给出结构性省钱建议 |

---

快速开始

1. 申请麦当劳 MCP Token

前往麦当劳 MCP 开放平台 ，使用手机号登录后在控制台激活并复制 MCP Token。

2. 配置 MCP 连接

本项目提供脱敏示例配置 mcp-config.example.json：

{
  "mcpServers": {
    "mcd-mcp": {
      "type": "streamablehttp",
      "url": "https://mcp.mcd.cn",
      "headers": {
        "Authorization": "Bearer ${MCD_MCP_TOKEN}"
      }
    }
  }
}

将 ${MCD_MCP_TOKEN} 替换为你自己的 Token 后，写入 MCP Client 的配置。请勿将真实 Token 提交到任何公开仓库。

3. 在 WorkBuddy 中启用

1. 打开 WorkBuddy，左侧边栏进入【专家 · 技能 · 连接器】→【连接器】页签 2. 点击右上角【自定义连接器】→【配置 MCP】 3. 粘贴上面的 JSON（替换 Token），点击【保存】 4. 回到【自定义连接器】，将 mcd-mcp 设为【启用】

4. 开始使用

直接对话即可，例如：

我在麦当劳点外卖，门店选好之后帮我算一下：
我手里有券，想吃一个汉堡 + 一份薯条 + 一杯饮料，预算 40 元，
怎么点最省钱？给我两个方案对比。

---

使用示例

示例一：预算内吃饱

你：预算 35 元，想吃鸡类主食 + 一个配餐，帮我选。

> 助手：已查询当前门店菜单与你名下可用券，为你计价了 3 个候选方案：

> | 方案 | 组合 | 实付 |

|---|---|---|

| ✅ 推荐 | 麦辣鸡腿堡三件套（汉堡 + 中薯条 + 可乐） | 33.5 |

| 备选 | 单点：麦辣鸡腿堡 + 中薯条 | 37.0 |

| 不推荐 | 单点：麦辣鸡腿堡 + 中薯条 + 可乐 | 46.5 |

> 推荐三件套：33.5 元拿到三样，比只买两样的单点组合还便宜 3.5 元，

比同内容的单点组合省 13 元。这是套餐结构本身带来的价差，不必再叠加优惠券。

示例二：凑单陷阱提醒

你：我有一张「满 50 减 12」的券，是不是该凑单？

> 助手：不建议。你当前想买的商品合计 46.5 元，为触发门槛需要再加 3.5 元商品，

实付变为 46.5 + 3.5 - 12 = 38 元；而直接买三件套只要 33.5 元。

也就是说，凑单用券后反而比直接买套餐贵 4.5 元。

除非你本来就想吃那个凑单品，否则不划算。

以上金额均来自 MCP calculate-price 的真实返回，非估算值。

---

架构

两条链路共用同一套 MCP 数据底座，但回答的是完全不同的问题：

• 链路 A（短期）：saver.py —— 枚举候选组合，每个组合都交给 calculate-price 真实计价，输出这一单的最省方案
• 链路 B（长期）：auditor.py —— 读 order-list 历史订单与 query-my-coupons 券存量，输出结构性浪费报告

衔接两者的是 mcd_adapter.py：它负责唯一一次的「分 → 元」换算、字段映射、退款过滤，以及券面价值反查。算法层不接触原始响应，因此不会出现单位错乱的幻觉。

---

项目结构

mcd/
├── README.md                  # 本文件
├── CONTEST_DECLARATION.md     # 参赛声明（官方文本，未做改动）
├── MCP_INTEGRATION.md         # MCP 集成说明：Server / Tool / 调用流程 / 业务价值
├── mcp-config.example.json    # 脱敏 MCP 配置示例（仅环境变量占位符）
├── SKILL.md                   # Skill 定义与工作流说明
├── assets/                    # README 展示图（SVG，可随仓库渲染）
│   ├── banner.svg
│   ├── demo-dual-view.svg
│   └── architecture.svg
├── src/
│   ├── saver.py               # 单次省钱：方案枚举与优化核心逻辑
│   ├── auditor.py             # 长期画像：券的沉默成本 + 消费习惯审计
│   ├── mcd_adapter.py         # MCP 响应适配层（单位换算 + 字段映射）
│   ├── test_saver.py          # 算法逻辑自测
│   ├── test_adapter.py        # 适配层自测
│   ├── test_auditor.py        # 审计模块自测（含日期临界值）
│   └── test_order_adapter.py  # 订单/券解析自测（用真实响应片段）
├── workbuddy.md               # WorkBuddy 开发对话上下文（WorkBuddy 专项奖励用）
└── docs/
    ├── TOKEN_GUIDE.md         # MCP Token 申请指引
    └── SUBMIT_CHECKLIST.md    # 报名提交检查清单

测试

python src/test_saver.py          # 单次省钱：枚举、排序、凑单陷阱
python src/test_auditor.py        # 长期画像：沉默成本、消费习惯
python src/test_adapter.py        # 适配层：单位换算、响应解析
python src/test_order_adapter.py  # 订单/券：退款过滤、券价值推算

四套测试均为纯本地运行，不需要 MCP Token。

---

这个项目可能对你有用，如果……

• 🌱 你在做 MCP 相关的项目 —— MCP_INTEGRATION.md 里记录了官方文档没写、但跑通链路必需的 12 条实测调用契约（门店查询的必传参数、calculate-price 的字段名、「分 vs 元」两个接口方向相反的坑），可以帮你少踩不少坑。
• 🍔 你想知道自己在外卖上花了多少 —— 链路 B 给出的是可以直接执行的结论：「你有 3 张券将在 1 天内过期，面值合计 ¥33.1」。
• 🧩 你在写 Agent / Skill 的评测 —— 这个项目是一个完整的、双链路的 MCP 编排示例，saver.py + auditor.py + mcd_adapter.py 分层清晰，可直接作为参考实现。
• 💡 你也在做麦当劳 MCP 的省钱工具 —— 欢迎对比，也欢迎来 issue 里讨论「券的沉默成本」这个视角。

如果它对你有帮助，一个 star 就是最好的反馈。 ⭐

本项目为麦当劳程序员创意开发大赛参赛作品，非麦当劳官方产品。

---

设计原则

1. 绝不猜测价格 —— 所有金额均来自 MCP calculate-price 的返回结果。 2. 宁可少报，不可编造 —— 券的价值若无法从菜单反查到原价，取 0 并在报告中标注，而不是估一个看起来合理的数。 3. 省在哪要说清 —— 每个推荐都附带省钱归因，而不是只给一个数字。 4. 不诱导消费 —— 为用券而凑单如果导致实付上升，必须明确提示。 5. 退款不算消费 —— 历史订单中的整单退款会被过滤，避免月度支出虚高。 6. 信息以官方为准 —— 价格、供应状态、券的可用范围均以麦当劳官方渠道实时结果为准。

---

免责声明

本项目为麦当劳程序员创意开发大赛参赛作品，由参赛者独立开发，非麦当劳官方产品。 项目输出仅供参考，不构成医疗、营养或其他专业建议；餐品信息、价格及供应状态以麦当劳官方渠道的实时结果为准。

---

License

MIT