name: mcd-cn-assistant description: 麦当劳中国官方 MCP 智能助手。当用户提到麦当劳、金拱门、麦乐送、到店取餐、麦咖啡、麦麦省、优惠券、领券、活动日历、麦当劳活动、品牌联名、联名款、联名周边、限定、IP合作、积分、麦麦商城、抽奖、点餐、下单、比价、怎么点最划算、拼单、群点、聚餐点餐、办公室下午茶、夜宵拼单、多人点餐、分摊等，优先使用本 skill。四大能力：①获取最新活动推送（查询当月营销活动日历并摘要推送）；②联名关注推送（盯联名/限定活动：按 config/keywords.json 中的关键词筛选活动并推送，默认关键词「联名」+ 同义词扩展，支持对话增删关键词）；③最优惠点餐（门店→菜单→领券→算价的全链路比价，输出应付金额最低的组合）；④多人群点聚合（聚餐拼单：代录全员餐品→满减凑单→券归属→公共费用分摊（配送费+打包费）→自动生成每人账单，组织者单账户统一结算）。**点餐入口会先主动询问「单人还是多人拼单」，命中多人即转入④，无需用户自己提出。**另含小红书场景五项：隐藏吃法一键还原（文案/截图解析→单品映射→特调/备注→下单）、穷鬼套餐凑单演算、周边联名抢货雷达（按需扫店+麦金卡随单购优化；无实时库存接口）、参数化营养搭配（热量/蛋白/控糖约束）、晒单卡片生成、天气与场景感应推送。 description_en: McDonald's China official MCP assistant. Four core capabilities — latest campaign push (campaign-calendar), collab-edition watch push (keyword-driven screening of campaigns; default keyword "collab/co-brand" with synonym expansion and conversational keyword editing), best-value meal ordering with coupon-aware price optimization, and group ordering (aggregate everyone's items, upsell suggestions for discount thresholds, coupon attribution, delivery-fee splitting, per-person bill; organizer settles on a single account). At the ordering entry point the agent ALWAYS asks whether it is a solo order or a group order, so group ordering never depends on the user bringing it up. Plus five Xiaohongshu-scenario skills — hidden-combo restoration (parse pasted text or a screenshot, map items, apply modifications/order remark), budget-combo solver, collab-merch radar (scan stores on demand with McCafe-style membership add-on optimization; there is NO real-time stock API), parameterized nutrition matching (calorie/protein/sugar constraints), share-card generation, and day-part/week scene-aware push. metadata: author: mcd-cn-assistant homepage: https://open.mcd.cn/mcp category: lifestyle source: https://github.com/M-China/mcd-mcp-server

麦当劳中国 MCP 助手（mcd-cn-assistant）

麦当劳中国官方远程 MCP 服务的封装技能，覆盖活动推送、联名关注、最优惠点餐、多人群点聚合四条业务主线，以及面向小红书场景的隐藏吃法还原 / 穷鬼套餐演算 / 周边抢货雷达 / 参数化营养搭配 / 晒单卡片 / 场景感应推送六项扩展能力。

核心交互约定：所有点餐请求都从同一个入口进入——Agent 会先主动问一句"单人还是多人拼单"，再据此分流到能力三（最优惠点餐）或能力四（多人群点聚合）。多人拼单不是"用户得自己想到才有的隐藏功能"。见第 3 节。

能力总览与实测边界：第 4~7 节为四大主线；第 8 节为小红书场景六项。每一项都标注了能做到与做不到——凡写"做不到"的（如实时库存、天气数据、小红书链接抓取、到店单备注），不得承诺、不得编造，按文档给的降级路径处理。

1. 前置依赖与工具寻址

• 依赖已配置的远程 MCP 服务 mcd-mcp（Streamable HTTP，https://mcp.mcd.cn，需 Authorization: Bearer <你的 MCP Token>）。
• 接入方式见 docs/mcp-setup.md。若 Token 仍是占位符 ${MCD_MCP_TOKEN} 未替换，或返回 401 / 403，需引导用户：
  1. 前往 https://open.mcd.cn/mcp 登录并申请自己的 MCP Token；
  2. 把 MCP 客户端配置里的 ${MCD_MCP_TOKEN} 占位符替换为使用者自己的真实 Token（注意保留 Bearer 前缀）；
  3. 在客户端中信任 / 启用该服务（多数客户端不会自动生效）。

  本仓库已脱敏，不含任何真实 Token；所有占位符都需使用者自行替换。

• 工具调用名形如 mcp__mcd-mcp__<tool-name>（如 mcp__mcd-mcp__campaign-calendar）。若列表中找不到工具，先确认服务是否已被信任启用，而不是改用其它数据源。
• 完整工具清单见 references/mcd-tools.md。
• 能力四（多人群点聚合）的订单结构、分摊算法与账单模板见 references/group-order.md。
• 小红书场景六项能力（隐藏吃法 / 穷鬼套餐 / 周边雷达 / 营养搭配 / 晒单卡片 / 场景推送）的词典、算法与模板见 references/xhs-playbook.md。

2. 硬性规则（必须遵守）

