麦算盘 · 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/coupon-max-savings.html · 实跑方案：docs/order-plan-20261015.html

下面三张图都是真实运行结果（非示意图）：门店、菜单、券池、价格、热量全部来自麦当劳 MCP，价格由 calculate-price 实算返回。

你说：汉堡 + 鸡翅 + 2 份中薯条 + 冰淇淋 + 可乐，用最省的方式点。 它给：逐件单点 ¥79.50 → 精算实付 ¥45.80（省 ¥33.70，42.4%）。汉堡 + 可乐走「1+1 随心配」压到 ¥13.90，两份薯条用买一送一券，圆筒用 3.9 元券；因为一单只能挂一张券，所以拆成 2 单。

你说：减脂期想吃麦当劳，800 大卡以内还要便宜。 它给：3 套卡在预算内的方案 —— 773 kcal / ¥42.50（最贴近上限）、774 kcal / ¥36.50（最省）、306 kcal / ¥19.50（最轻）。热量取自 MCP 营养库 list-nutrition-foods，价格逐条实算，人不用自己对表。

你说：家里来 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 调用参数 → 生成候选组合 → 逐组实算 → 按约束筛选 → 再判断该用哪种省钱杠杆。

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 → 支付链接]

几个关键决策点（也就是最容易做错的地方）：

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 里的内容填进你的 Agent 的 MCP 连接配置，将 ${MCD_MCP_TOKEN} 替换为真实 Token，保存并启用。
3. 装上技能：把 skills/mai-suanpan/ 复制进 Agent 的技能目录。装好后直接说「帮我用最省的方式点一份汉堡 + 鸡翅 + 2 份中薯条 + 冰淇淋 + 可乐」即可触发。

开发过程用真实 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 原子工具。

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

MIT License。