name: mcdonalds description: 麦当劳中国官方 MCP 全能助手。当用户提到麦当劳、麦乐送、开心乐园餐、麦麦省优惠券、领券、点麦当劳、外送到家、得来速、麦当劳积分、积分抽奖、积分商城兑换、麦当劳餐品热量/营养、麦当劳订单查询或取消、麦当劳周边玩具与活动时使用。覆盖官方 35 个工具的全部能力，内置领券、到店点餐、外送、玩具雷达、积分抽奖、热量计算、优惠计算器七大工作流。 agent_created: true

麦当劳 MCP 全能助手

通过麦当劳中国官方 MCP Server（mcd-mcp @ https://mcp.mcd.cn）为用户完成从领券、比价、点餐、外送到积分抽奖、营养计算的全流程。共 35 个工具，全部能力见 references/tools.md。

前置条件

1. ~/.workbuddy/mcp.json 中需存在 mcpServers.mcd-mcp（含 Authorization: Bearer <token>）。Token 获取：https://open.mcd.cn/mcp
2. 该 MCP 需在「连接器管理」中点击信任后，工具才会出现在可用工具列表里。

两种调用通道

通道 B 示例：

python scripts/mcd_cli.py list 优惠
python scripts/mcd_cli.py call auto-bind-coupons
python scripts/mcd_cli.py call query-nearby-stores '{"beType":1,"searchType":1,"city":"北京"}'

通用铁律（违反会直接报错或下错单）

1. beType 决定一切：1=到店自取、2=麦乐送外送、5=得来速、6=企业团餐。
2. orderType：到店类（含自取 + 得来速）= 1；外送类（含麦乐送 + 团餐）= 2。
3. beCode 与 storeCode 配对：到店自取(beType=1)不传 beCode；得来速从 query-nearby-stores 取；麦乐送/团餐从 delivery-query-stores 取。传错会报错。
4. query-nearby-stores.searchType 必须传对（实测坑）：
   • searchType=1 查收藏餐厅；该 beType 无收藏时返回 600050 收藏餐厅列表为空。到店自取(beType=1)通常有收藏店，得来速(beType=5)常为空。
   • searchType=2 按位置搜索，必须 city 与 keyword 同时传；只传其一必报 600058 城市名或者关键词不能为空。
   • 稳妥路径：先试 searchType=1，报 600050 则改用 searchType=2 + city + keyword。
5. 菜单编码路径：query-meals 的餐品编码在 data.categories[].meals[].code，详情在 data.meals.{code}（含 name/currentPrice/originalPrice）。 ⚠️ 不要误取响应外层的 code——那是业务状态码（200），不是餐品编码。
6. 绝不臆造编码：storeCode、beCode、addressId、productCode、couponId、skuId 都必须来自上游工具返回，不得凭空生成。
7. reservationDate 仅预约场景传（格式 yyyy-MM-dd HH:mm），非预约不要传。门店返回 reservation=true 时，其 reservationTimeOptions 必须完整展示，缺项会导致用户无法预约。
8. 下单前必须 calculate-price，把明细与总价展示给用户并取得明确确认，再调 create-order。禁止跳过算价直接下单。
9. 到店场景（orderType=1）下单必传 takeWayCode，取值只能来自 calculate-price 返回的 data.takeWayList[].code（实测取值：eat-in / take-in-store）；外送/团餐（orderType=2）不要传（其算价返回不含 takeWayList）。
10. 抽奖必须两段式：先 query-lottery-info 展示 drawDecision.nextConsumption，用户明确确认后才可 draw-lottery。禁止试抽、自动抽、连续抽。
11. 业务成败看 success 字段（仅适用于结构化返回）：工具调用不报错 ≠ 业务成功。响应 JSON 中 success=false 即失败（如 60006 商品已售罄、600058 城市名为空），须如实转述 message，不得改写或掩盖。
12. 返回有两种形态，别搞混：
    • 结构化返回（多数工具）：字段说明 + 原始 JSON，按字段取值。
    • 服务端已渲染的 Markdown（实测 available-coupons、query-my-coupons、campaign-calendar）：直接原样展示给用户，不要试图解析字段、也没有 success 可判。空文本即视为无数据。
