name: mcd-buddy description: 麦门四重奏 —— 基于麦当劳中国 MCP 的多玩法助手。当用户提到"麦当劳"、"麦门"、"MCD"、"点麦当劳"、"巨无霸"、"麦乐送"、"团餐点单"、"隐藏菜单"、"套餐怎么配"、"麦当劳积分/优惠券/活动"、"今天吃什么麦当劳"等需求时使用。提供四大玩法：修行录（点餐成就与段位）、团餐指挥官（多人凑单）、隐藏菜单实验室（重组套餐配方）、每日运势签（宜吃与抽奖吉时）。 agent_created: true

麦门四重奏 McQuartet

基于麦当劳中国官方 MCP（https://mcp.mcd.cn）的多玩法助手。先判断用户想要哪种玩法，再按对应流程调用工具。

⚠️ 本文档中的所有接口细节均来自真实调用验证。麦当劳 MCP 的实际行为与直觉差异很大， 请严格按本文档的参数与结构调用，不要凭常识推测。

0. 前置条件

需要麦当劳 MCP 已连接（连接器 mcd-mcp）。若工具不可用，提示用户： 前往 https://open.mcd.cn/mcp 手机号登录 →【控制台】→【激活】→ 复制 Token， 再在 WorkBuddy 的【连接器 → 自定义连接器 → 配置 MCP】中填入：

{
  "mcpServers": {
    "mcd-mcp": {
      "type": "streamablehttp",
      "url": "https://mcp.mcd.cn",
      "headers": { "Authorization": "Bearer YOUR_MCP_TOKEN" }
    }
  }
}

0.1 必须知道的四件事

1. 所有工具返回统一信封 {success, code, message, datetime, traceId, data}， 业务数据在 data 里；success=false 时 message 是中文错误原因，data 不存在。
2. 金额单位是「分」：11450 = ¥114.50。（但 order-list 的 realTotalAmount 是元字符串。）
3. 菜单 / 价格 / 优惠券类工具都必须先有门店（storeCode + orderType + beType）。
4. 到店自取场景不要传 beCode，传了会报错；外送 / 团餐场景必须传。

1. 意图路由

2. 🧘 修行录

1. 调 now-time-info 拿今天日期（data.date）。
2. 调 order-list 拿历史订单。真实结构：data.list[].orderProductList[].comboItemList[]， 金额在 realTotalAmount（元字符串，如 "13.9"），时间在 createTime。

   ⚠️ 套餐的子项藏在 comboItemList 里，统计「本命单品」时必须拆开，否则套餐名会占满榜单。

3. 调 query-my-account 拿积分（availablePoint / accumulativePoint，都是字符串）。
4. 调 query-my-coupons 数券、query-my-prizes 数奖品。
5. 统计：单数、天数、连续连击（从今天或昨天往前数连续有单的天）、累计消费、早餐次数（10:00 前）、咖啡次数。
6. 判定成就徽章（12 个）：初入麦门 / 三连修行 / 七日不辍 / 巨无霸十人斩 / 晨钟暮鼓 / 咖啡因续命 / 深夜食堂 / 麦门金主 / 单品收集家 / 券包大户 / 麦金喜锦鲤 / 麦门信徒。
7. 评级：见习麦徒(0) → 麦门学徒(5) → 麦门弟子(15) → 麦门执事(30) → 麦门长老(60) → 麦门宗主(100)，附薯条进度条与「距下一段位还差 N 单」。

3. 🍱 团餐指挥官

1. 收集每个人的 {name, budget, want, avoid}，缺的主动问。
2. 先解析门店：调 query-nearby-stores，参数 {beType: 1, searchType: 2, city, keyword}。

   ⚠️ city 与 keyword 必须同时非空，只传一个会报 600058「城市名或者关键词不能为空」。 选营业中（businessStatus=true）且距离最近的那家。

