PLX-08 / mcd-smartpick

# 🍔 麦门聪明点 · McSmartPick
> 基于 **麦当劳官方 MCP（https://mcp.mcd.cn）** 的「目标导向智能点餐」Agent Skill。
> 说一句「我要**增肌 / 省钱 / 低卡 / 解馋**，预算 N 块」，它就会调用麦当劳 MCP 拉取**实时菜单与优惠券**，用**代码算出最优组合**，再把结果**讲成人话**给你。
**核心原则：取数交给 MCP，算术交给代码，表达交给 Agent。**
本项目为 **麦当劳中国 1024 程序员节创意开发大赛** 参赛作品（官方仓库 `M-China/mcd-developer-innovation-challenge`）。非麦当劳官方产品，与麦当劳官方无隶属关系。
---
## ✨ 为什么值得一看
- **不让大模型"算钱"**：套餐 / 优惠券的最优解交给确定性算法（纯函数），避免模型口算出错——这是用户最痛、模型最弱的点。
- **目标驱动，而非菜单罗列**：省钱 / 增肌 / 低卡 / 解馋 / 儿童营养五档，直接对齐用户的真实意图。
- **打开即跑**：`--demo` 离线模式 + `demo/index.html` 交互页，**不填 Token 也能立刻看到效果**。
- **真连官方，且已实跑留证**：零依赖 Streamable HTTP 客户端（兼容 JSON 与 SSE 响应）对接 `https://mcp.mcd.cn`；四段链路（门店→菜单→券→计价）已真实跑通并留存官方 `traceId`，见 `evidence-real.md`。
- **安全默认**：下单等交易类工具必须用户显式确认，默认只读与规划，不产生未授权订单。
---
## 🔬 真实数据验证（已实跑，含 traceId）
2026-10-14 对 `mcp.mcd.cn` 的一次真实调用（门店：宁波海曙区开明街餐厅 `3330480`）：
| 验证项 | 官方返回 |
|---|---|
| 附近门店 | 宁波天一广场命中 5 家，最近 218 m |
| 实时菜单 | 巨无霸 `1100` = ¥25.50、中薯条 = ¥13.50、可乐 = ¥10.00 |
| 门店券 | 2 张：中薯条买一送一、王牌小食拼 |
| 官方计价 | 巨无霸+中薯条+可乐 = **¥49.00**（与本地算术一致 ✅） |
| 券后价 | 中薯条买一送一 ¥27 → **¥13.50**；王牌小食拼 ¥22 → **¥15.90** |
> 完整出入参与 `traceId` 见 `evidence-real.md`；真实回包已固化为离线 fixtures（`tests/test_live_adapt.py`，30 项回归全绿，**无需 Token**）。
> 一个重要发现：**门店券是"指定商品特价券品"，不是满减券**——券挂在普通商品上会被官方拒绝（`code 600012`）。本项目据此把券建模为"券品"，先逐张取券后价再参与组合优化。
---
## 项目介绍
点餐时我们常卡在三件事：吃什么、怎么点最划算、营养够不够。大模型擅长"说人话"，却不擅长"算价格"——让它口算套餐组合，十次有八次会算错。
**麦门聪明点**把这件事拆成清晰的三层（这也是本项目的核心设计原则）：
| 层 | 谁来做 | 说明 |
|---|---|---|
| 取数 | 麦当劳 MCP | 实时菜单、营养、门店券、活动日历 |
| 算术 | 本项目代码（纯函数） | 在预算与目标约束下做组合优化，**可复现、可测试、可审计** |
| 表达 | Agent / `SKILL.md` | 把"省了多少、为什么这么搭"讲成人话 |
五个目标模式：
| 目标 | 代码 | 一句话定义 |
|---|---|---|
| 省钱 | `save` | 预算内拿到最划算的「管饱组合」：按每元饱腹性价比 (蛋白 + 0.3×热量) 最大化 |
| 增肌高蛋白 | `protein` | 预算内最大化蛋白质总量 |
| 低卡控糖 | `lowcal` | 预算内、热量上限内最大化"蛋白/热量"比 |
| 解馋满足 | `crave` | 预算内最大化"解馋满足度" |
| 儿童营养 | `kids` | 预算内兼顾蛋白(长身体)+ 钙/蔬果/维C 友好 + 控钠 |
---
## 🚀 快速开始（无需 Token）
 [code] 
> 需要 Python 3.8+，**零第三方依赖**。
> 也可以直接用浏览器打开 `index.html` 查看完整项目展示页（含可交互演示与真实链路证据），或打开 `demo/index.html`（独立交互式演示），均**无需 Token**。
---
## 安装方法
### 方式一：作为 WorkBuddy / 任意 MCP 客户端 Skill 使用（推荐参赛路径）
1. 领取麦当劳 MCP Token：登录 https://open.mcd.cn/mcp ，手机号验证后在「控制台」激活并复制 Token（免费）。
2. 按 `mcp-config.example.json` 配置 MCP（Token 用环境变量占位，**切勿硬编码**）。
3. 把本仓库放到本地，在 WorkBuddy 中加载 `SKILL.md` 即可对话式使用：
 > "我想增肌，预算 35 块，帮我点一份"
### 方式二：命令行调用真实 MCP
 [code] 
完整链路：`query-nearby-stores → query-meals → list-nutrition-foods（官方营养覆盖近似值）→ query-store-coupons（券品取券后价）→ smart_pick → calculate-price`，
输出为 JSON，含 `store`（命中门店）、`items/items_codes`、`nutrition_source`（营养来源：`official`=官方 / `approx`=近似值兜底）、`live_price_check`（官方核算）。
环境变量：`MCD_MCP_TOKEN`（live 模式使用，也可用 `--token` 传入）。参数：`--city` / `--keyword` / `--max-items`。
---
## 使用示例（离线真实输出）
**增肌高蛋白（预算 ¥35）：**
 [code] 
**解馋满足（预算 ¥25）：**
 [code] 
**对话式（WorkBuddy + 真实 MCP）：**
> 用户：我想吃麦当劳，预算 30，要低卡的
> 麦门聪明点：拉取门店菜单与券 → 计算 →
> "推荐 田园脆鸡沙拉，实付 ¥16.20，约 180 kcal、蛋白 12g，用券（全场9折）后比原价省约 10%。"
完整离线样例见 `demo/sample_run.md`，可交互网页演示见 `demo/index.html`（**无需 Token**）。
---
## 🧑‍🤝‍🧑 拼单（组队点餐）
和朋友一起吃麦当劳？把每个人的「目标 + 预算」一次性交给引擎，它会：
1. 先为**每个人*