1. 写操作必须二次确认：create-order、party-order-create、mall-create-order、auto-bind-coupons、cancel-order、draw-lottery、delivery-create-address 等会产生费用、消耗积分或改变账户状态的调用，必须先向用户列清明细并获得明确同意，严禁静默执行或"顺手"下单。
2. 下单前必须先算价：一律以 calculate-price 的返回为准，不要自行心算金额、优惠或配送费。
3. 先取时间：涉及日期、当月活动、可预约日期时，先调用 now-time-info 获取当前日期，避免使用模型内置时间。
4. 限流：每个 Token 每分钟最多 600 次请求，超出返回 429。串行调用、缓存本次会话已获得的结果，避免重复查询同一门店/菜单。
5. 金额展示统一用 ¥，保留两位小数。
6. 点餐入口主动询问是否多人拼单：任何点餐请求在定位门店前，必须先问"单人还是多人拼单"（见第 3 节），不得等用户自己提出，也不得默认按单人处理。
7. 商品编码必须按「门店 × 渠道」现取：外送菜单编码与到店不同（巨无霸 到店 1100 / 外送 901100；麦香鸡 1450 / 901450），且不同门店在售商品可能不同。严禁跨渠道、跨门店复用编码或价格；每次先 query-meals 再算价。
8. 特调（modification）按 key 规则传参：选中项用 selectedKey；未选中但该组有 unselectedKey 的项也必须一并传入（用 unselectedKey）。calculate-price 不回显特调结果，只能确认不报错，不得据此向用户断言"已生效"。
9. 免费配件不是商品：番茄酱 / 糖 / 胡椒粉 / 空杯 / 奶球等无法加购，只能进 create-order 的 remark；而 remark 仅 orderType=2（外送）可用、最多 50 字。到店单改为给用户到店话术，不得虚构参数。
10. 不承诺没有的能力：MCP 无门店库存接口、无天气接口、抓不到小红书链接内容。凡问到此三类，按第 8 节与第 9 节的降级路径处理，不得编造库存数字、气温降雨或笔记内容。
11. 小红书卡片 / 文案里的数字必须真实：价格来自 calculate-price，热量来自 list-nutrition-foods；没查过就不写，不为好看而编造。

3. 点餐入口：下单前必须主动询问「单人 / 多人拼单」

红线：任何进入点餐 / 下单流程的请求（"帮我点个麦当劳""中午吃什么""买份早餐""下午茶"），在澄清基本需求之后、定位门店之前，Agent 必须主动问一句是单人还是多人拼单——不得等用户自己提出来。这是能力三与能力四的分流闸口，也是本 skill 的关键交互点。

询问话术（一句话自然问出即可，不要做成问卷）：

这单是你自己一个人吃，还是帮几个人一起点（拼单）？拼单的话我可以代录大家想吃的、帮你凑满减、把配送费和打包费算清楚，最后出一张「每人应付多少」的账单。

路由判定：

入口免问的例外：若用户在同一句话里已明确表达群体诉求，视为已答复，直接进入能力四（可顺带确认人数），不要重复问第二遍。

主动识别信号（命中任一 → 在入口按群体意图确认，或直接进入能力四）：拼单、群点、一起点、帮大家点、多人、几个人、N 人份、办公室、同事、同学、室友、宿舍、家庭、聚餐、下午茶、夜宵拼单、AA、算账、分账、账单、每人多少。

忌：

• 问一次就够——用户答复过就不再追问；
• 用户已明确单人（如"我就想喝杯咖啡"）时不再提拼单，也不反复推销；
• 不得把"用户没提"当成"单人"：入口的默认动作是问一句，而不是默认单人。这正是本节点要修正的问题。

4. 能力一：获取最新活动推送

触发：用户问"最近有什么活动""麦当劳有什么优惠/新品""活动日历""这个月有什么"。

流程：

1. now-time-info → 拿到当前年月。
2. campaign-calendar → 获取当月营销活动日历，返回进行中 / 往期 / 未来三类。
3. 可选增强：available-coupons（麦麦省可领券）、query-my-coupons（我已有的券）。
4. 按"进行中 → 即将开始"分组摘要输出，略过往期（除非用户点名要看）。

输出格式（每条一行）：

末尾补一句「需要我盯着联名款 / 限定活动，有新的就推给你吗？」引导用户进入能力二。

5. 能力二：联名活动关注推送（关键词机制驱动）

定位：这是"只看我关心的那几条"的能力。默认瞄准联名 / 限定 / IP 合作这类最容易错过开售时点的活动，但底层是通用关键词匹配——用户换成"新品""早餐""周边"同样成立。

关键词来源：本 skill 的 config/keywords.json → follow_keywords（默认：["联名"]），并参考其中的 synonyms 做同义扩展匹配（联动 / 限定 / 合作款 / 联名款 / IP合作 / 品牌合作 / co-brand / 联名活动）。

「联动」必须留在同义词里：麦当劳对 IP 合作的官方文案常写「联动」而非「联名」（如「麦当劳联动G-DRAGON」）。2026-10-13 实测：同义词缺「联动」时该活动被整条漏推，而它的联名食品（龙焰鸡腿堡）在菜单里明明可以买到——漏推代价是实的。已知残留边界：同系列活动但标题与描述均不含关键词的（如「韩式风味蘸酱」，仅描述含"getGD同款"）仍不会命中，此时应回退到当日全量日历逐条讲给用户，不要为它把词放宽到「同款」这类过泛词（会误伤「心形薯饼同款比心」等无关活动）。

执行流程（推送任务与被追问时均执行）：

1. 读取 config/keywords.json。若文件不存在，用默认关键词重建。
2. now-time-info → campaign-calendar（必要时叠加 available-coupons）。
3. 用关键词对活动名称 + 活动描述 + 标签做不区分大小写的命中匹配，支持同义词扩展（如"联名"≈"合作款 / 联名款 / IP合作 / 品牌合作"）。
4. 按活动名去重：campaign-calendar 会把同一条活动按排期日 / 结束日重复返回多次（实测 2026-10-17：「麦当劳 X PEACEMINUSONE 棒球帽」在 10-13 与 10-17 各行一次、「麦当劳联动G-DRAGON」在 10-16 与 10-17 各行一次、「韩式风味蘸酱」在 10-17 与 10-18 各行一次）。同一活动名只保留一条，状态按"进行中 > 即将开始 > 往期"取最高优先级的那次出现；往期一律不推（除非用户点名要看）。
5. 只推送去重后命中的活动；无命中时明确回复：今日无命中关键词「X」的新活动，不要用无关活动凑数。
6. 定时推送由外部自动化任务触发（建议每日 09:00，见 config/keywords.json 的 push_time），本 skill 只负责"查询 + 筛选 + 组织推送内容"。