3. 调 query-meals（{storeCode, orderType: 1, beType: 1}）拿菜单编码 —— 它只返回 data.categories[].meals[].code 和 tags，没有名称也没有价格。
4. 调 calculate-price 批量补全名称与价格：items: [{productCode, quantity: 1}, ...]， 一次可传多个。名称取 productList[].productName，价格取 subtotal ÷ 100。
5. 分层匹配（口味优先级必须高于预算）： 排除忌口 → 排除非餐品 → 满足「想吃什么」→ 卡预算 → 取最优。
   • 关键词命中：名称包含 / 类目包含 / 标签包含（否定式标签除外）。 标签是长串营销词，「牛肉」必须能命中 100%纯牛肉； 但不能让「咖啡」命中 无咖啡因、让「油炸」命中 非油炸 —— 所以要先看关键词前面有没有 无 / 非 / 不含 / 零 / 去，有就不算命中。
   • 排除非餐品：真实菜单的「小食甜品 /其他」类目里混着周边（¥14.90 的按摩捶、¥2 的饼干）， 「蘸酱炸鸡」里混着蘸酱（¥3，名称以「酱」结尾）。这些不能进候选池。
   • 预算内取最接近预算的一份，而不是最便宜的那份； 否则 ¥25 预算会被推 ¥2 的饼干。没有预算时按一顿正餐的目标价（¥30）挑。
   • 餐品等级：主食/套餐 > 小食/炸鸡 > 饮品。 等级要同时看类目和名称 —— 「巨无霸」名字里没有「堡」字，只看名称会把它误判成小食。
6. 合并同名单品数量，调 calculate-price 算整单：金额在 data.price（分）。
7. 调 query-my-coupons 列卡包、query-store-coupons 列本门店可用券。

   ⚠️ 必须说明区别：卡包的券不校验门店与渠道，能否用以下单时系统判定为准。

8. 如实报告没能满足的需求：真实菜单的 tags 是营销标签（爆款/冷饮）， 不含「油炸」「辣」这类烹饪属性，所以忌口未必生效；为满足口味也可能超预算。 这些都要在「匹配说明」里写出来，不要静默吞掉。
9. 输出：每人推荐 + 匹配说明 + 合并订单 + 价格明细 + 人均分摊 + 凑券建议。
10. 人数 ≥10 时提示可启用企业团餐助餐服务（需 beType=6 + beCode，走 delivery-query-stores 流程）。

4. 🧪 隐藏菜单实验室

1. 确认基础套餐（传名称关键词或编码，如「双人分享餐」或 9900011056）与目标（减脂 / 增肌 / 解馋 / 清醒）。

2. 调 query-meal-detail（{storeCode, orderType: 1, beType: 1, code}）拿套餐轮次。 真实结构：data.rounds[].choices[]，每个 choice 有 {code, name, quantity, isDefault, diffPrice, supportModify}。

   ⚠️ diffPrice 是字符串（"+ ¥2.5"），要自己解析成数字。 ⚠️ 同名轮次会出现多次（「选择小食」可能出现 3 次），不能按名字定位轮次。

3. 调 list-nutrition-foods 拿营养表 —— 不是 JSON，是一段自定义格式的文本：

   [160]{productName,nutritionDescription,energyKj,energyKcal,protein,fat,carbohydrate,sodium,calcium}:
     巨无霸,null,2146,513,27,26,42,961,171
   

   用 energyKcal（千卡），不是 energyKj（千焦，差 4.184 倍）。

4. 按目标给每个轮次的可选项打分，取最高分：

   • 减脂：最小化 energyKcal
   • 增肌：最大化 protein
   • 解馋：最大化 energyKcal
   • 清醒：优先含咖啡因的（关键词用单字「咖」——菜单里叫「鲜萃冰咖」，不含「咖啡」二字）

5. 两个必须遵守的评分规则：

   • 查不到营养数据的选项不参与比较。新品常常不在官方营养表里， 如果让它们以 0 分参与，会伪装成「零热量」，让减脂配方越减越离谱。
   • 餐品名要归一化后再匹配。菜单叫「麦辣鸡翅2块」，营养表叫「麦辣鸡翅-2块」， 不归一化就双双查不到数据。

6. 算真实价格：调 calculate-price，传完整的 roundList：

   {"productCode": "9900011056", "quantity": 1,
    "roundList": [{"round": "1", "comboItemList": [{"code": "1440", "quantity": 1}]}, ...]}
   

   三条硬规则（实测得出）：

   • round 必须是轮次数字 id 的字符串（"1"），不是轮次名称（传名称会 500）
   • roundList 必须覆盖全部轮次，漏一个就报 60006
   • 只能选该轮次 choices 里真实存在的 code，否则同样 60006

   价格公式：新价 = 套餐基准价 + Σ(diffPrice × 该轮次数量) （乘的是轮次数量，不是 comboItemList 里的数量 —— 最容易算错的地方）

7. 输出「改配说明 + 配方组成 + 可替换选项 + 营养对比 + 价格 + 可分享配方卡」。

5. 🔮 每日运势签

