Skip to content
Back to search

mcd-omni-assistant

SkillWorks with Claude CodeGitHub

麦当劳 MCP 全能助手 | 全覆盖 35 个工具 · 7 大工作流 · 14 条防错铁律 | 领券 / 点餐 / 外送 / 派对预约 / 积分到期止损,附零依赖 CLI 通道

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/lemon177777--mcd-omni-assistant/badge.svg)](/listings/lemon177777--mcd-omni-assistant)

HTML

<a href="/listings/lemon177777--mcd-omni-assistant"><img src="/api/listings/lemon177777--mcd-omni-assistant/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 237 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: mcdonalds
  3. description: 麦当劳中国官方 MCP 全能助手。当用户提到麦当劳、麦乐送、开心乐园餐、麦麦省优惠券、领券、点麦当劳、外送到家、得来速、麦当劳积分、积分抽奖、积分商城兑换、麦当劳餐品热量/营养、麦当劳订单查询或取消、麦当劳周边玩具与活动时使用。覆盖官方 35 个工具的全部能力,内置领券、到店点餐、外送、玩具雷达、积分抽奖、热量计算、优惠计算器七大工作流。
  4. agent_created: true
  5. ---
  6. # 麦当劳 MCP 全能助手
  7. 通过麦当劳中国官方 MCP Server(`mcd-mcp` @ `https://mcp.mcd.cn`)为用户完成从领券、比价、点餐、外送到积分抽奖、营养计算的全流程。共 **35 个工具**,全部能力见 `references/tools.md`。
  8. ## 前置条件
  9. 1. `~/.workbuddy/mcp.json` 中需存在 `mcpServers.mcd-mcp`(含 `Authorization: Bearer <token>`)。Token 获取:https://open.mcd.cn/mcp
  10. 2. 该 MCP 需在「连接器管理」中点击**信任**后,工具才会出现在可用工具列表里。
  11. ## 两种调用通道
  12. | 通道 | 适用 | 说明 |
  13. |---|---|---|
  14. | **A. 直接调用 MCP 工具**(首选) | MCP 已被信任 | 直接调用工具名,如 `query-meals`。参数严格按 `references/tools.md` |
  15. | **B. 命令行脚本**(备选/排障) | MCP 未信任、或需在终端验证 | `python scripts/mcd_cli.py call <工具名> '<json>'`;`list` 列工具、`desc` 查参数 |
  16. 通道 B 示例:
  17. ```bash
  18. python scripts/mcd_cli.py list 优惠
  19. python scripts/mcd_cli.py call auto-bind-coupons
  20. python scripts/mcd_cli.py call query-nearby-stores '{"beType":1,"searchType":1,"city":"北京"}'
  21. ```
  22. ## 通用铁律(违反会直接报错或下错单)
  23. 1. **`beType` 决定一切**:`1`=到店自取、`2`=麦乐送外送、`5`=得来速、`6`=企业团餐。
  24. 2. **`orderType`**:到店类(含自取 + 得来速)= `1`;外送类(含麦乐送 + 团餐)= `2`。
  25. 3. **`beCode` 与 `storeCode` 配对**:到店自取(`beType=1`)**不传** `beCode`;得来速从 `query-nearby-stores` 取;麦乐送/团餐从 `delivery-query-stores` 取。传错会报错。
  26. 4. **`query-nearby-stores.searchType` 必须传对**(实测坑):
  27. - `searchType=1` 查**收藏餐厅**;该 `beType` 无收藏时返回 `600050 收藏餐厅列表为空`。到店自取(beType=1)通常有收藏店,得来速(beType=5)常为空。
  28. - `searchType=2` 按位置搜索,**必须 `city` 与 `keyword` 同时传**;只传其一必报 `600058 城市名或者关键词不能为空`。
  29. - 稳妥路径:先试 `searchType=1`,报 600050 则改用 `searchType=2` + `city` + `keyword`。
  30. 5. **菜单编码路径**:`query-meals` 的餐品编码在 **`data.categories[].meals[].code`**,详情在 `data.meals.{code}`(含 `name`/`currentPrice`/`originalPrice`)。
  31. ⚠️ **不要误取响应外层的 `code`**——那是业务状态码(`200`),不是餐品编码。
  32. 6. **绝不臆造编码**:`storeCode`、`beCode`、`addressId`、`productCode`、`couponId`、`skuId` 都必须来自上游工具返回,不得凭空生成。
  33. 7. **`reservationDate` 仅预约场景传**(格式 `yyyy-MM-dd HH:mm`),非预约**不要传**。门店返回 `reservation=true` 时,其 `reservationTimeOptions` 必须**完整展示**,缺项会导致用户无法预约。
  34. 8. **下单前必须 `calculate-price`**,把明细与总价展示给用户并取得明确确认,再调 `create-order`。禁止跳过算价直接下单。
  35. 9. **到店场景(`orderType=1`)下单必传 `takeWayCode`**,取值只能来自 `calculate-price` 返回的 `data.takeWayList[].code`(实测取值:`eat-in` / `take-in-store`);外送/团餐(`orderType=2`)**不要传**(其算价返回**不含** `takeWayList`)。
  36. 10. **抽奖必须两段式**:先 `query-lottery-info` 展示 `drawDecision.nextConsumption`,用户明确确认后才可 `draw-lottery`。禁止试抽、自动抽、连续抽。
  37. 11. **业务成败看 `success` 字段**(仅适用于结构化返回):工具调用不报错 ≠ 业务成功。响应 JSON 中 `success=false` 即失败(如 `60006 商品已售罄`、`600058 城市名为空`),须如实转述 `message`,不得改写或掩盖。
  38. 12. **返回有两种形态,别搞混**:
  39. - **结构化返回**(多数工具):字段说明 + 原始 JSON,按字段取值。
  40. - **服务端已渲染的 Markdown**(实测 `available-coupons`、`query-my-coupons`、`campaign-calendar`):**直接原样展示给用户**,不要试图解析字段、也没有 `success` 可判。空文本即视为无数据。
  41. 13. **点单前必须检查「口味 / 套餐选项」**:任何商品在算价/下单前都要用 `query-meal-detail` 看它有没有 `rounds`(选一/套餐组)或特制(modification)。**有选项就必须先让用户选**,不能默认带过——`rounds[].choices[].quantity=1` 的只是默认项,不代表用户已选。
  42. 14. **消耗性取舍不得替用户决定**:凡是「要不要多花积分 / 多下单 / 溢出到其他资产」这类取舍,必须把**每个方案的代价**(花多少、分别来自哪部分资产)摊开给用户,由用户拍板。脚本与 agent 只负责给方案,**不预设默认、不自行选择**。典型场景:抽奖是否「溢出」到非将过期积分。
  43. ## 七大核心工作流
  44. ### 0. 入口:先确认取餐方式(凡涉及门店 / 菜单 / 下单,都必须先走这一步)
  45. **不要一上来就搜门店或菜单**。先问用户一句:
  46. > 「你要怎么取餐?① 到店自取 ② 麦乐送外送 ③ 得来速(车道取餐)」
  47. | 用户选择 | beType | 紧接着**必须先问** | 之后 |
  48. |---|---|---|---|
  49. | ① 到店自取 | `1` | **「你在哪儿?」**(城市 + 地标) | `query-nearby-stores(searchType=2, city, keyword)` → 按 `distance` 升序取最近 |
  50. | ② 麦乐送外送 | `2` | **「用哪个配送地址?」** | `delivery-query-addresses` → 选中或新增地址 → `delivery-query-stores` |
  51. | ③ 得来速 | `5` | **「你在哪儿?」**(开车去哪个区域) | `query-nearby-stores(searchType=2, city, keyword)`(`beType=5`) |
  52. - **自取 / 得来速**:位置是必需输入 → 用「低成本问法」:先查 `order-list` 问「你现在是不是在常去那家 XX 店附近?」,答否再问「城市 + 地标」。
  53. - **麦乐送**:**不要问「你在哪」** —— 由配送地址决定门店;没有地址就先问地址或帮用户新增。
  54. - 门店菜单/玩具/活动等查询同理:先定取餐方式,再定门店,最后才取菜单。
  55. ### 1. 领券
  56. 触发:「帮我领券」「有什么优惠券」「领麦麦省的券」
  57. ```
  58. available-coupons → 展示当前可领取的券(名称/图片/状态/标签)
  59. auto-bind-coupons → 一键领取全部可领券(无入参)
  60. query-my-coupons → 查卡包已有券(page/pageSize)
  61. ```
  62. > `query-my-coupons` 不校验门店与下单规则;要看「这家店这个订单能用的券」须用 `query-store-coupons`(见工作流 7)。
  63. ### 2. 点餐(到店自取 / 得来速)
  64. ```
  65. # 前置:第 0 步已确认「自取 / 得来速」并问到位置
  66. # ① 找店:用「城市 + 地标」搜(searchType=2),结果按 distance 升序,第一条即最近
  67. query-nearby-stores {beType:1(自取)/5(得来速), searchType:2, city:"北京市", keyword:"长安小区"}
  68. → 取 storeCode;得来速(beType=5)另需 beCode
  69. # ② 菜单:餐品编码在 data.categories[].meals[].code
  70. query-meals {storeCode, orderType:1, beType}
  71. query-meal-detail {storeCode, orderType:1, beType, code} # 规格 / 特制 / 营养
  72. # ③ 算价:返回 data.takeWayList[].code —— 下一步下单要用
  73. calculate-price {storeCode, orderType:1, beType, items:[{productCode, quantity}]}
  74. # ④ 下单:orderType=1 必带 takeWayCode
  75. create-order {storeCode, orderType:1, beType, takeWayCode:"take-in-store", items:[...]}
  76. ```
  77. > **不知道用户在哪儿 → 先问,而且用「低成本问法」**:
  78. > ① 先查 `order-list` 历史订单(和收藏门店),统计**用户最常去的门店**,直接问:「你现在是不是在 XX 店附近?」
  79. > ② 用户答否,再问「在哪个城市 + 附近哪个地标」,然后用 `searchType=2` + `city` + `keyword` 搜。
  80. >
  81. > `searchType=2` 返回**真实距离且结果按 `distance` 升序**,第一条即最近门店;`searchType=1`(收藏店)的 `distance` 恒为 `0`,不能用来判断远近。
  82. > **keyword 取「具体地标」而非行政区名**(实测:`密云` 命中 0 家,`长安小区` 命中 5 家)。用户给详细地址时,剥出其中的小区名/地标名当 keyword。
  83. > **不要猜位置、也不要声称自己知道用户在哪。**
  84. ### 3. 外送(麦乐送)
  85. **前置**:第 0 步已确认取餐方式,且已问到**用哪个配送地址**(外送**不问「你在哪」**,由地址决定门店)。
  86. ```
  87. delivery-query-addresses → 取 addressId(无地址则先 delivery-create-address)
  88. delivery-query-stores (beType=2, addressId) → 取 storeCode + beCode
  89. query-meals (storeCode, beCode, orderType=2, beType=2)
  90. calculate-price (addressId, storeCode, beCode, orderType=2, beType=2, items=[...])
  91. create-order → 生成支付链接
  92. ```
  93. 配送进度:`query-order(orderId)`。详细字段示例见 `references/workflows.md`。
  94. ### 4. 周边玩具雷达
  95. MCP **没有**独立「玩具」接口,这是**组合能力**,按下列顺序拼出玩具/周边上新情报:
  96. ```
  97. campaign-calendar (specifiedDate=当月) → 当月活动:主题派对、品鉴会、麦麦体验营等
  98. mall-points-products (catRuleIds 含 "2>8") → 积分商城「周边产品」类目
  99. query-meals (门店菜单) → 找含玩具的套餐(开心乐园餐等)
  100. query-promotions (仅团餐门店) → 门店满减/折扣规则
  101. ```
  102. 输出建议:**玩具/周边 × 获取途径 × 时间窗** 三列表。若接口未返回玩具字段,如实说明「本期接口未返回玩具信息」,不要编造款式名称。
  103. ### 5. 积分抽奖
  104. ```
  105. query-my-account → 积分余额(可选,用于展示)
  106. query-lottery-info → 活动名/状态/单次消耗 drawPoint/剩余次数/奖品列表/drawDecision
  107. ↓ 必须展示 drawDecision.nextConsumption 并获用户明确确认
  108. draw-lottery → 抽奖(服务端原子扣减)
  109. query-my-prizes → 我的奖品(pageNum/pageSize)
  110. ```
  111. > `drawDecision.resourceEligible=false` 时**禁止**调用 `draw-lottery`。返回「操作太频繁」时如实转述,不要重试。
  112. #### 5.1 到期止损:一键用「即将过期积分」抽奖
  113. 触发:「用快过期的积分抽奖」「别让积分白白过期」「把将过期积分花掉」
  114. ```
  115. query-my-account → currentMouthExpirePoint(本月将过期)、availablePoint
  116. query-lottery-info → drawPoint(单次消耗)、drawDecision
  117. 可抽次数 N = floor(currentMouthExpirePoint / drawPoint)
  118. ↓ 展示「抽 N 次、消耗 X 分、剩余 Y 分仍会过期」并获确认
  119. draw-lottery × N → 逐次执行,间隔 ≥1s;遇限流/失败立即停止,不重试
  120. ```
  121. 现成脚本(推荐直接用):
  122. ```bash
  123. python scripts/points_expiry_draw.py # dry-run:摊开「不溢出 / 溢出」两方案
  124. python scripts/points_expiry_draw.py --yes # 执行「不溢出」方案
  125. python scripts/points_expiry_draw.py --yes --times 12 --allow-overflow # 用户同意溢出后才可执行
  126. ```
  127. **是否溢出由用户决定**(见铁律 14):脚本默认只花将过期积分;`--times` 超出可覆盖次数时必须再加 `--allow-overflow`,否则以退出码 2 拒绝;将过期积分不足一次消耗时只提示「可改用其他积分」,不自行执行。
  128. > **扣减顺序(实测)**:**先扣将过期积分,不足部分才从其他积分扣**。
  129. > 例:将过期 17.1 + 抽 1 次(24 分)→ 17.1 来自将过期、6.9 来自其他积分,抽后 `currentMouthExpirePoint` 归 0。
  130. > 故「溢出」= **总消耗 > 将过期积分**(超 1 分也算);拆分按**金额** `min(总消耗, 将过期积分)`,**不是**按次数取整。
  131. > `draw-lottery` 结果在 **`data` 层下**:`data.status.code`(`SUCCESS` 才算成功)、`data.win`、`data.prizes[]`(含 `name`/`validDateInfo`)、`data.consumePoint`。
  132. > ⚠️ **不是顶层 `status`** —— 按顶层读会把「已中奖」误判为失败并中断(实测踩过)。
  133. ### 6. 热量计算
  134. ```
  135. list-nutrition-foods → 全量营养成分(能量/蛋白质/脂肪/碳水/钠/钙)(无入参)
  136. query-meal-detail → 单个餐品详情(含营养)
  137. ```
  138. 按用户目标(减脂/增肌/总热量上限)组合餐品,输出**热量-蛋白质-脂肪-碳水**表格并给出总热量。餐品缺失营养数据时标注「接口未提供」,不要估算填充。
  139. ### 7. 优惠计算器
  140. 目标:算出「用券 vs 不用券」哪个更省。
  141. ```
  142. query-store-coupons (storeCode, orderType, beCode?, reservationDate?) → 该店该场景可用券
  143. ↓ 取候选券的 couponId / couponCode
  144. calculate-price (items=[{productCode, quantity, couponId?, couponCode?}]) → 逐方案算价
  145. ```
  146. 至少输出两组结果(不用券 / 用最优券)对比,标注节省金额。`available-coupons` 用于发现新券,`auto-bind-coupons` 补齐后再比价效果最佳。
  147. ## 扩展能力(MCP 中已有,按需使用)
  148. | 场景 | 工具链 |
  149. |---|---|
  150. | **积分商城兑换** | `mall-points-products` → `mall-product-detail`(选 skuId) → `mall-create-order`(虚拟券/实物,`spuCategory=1/2`)。多商品**必须分别下单并排队** |
  151. | **商城订单** | `mall-order-list` / `mall-order-detail` |
  152. | **订单管理** | `order-list`(历史)/ `query-order`(详情、配送进度)/ `cancel-order`(需 `cancelReasonCode`) |
  153. | **派对 / 活动预约** | `query-party-city` → `query-party-store` → `query-party-store-date` → `query-party-store-session` → `party-order-create`(生日派对、主题派对、麦麦体验营、品鉴会、读书会、积分兑换活动) |
  154. | **企业团餐** | `delivery-query-stores(beType=6)` → `query-meals` → `query-meal-assistance`(取 `gmServiceCode`) → `query-promotions` → `calculate-price` → `create-order` |
  155. | **满意度奖券** | `query-survey-coupon(orderId)` |
  156. | **时间基准** | `now-time-info`(判断活动日期、预约时间前先取服务器时间) |
  157. ## 常见触发 → 工作流对照
  158. | 用户说 | 走 |
  159. |---|---|
  160. | 「帮我领券」「有什么优惠」 | 工作流 1 |
  161. | 「点个麦当劳」「到店取」 | 工作流 2 |
  162. | 「叫个麦乐送」「送到家」 | 工作流 3 |
  163. | 「有没有新玩具」「开心乐园餐送什么」 | 工作流 4 |
  164. | 「积分抽奖」「抽一次」 | 工作流 5 |
  165. | 「这个多少卡」「帮我配个 500 大卡」 | 工作流 6 |
  166. | 「怎么买最划算」「有券便宜多少」 | 工作流 7 |
  167. | 「我的积分」「兑换券」 | 扩展 · 积分商城 |
  168. | 「订单到哪了」「取消订单」 | 扩展 · 订单管理 |
  169. ## 参考资源
  170. - `references/tools.md` —— **35 个工具**完整参数手册(含 enum、必填、原始描述)
  171. - `references/workflows.md` —— 外送/点餐/团餐的字段级示例与 `items` 数组构造
  172. - `scripts/mcd_cli.py` —— 零依赖命令行调用器(`list` / `desc` / `call` / `raw`)
  173. - `scripts/points_expiry_draw.py` —— **积分到期止损**:一键用将过期积分抽奖(dry-run / `--yes` / `--times N` / `--allow-overflow` / `--interval`);**是否溢出由用户决定**
  174. ## 排障
  175. | 现象 | 处理 |
  176. |---|---|
  177. | 工具不在可用列表 | 到「连接器管理」信任 `mcd-mcp`;或用通道 B 脚本 |
  178. | 401 / 无工具返回 | Token 失效,重新到 open.mcd.cn/mcp 激活 |
  179. | 502 / 连接失败 | 多为代理拦截,脚本已默认绕过代理;确认 `MCD_MCP_URL` 未被改写 |
  180. | 「操作太频繁」 | 抽奖频控,如实告知用户稍后再试,不要重试 |
  181. | 菜单查不到某商品 | 促销品用 `query-meals` 全量兜底,`query-meal-detail` 可能取不到 |