推送文案结构（先经步骤 4 去重，同一活动只出现一行）：

🎉 麦当劳活动关注推送 | <日期>
命中关键词：<关键词列表>
—— 进行中 ——
· <活动名>  <起止时间>
  <一句话说明>
—— 即将开始 ——
· ...
无命中关键词时直接说明，不凑数。

关键词维护（对话式）：

• 用户说"关注一下XX""加上关键词XX" → 追加到 follow_keywords，去重。
• 用户说"不再关注XX" → 从 follow_keywords 移除。
• 用户说"我关注了哪些关键词" → 读取并回显列表。
• 每次修改后写回 config/keywords.json 并更新 updated_at，然后回显最新完整列表确认。

联名周边的购买渠道（2026-10-16 实测修正，取代 10-13 的错误结论）：

⚠️ 史误记录：10-13 曾据此写下"联名周边无法通过 MCP 购买、必须引导去 APP"。该结论是错的——当时只测了上海一家门店的到店自取菜单就下了全局判断。10-16 测外送菜单后发现周边就在菜单里、可以正常算价下单。教训：菜单能力必须按「门店 × 渠道」分别实测，不能用一个门店的一个渠道推断全局。

联名周边（棒球帽 / 徽章 / 丝巾 / 毛绒周边等）以普通可售商品形式出现在 query-meals 返回里，discountType 为 随单购麦金卡优惠，并带 withOrder: {membershipCode: "106", specId: "880"}。实测编码（深圳金丰城外送，2026-10-16）：521954 麦当劳联名复古棒球帽（¥39.90，麦金卡价 ¥34.90）、521955 麦当劳联名徽章、521743 薯条脆卜卜毛绒周边（¥29.90 / ¥24.90）。

实测算价（外送 · 深圳金丰城 1421053）：

三条硬结论：

1. 周边能买，走 query-meals → calculate-price → create-order 主链路即可，不需要积分商城。
2. 加购 15 天麦金卡体验卡（¥9.90）几乎总是更划算：周边降 ¥5 + 免配送费 + 免打包费，实测净省 ¥1.10～¥12.10。calculate-price 会自动把 521234 麦金卡体验卡（15天） 和归零的配送/打包费写进 productList，照抄返回值即可，不要自己拼价格。
3. 周边随门店和渠道变化：同一时刻上海陆家嘴门店的到店菜单里没有帽/徽章（只有 521946 旋旋星愿贴 ¥3.9 这类低价贴纸），深圳外送菜单里有。所以不能说"附近买不到"，必须先按目标门店 + 渠道实拉 query-meals 再下结论。

仍做不到的事（不要承诺）：mall-points-products 类目 2>8（周边产品）实测只有 3 项且全部过期（罗技键鼠 8-21、Nike Book 2 联名款 6-5、酸黄瓜吧唧 8-14），积分商城换不到联名周边；且 MCP 没有任何门店库存查询工具，无法回答"这家店还有没有货"（详见能力七）。

6. 能力三：最优惠点餐

目标：在满足用户需求（想吃什么 / 人数 / 预算 / 就餐方式）的前提下，给出应付金额最低的组合。

严格按序执行：

1. 澄清需求：吃什么、几人份、预算、堂食（到店取餐/得来速）还是外送、是否预约。其中"几人份"必须来自第 3 节的入口询问——若用户答"多人拼单"，本能力即终止并改走能力四；只有确认是单人（或用户明确只要一人份）才继续往下走。
2. now-time-info 获取当前时间。
3. 定位门店：
   • 到店/堂食 → query-nearby-stores（需用户提供或确认地址）；团餐再叠加 query-meal-assistance。
   • 外送 → delivery-query-addresses 取地址 → delivery-query-stores 取可配送门店；无地址时先征得同意再 delivery-create-address。
4. 盘券（最优惠的关键）：
   • available-coupons 看麦麦省当前可领券；
   • 有可领券且用户同意 → auto-bind-coupons 一键领券；
   • query-my-coupons 看账户已有券；query-store-coupons 看当前门店可用券。
   • 记录每张券的适用条件（门槛、指定商品、第二份半价、限渠道等）。
5. 看菜单：query-meals（分类 / 餐品编码 / 标签 / 优惠价）；套餐内容或换购选项用 query-meal-detail。
6. 枚举组合：围绕券的适用条件构造候选方案（单品券方案、满减凑单方案、第二份半价方案等），至少 2 个候选，最多不超过 4~5 个以避免超限流。
7. 逐个算价：对每个候选调用 calculate-price（把已选券一并带上），拿到 商品金额 / 配送费 / 优惠金额 / 应付总价。
8. 择优输出：主推应付最低的方案，另列 1~2 个备选与差价，并说明"为什么它最省"（哪张券起的作用）。
9. 用户确认后才调用 create-order 下单，返回订单详情与支付链接。

输出格式：

要点：

