麦麦省钱营养师 · MCD Budget Planner

「我想吃麦当劳，但想控钠 / 想花 30 块以内 / 别浪费我的券」——说人话，它算出实付最省的组合。

基于麦当劳 MCP Server 的「预算 + 营养」双约束套餐优选 Skill。 不是券列表查询器，是点餐决策器：把「省钱的券」和「健康的餐」放在一起求解。

你：30块以内怎么点？还想控钠

它：卡包 14 张券 → 此刻该门店真实可用 1 张
    营养数据 → 158 项餐品，钠从 0mg 到 1373mg
    约束求解 →

    最省方案：薯薯任选 ×1
    实付 ¥9.90（原价 ¥16.00，省 ¥6.10）
    门店：成都南站站前广场（步行 273m）

    ─── 其他可选 ───
    · 火腿扒麦满分 单点 约 ¥11.00　无券可用，钠 608mg
    · 巨无霸 + 中杯可乐 约 ¥24.00　钠 961mg（若不控钠）

    ⚠ 你卡包里还有 10 张早餐券，但有效期是每天 05:00–10:29，
      下午用不了，明天早点去

这条回复背后是 6 次 MCP 调用，包括门店定位、券可用性二次核验、 带券价格试算（拿到真实 couponId 而不是估算），再叠加 158 项营养数据的约束求解。

联调时实测某用户卡包有 14 张券，但在同一时刻、同一门店， query-store-coupons 只认得出 1 张：

差的 10 张是早餐券，有效期限定每日 05:00–10:29，而查询时刻是 18:23。

MCP 文档明确声明 query-my-coupons 不做门店、渠道、场景校验—— 返回的是「我拥有的」，不是「我能用的」。

由此得出本项目最关键的一条约束：券可用性必须以门店维度二次确认为准， 不得用卡包数据直接推导。 顺序反了，整个逻辑就是错的。

MCP 营养接口返回 158 项餐品，钠含量跨度极大：

一份巨无霸的钠含量是中杯可乐的上千倍。但这些数据以紧凑字符串形式返回， 用户既看不懂，也没法用来做选择。

本项目做的事，是把这两类数据交叉起来 —— 让省钱和健康能同时被满足， 而不是二选一。

git clone https://github.com/AAA-EE/mcd-budget-planner.git
cd mcd-budget-planner

# 运行离线演示：5 个真实场景
python examples/demo_offline.py

# 运行单元测试：12 项
python tests/test_solver.py

examples/demo_offline.py 会输出：

场景一：控钠午餐｜钠 ≤ 600mg 且 热量 ≤ 500kcal
  → 小杯玉米杯 + 大杯玉米杯 + 浓缩咖啡
    热量 153kcal · 蛋白 7g · 钠 3mg

场景三：钠含量最低的 8 款餐品
  → 0mg  147kcal  可乐中杯
    0mg    2kcal  锡兰红茶
    ...

场景四：零热量饮品（用于替换含糖饮料）
  → 0kcal  钠 35mg  无糖可口可乐中杯
    0kcal  钠  0mg  纯悦

将skills/mcd-deal-gen/ 目录复制到 ~/.workbuddy/skills/ 后：

cp -r skills/mcd-deal-gen ~/.workbuddy/skills/

重启会话后，用自然语言触发：

帮我配个30块以内的麦当劳
我要吃麦当劳，但想控钠
明天早餐有什么券能用
用券点单，最便宜的要多少
低钠的麦当劳套餐推荐一下

Skill 会自动完成：场景确认 → 门店定位 → 券可用性核验 → 餐品与营养匹配 → 带券试算 →排序输出。

# 生成一个带券试算的 MCP 调用任务
python skills/mcd-deal-gen/scripts/price_planner.py \
  --store 3450312 \
  --be-type 1 \
  --item 9900016370:1 \
  --coupon "E86377A0349D730EF7C27EBBE7B4C0FE:MCD60Z01Y0V19V9B24804" \
  --tableware