README.md · README · 278 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <img src="assets/banner.jpg" alt="McOmni · 麦麦全能助手" width="100%">
  3. # 🍟 麦麦全能助手 · McOmni
  4. **一句话,搞定吃麦全流程**
  5. `领券` → `选店` → `配餐` → `比价` → `下单` → `派对预约` → `积分止损`
  6. [![MCP](https://img.shields.io/badge/MCP-Streamable%20HTTP-blue)](https://open.mcd.cn/mcp)
  7. [![Tools](https://img.shields.io/badge/MCP%20Tools-35%20%2F%2035-success)](#-能力总览)
  8. [![Python](https://img.shields.io/badge/Python-3.8%2B-3776AB)](https://www.python.org/)
  9. [![Dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen)](#-快速开始)
  10. [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
  11. 基于**麦当劳中国官方 MCP Server**(`mcd-mcp` @ `https://mcp.mcd.cn`)构建的全能助手 Skill。
  12. </div>
  13. > **关于徽章**:图片来自 shields.io,个别网络环境下可能加载较慢。README 的全部信息在正文中都有文字说明,徽章缺失不影响阅读。
  14. ---
  15. ## 目录
  16. - [它解决什么问题](#-它解决什么问题)
  17. - [能力总览](#-能力总览)
  18. - [快速开始](#-快速开始)
  19. - [七大核心工作流](#-七大核心工作流)
  20. - [为什么它靠谱](#-为什么它靠谱)
  21. - [项目结构](#-项目结构)
  22. - [排障速查](#-排障速查)
  23. - [安全与边界](#-安全与边界)
  24. ---
  25. ## 🧩 它解决什么问题
  26. 麦当劳把 **35 个能力**开放给了 AI。但在真实账号上跑一遍就会知道:**能调用 ≠ 会用**。
  27. ```mermaid
  28. flowchart TD
  29. U["👤 用户:想点个麦当劳"] --> Q{"🍽️ 怎么取餐?"}
  30. Q -->|"到店自取"| S1["query-nearby-stores<br/>→ storeCode"]
  31. Q -->|"麦乐送"| S2["delivery-query-stores<br/>→ storeCode + beCode"]
  32. Q -->|"得来速"| S3["query-nearby-stores<br/>→ storeCode + beCode"]
  33. S1 --> M["query-meals<br/>→ productCode"]
  34. S2 --> M
  35. S3 --> M
  36. M --> P["calculate-price<br/>→ takeWayCode"]
  37. P --> C["create-order<br/>→ orderId"]
  38. style Q fill:#FAEEDA,stroke:#854F0B,stroke-width:0.5px,color:#633806
  39. style P fill:#E6F1FB,stroke:#185FA5,stroke-width:0.5px,color:#042C53
  40. style C fill:#EAF3DE,stroke:#3B6D11,stroke-width:0.5px,color:#173404
  41. ```
  42. **每一环都必须来自上一环的返回值**;中间任何一环猜错,订单就下不出去。
  43. 同时还要管住三件事:
  44. | # | 要管住的事 | 不遵守的后果 |
  45. |:--:|---|---|
  46. | ① | `beType` / `orderType` 的组合 | 取餐方式错乱 |
  47. | ② | 有副作用的操作(下单 / 领券 / 抽奖)不能误触发 | 真花钱、真扣分 |
  48. | ③ | 花积分类的取舍不能替用户拍板 | 僭越了用户的决定权 |
  49. > McOmni 的价值不在"能调用工具",而在**知道什么时候不该调用**——它把踩过的坑固化成硬约束,让 AI 在你的真实账号上安全地跑完整个流程。
  50. ---
  51. ## 🎯 能力总览
  52. **35 / 35 工具全覆盖**,不只是检索类接口。
  53. | 分组 | 数量 | 代表能力 |
  54. |---|:--:|---|
  55. | 🎫 活动与优惠 | 4 | 当月活动日历、可领券、一键领券、我的券 |
  56. | 🏪 到店点餐 | 7 | 门店查询、菜单、详情、算价、下单、取消、订单详情 |
  57. | 🛵 麦乐送外送 | 3 | 地址管理、可配送门店 |
  58. | 🎁 积分与商城 | 7 | 积分账户、抽奖、奖品、商城兑换、商城订单 |
  59. | 🥗 营养数据 | 2 | 160+ 条餐品营养(能量 / 蛋白 / 脂肪 / 碳水 / 钠 / 钙)|
  60. | 🎉 派对与活动预约 | 5 | 城市 → 门店 → 日期 → 场次 → 下单 |
  61. | 🏢 企业团餐 | 3 | 团餐门店、助餐服务、促销规则 |
  62. | 🧩 其他 | 4 | 服务器时间、历史订单、满意度奖券、门店级用券 |
  63. 三种取餐方式全部支持:**到店自取** / **麦乐送外送** / **得来速车道取餐**。
  64. ---
  65. ## 🚀 快速开始
  66. ### 第 1 步 · 拿 Token
  67. 访问 <https://open.mcd.cn/mcp>,手机号登录 → 控制台 → 激活,一键复制 Token。
  68. ### 第 2 步 · 让助手能用上它
  69. **方式 A:作为 WorkBuddy Skill(推荐)**
  70. ```bash
  71. cp -r . ~/.workbuddy/skills/mcdonalds
  72. ```
  73. 然后在「连接器 → 自定义连接器」中填入配置(参考 `mcp-config.example.json`),把 `${MCD_MCP_TOKEN}` 换成你自己的 Token。
  74. **方式 B:只用命令行通道(不需要任何 AI 客户端)**
  75. ```bash
  76. export MCD_MCP_TOKEN=<你的Token>
  77. python scripts/mcd_cli.py list 优惠
  78. # 找门店(searchType=2 按位置搜,city 与 keyword 必须同时传)
  79. python scripts/mcd_cli.py call query-nearby-stores \
  80. '{"beType":1,"searchType":2,"city":"北京市","keyword":"鼓楼南街"}'
  81. ```
  82. Token 解析顺序(任选其一即可):
  83. | 顺序 | 来源 |
  84. |:--:|---|
  85. | 1 | 环境变量 `MCD_MCP_TOKEN` |
  86. | 2 | 环境变量 `MCD_MCP_CONFIG` 指向的 JSON 文件 |
  87. | 3 | `~/.workbuddy/mcp.json` |
  88. | 4 | 项目根目录 / 当前目录下的 `mcp.json` |
  89. ### 第 3 步 · 用起来
  90. ```bash
  91. # 看有什么券,然后一键领掉
  92. python scripts/mcd_cli.py call available-coupons
  93. python scripts/mcd_cli.py call auto-bind-coupons
  94. # 积分快过期了?先 dry-run 看方案,再决定花不花
  95. python scripts/points_expiry_draw.py
  96. ```
  97. ---
  98. ## 🧭 七大核心工作流
  99. | # | 工作流 | 工具链 |
  100. |:--:|---|---|
  101. | 0 | **入口 · 确认取餐方式** | 先问「到店自取 / 麦乐送 / 得来速」,再决定后续全部参数 |
  102. | 1 | 🎫 **领券** | `available-coupons` → `auto-bind-coupons` → `query-my-coupons` |
  103. | 2 | 🏪 **点餐(到店 / 得来速)** | `query-nearby-stores` → `query-meals` → `query-meal-detail` → `calculate-price` → `create-order` |
  104. | 3 | 🛵 **外送(麦乐送)** | `delivery-query-addresses` → `delivery-query-stores` → `query-meals` → `calculate-price` → `create-order` |
  105. | 4 | 🧸 **周边玩具雷达** | `campaign-calendar` + `mall-points-products(2>8)` + `query-meals` 组合拼出 |
  106. | 5 | 🎰 **积分抽奖 / 到期止损** | `query-my-account` → `query-lottery-info` → `draw-lottery` → `query-my-prizes` |
  107. | 6 | 🥗 **热量计算** | `list-nutrition-foods` / `query-meal-detail` |
  108. | 7 | 💰 **优惠计算器** | `query-store-coupons` → `calculate-price`(用券 / 不用券 两组对比)|
  109. > ⚠️ 工作流 4 需要特别说明:MCP **没有**原生"玩具"接口,这是**组合能力**。若接口未返回玩具字段,助手会如实说明「本期接口未返回玩具信息」,**不会编造款式**。
  110. ---
  111. ## 🛡️ 为什么它靠谱
  112. ### 14 条防错铁律(节选)
  113. | # | 规则 | 不遵守的后果 |
  114. |:--:|---|---|
  115. | 1 | `beType` 决定一切(1 自取 / 2 麦乐送 / 5 得来速 / 6 团餐)| 取餐方式错乱 |
  116. | 2 | `orderType`:到店类 = 1,外送类 = 2 | 下单到错误渠道 |
  117. | 3 | 到店自取**不传** `beCode`;得来速 / 外送**必传** | 直接报错 |
  118. | 4 | 菜单编码取 `data.categories[].meals[].code` | 会误取外层状态码 `200` |
  119. | 5 | 到店下单**必传** `takeWayCode`,只能来自 `calculate-price` | 下单失败 |
  120. | 6 | `searchType=2` 必须 `city` + `keyword` **同时传** | 报 `600058` |
  121. | 7 | **绝不臆造编码**,一切 code 来自上游返回 | 下单到不存在的商品 |
  122. | 8 | 下单前**必须**算价并让用户确认 | 花冤枉钱 |
  123. | 9 | 抽奖**两段式**:先看 `drawDecision` 再执行 | 误消耗积分 |
  124. | 10 | 判定成败看 `success` 字段,而非是否报错 | 把失败当成功 |
  125. 完整 14 条见 [`SKILL.md`](SKILL.md)。
  126. ### 三条设计原则
  127. ```text
  128. ① 绝不臆造编码 一切 code 必须来自上游工具的返回值
  129. ② 副作用必二次确认 下单前必算价;抽奖前必展示消耗明细
  130. ③ 消耗性取舍交用户 不替用户决定花多少积分、要不要溢出
  131. ```
  132. ### 💡 积分到期止损:一个具体例子
  133. 麦当劳积分会过期。实测扣减顺序是 **先扣将过期积分,不足才从其他积分扣**,所以:
  134. ```text
  135. 「是否溢出」 = 总消耗 > 「本月将过期积分」 (超出 1 分也算溢出)
  136. ```
  137. ```bash
  138. python scripts/points_expiry_draw.py # 默认 dry-run,列出两套方案的代价
  139. python scripts/points_expiry_draw.py --yes # 只花将过期积分
  140. python scripts/points_expiry_draw.py --yes --allow-overflow # 用户明确同意后才可溢出
  141. ```
  142. ```mermaid
  143. flowchart LR
  144. A["读取将过期积分"] --> B["算可抽次数 N"]
  145. B --> C{"会溢出吗?"}
  146. C -->|"不会"| D["直接执行"]
  147. C -->|"会"| E["拒绝执行<br/>退出码 2"]
  148. E --> F["需显式加 --allow-overflow"]
  149. style C fill:#FAEEDA,stroke:#854F0B,stroke-width:0.5px,color:#633806
  150. style D fill:#EAF3DE,stroke:#3B6D11,stroke-width:0.5px,color:#173404
  151. style E fill:#FCEBEB,stroke:#A32D2D,stroke-width:0.5px,color:#791F1F
  152. ```
  153. **把决定权留给你**,而不是"帮你想开一点"。
  154. ---
  155. ## 📂 项目结构
  156. ```text
  157. .
  158. ├── SKILL.md # 主文件:14 条铁律 + 7 大工作流 + 触发对照表
  159. ├── README.md
  160. ├── MCP_INTEGRATION.md # 实际使用的 Server / Tool / 调用流程 / 业务价值
  161. ├── CONTEST_DECLARATION.md # 参赛声明(官方原文件,未改动)
  162. ├── mcp-config.example.json # 脱敏配置示例(仅环境变量占位符)
  163. ├── LICENSE
  164. ├── scripts/
  165. │ ├── mcd_cli.py # 零依赖 MCP 命令行通道(list / desc / call / raw)
  166. │ └── points_expiry_draw.py # 积分到期止损(dry-run / --yes / --allow-overflow)
  167. └── references/
  168. ├── tools.md # 35 个工具完整参数手册
  169. └── workflows.md # 字段级示例与 items 数组构造
  170. ```
  171. ---
  172. ## 🔧 排障速查
  173. | 现象 | 原因与处理 |
  174. |---|---|
  175. | 工具不在可用列表里 | MCP 未信任。到「连接器管理」信任 `mcd-mcp`;或改用 `scripts/mcd_cli.py` |
  176. | `401` / 无工具返回 | Token 失效,到 <https://open.mcd.cn/mcp> 重新激活 |
  177. | `502` / 连接失败 | 多为系统代理拦截;`mcd_cli.py` 已默认绕过代理 |
  178. | 报 `600050` | 该 `beType` 无收藏餐厅 → 改用 `searchType=2` + `city` + `keyword` |
  179. | 报 `600058` | `searchType=2` 时 `city` 或 `keyword` 为空 |
  180. | 「操作太频繁」 | 抽奖频控,稍后再试,**不要重试轰炸** |
  181. | 菜单查不到某商品 | 促销品用 `query-meals` 全量兜底,`query-meal-detail` 可能取不到 |
  182. ---
  183. ## 🔐 安全与边界
  184. - **Token 即身份**:本项目**不保存、不打印**你的 Token。仓库中只保留 `mcp-config.example.json` 占位符示例,**不包含任何真实凭证**。
  185. - **有副作用的操作需明确确认**:下单、领券、抽奖、兑换均需用户确认后才执行。
  186. - **本项目非麦当劳官方产品**。餐品信息、价格与供应状态**以麦当劳官方渠道的实时结果为准**;项目输出仅供参考。
  187. ---
  188. ## 🏆 参与的活动
  189. 本项目为「**麦当劳程序员创意开发大赛(M-CODE 1024)**」参赛作品,由参赛者独立开发。
  190. 开发过程使用 **腾讯 WorkBuddy**,完整对话上下文见 [`workbuddy.md`](workbuddy.md)。
  191. ---
  192. <div align="center">
  193. <img src="assets/mascot.jpg" alt="McOmni 吉祥物" width="140">
  194. **如果这个项目对你有帮助,欢迎点一个 Star ⭐**
  195. </div>
  196. ## 📄 License
  197. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.