• 「第二份半价 / 买一送一 / 满减」这类券只有凑到门槛才生效，必须真的把组合跑一遍 calculate-price 验证，不能凭券面文字判断。
• 券有使用门槛与限渠道，选品时必须满足其条件，否则该方案作废。
• 券专享商品必须带券算价：部分餐品的 productCode 只在某张券下可售（如"XX 早餐两件套"），不带 couponId/couponCode 调用 calculate-price 会返回 price:0 且 productList 为空数组。这不是报错，而是"该商品不单独售卖"——此时应带上对应券再算，而不是判定商品下架。
• 外送价 ≠ 到店价：同一餐品在两个渠道的菜单价不同（实测：脆薯饼 到店 ¥8.5 / 外送 ¥9.5；猪柳蛋麦满分 到店 ¥18 / 外送 ¥18.5），严禁跨渠道复用价格，每次都必须从当前 orderType 的 query-meals 重新取值。
• 外送编码也可能 ≠ 到店编码（2026-10-16 实测）：巨无霸 到店 1100 / 外送 901100；麦香鸡 1450 / 901450。用错编码会让 calculate-price 返回 price:0、productList 为空——这与"券专享商品没带券"的现象一模一样，但根因不同，排查时先确认编码是否来自当前渠道的 query-meals。
• 到店单基本没有满减档位（2026-10-16 实测）：到店 ¥94 的篮子 discount:0、无 enjoyable。满减主要在外送 / 团餐场景，别对到店单承诺凑满减。
• 外送单还有打包费：外送（orderType=2）除配送费外还会产生打包服务费（packingPrice，且可能自带打包优惠），算总价时必须计入。
• 若用户明确"只要某单品"，则退化为：该单品可用券中优惠最大的组合。
• 关注热量/营养时可叠加 list-nutrition-foods。

7. 能力四：多人群点聚合（聚餐拼单）

触发：① 入口询问的答复为"多人 / 拼单"（见第 3 节：点餐前必须主动问一句，这是本能力最主要的触发路径，不依赖用户自己提出）；② 用户直接表达群体点单诉求，如"帮大家点麦当劳""办公室下午茶拼单""加班夜宵一起点""宿舍/家庭聚餐点餐""群里点单帮我算账""几个人一起点怎么划算"等。

能力四不是"用户提了才有"的可选项。只要入口确认是多人，必须按本能力走完整流程（尤其"算账"环节），不得退化成"把 N 份餐加进购物车"。

定位（必须先向用户讲清）：MCP 为单账户鉴权，本能力是组织者模式——全体成员的餐品由下单人在会话内代录，最后用下单人自己的账户统一结算，其他人按账单向下单人支付。严禁模拟登录、代理登录或索取任何成员的账号 / 密码 / 验证码。收款由组织者自行完成（微信群收款 / 本人收款码），本 Skill 不代收款项、不生成官方收款码。

数据结构、分摊算法与账单模板见 references/group-order.md，实现时必须遵循其中定义。

阶段一 · 开单：

1. 澄清：就餐方式（外送 / 到店取）、门店或地址、大致人数、分摊偏好；
2. 分摊偏好三项：公共费用（配送费 + 打包费；均摊 / 按消费比例 / 指定人承担）、优惠券省额（归下单人 / 平摊）、是否接受凑单建议；
3. 门店与地址沿用能力三第 3 步链路；
4. 创建订单会话文件 <workspace>/.workbuddy/group-orders/yyyymmdd-hhmm-<N>人.json，回显订单标识，方便后续轮次续单。

阶段二 · 收单：

• 支持随时增改撤："张三 麦辣鸡腿堡×1 可乐×1""李四跟张三一样""王五撤销"；
• 每次变动后增量回显聚合列表：共 N 人 / M 件 / 小计 ¥X，若接近满减档位则附「距下一档还差 ¥Y」；
• 重复提醒：多人点相同餐品时自动合并展示数量，并问一句"是否需要分开包装"；
• 餐品单价一律取自当前渠道的 query-meals / query-meal-detail，不得使用记忆价（外送与到店菜单价不同，见第 6 节要点）。

阶段三 · 算账（成员确认"收完了"后才进入）：

1. 盘券沿用能力三第 4 步（下单人账户）；
2. 满减凑单：对全员总价比对满减档位；若加购小额单品（派 / 圆筒等）可跨档且净支付更低，给出建议——必须整体送 calculate-price 实算验证「加购后总支出 < 不加购总支出」，征得同意才加入清单，绝不自动加购；若 calculate-price 未返回 enjoyable/balance，说明当前订单无可跨档位，直接说明"无凑单空间"，不要臆造档位；
3. 券归属：用下单人账户券参与 calculate-price，账单明确标注「券省 ¥X 归下单人」或「平摊每人减 ¥Y」；
4. 公共费用分摊：以 calculate-price 返回的配送费 deliveryPrice + 打包费 packingPrice 之和为准，按选定规则计算每人明细（算法含尾差兜底，见参考文档 3.3/3.4）；
5. 小计口径（易错）：账单"小计"列对用了券的成员要用券前基准价（现价 + 该券省额），否则"券省"会在小计里被重复扣减，导致合计与实付差额正好等于券省额；
6. 分摊总原则：每人应付之和必须严格等于实付总额（尾差落在最后一人）。

阶段四 · 成单与结算：

1. 生成账单：每人（餐品明细 / 券前小计 / 分摊券省 / 分摊公共费 / 应付）+ 合计行 + 优惠归属说明 + 凑单判定结论（模板见参考文档 4.1）；
2. 对话内输出 Markdown 账单；组织者需要时可生成单文件 HTML 账单（内联样式，可嵌入组织者本人的收款码图片）供分享；
3. 组织者对账单确认后，按能力三第 9 步下单（写操作二次确认红线不变，单账户结算）；
4. 收款：账单给出每人应付金额，组织者用微信「群收款」（逐个按金额）或自己的收款码收款。

异常处理：

• 成员中途加单 / 撤单：未下单前随时回到阶段二重算；
• 下单时券失效：create-order 报错即停止并回滚提示，不自动重试扣款；
• 有人不付款：账单即为凭据，不做任何催收、代扣或垫付建议。

8. 小红书场景能力（能力五 ~ 十）

以下五项围绕"刷爆小红书的麦当劳玩法"设计。共同前提：只要最终要落到下单，就仍然受第 3 节点餐入口（先问单人 / 多人拼单）与第 2 节硬性规则（写操作二次确认、下单前必须 calculate-price 实算）约束，新能力不豁免任何红线。

