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 返回的券通常只有名字，没有面值：

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

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

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

目标用户

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

核心能力

快速开始

1. 申请麦当劳 MCP Token

前往麦当劳 MCP 开放平台 https://open.mcd.cn/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 / 调用流程 / 业务价值
├── SKILL.md                   # Skill 定义与工作流说明
├── mcp-config.example.json    # 脱敏 MCP 配置示例（仅环境变量占位符）
├── .env.example               # 环境变量占位符
├── .gitignore
├── LICENSE                    # MIT
├── assets/                    # README 展示图
│   ├── banner.svg             #   头图
│   ├── demo-dual-view.svg     #   两种问法对比
│   ├── architecture.svg       #   双链路架构
│   └── social-preview.png     #   GitHub 社交预览图（1280×640）
├── 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