13. 点单前必须检查「口味 / 套餐选项」：任何商品在算价/下单前都要用 query-meal-detail 看它有没有 rounds（选一/套餐组）或特制（modification）。有选项就必须先让用户选，不能默认带过——rounds[].choices[].quantity=1 的只是默认项，不代表用户已选。
14. 消耗性取舍不得替用户决定：凡是「要不要多花积分 / 多下单 / 溢出到其他资产」这类取舍，必须把每个方案的代价（花多少、分别来自哪部分资产）摊开给用户，由用户拍板。脚本与 agent 只负责给方案，不预设默认、不自行选择。典型场景：抽奖是否「溢出」到非将过期积分。

七大核心工作流

0. 入口：先确认取餐方式（凡涉及门店 / 菜单 / 下单，都必须先走这一步）

不要一上来就搜门店或菜单。先问用户一句：

「你要怎么取餐？① 到店自取 ② 麦乐送外送 ③ 得来速（车道取餐）」

• 自取 / 得来速：位置是必需输入 → 用「低成本问法」：先查 order-list 问「你现在是不是在常去那家 XX 店附近？」，答否再问「城市 + 地标」。
• 麦乐送：不要问「你在哪」 —— 由配送地址决定门店；没有地址就先问地址或帮用户新增。
• 门店菜单/玩具/活动等查询同理：先定取餐方式，再定门店，最后才取菜单。

1. 领券

触发：「帮我领券」「有什么优惠券」「领麦麦省的券」

available-coupons      → 展示当前可领取的券（名称/图片/状态/标签）
auto-bind-coupons      → 一键领取全部可领券（无入参）
query-my-coupons       → 查卡包已有券（page/pageSize）

query-my-coupons 不校验门店与下单规则；要看「这家店这个订单能用的券」须用 query-store-coupons（见工作流 7）。

2. 点餐（到店自取 / 得来速）

# 前置：第 0 步已确认「自取 / 得来速」并问到位置
# ① 找店：用「城市 + 地标」搜（searchType=2），结果按 distance 升序，第一条即最近
query-nearby-stores {beType:1(自取)/5(得来速), searchType:2, city:"北京市", keyword:"长安小区"}
  → 取 storeCode；得来速(beType=5)另需 beCode
# ② 菜单：餐品编码在 data.categories[].meals[].code
query-meals {storeCode, orderType:1, beType}
query-meal-detail {storeCode, orderType:1, beType, code}    # 规格 / 特制 / 营养
# ③ 算价：返回 data.takeWayList[].code —— 下一步下单要用
calculate-price {storeCode, orderType:1, beType, items:[{productCode, quantity}]}
# ④ 下单：orderType=1 必带 takeWayCode
create-order {storeCode, orderType:1, beType, takeWayCode:"take-in-store", items:[...]}

不知道用户在哪儿 → 先问，而且用「低成本问法」： ① 先查 order-list 历史订单（和收藏门店），统计用户最常去的门店，直接问：「你现在是不是在 XX 店附近？」 ② 用户答否，再问「在哪个城市 + 附近哪个地标」，然后用 searchType=2 + city + keyword 搜。

searchType=2 返回真实距离且结果按 distance 升序，第一条即最近门店；searchType=1（收藏店）的 distance 恒为 0，不能用来判断远近。 keyword 取「具体地标」而非行政区名（实测：密云 命中 0 家，长安小区 命中 5 家）。用户给详细地址时，剥出其中的小区名/地标名当 keyword。 不要猜位置、也不要声称自己知道用户在哪。

3. 外送（麦乐送）

前置：第 0 步已确认取餐方式，且已问到用哪个配送地址（外送不问「你在哪」，由地址决定门店）。