输入层三种形态与实测边界：

8.1 能力五：爆款"隐藏吃法"一键还原

定位：把"薯条 + 冰淇淋""苹果派 + 麦旋风爆浆""热红茶 + 免费奶球 = 自制港奶""麦乐鸡 + 薯条 + 两包胡椒粉 + 两包辣椒酱 + 一包糖 = 摇摇乐"这类小红书爆款，还原成可下单的订单。

流程：

1. 解析：从文案 / 截图里抽出三类要素——① 基础单品（可加购的商品）；② 特调要求（走酱、去冰、换燕麦奶等，可用 modification 真做到）；③ 免费配件（多要两包番茄酱 / 糖 / 胡椒粉 / 空杯 / 奶球，不是商品，无法加购）。
2. 映射菜单：query-meals 拿当前门店 + 渠道的商品编码。必须按 orderType 分别取码（外送编码与到店不同）。
3. 分类处理：
   • 特调 → query-meal-detail 读 modification，按 key 规则（选中用 selectedKey、未选且有 unselectedKey 的必须一并传 unselectedKey）传入 calculate-price / create-order；
   • 免费配件 → 只能进 remark（见下）；
   • 菜单里没有的单品 → 明说"这家店 / 这个渠道没有"，给替代单品或换店建议，不要虚构。
4. 算价下单：calculate-price → 展示 → 用户确认 → create-order（写操作二次确认不变）。

免费配件与 remark 的硬边界（最容易踩的坑）：

• create-order 的 remark 仅 orderType=2（外送）场景有意义，最多 50 字；到店自取（orderType=1）没有备注入口。
• 因此：外送单 → 自动把配件要求写进 remark（如"麦乐鸡薯条摇摇乐：请给 2 包胡椒粉、2 包番茄酱、1 包糖，多谢！"）；到店单 → 改为给用户一句到店话术让他取餐时跟店员说，并说明 MCP 侧无法代填。
• 备注里不要写支付、改价、退单等无效诉求；50 字内优先写"数量 + 品类"。

已知映射实例（完整词典见 references/xhs-playbook.md）：

• "走酱鱼柳包" → 麦香鱼 + modification 取消 100126 麦香鱼酱（真能做到，不是备注）；
• "港式奶茶" → 锡兰红茶 3505 实测 supportModify=false，加不了奶球；能"正规走特调"的是小杯鲜萃咖啡 520689（¥11），默认自带 120550 奶油球 + 120551 白砂糖（均 price 0）。红茶的奶球只能进备注 / 到店话术，别承诺能特调；
• "无糖版 XXX" → 饮料换 无糖可口可乐（实测 +¥0，热量 0 大卡）。到店与外送实现不同：到店可乐 9900008751 是 rounds 选配商品，必须用 roundList 传 3021 无糖可口可乐小杯；外送的无糖可乐是独立商品 903071，直接换码；
• "多要两包胡椒粉" → 只能 remark（外送）或到店话术。

8.2 能力六："小红书式"穷鬼套餐 / 神仙组合穷尽演算

定位：用自然语言约束（预算上限、必须有肉 / 主食 / 无糖饮料、手里有张满 30 减 10）让 Agent 凑出最优组合。

流程：

1. 结构化约束：把用户的话拆成硬约束（预算 ≤X、必须包含某类、热量 ≤Y）与软目标（越便宜越好 / 蛋白越高越好）。
2. 盘券：query-store-coupons（唯一返回 couponId/couponCode 的接口，query-my-coupons 与 available-coupons 都不返回 ID、无法直接用于算价），记录每张券的门槛、指定商品、渠道限制；要领券先征得同意。
3. 枚举候选：从当前渠道 query-meals 里按约束挑 2~5 个候选组合；优先用套餐（套餐通常比单点叠加便宜），需要换购选项时 query-meal-detail。
4. 逐个真算：每个候选都送 calculate-price（带券传 couponId/couponCode），以返回值排序，严禁心算。
5. 给结论：输出"应付最低"方案 + 一句为什么（用到了哪张券、省多少），并说明原价 vs 实付。

硬边界：

• 到店单基本没有满减档位：实测到店 ¥94 的篮子 discount:0、无 enjoyable。满减主要出现在外送 / 团餐场景。
• 用户手里可能根本没有满减券：实测该账户 6 张券全是商品券 / 早餐券，无"满 30 减 10"这类满减券。遇到"帮我凑满减"先 query-store-coupons 核实，没有就明说，不能顺着用户的话术臆造一张券。
• 硬约束可能根本不可满足，要敢说做不到：实测"≤20 元 + 有肉 + 有主食 + 无糖饮料"在该门店菜单下无解（最便宜主食麦香鸡 ¥19.5，再加任意饮料必超 20）。正确做法：宣告不可满足 → 给"最接近"方案 → 说清"放松哪一条就能满足"（放松预算到 ¥30.5 即得麦香鸡 + 无糖可乐）。不得为凑数把饮料偷偷去掉，也不许把纯净水算成无糖饮料。
• 无档位就明说：calculate-price 未返回 enjoyable/balance 时，直接说"当前无凑单空间"，不臆造档位。
• 券价优先于菜单促销价，且 discount 按券原价口径计：实测冰美式中杯菜单促销价 ¥11.9，用「9.9 元」券后 price: 990、discount: 1310（相对 productOriginalPrice 2300 算的，不是 2300 − 1190）。向用户解释"省了多少"别直接引用 discount 字段。
• 凑单建议必须自证：建议加购小额单品跨档时，必须整体送 calculate-price 证明"加购后总支出 < 不加购"，征得同意才加入，绝不自动加购。
• 外送单还有配送费 + 打包费，跨档判定要把它们算进去（免配时麦金卡随单购可能反而更省，见能力七）。
• 外送打包费有显示坑：packingPrice: 110 但 productList 里「打包服务费」那行 subtotal: 0，逐行 subtotal 相加会漏掉打包费。账单一律以顶层 price 为准。