1. 调 now-time-info 拿日期，以日期为随机种子做确定性抽签（同一天结果必须一致，跨设备也一致）。
2. 调 list-nutrition-foods 拿餐品清单 —— 用营养表而不是 query-meals， 因为后者需要先解析门店还要额外请求补全名称，而运势是全局玩法，不该绑定门店。
3. 调 campaign-calendar 拿今日活动：真实结构是 data.dailyList[].events[].articleDto， 有 title / content / highlights。
4. 调 query-lottery-info 拿抽奖情报：activityName、activityStatusText、drawPoint、 drawDecision.nextConsumption.text、prizes[].name。调 query-my-prizes 拿已中奖品。
5. 输出：签等 + 签文 + 宜吃（带 kcal/蛋白）+ 小忌 + 幸运色/数字 + 抽奖吉时 + 今日活动 + 我的奖品。

6. 注意事项

• 每个 Token 每分钟最多 600 次请求，避免密集循环调用；命中 429 要退避重试。
• 本助手只做查询与试算：不调用 create-order / draw-lottery / mall-create-order， 不自动下单、不自动抽奖、不自动兑换积分。涉及资金或积分扣减的操作留给用户在官方 App 完成。
• 门店打烊后（businessStatus=false）调 query-meals 会报 600057，要换一家营业中的门店。
• 营养数据仅供参考，不构成医疗或营养建议，需明确告知用户。
• 不要把真实 Token 写进任何文件或提交到仓库。

🎬 30 秒看懂

👋 认识一下麦麦

麦麦是麦门四重奏的吉祥物——一只圆滚滚的汉堡小人，头顶金拱门小帽，笑眯眯的。 它每天的工作，就是帮你把「吃麦当劳」这件小事，变得更有趣、更明白、更划算。

🎥 完整宣传片（发社交媒体用）

• 片里没有一个是编的数字。 修行录的 8 单 / ¥138.00 / 3 张卡包券、团餐的 ¥109.50（人均 ¥18.25）、 隐藏菜单的 2150 → 1212 kcal，全部来自麦当劳中国 MCP 的真实菜单与价格数据。
• 而且你可以自己复现。 视频里的每一帧数字，都和 mcd-buddy <模块> --demo 跑出来的完全一致 —— 不用申请 Token，clone 下来敲一条命令就能看到同一份结果。
• 视频不是录屏，是 promo/make_promo.py 用 Pillow 逐帧绘制 + ffmpeg 编码生成的， 改一句文案、换一个数字就能重新出片。
• 各平台配套文案（含发布节奏与「求 Star」话术）在 promo/推广文案.md， 技术长文在 promo/掘金长文.md。
• 想拍一条实拍质感的版本？ promo/剪映实操脚本.md 里有完整的 12 镜拍摄清单、精确到秒的分镜表、逐句字幕文案、音效清单，配 promo/overlay/ 的 4 张透明底产品截图，照着铺就能出片。

🎮 四大玩法

✨ 长这样

🧘 修行录 —— 把吃麦当劳变成一场修行

  🍟 麦门修行录 🍔
  McQuartet · 点餐即修行
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

╭─ 🧘 我的修行进度 ──────────────────────────────────────╮
│ 📅 修行日期：2026-10-10                                │
│ 🎖️ 当前段位：麦门学徒                                  │
│ 🍟 ▰▰▰▰▱▱▱▱▱▱▱▱ 3/10　距「麦门弟子」还差 7 单          │
╰────────────────────────────────────────────────────────╯

▍ 📊 修行数据

| 指标 | 数值 |
| --- | --- |
| 🍔 累计点餐 | 8 单 |
| 💸 累计消费 | ¥138.00 |
| 🌅 早餐修行 | 2 次 |
| ☕ 咖啡因摄入 | 2 杯 |
| 🏅 可用积分 | 2860.5 分 |
| 🎟️ 卡包券数 | 3 张 |

▍ 🏅 成就徽章　5/12

|  | 成就 | 达成条件 | 状态 |
| --- | --- | --- | --- |
| 🌙 | 「深夜食堂」 | 在 21:00 之后点过餐 | ✅ |
| 🏅 | 「单品收集家」 | 点过 8 种以上不同单品 | ✅ |
| 🔒 | 「巨无霸十人斩」 | 累计点过 10 个巨无霸 | — |

🍱 团餐指挥官 —— 一群人的点单终于不用吵了

╭─ 🍱 本次团餐 ──────────────────────────────────────────╮
│ 👥 团餐人数：6 人                                      │
│ 🏪 取餐门店：麦当劳深圳福华一路(卓悦中心)餐厅          │
│ 🛵 取餐方式：到店自取                                  │
│ 💰 预计应付：¥109.50                                   │
│ 🍔 人均分摊：¥18.25                                    │
╰────────────────────────────────────────────────────────╯