delivery-query-addresses                    → 取 addressId（无地址则先 delivery-create-address）
delivery-query-stores (beType=2, addressId)  → 取 storeCode + beCode
query-meals (storeCode, beCode, orderType=2, beType=2)
calculate-price (addressId, storeCode, beCode, orderType=2, beType=2, items=[...])
create-order → 生成支付链接

配送进度：query-order(orderId)。详细字段示例见 references/workflows.md。

4. 周边玩具雷达

MCP 没有独立「玩具」接口，这是组合能力，按下列顺序拼出玩具/周边上新情报：

campaign-calendar (specifiedDate=当月)     → 当月活动：主题派对、品鉴会、麦麦体验营等
mall-points-products (catRuleIds 含 "2>8")  → 积分商城「周边产品」类目
query-meals (门店菜单)                      → 找含玩具的套餐（开心乐园餐等）
query-promotions (仅团餐门店)               → 门店满减/折扣规则

输出建议：玩具/周边 × 获取途径 × 时间窗 三列表。若接口未返回玩具字段，如实说明「本期接口未返回玩具信息」，不要编造款式名称。

5. 积分抽奖

query-my-account      → 积分余额（可选，用于展示）
query-lottery-info    → 活动名/状态/单次消耗 drawPoint/剩余次数/奖品列表/drawDecision
   ↓ 必须展示 drawDecision.nextConsumption 并获用户明确确认
draw-lottery          → 抽奖（服务端原子扣减）
query-my-prizes       → 我的奖品（pageNum/pageSize）

drawDecision.resourceEligible=false 时禁止调用 draw-lottery。返回「操作太频繁」时如实转述，不要重试。

5.1 到期止损：一键用「即将过期积分」抽奖

触发：「用快过期的积分抽奖」「别让积分白白过期」「把将过期积分花掉」

query-my-account    → currentMouthExpirePoint（本月将过期）、availablePoint
query-lottery-info  → drawPoint（单次消耗）、drawDecision
可抽次数 N = floor(currentMouthExpirePoint / drawPoint)
   ↓ 展示「抽 N 次、消耗 X 分、剩余 Y 分仍会过期」并获确认
draw-lottery × N    → 逐次执行，间隔 ≥1s；遇限流/失败立即停止，不重试

现成脚本（推荐直接用）：

python scripts/points_expiry_draw.py                                     # dry-run：摊开「不溢出 / 溢出」两方案
python scripts/points_expiry_draw.py --yes                               # 执行「不溢出」方案
python scripts/points_expiry_draw.py --yes --times 12 --allow-overflow   # 用户同意溢出后才可执行

是否溢出由用户决定（见铁律 14）：脚本默认只花将过期积分；--times 超出可覆盖次数时必须再加 --allow-overflow，否则以退出码 2 拒绝；将过期积分不足一次消耗时只提示「可改用其他积分」，不自行执行。

扣减顺序（实测）：先扣将过期积分，不足部分才从其他积分扣。 例：将过期 17.1 + 抽 1 次（24 分）→ 17.1 来自将过期、6.9 来自其他积分，抽后 currentMouthExpirePoint 归 0。 故「溢出」= 总消耗 > 将过期积分（超 1 分也算）；拆分按金额 min(总消耗, 将过期积分)，不是按次数取整。 draw-lottery 结果在 data 层下：data.status.code（SUCCESS 才算成功）、data.win、data.prizes[]（含 name/validDateInfo）、data.consumePoint。 ⚠️ 不是顶层 status —— 按顶层读会把「已中奖」误判为失败并中断（实测踩过）。

6. 热量计算

list-nutrition-foods        → 全量营养成分（能量/蛋白质/脂肪/碳水/钠/钙）（无入参）
query-meal-detail           → 单个餐品详情（含营养）

按用户目标（减脂/增肌/总热量上限）组合餐品，输出热量-蛋白质-脂肪-碳水表格并给出总热量。餐品缺失营养数据时标注「接口未提供」，不要估算填充。

7. 优惠计算器