8.3 能力七：周边 / 联名 / 限定款"抢货雷达"

能做到：

• 按需扫店：对用户指定的 1~N 家门店逐一 query-meals，看目标周边是否在售（实测编码：521954 联名复古棒球帽、521955 联名徽章、521743 薯条脆卜卜毛绒周边、521946 旋旋星愿贴）。周边随门店和渠道变化，同一时刻上海某店到店菜单没有帽/徽章、深圳外送菜单有，所以必须先扫再下结论。
• 一键锁单：确认在售后走 calculate-price → 用户确认 → create-order。抢限量款时提前把门店、商品编码、withOrder 参数备好，减少往返。
• 麦金卡随单购优化：实测加购 521234 麦金卡体验卡（15 天）¥9.90 后，周边降 ¥5、配送费与打包费归零，几乎总是更省（净省 ¥1.10～¥12.10）。calculate-price 会自动把体验卡和归零费用写进 productList，照抄返回值。

做不到（不要承诺）：

• ❌ 实时库存查询：35 个工具里没有任何门店库存接口，"这家店还有几顶帽"无法回答。
• ❌ 持续监控 / 补货提醒：无法后台轮询；只能做"用户问一次、扫一次"的按需查询，并明确告知这是查询时点的在售状态，不是实时库存。
• ❌ 积分商城换周边：mall-points-products 类目 2>8 实测仅 3 项且全部过期。

话术要点：用户要"监控"时，先给按需扫描结果，再说明边界，并建议：想稳拿限量款，直接下单锁单比监控更可靠（MCP 侧锁单即生成真实订单）。

8.4 能力八：减脂期 / 打工人"参数化营养买手"

定位：按"热量 ≤450 大卡、蛋白质 >25g、控糖、去酱"等参数组合出定制订单。

数据源与流程：

1. list-nutrition-foods（无入参）一次性拿全量营养表，字段：productName / energyKj / energyKcal / protein / fat / carbohydrate / sodium / calcium（单位分别为 kJ、kcal、g、g、g、mg、mg）。实测约 180 项，含 无糖可口可乐（0 kcal）、锡兰红茶（2 kcal）、苹果片（32 kcal）、麦香鱼（325 kcal / 蛋白 16g）等。
2. 在表里按约束筛候选 → 回 query-meals 确认该门店在售及现价 → calculate-price 实算。
3. 特调降卡：query-meal-detail 的 modification 可取消酱料（巨无霸 100116 巨无霸酱、麦香鱼 100126 麦香鱼酱）、改冰量（标准/去冰/多冰/少冰）、换燕麦奶（+¥2）。注意：营养表按标准份计，取消酱料能省的热量不会自动反映在表里，需在结论里注明"已去酱，实际热量略低于表中值"。

硬边界：

• 营养表是标准份数据，改特调 / 换小份大份后不会自动重算，不要谎称精确；
• 表中同名项可能重复（如"小杯玉米杯""纯牛奶"出现多次），取值一致即可，别当成不同商品；
• 套餐的营养 ≠ 各子项简单相加（有烹饪方式差异），给区间并说明是估算；
• 热量约束是近似满足，结论里写"约 XXX 大卡"。

8.5 能力九：晒单卡片一键生成

定位：点完单 / 想分享时，生成小红书风格的卡片 + 文案，纯本地产出，不消耗 MCP 调用。

卡片内容（用订单与算价结果填充）：

• 商品清单 + 缩略图（query-meals 返回的 image 字段可直接引用）；
• 省钱对比：原价（originalPrice/originalSubtotal）vs 实付（price/subtotal），高亮"立省 ¥X"；
• 热量对比：来自 list-nutrition-foods 的柱状 / 环形图（三大营养素占比）；
• 一句小红书味文案（见下）。

产出形态：单文件 HTML 或 SVG（内联样式、无外部依赖），与 assets/ 既有视觉资产同一套手法（手写矢量、静态帧完整、不启动浏览器渲染）。

交付前自检（必做）：XML / HTML 合法性 + 逐条文本边界推算（CJK 记 1em、拉丁 0.55em、空格 0.3em），确认无左右下溢出；右对齐金额统一用 text-anchor="end"。现成样例见 assets/xhs-card-demo.svg（900×1200 竖版）。

文案风格：短句 + emoji + 具体数字 + 行动号召。模板与示例见 references/xhs-playbook.md 第 5 节。红线：文案里的价格 / 热量 / 省钱数字必须来自本次真实订单与 calculate-price / 营养表，不得为好看而编造；用户没做过营养查询就不编热量。

8.6 能力十：天气与场景感应式推送

能做到（基于 now-time-info 的日期 / 星期 / 时刻）：

• 时段场景：早餐时段推早餐卡 / 9.9 元早餐两件套；下午茶时段推麦旋风 / 派；夜市时段（实测门店 reservationTimeOptions 里有"夜市 17:30 至 23:30"）推炸鸡小食。
• 星期场景：周五下班推"打工人周五福利"（自动带上麦乐鸡 + 特调饮料）；周末推"麦麦周末"专享（实测外送菜单有 麦麦周末 分类与 9900013854 麦麦炸鸡5拼 促销）。
• 活动叠加：与能力一 / 能力二联动，命中联名或限定时优先推。

做不到：

• ❌ 天气：MCP 无天气工具，拿不到气温 / 降雨 / 降温。用户说"今天下雨"→ 可以据此推荐热饮热食，但不要自称查了天气，也不要编造温度。
• ❌ 定时自动推送到点：由外部自动化任务触发（建议每日 09:00，同能力二），本 skill 只负责"判断场景 + 组织推送内容"。

