内容
# 麦算盘 · mai-suanpan
> 基于 **麦当劳中国 MCP（McDonald's China MCP）** 开发的点餐省钱 Skill / AI 智能体技能：
> **取数交给 MCP，比价交给 Skill，下单交给你确认。**
> 点单省钱 · 算热量 · 办团餐派对，一个 Skill 全包。
> 又名：麦算盘 / 麦门算盘 / 麦当劳全能助手 / MCD Saver Pan。
麦当劳程序员节创意开发大赛参赛作品 · 非麦当劳官方产品。
---
## 一句话介绍
**用户说「汉堡 + 鸡翅 + 2 份中薯条 + 冰淇淋 + 可乐，帮我用最省的方式点」，它拉取门店菜单与可用券，枚举出总价最低的合规组合并报给你。**
示例：直选逐件 **¥79.50** → 精算 **¥45.80**，省 **¥33.70（42.4%）**；单笔最高可省 **60.9%**（套餐选对品项）。
📊 效果与流程页：[`docs/capability-overview.html`](docs/capability-overview.html) · 券+套餐方案：[`docs/coupon-max-savings.html`](docs/coupon-max-savings.html) · 实跑方案：[`docs/order-plan-20261015.html`](docs/order-plan-20261015.html)
---
## 三种场景 · 实跑结果
> 下面三张图都是**真实运行结果**（非示意图）：门店、菜单、券池、价格、热量全部来自麦当劳 MCP，价格由 `calculate-price` 实算返回。
### 场景一 · 点单省钱 —— 同样的东西，少花 ¥33.70
**你说**：汉堡 + 鸡翅 + 2 份中薯条 + 冰淇淋 + 可乐，用最省的方式点。
**它给**：逐件单点 ¥79.50 → 精算实付 **¥45.80**（省 **¥33.70，42.4%**）。汉堡 + 可乐走「1+1 随心配」压到 ¥13.90，两份薯条用买一送一券，圆筒用 3.9 元券；因为一单只能挂一张券，所以拆成 2 单。
### 场景二 · 热量营养 —— 800 大卡以内，还要便宜
**你说**：减脂期想吃麦当劳，800 大卡以内还要便宜。
**它给**：3 套卡在预算内的方案 —— 773 kcal / ¥42.50（最贴近上限）、774 kcal / ¥36.50（最省）、306 kcal / ¥19.50（最轻）。热量取自 MCP 营养库 `list-nutrition-foods`，价格逐条实算，人不用自己对表。
### 场景三 · 团餐派对 —— 8 个人的量，不多不少还自动打折
**你说**：家里来 7 个朋友，连我 8 个人，团餐点什么合适？
**它给**：先算一个人吃多少（1 主食 + ½ 薯条 + ½ 鸡翅 + 1 饮料），再 ×8 组单；MCP 自动套上团餐满折、免运费、打包费也减免 —— 商品 ¥426.00 → **实付 ¥341.28**（省 ¥105.92，人均 ¥42.66），还顺手提示「再点 ¥74 可升到 7.4 折」。
### 还有 · 麦乐送
> 用户：帮我在麦乐送点份午餐，别超过 40 元。
`delivery-query-addresses` → `delivery-query-stores` → 后续流程同上，`calculate-price` 核价（含运费与打包费），预算超了会自动换更便宜的组合再报给你。
---
## 它解决什么问题
麦当劳的优惠是典型的**组合爆炸**：菜单几十项、券十几张、套餐与券规则各不相同，而价格/折扣**口算极易出错**。
本 Skill 的核心约束：**所有价格、优惠、积分数值一律由 MCP 计算，Skill 只做「枚举候选 + 取最小」。**
| 角色 | 职责 |
|---|---|
| 麦当劳 MCP | 实时菜单、门店、价格、优惠券、积分、营养、下单 |
| 麦算盘 Skill | 意图理解、参数矩阵处理、候选枚举、比价取优、讲解与确认 |
| 用户 | 说需求、确认下单 |
---
## 架构与决策流程
麦算盘不是一个「转发请求」的壳。它的价值全在中间那层**决策**：把模糊需求翻译成 MCP 调用参数 → 生成候选组合 → 逐组实算 → 按约束筛选 → 再判断该用哪种省钱杠杆。
```mermaid
flowchart TD
U([用户：想吃什么 / 预算 / 热量 / 人数]) --> T{需求归到哪一类}
T -->|指定商品 + 要划算| P1[省钱模式]
T -->|给热量上限| P2[热量模式]
T -->|给人数 / 预算| P3[团餐模式]
P1 --> SC{取餐场景是哪种}
P2 --> SC
P3 --> SC
SC -->|到店 / 得来速| C1["beType=1 或 5 · orderType=1<br/>得来速必传 beCode"]
SC -->|麦乐送| C2["beType=2 · orderType=2<br/>必传 beCode"]
SC -->|企业团餐| C3["beType=6 · orderType=2<br/>必传 beCode ＋ 助餐服务"]
L["取数据：门店 → 菜单 → 券池 → 营养库<br/>query-meals · query-store-coupons · list-nutrition-foods"]
C1 --> L
C2 --> L
C3 --> L
L --> CL{是热量模式吗}
CL -->|是| CL1[按 kcal 分桶挑餐品，先剔除超限项]
CL -->|否| CL2[按品类把需求拆成可替换的槽位]
CL1 --> CV[需求槽位]
CL2 --> CV
CV --> H{券池里有匹配的券吗}
H -->|有| H1[候选＝原品挂券 / 券绑定专用 SKU]
H -->|没有| H2{积分够兑这张券吗}
H2 -->|够| H3[积分商城换券 → 再挂券]
H2 -->|不够| H4[不走券，只用套餐杠杆]
H1 --> G
H3 --> G
H4 --> G
G["生成候选组合<br/>① 原生单品 ② 固定价套餐 / 1+1 随心配<br/>③ 券绑定专用 SKU ④ 同价位替代品"]
G --> E["calculate-price 逐组实算<br/>唯一价格来源，Skill 绝不口算"]
E --> V{满足约束吗<br/>预算 / 热量 / 人数}
V -->|不满足，换下一组| G
V -->|满足| W{哪个杠杆更省}
W -->|套餐最省| W1[套餐打底]
W -->|单张券最省| W2[挂券]
W -->|两个都要| W3["一单只能挂一张券 → 拆单"]
W -->|团餐| W4["满折由 MCP 自动生效<br/>再用 enjoyable.balance 凑到下一档"]
W1 --> O
W2 --> O
W3 --> O
W4 --> O
O[按实付金额排序 · 输出 Top-N：直选 vs 精算 ＋ 省了多少] --> CF{用户确认吗}
CF -->|否，重新枚举| G
CF -->|是| CO[create-order → 支付链接]
```
**几个关键决策点**（也就是最容易做错的地方）：
| 决策点 | 判断依据 | 走错会怎样 |
|---|---|---|
| 场景参数矩阵 | `beType · orderType · beCode` 三者联动，到店**不能**传 `beCode` | 传错直接报错，单下不出来 |
| 券能不能用 | 券绑定的 `productCode` 是否在购物车里 | 车里没有对应商品 → 券静默失效，用户以为没优惠 |
| 买一送一怎么用 | 券绑定**专用 SKU**（不在常规菜单），必须用该码下单 | 挂普通商品报 `600012`，挂促销码被忽略 |
| 券能不能叠 | 一单一张券；但**套餐与 1 张券可同单** | 多券同单报 `600022`，必须拆单 |
| 该用券还是套餐 | 两者都实算，比大小 | 券最高 50%，套餐最高 60.9% —— 只看券会漏掉更省的方案 |
| 团餐要不要凑单 | `enjoyable.balance` 给出的门槛差额 | 差一点点就到下一档，白花钱 |
---
## 一句话安装
```bash
cp -r skills/mai-suanpan <你的 Agent 技能目录>/
```
Skill 只依赖 MCP 原子工具，不引入任何私有 SDK 或依赖，**任何支持 MCP 的 Agent 都能直接跑**。
---
## 安装
1. **申请麦当劳 MCP Token**：前往麦当劳 MCP 开放平台 <https://open.mcd.cn/mcp>，登录后在控制台激活并复制 Token。
2. **接入 MCP**：把 [`mcp-config.example.json`](mcp-config.example.json) 里的内容填进你的 Agent 的 MCP 连接配置，将 `${MCD_MCP_TOKEN}` 替换为真实 Token，保存并启用。
3. **装上技能**：把 `skills/mai-suanpan/` 复制进 Agent 的技能目录。装好后直接说「帮我用最省的方式点一份汉堡 + 鸡翅 + 2 份中薯条 + 冰淇淋 + 可乐」即可触发。
---
## 真实性对照表
| 项目 | 性质 | 说明 |
|---|---|---|
| 三种场景截图 | ✅ 真实 | 2026-10-15 南京门店实跑，截图内每个数字都是 MCP 原始返回值 |
| 价格 / 优惠 / 积分 | ✅ 真实 | 全部由 MCP `calculate-price` 计算 |
| 「省 42.4% / 团餐省 ¥105.92 / 最高 60.9%」 | ✅ 真实 | 门店 `1990583`（南京软件谷科创城）、团餐门店 `1990226` 实跑，可复现 |
| BOGO 券、套餐「随心配」用法 | ✅ 真实 | 均由 MCP 实测确认 |
| 菜单 / 券内容 | 🟡 实时快照 | 以门店实时返回为准，会随活动变化 |
| 下单 | ✅ 真实 | 需用户确认后 `create-order`；本仓库不含实际支付 |
---
## 实测发现
开发过程用真实 MCP 联调得到的观察（2026-10-15，南京）：
- **到店无自动促销**：到店场景不会自动套卡包券，**必须显式挂券**；只有团餐会**自动满折**。
- **券生效三条件**：有券 → 商品匹配券绑定的 `productCode` → 显式传 `couponId/couponCode`。
- **买一送一不是普通单品折扣**：BOGO 券绑定**专用 SKU**（如「中薯条买一送一」=`9900012387`，不在常规菜单），必须用它下单才生效。
- **一单只能一张券**（多券报 `600022`）→ 用满券须**拆单**；但**套餐与券可同单叠加**。
- **套餐往往比券更省**：1+1 随心配等固定价套餐最高省 **60.9%**，高于任何单张券（最高 50%）。
- **积分不能抵现**，但可「换券 → 用券」间接降价。
- **菜单无热量字段**：kcal 只能来自 `list-nutrition-foods`，需按餐品名称匹配。
---
## 目录结构
```
.
├── README.md # 本文件
├── CONTEST_DECLARATION.md # 参赛声明（官方原文，未改动）
├── MCP_INTEGRATION.md # MCP 集成：Tool 清单 / 调用流程 / 业务价值
├── mcp-config.example.json # 脱敏 MCP 配置（仅环境变量占位符）
├── docs/
│ ├── DESIGN.md # 运作设计与关键计算逻辑
│ ├── FEASIBILITY.md # 三能力可行性 + 实测证据
│ ├── TROUBLESHOOTING.md # 优惠不生效排查
│ ├── capability-overview.html # 核心能力 + 运行流程图 + 效果图
│ ├── coupon-max-savings.html # 券 + 套餐最大化省钱方案
│ ├── order-plan-20261015.html # 实跑点单方案示例
│ ├── scene-1-order.html # 场景一 展示页（截图的源文件）
│ ├── scene-2-nutrition.html # 场景二 展示页
│ ├── scene-3-group.html # 场景三 展示页
│ └── img/ # README 里的三张实跑截图
│ ├── scene-1-order.png
│ ├── scene-2-nutrition.png
│ └── scene-3-group.png
└── skills/mai-suanpan/ # ← Skill 本体
├── SKILL.md # 技能指令（Agent 加载）
├── references/ # ordering / nutrition / party 细则
└── assets/ # 品类桶 / 招牌清单 / 名称别名
```
---
## 目标用户
- **价格敏感的学生 / 上班族**：想吃得划算，又懒得比价算券。
- **减脂健身人群**：控热量，还不想多花钱。
- **家庭 / 拼单党**：预算内配齐多人餐。
- **麦门会员**：手里券多、积分多，需要最优组合。
---
## 技术亮点
- **价格权威**：所有金额取 MCP 返回值，Skill 不口算，规避"到店付不出"的假低价。
- **三场景一体**：到店 / 得来速 / 麦乐送 / 团餐的参数矩阵 `beType·orderType·beCode` 自动处理。
- **套餐嗅觉**：识别「随心配 / 三件套」等固定价套餐，并支持与券叠加、拆单。
- **可核验闭环**：下单前统一用 `calculate-price` 复核，方案 = 实付。
- **零私有依赖**：仅调用 MCP 原子工具。
---
## 搜索关键词
<details>
<summary>🔍 想用哪些词能搜到本项目？（点开查看）</summary>
**中文**：麦当劳 · 麦门 · 麦当劳优惠券 · 麦当劳省钱 · 麦当劳点餐 · 麦乐送 / 外送 · 团餐 · 巨无霸 · 1+1 随心配 · 买一送一 · 优惠券叠加 · 组合优化 · 热量点餐 · 派对策划 · 麦当劳程序员节创意开发大赛 · AI 智能体技能
**English**: McDonald's / McDonalds China / MCD · MCP (Model Context Protocol) · mcd-mcp · coupon optimizer · money saving · combo deal · nutrition · agent skill · AI agent
推荐搜索词：`麦当劳 MCP` · `mcd mcp` · `麦当劳 省钱 技能` · `随心配 最省`
</details>
---
## 免责声明
本项目为麦当劳程序员节创意开发大赛参赛作品，由参赛者独立开发，**非麦当劳官方产品**。
项目输出仅供参考，不构成医疗、营养或其他专业建议；餐品信息、价格及供应状态以麦当劳官方渠道的实时结果为准。
使用麦当劳 MCP 服务须遵守其《使用条款》与《麦当劳 MCP 服务规则》。
## 许可
MIT License。
连接信息
猜你喜欢
暂无推荐服务器