| 伙伴 | 推荐单品 | 单价 | 依据 |
| --- | --- | --- | --- |
| 小王 | 巨无霸 | ¥24.50 | 想吃「牛肉」 · 预算 ¥25 |
| 小李 | 麦香鸡 | ¥15.50 | 想吃「鸡肉」 · 预算 ¥20 · 忌口 辣 |
| 小张 | 麦香鱼 | ¥17.50 | 想吃「鱼」 · 预算 ¥15 |
| 小赵 | 高达吉士双牛堡 | ¥26.00 | 想吃「汉堡」 · 预算 ¥30 · 忌口 油炸 |
| 小陈 | 大薯条 | ¥13.50 | 想吃「素食」 · 预算 ¥22 |
| 小周 | 大杯鲜萃咖啡 | ¥12.50 | 想吃「咖啡」 · 预算 ¥18 |

⚠️ 匹配说明：
  · **小张**：超预算 ¥2.50

▍ 💰 价格明细

| 项目 | 金额 |
| --- | --- |
| 🍔 商品小计 | ¥109.50 |
| 🎟️ 优惠减免 | — |
| 💳 **应付合计** | **¥109.50** |
| 👛 **人均分摊** | **¥18.25** |

▍ 💡 凑单建议

官方团餐搭配规则：
- **20 元以下**：小食
- **30 元以下**：汉堡 + 小食 或 汉堡 + 饮料
- **40 元以下**：汉堡 + 薯条/小食 + 饮料

🧪 隐藏菜单实验室 —— 人人都能发明自己的麦当劳

╭─ 🧪 我的隐藏配方 ──────────────────────────────────────╮
│ 🍔 配方名称：全明星双人分享餐八件套·减脂版             │
│ 🔖 配方编号：HM-8655                                   │
│ 🧾 基础套餐：全明星双人分享餐八件套（9900011056）      │
╰────────────────────────────────────────────────────────╯

▍ 🔧 改配说明

- 选择汉堡：麦辣鸡腿汉堡 ➜ 板烧鸡腿堡
- 选择小食：麦乐鸡4块 ➜ 脆薯饼
- 选择小食：麦辣鸡翅2块 ➜ 麦乐鸡4块（+¥1）
- 选择小食：中薯条 ➜ 小杯玉米杯
- 选择套餐内饮料：可乐中杯 ➜ 无糖可口可乐中杯

▍ 🍔 配方组成

| 轮次 | 已选 | 数量 | 差价 |
| --- | --- | --- | --- |
| 选择汉堡 | 板烧鸡腿堡 | ×1 | ±¥0 |
| 选择主食 | 板烧鸡腿堡 | ×1 | ±¥0 |
| 选择小食 | 脆薯饼 | ×1 | ±¥0 |
| 选择小食 | 麦乐鸡4块 | ×1 | +¥1 |
| 选择小食 | 小杯玉米杯 | ×2 | ±¥0 |
| 选择套餐内饮料 | 无糖可口可乐中杯 | ×2 | ±¥0 |

▍ 📈 营养对比

| 指标 | 原配方 |  | 新配方 | 变化 |
| --- | --- | --- | --- | --- |
| 🔥 能量 | 2150 kcal | ➜ | 1212 kcal | -938 kcal |
| 💪 蛋白质 | 78 g | ➜ | 61 g | -17 g |
| 🧈 脂肪 | 90 g | ➜ | 55 g | -35 g |
| 🍚 碳水 | 245 g | ➜ | 111 g | -134 g |
| 🧂 钠 | 3468 mg | ➜ | 2817 mg | -651 mg |

▍ 💰 价格

| 版本 | 价格 |
| --- | --- |
| 原套餐 | ¥114.50 |
| **减脂版** | **¥115.50** |

定价来源：已通过 calculate-price 实时核算

▍ 📤 分享配方卡

🧪 全明星双人分享餐八件套·减脂版
🍔 板烧鸡腿堡 + 板烧鸡腿堡 + 脆薯饼 + 麦乐鸡4块 + 小杯玉米杯 + 无糖可口可乐中杯
🔥 1212 kcal | 蛋白 61g | 脂肪 55g
💰 ¥115.50
—— 来自麦门四重奏 · 隐藏菜单实验室

🔮 每日运势签 —— 今天宜吃巨无霸