9. 常见问题处理

10. 兼容性

本 skill 不绑定特定 Agent 框架，全程使用官方工具名描述流程，可接入任何支持 MCP 的框架（Claude Code / Cursor / Cline / Cherry Studio / Trae / Kiro / VSCode / WorkBuddy 等）。

config/keywords.json 的读写依赖文件系统权限；若运行环境无文件权限，可把关键词直接写在对话上下文中，其余流程不变。

第 8 节各能力对运行环境的额外依赖：截图解析需客户端支持把图片传入对话（多模态）；小红书链接解析已实测不可用，不依赖任何额外能力；晒单卡片产物为本地 SVG / HTML 文件，需要文件写权限。

mcd-cn-assistant

把麦当劳中国官方 MCP 工具，封装成一个开箱即用的 Agent 技能：活动不错过、优惠不放过、点餐不吃亏、群点不算账。

一、项目介绍

1.1 这是什么

mcd-cn-assistant 是一个面向 AI Agent 的技能包（Skill），建立在麦当劳中国官方 MCP 服务（https://mcp.mcd.cn）之上。

麦当劳中国官方 MCP 提供了 30+ 个原子工具——查门店、查菜单、查券、领券、算价、下单、查积分、积分商城、积分抽奖、主题活动预约……但原子工具不等于能用的助手。直接用这些工具，用户需要自己记住几十个工具名、自己判断先调哪个后调哪个、自己组合券和商品算最便宜的方案，还得时刻提防 AI 擅自下单。

本项目做的事情是：把这堆原子工具编排成四条用户真正会用的业务流，并把安全边界写死。

1.2 解决什么问题

1.3 四大能力 + 小红书场景六项

统一入口（关键设计）：能力三与能力四共用一个点餐入口——只要是点餐请求，Agent 在定位门店前会主动问一句「这单是你自己吃，还是帮几个人一起点（拼单）？」，再据此分流。多人拼单不需要用户自己想到，答一句"拼单"即可进入完整的分账流程；回答含糊时会再确认一次，不会默认按单人处理。

小红书场景六项（2026-10-16 新增）

完整词典、算法与模板见 references/xhs-playbook.md；真实对话示例见 docs/examples.md 示例 13~16。

1.4 架构

flowchart TD
    A["麦当劳中国 MCP 服务<br/>mcp.mcd.cn · Streamable HTTP · Bearer Token"]
    A --> B1["能力一：最新活动推送"]
    A --> B2["能力二：联名关注推送"]
    A --> G["点餐统一入口<br/>先主动问：单人还是多人拼单？"]
    G --> B3["能力三：最优惠点餐"]
    G --> B4["能力四：多人群点聚合"]
    B1 --> C1["now-time-info<br/>campaign-calendar<br/>available-coupons"]
    B2 --> C2["config/keywords.json<br/>关键词 + 同义词扩展"]
    B3 --> C3["门店 → 领券 → 菜单<br/>calculate-price 比价<br/>确认后 create-order"]
    B4 --> C4["开单 → 收单聚合<br/>满减凑单 + 券归属 + 公共费用分摊<br/>每人账单 → 确认后单账户结算"]
    C2 --> D["定时自动化<br/>每天 09:00 只读推送"]
    A --> E1["小红书场景六项"]
    E1 --> E2["⑤ 隐藏吃法还原：文案/截图解析<br/>→ 特调 modification + 外送 remark"]
    E1 --> E3["⑥ 穷鬼套餐演算：约束拆解<br/>→ 多候选 calculate-price 实算"]
    E1 --> E4["⑦ 周边雷达：逐门店扫菜单<br/>→ 麦金卡随单购优化 → 锁单"]
    E1 --> E5["⑧ 营养搭配：list-nutrition-foods<br/>→ 去酱 / 换无糖 / 算价"]
    E1 --> E6["⑨ 晒单卡片：本地生成 SVG<br/>⑩ 场景推送：时段 + 星期"]
    style A fill:#5DCAA5,stroke:#0F6E56,color:#04342C
    style G fill:#FAC775,stroke:#854F0B,color:#412402
    style B1 fill:#9FE1CB,stroke:#0F6E56,color:#04342C
    style B2 fill:#9FE1CB,stroke:#0F6E56,color:#04342C
    style B3 fill:#9FE1CB,stroke:#0F6E56,color:#04342C
    style B4 fill:#9FE1CB,stroke:#0F6E56,color:#04342C
    style E1 fill:#FAC775,stroke:#854F0B,color:#412402
    style E2 fill:#FFF4E0,stroke:#854F0B,color:#412402
    style E3 fill:#FFF4E0,stroke:#854F0B,color:#412402
    style E4 fill:#FFF4E0,stroke:#854F0B,color:#412402
    style E5 fill:#FFF4E0,stroke:#854F0B,color:#412402
    style E6 fill:#FFF4E0,stroke:#854F0B,color:#412402
    style C1 fill:#E1F5EE,stroke:#5DCAA5,color:#085041
    style C2 fill:#E1F5EE,stroke:#5DCAA5,color:#085041
    style C3 fill:#E1F5EE,stroke:#5DCAA5,color:#085041
    style C4 fill:#E1F5EE,stroke:#5DCAA5,color:#085041
    style D fill:#FAC775,stroke:#854F0B,color:#412402

1.5 目标用户

核心用户

典型痛点