输出（已实测与真实成功调用的参数完全一致）：

{
  "tool": "mcp__mcd-mcp__calculate-price",
  "params": {
    "storeCode": "3450312",
    "orderType": 1,
    "beType": 1,
    "items": [{
      "productCode": "9900016370",
      "quantity": 1,
      "couponId": "E86377A0349D730EF7C27EBBE7B4C0FE",
      "couponCode": "MCD60Z01Y0V19V9B24804"
    }],
    "needTableware": true
  }
}

mcd-budget-planner/
├── README.md                    # 本文件
├── CONTEST_DECLARATION.md       # 参赛声明（官方原文，未改动）
├── MCP_INTEGRATION.md           # MCP Server / Tool / 调用流程说明
├── workbuddy.md                 # WorkBuddy 开发对话上下文
├── LICENSE
├── data/
│   └── nutrition_mcd.json       # 158 项营养数据集（去重后）
├── src/
│   └── mcd_planner/
│       └── solver.py            # 营养约束求解器（核心算法）
├── examples/
│   └── demo_offline.py          # 离线演示：5 个场景
├── tests/
│   └── test_solver.py           # 12 项单元测试
├── skills/
│   └── mcd-deal-gen/            # 可安装的 WorkBuddy Skill
│       ├── SKILL.md
│       └── scripts/price_planner.py
└── docs/
    └── ALGORITHM.md             # 算法说明

支持同时施加多维约束，求解满足全部硬约束的组合：

Constraints(
    max_sodium_mg=600,     # 钠上限
    max_kcal=500,          # 热量上限
    min_protein_g=15,      # 蛋白下限
    budget=30,             # 预算上限（元）
    exclude=frozenset({"巨无霸"}),  # 排除项
    categories=frozenset({"burger", "side", "drink"}),  # 类别限定
)

在满足硬约束的候选中，按综合评分升序：

score = 3.0 × (钠/100) + 1.0 × (热量/100) - 0.15 × 蛋白 - 饱腹惩罚

• 钠权重最高（3.0）：实测数据中钠含量差异达三个数量级，是首要筛选维度
• 饱腹惩罚：热量低于 200kcal 的组合会被惩罚，避免出现「控钠午餐 = 三杯咖啡」这类不合理结果
• 蛋白正向加权：同等条件下优先高蛋白

1. 单品级粗筛：先按约束过滤单品，缩小搜索空间
2. 同类目截断：每个类别保留钠含量最低的 6 项
3. 增量剪枝：递归过程中钠/热量一旦超标立即剪枝
4. 多样性约束：同类别最多选 2 项，避免堆砌同类

分类覆盖率：148/158（剩余 10 项为联名新品，无法可靠归类，保留 other 类别）

1. 基于实测，而非文档推测

MCP_INTEGRATION.md 中记录的每一条接口行为都来自真实联调，包括三个「反直觉」发现：

• 卡包 14 张券 ≠ 14 张可用券
• 传 reservationDate 反而让可用券查询返回空
• 营养接口原始返回 162 行，含 4 行重复数据

这些特征直接决定了项目的实现方式，文档中均如实记录。

2. 双层架构，可离线验证

MCP 只负责必须实时的部分（门店、券、价格），营养计算放在离线层。 好处是核心算法能被单元测试覆盖，项目在无 MCP 环境下也能完整运行和演示。

3. 有安全边界的自动化

明确不调用 create-order（需用户明确确认），不调用 draw-lottery （MCP 要求人工确认消耗且有频次限制）。自动化程度止于「推荐」而非「购买」。

• 不含任何真实 Token、密钥、密码或账号凭证
• 不含任何用户个人信息
• 不执行下单操作，不产生实际消费
• 营养数据来自 MCP 公开接口，不含用户数据

详见 CONTEST_DECLARATION.md。

MIT License，见 LICENSE。

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