╭─ 🔮 麦门灵签 ──────────────────────────────────────────╮
│ 🎋 签　等：中吉                                        │
│ 📅 日　期：2026-10-10 星期六                           │
│                                                        │
│ 📜 签　文：咖啡入喉，万事不愁。今日宜早起，忌拖延。    │
╰────────────────────────────────────────────────────────╯

▍ 🍟 今日宜吃

| 推荐 | 说明 |
| --- | --- |
| 🥇 高达吉士双牛堡 | 今日头牌，主推　448 kcal · 蛋白 26g |
| 🥈 猪柳蛋麦满分 | 搭配之选，可加购　387 kcal · 蛋白 23g |

▍ 🎰 抽奖吉时

| 项目 | 今日指引 |
| --- | --- |
| ⏰ 吉时 | 09:00 - 10:00 |
| 🎁 抽奖活动 | 周六麦金喜抽奖（进行中） |
| 💳 单次消耗 | 本次将消耗 24 积分 |

📎 完整输出见 examples/sample-outputs.md

🚀 快速开始

1️⃣ 申请麦当劳 MCP Token

前往 https://open.mcd.cn/mcp → 右上角【登录】→ 手机号验证 → 【控制台】→【激活】→ 复制 Token。

2️⃣ 安装

git clone https://github.com/janetom645-coder/mcd-buddy.git
cd mcd-buddy
pip install -r requirements.txt
pip install -e .

3️⃣ 先玩离线演示（不需要 Token）

mcd-buddy practice --demo
mcd-buddy group-meal --demo
mcd-buddy hidden-menu --meal 双人分享餐 --preset 减脂 --demo
mcd-buddy fortune --demo

4️⃣ 接上真实麦当劳 MCP

export MCD_MCP_TOKEN="你的 Token"   # Windows: set MCD_MCP_TOKEN=...

# 修行录 / 运势签 只用你的账号数据，直接跑
mcd-buddy practice
mcd-buddy fortune

# 团餐 / 隐藏菜单 需要先定位门店
mcd-buddy group-meal --city 深圳市 --keyword 麦当劳
mcd-buddy hidden-menu --city 深圳市 --keyword 麦当劳 --meal 双人分享餐 --preset 增肌

🧭 命令一览

通用参数

💡 --city / --keyword 只在团餐指挥官和隐藏菜单实验室生效 —— 其余两个模块只用你的账号数据，不依赖门店。

写法一：直接说人话（推荐，每个人用 ; 分隔，字段用 : 分隔）

mcd-buddy group-meal --city 深圳市 --keyword 麦当劳 \
  --people "小王:25:要牛肉;小李:20:要鸡肉:不要辣;小张:15:要鱼"

字段按内容自动归类：纯数字 = 预算，不要/忌/免… 开头 = 忌口，要/想吃… 开头 = 口味， 其余第一个字段 = 名字。--people "小王:预算25:不要辣,不要香菜" 这种混写也能识别。

写法二：JSON（适合脚本调用）

mcd-buddy group-meal --city 深圳市 --keyword 麦当劳 --people \
  '[{"name":"小王","budget":25,"want":"牛肉"},
    {"name":"小李","budget":20,"want":"鸡肉","avoid":["辣"]}]'

写法三：从文件读取 —— --people @examples/people.json

字段说明：name 姓名、budget 预算（元）、want 想吃什么、avoid 忌口列表。

匹配优先级：忌口 > 口味 > 预算。预算内取最接近预算的一份，而不是最便宜的那份； 如果为了满足口味不得不超预算，会在「匹配说明」里写明。

先看看这个门店有什么、套餐能怎么换：

mcd-buddy hidden-menu --list --city 深圳市 --keyword 麦当劳
mcd-buddy hidden-menu --city 深圳市 --keyword 麦当劳 --meal 双人分享餐

再按「轮次 = 商品」指定替换（轮次可以是编号，也可以是名称）：

# 按编号
mcd-buddy hidden-menu --city 深圳市 --keyword 麦当劳 --meal 9900011056 \
  --swap "1=巨无霸" --swap "6=纯牛奶"

# 按轮次名称
mcd-buddy hidden-menu --city 深圳市 --keyword 麦当劳 --meal 双人分享餐 \
  --swap "选择套餐内饮料=大杯鲜萃咖啡"

⚠️ 替换只能选该轮次真实存在的选项，否则门店会返回「商品已售罄或不可售」。 程序会替你校验，不合法就自动退回默认选项。

🏗️ 项目结构

mcd-buddy/
├── assets/                  # 🎨 手绘卡通视觉资产（SVG，可缩放不糊）
│   ├── banner.svg           # README 头图
│   ├