目标：算出「用券 vs 不用券」哪个更省。

query-store-coupons (storeCode, orderType, beCode?, reservationDate?)  → 该店该场景可用券
   ↓ 取候选券的 couponId / couponCode
calculate-price (items=[{productCode, quantity, couponId?, couponCode?}])  → 逐方案算价

至少输出两组结果（不用券 / 用最优券）对比，标注节省金额。available-coupons 用于发现新券，auto-bind-coupons 补齐后再比价效果最佳。

扩展能力（MCP 中已有，按需使用）

常见触发 → 工作流对照

参考资源

• references/tools.md —— 35 个工具完整参数手册（含 enum、必填、原始描述）
• references/workflows.md —— 外送/点餐/团餐的字段级示例与 items 数组构造
• scripts/mcd_cli.py —— 零依赖命令行调用器（list / desc / call / raw）
• scripts/points_expiry_draw.py —— 积分到期止损：一键用将过期积分抽奖（dry-run / --yes / --times N / --allow-overflow / --interval）；是否溢出由用户决定

排障

🍟 麦麦全能助手 · McOmni

一句话，搞定吃麦全流程

领券 → 选店 → 配餐 → 比价 → 下单 → 派对预约 → 积分止损

基于麦当劳中国官方 MCP Server（mcd-mcp @ https://mcp.mcd.cn）构建的全能助手 Skill。

关于徽章：图片来自 shields.io，个别网络环境下可能加载较慢。README 的全部信息在正文中都有文字说明，徽章缺失不影响阅读。

目录

• 它解决什么问题
• 能力总览
• 快速开始
• 七大核心工作流
• 为什么它靠谱
• 项目结构
• 排障速查
• 安全与边界

🧩 它解决什么问题

麦当劳把 35 个能力开放给了 AI。但在真实账号上跑一遍就会知道：能调用 ≠ 会用。

flowchart TD
    U["👤 用户：想点个麦当劳"] --> Q{"🍽️ 怎么取餐？"}

    Q -->|"到店自取"| S1["query-nearby-stores<br/>→ storeCode"]
    Q -->|"麦乐送"| S2["delivery-query-stores<br/>→ storeCode + beCode"]
    Q -->|"得来速"| S3["query-nearby-stores<br/>→ storeCode + beCode"]

    S1 --> M["query-meals<br/>→ productCode"]
    S2 --> M
    S3 --> M
    M --> P["calculate-price<br/>→ takeWayCode"]
    P --> C["create-order<br/>→ orderId"]

    style Q fill:#FAEEDA,stroke:#854F0B,stroke-width:0.5px,color:#633806
    style P fill:#E6F1FB,stroke:#185FA5,stroke-width:0.5px,color:#042C53
    style C fill:#EAF3DE,stroke:#3B6D11,stroke-width:0.5px,color:#173404

每一环都必须来自上一环的返回值；中间任何一环猜错，订单就下不出去。

同时还要管住三件事：

McOmni 的价值不在"能调用工具"，而在知道什么时候不该调用——它把踩过的坑固化成硬约束，让 AI 在你的真实账号上安全地跑完整个流程。

🎯 能力总览

35 / 35 工具全覆盖，不只是检索类接口。

三种取餐方式全部支持：到店自取 / 麦乐送外送 / 得来速车道取餐。

🚀 快速开始

第 1 步 · 拿 Token

访问 https://open.mcd.cn/mcp，手机号登录 → 控制台 → 激活，一键复制 Token。

第 2 步 · 让助手能用上它

方式 A：作为 WorkBuddy Skill（推荐）

cp -r . ~/.workbuddy/skills/mcdonalds

然后在「连接器 → 自定义连接器」中填入配置（参考 mcp-config.example.json），把 ${MCD_MCP_TOKEN} 换成你自己的 Token。

方式 B：只用命令行通道（不需要任何 AI 客户端）

export MCD_MCP_TOKEN=<你的Token>
python scripts/mcd_cli.py list 优惠

