mcd-coupon-strategist

<div align="center"> <img src="./assets/banner.svg?v=2" alt="麦麦省钱助手 — mcd-coupon-strategist" width="100%"> <br> [](./LICENSE) [](https://mcp.mcd.cn) [](#测试) [](#测试) [](#快速开始) **市面上的省钱工具都在回答「这一单怎么点最省」。** **我们多回答一个问题：「你正在白扔多少钱？」** [核心亮点](#我们做对了什么别人没做的) · [真实例子](#一个真实例子) · [快速开始](#快速开始) · [架构](#架构) · [设计原则](#设计原则) </div> --- <img src="./assets/demo-dual-view.svg?v=2" alt="同一个账号，两种问法：省这一单 vs 你正在白扔多少钱" width="100%"> 基于麦当劳中国 MCP 打造的点餐成本助手，做两件事： **短期 —— 这一单怎么点最省** - 拉取**当前门店**的实时菜单与价格 - 拉取你**账户里当前门店可用**的优惠券 - 枚举「单品 / 套餐 / 券组合 / 加购凑单」的候选方案 - 用 MCP 的 `calculate-price` 逐方案**真实计价**（而不是猜） - 输出最省钱的方案，以及**为什么不推荐更便宜但吃不饱的选项** **长期 —— 你白扔了多少钱** - **券的沉默成本**：你手里有几张券即将过期？那就是正在流失的钱 - **消费习惯画像**：近 N 个月花了多少、客单价是否偏高、哪些单品该改成套餐 - 数据来自 `order-list` 历史订单 + `query-my-coupons` 券存量 <div align="center"> | 🍟 一次点餐平均省 | 💸 沉默成本发现 | 🧮 价格来源 | 🔑 使用门槛 | |:---:|:---:|:---:|:---:| | **3 ~ 13 元** | **一次几十元** | MCP 真实计价 | 无需 Token 即可跑测试 | </div> --- ## 一个真实例子 同一个账号，同一个门店，两种问法： **问「今天怎么点最省」** → ``` 推荐方案 组合：麦辣鸡腿堡三件套（汉堡 + 中薯条 + 可乐） 实付 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` 回填 | 模型给不出真实价格，只能猜 | | 只说「推荐买这个」 | 说清**省在哪**：哪张券、哪个套餐、加了什么 | 用户才能学会，而不是依赖工具 | | 为用券鼓励凑单 | 主动检测**凑单陷阱**并劝退 | 凑单常常反而更贵 | | 只看这一单 | 同时看**历史订单 + 券存量** | 一次性工具看不到长期结构 | | 券是「可用资源」 | 券是**有保质期的钱** | 过期即损失，这是本项目独有的视角 | | —— | **券的沉默成本** | 别处见不到这个指标 | <div align="center"> > **差异化内核：别处都在帮用户花钱，我们在帮用户止损。** > 下单前省的那几块钱是「收益」，快过期的券是「损失」—— > 人对损失的敏感度是对收益的两倍，而这个数字从来没人给他算过。 </div> ### 关键实现：券面价值反查 「券的沉默成本」要成立，前提是得知道**每张券真实值多少钱**。而 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 开放平台 <https://open.mcd.cn/mcp> ，使用手机号登录后在控制台激活并复制 MCP Token。 ### 2. 配置 MCP 连接 本项目提供脱敏示例配置 [`mcp-config.example.json`](./mcp-config.example.json)： ```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` 的真实返回，非估算值。 --- ## 架构 <img src="./assets/architecture.svg?v=2" alt="架构图：MCP 数据底座 → 适配层 → 链路 A 单次省钱 / 链路 B 消费审计" width="100%"> 两条链路**共用同一套 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 # 报名提交检查清单 ``` ### 测试 ```bash 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`](./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 就是最好的反馈。** ⭐ > 本项目为[麦当劳程序员创意开发大赛](https://open.mcd.cn/mcp)参赛作品，非麦当劳官方产品。 --- ## 设计原则 1. **绝不猜测价格** —— 所有金额均来自 MCP `calculate-price` 的返回结果。 2. **宁可少报，不可编造** —— 券的价值若无法从菜单反查到原价，取 0 并在报告中标注，而不是估一个看起来合理的数。 3. **省在哪要说清** —— 每个推荐都附带省钱归因，而不是只给一个数字。 4. **不诱导消费** —— 为用券而凑单如果导致实付上升，必须明确提示。 5. **退款不算消费** —— 历史订单中的整单退款会被过滤，避免月度支出虚高。 6. **信息以官方为准** —— 价格、供应状态、券的可用范围均以麦当劳官方渠道实时结果为准。 --- ## 免责声明 本项目为麦当劳程序员创意开发大赛参赛作品，由参赛者独立开发，**非麦当劳官方产品**。 项目输出仅供参考，不构成医疗、营养或其他专业建议；餐品信息、价格及供应状态以麦当劳官方渠道的实时结果为准。 --- ## License MIT