• 活动散落在 App 首页、公众号、门店海报，看到时往往已经结束；
• 优惠券种类多、门槛各异（满减 / 第二份半价 / 指定商品 / 限渠道），靠人脑判断哪种买法最便宜成本极高；
• 群点时刷屏报菜名记不住、满减档差几块钱没人算、配送费、打包费和优惠券没人分，收钱环节更是大型社死现场；
• 想拼单却不知道工具支持——多人点餐能力如果只能靠用户自己提起，等于不存在；本项目把它前置为点餐入口的主动提问；
• 刷到小红书爆款吃法，不知道哪些真能点、哪些只能跟店员说，也懒得自己拆；
• 想凑"20 块穷鬼套餐"或"450 大卡减脂餐"，人脑枚举不出最优解；
• AI 助手能查菜单，但用户不敢让它下单——怕它算错价、用错券、多花钱。

适用环境

• 任意支持 MCP 的 AI 客户端（WorkBuddy / Claude Code / Cursor / Cline / Cherry Studio / Trae / Kiro / VSCode Copilot 等）；
• 需自备一枚麦当劳中国 MCP Token；
• 仅面向中国大陆地区（麦当劳 MCP 服务不含港澳台）。

二、仓库结构

mcd-cn-assistant/
├── README.md                  # 项目介绍 / 安装方法 / 使用示例 / 目标用户
├── CONTEST_DECLARATION.md     # 参赛声明（官方文件，内容未改动）
├── MCP_INTEGRATION.md         # MCP 集成说明：Server / Tool / 调用流程 / 业务价值
├── mcp-config.example.json    # 脱敏配置示例（仅环境变量占位符）
├── workbuddy.md               # WorkBuddy 开发上下文（WorkBuddy 专项奖励用）
├── SKILL.md                   # 技能主体（Agent 运行时加载）
├── LICENSE                    # MIT
├── assets/
│   ├── banner.svg             # 顶部横幅（自绘动画 SVG）
│   └── cta-star.svg           # 结尾 Star CTA 图
├── config/
│   └── keywords.json          # 联名 / 活动关注关键词配置（能力二读取）
├── references/
│   ├── mcd-tools.md           # 35 个 MCP 工具速查表 + 调用顺序 + 错误码 + 2026-10-16 实测要点
│   ├── group-order.md         # 能力四：订单会话结构 + 分摊算法（尾差兜底）+ 账单模板
│   └── xhs-playbook.md        # 小红书场景：隐藏吃法词典 + 凑单算法 + 营养子集 + 晒单模板
└── docs/
    ├── mcp-setup.md           # MCP 接入说明（WorkBuddy / Cursor / Cherry Studio / Trae / Claude Code …）
    └── examples.md            # 四大能力 + 小红书六项的真实对话示例

三、安装方法

前置条件：已取得麦当劳中国 MCP Token（在 https://open.mcd.cn/mcp 手机号登录 → 控制台 → 激活 → 复制）。

第 1 步：配置 MCP 服务（WorkBuddy 官方流程）

1. 打开 WorkBuddy，在左侧边栏【专家·技能·连接器】，选中【连接器】页签；

2. 点击右上角【自定义连接器】→【配置MCP】；

3. 在打开的手动配置页面中填入以下的 JSON 内容：

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

   ⚠️ 一定记得把 ${MCD_MCP_TOKEN} 替换为「你自己的」实际 MCP Token，点击【保存】！

   填入后请确认 Authorization 的值已经是你的真实 Token（形如 Bearer abc123...）——WorkBuddy 手动配置页填入的是字面值，不要保留 ${MCD_MCP_TOKEN} 这个写法本身。

4. 回到【自定义连接器】，将 mcd-mcp【启用】。

其他客户端（Cursor / Cherry Studio / Trae / VSCode / Claude Code）见 docs/mcp-setup.md。

📌 关于占位符：本仓库不含任何真实凭证，所有出现 ${MCD_MCP_TOKEN}、<你的 MCP Token> 的位置都需要你填入自己的 MCP Token。完整对照见 docs/mcp-setup.md · 占位符速查。

第 2 步：安装技能

将这段话复制给你的AI Agent（WorkBuddy、claw等）： 帮我安装mcd-cn-assistant这个skill： 1、https://github.com/junxchan54-maker/mcd-cn-assistant/ 2、以后我说麦当劳下单相关的就调用mcd-cn-assistant这个skill 3、把仓库里 skill/mcd-cn-assistant 文件夹复制到用户级技能目录

把本仓库的 SKILL.md、config/、references/ 放进你所用客户端的技能目录。推荐 clone：

git clone https://github.com/<your-name>/mcd-cn-assistant.git ~/.workbuddy/skills/mcd-cn-assistant

各客户端的技能目录：

若你的客户端不支持技能目录机制，也可直接把 SKILL.md 的内容作为系统提示词或项目 Rules 粘贴进去，流程完全一致。

第 3 步：验证

对 Agent 说一句：

用 mcd-cn-assistant 查一下这个月麦当劳有什么活动

能正常返回活动列表即接入成功。若报 401，说明 Token 无效或未提供；若报 429，说明触发了 600 次/分钟的限流。

四、使用示例

入口 · 点餐前主动询问（能力三 / 四 共用）

你：帮我点个麦当劳，中午想吃点好的

Agent（澄清需求后，不会直接查门店，而是先问）： 「这单是你自己一个人吃，还是帮几个人一起点（拼单）？拼单的话我可以代录大家想吃的、帮你凑满减、把配送费和打包费算清楚，最后出一张「每人应付多少」的账单。」

• 你答「就我自己」→ 进入能力三 · 最优惠点餐；
• 你答「我们部门 5 个人一起点」→ 进入能力四 · 多人群点聚合，接着确认人数、门店/地址与分摊偏好；
• 你答「我们几个人一起吃，但我自己付」→ 走能力三按整单找最省，顺带问一句要不要分摊账单；
• 你答得含糊（如「随便点点」）→ 再确认一次，不会默认按单人处理。

能力一 · 最新活动推送

你：这个月麦当劳有