# 找门店（searchType=2 按位置搜，city 与 keyword 必须同时传）
python scripts/mcd_cli.py call query-nearby-stores \
  '{"beType":1,"searchType":2,"city":"北京市","keyword":"鼓楼南街"}'

Token 解析顺序（任选其一即可）：

第 3 步 · 用起来

# 看有什么券，然后一键领掉
python scripts/mcd_cli.py call available-coupons
python scripts/mcd_cli.py call auto-bind-coupons

# 积分快过期了？先 dry-run 看方案，再决定花不花
python scripts/points_expiry_draw.py

🧭 七大核心工作流

⚠️ 工作流 4 需要特别说明：MCP 没有原生"玩具"接口，这是组合能力。若接口未返回玩具字段，助手会如实说明「本期接口未返回玩具信息」，不会编造款式。

🛡️ 为什么它靠谱

14 条防错铁律（节选）

完整 14 条见 SKILL.md。

三条设计原则

① 绝不臆造编码      一切 code 必须来自上游工具的返回值
② 副作用必二次确认   下单前必算价；抽奖前必展示消耗明细
③ 消耗性取舍交用户   不替用户决定花多少积分、要不要溢出

💡 积分到期止损：一个具体例子

麦当劳积分会过期。实测扣减顺序是 先扣将过期积分，不足才从其他积分扣，所以：

「是否溢出」 = 总消耗 > 「本月将过期积分」   （超出 1 分也算溢出）

python scripts/points_expiry_draw.py                          # 默认 dry-run，列出两套方案的代价
python scripts/points_expiry_draw.py --yes                    # 只花将过期积分
python scripts/points_expiry_draw.py --yes --allow-overflow   # 用户明确同意后才可溢出

flowchart LR
    A["读取将过期积分"] --> B["算可抽次数 N"]
    B --> C{"会溢出吗？"}
    C -->|"不会"| D["直接执行"]
    C -->|"会"| E["拒绝执行<br/>退出码 2"]
    E --> F["需显式加 --allow-overflow"]

    style C fill:#FAEEDA,stroke:#854F0B,stroke-width:0.5px,color:#633806
    style D fill:#EAF3DE,stroke:#3B6D11,stroke-width:0.5px,color:#173404
    style E fill:#FCEBEB,stroke:#A32D2D,stroke-width:0.5px,color:#791F1F

把决定权留给你，而不是"帮你想开一点"。

📂 项目结构

.
├── SKILL.md                     # 主文件：14 条铁律 + 7 大工作流 + 触发对照表
├── README.md
├── MCP_INTEGRATION.md           # 实际使用的 Server / Tool / 调用流程 / 业务价值
├── CONTEST_DECLARATION.md       # 参赛声明（官方原文件，未改动）
├── mcp-config.example.json      # 脱敏配置示例（仅环境变量占位符）
├── LICENSE
├── scripts/
│   ├── mcd_cli.py               # 零依赖 MCP 命令行通道（list / desc / call / raw）
│   └── points_expiry_draw.py    # 积分到期止损（dry-run / --yes / --allow-overflow）
└── references/
    ├── tools.md                 # 35 个工具完整参数手册
    └── workflows.md             # 字段级示例与 items 数组构造

🔧 排障速查

🔐 安全与边界

• Token 即身份：本项目不保存、不打印你的 Token。仓库中只保留 mcp-config.example.json 占位符示例，不包含任何真实凭证。
• 有副作用的操作需明确确认：下单、领券、抽奖、兑换均需用户确认后才执行。
• 本项目非麦当劳官方产品。餐品信息、价格与供应状态以麦当劳官方渠道的实时结果为准；项目输出仅供参考。

🏆 参与的活动

本项目为「麦当劳程序员创意开发大赛（M-CODE 1024）」参赛作品，由参赛者独立开发。

开发过程使用 腾讯 WorkBuddy，完整对话上下文见 workbuddy.md。

如果这个项目对你有帮助，欢迎点一个 Star ⭐

📄 License

MIT