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
Markdown
[](/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)
- ---
- 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 需在「连接器管理」中点击**信任**后,工具才会出现在可用工具列表里。
- ## 两种调用通道
- | 通道 | 适用 | 说明 |
- |---|---|---|
- | **A. 直接调用 MCP 工具**(首选) | MCP 已被信任 | 直接调用工具名,如 `query-meals`。参数严格按 `references/tools.md` |
- | **B. 命令行脚本**(备选/排障) | MCP 未信任、或需在终端验证 | `python scripts/mcd_cli.py call <工具名> '<json>'`;`list` 列工具、`desc` 查参数 |
- 通道 B 示例:
- ```bash
- 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. 入口:先确认取餐方式(凡涉及门店 / 菜单 / 下单,都必须先走这一步)
- **不要一上来就搜门店或菜单**。先问用户一句:
- > 「你要怎么取餐?① 到店自取 ② 麦乐送外送 ③ 得来速(车道取餐)」
- | 用户选择 | beType | 紧接着**必须先问** | 之后 |
- |---|---|---|---|
- | ① 到店自取 | `1` | **「你在哪儿?」**(城市 + 地标) | `query-nearby-stores(searchType=2, city, keyword)` → 按 `distance` 升序取最近 |
- | ② 麦乐送外送 | `2` | **「用哪个配送地址?」** | `delivery-query-addresses` → 选中或新增地址 → `delivery-query-stores` |
- | ③ 得来速 | `5` | **「你在哪儿?」**(开车去哪个区域) | `query-nearby-stores(searchType=2, city, keyword)`(`beType=5`) |
- - **自取 / 得来速**:位置是必需输入 → 用「低成本问法」:先查 `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;遇限流/失败立即停止,不重试
- ```
- 现成脚本(推荐直接用):
- ```bash
- 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 中已有,按需使用)
- | 场景 | 工具链 |
- |---|---|
- | **积分商城兑换** | `mall-points-products` → `mall-product-detail`(选 skuId) → `mall-create-order`(虚拟券/实物,`spuCategory=1/2`)。多商品**必须分别下单并排队** |
- | **商城订单** | `mall-order-list` / `mall-order-detail` |
- | **订单管理** | `order-list`(历史)/ `query-order`(详情、配送进度)/ `cancel-order`(需 `cancelReasonCode`) |
- | **派对 / 活动预约** | `query-party-city` → `query-party-store` → `query-party-store-date` → `query-party-store-session` → `party-order-create`(生日派对、主题派对、麦麦体验营、品鉴会、读书会、积分兑换活动) |
- | **企业团餐** | `delivery-query-stores(beType=6)` → `query-meals` → `query-meal-assistance`(取 `gmServiceCode`) → `query-promotions` → `calculate-price` → `create-order` |
- | **满意度奖券** | `query-survey-coupon(orderId)` |
- | **时间基准** | `now-time-info`(判断活动日期、预约时间前先取服务器时间) |
- ## 常见触发 → 工作流对照
- | 用户说 | 走 |
- |---|---|
- | 「帮我领券」「有什么优惠」 | 工作流 1 |
- | 「点个麦当劳」「到店取」 | 工作流 2 |
- | 「叫个麦乐送」「送到家」 | 工作流 3 |
- | 「有没有新玩具」「开心乐园餐送什么」 | 工作流 4 |
- | 「积分抽奖」「抽一次」 | 工作流 5 |
- | 「这个多少卡」「帮我配个 500 大卡」 | 工作流 6 |
- | 「怎么买最划算」「有券便宜多少」 | 工作流 7 |
- | 「我的积分」「兑换券」 | 扩展 · 积分商城 |
- | 「订单到哪了」「取消订单」 | 扩展 · 订单管理 |
- ## 参考资源
- - `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`);**是否溢出由用户决定**
- ## 排障
- | 现象 | 处理 |
- |---|---|
- | 工具不在可用列表 | 到「连接器管理」信任 `mcd-mcp`;或用通道 B 脚本 |
- | 401 / 无工具返回 | Token 失效,重新到 open.mcd.cn/mcp 激活 |
- | 502 / 连接失败 | 多为代理拦截,脚本已默认绕过代理;确认 `MCD_MCP_URL` 未被改写 |
- | 「操作太频繁」 | 抽奖频控,如实告知用户稍后再试,不要重试 |
- | 菜单查不到某商品 | 促销品用 `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)
- <div align="center">
- <img src="assets/banner.jpg" alt="McOmni · 麦麦全能助手" width="100%">
- # 🍟 麦麦全能助手 · McOmni
- **一句话,搞定吃麦全流程**
- `领券` → `选店` → `配餐` → `比价` → `下单` → `派对预约` → `积分止损`
- [](https://open.mcd.cn/mcp)
- [](#-能力总览)
- [](https://www.python.org/)
- [](#-快速开始)
- [](LICENSE)
- 基于**麦当劳中国官方 MCP Server**(`mcd-mcp` @ `https://mcp.mcd.cn`)构建的全能助手 Skill。
- </div>
- > **关于徽章**:图片来自 shields.io,个别网络环境下可能加载较慢。README 的全部信息在正文中都有文字说明,徽章缺失不影响阅读。
- ---
- ## 目录
- - [它解决什么问题](#-它解决什么问题)
- - [能力总览](#-能力总览)
- - [快速开始](#-快速开始)
- - [七大核心工作流](#-七大核心工作流)
- - [为什么它靠谱](#-为什么它靠谱)
- - [项目结构](#-项目结构)
- - [排障速查](#-排障速查)
- - [安全与边界](#-安全与边界)
- ---
- ## 🧩 它解决什么问题
- 麦当劳把 **35 个能力**开放给了 AI。但在真实账号上跑一遍就会知道:**能调用 ≠ 会用**。
- ```mermaid
- 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
- ```
- **每一环都必须来自上一环的返回值**;中间任何一环猜错,订单就下不出去。
- 同时还要管住三件事:
- | # | 要管住的事 | 不遵守的后果 |
- |:--:|---|---|
- | ① | `beType` / `orderType` 的组合 | 取餐方式错乱 |
- | ② | 有副作用的操作(下单 / 领券 / 抽奖)不能误触发 | 真花钱、真扣分 |
- | ③ | 花积分类的取舍不能替用户拍板 | 僭越了用户的决定权 |
- > McOmni 的价值不在"能调用工具",而在**知道什么时候不该调用**——它把踩过的坑固化成硬约束,让 AI 在你的真实账号上安全地跑完整个流程。
- ---
- ## 🎯 能力总览
- **35 / 35 工具全覆盖**,不只是检索类接口。
- | 分组 | 数量 | 代表能力 |
- |---|:--:|---|
- | 🎫 活动与优惠 | 4 | 当月活动日历、可领券、一键领券、我的券 |
- | 🏪 到店点餐 | 7 | 门店查询、菜单、详情、算价、下单、取消、订单详情 |
- | 🛵 麦乐送外送 | 3 | 地址管理、可配送门店 |
- | 🎁 积分与商城 | 7 | 积分账户、抽奖、奖品、商城兑换、商城订单 |
- | 🥗 营养数据 | 2 | 160+ 条餐品营养(能量 / 蛋白 / 脂肪 / 碳水 / 钠 / 钙)|
- | 🎉 派对与活动预约 | 5 | 城市 → 门店 → 日期 → 场次 → 下单 |
- | 🏢 企业团餐 | 3 | 团餐门店、助餐服务、促销规则 |
- | 🧩 其他 | 4 | 服务器时间、历史订单、满意度奖券、门店级用券 |
- 三种取餐方式全部支持:**到店自取** / **麦乐送外送** / **得来速车道取餐**。
- ---
- ## 🚀 快速开始
- ### 第 1 步 · 拿 Token
- 访问 <https://open.mcd.cn/mcp>,手机号登录 → 控制台 → 激活,一键复制 Token。
- ### 第 2 步 · 让助手能用上它
- **方式 A:作为 WorkBuddy Skill(推荐)**
- ```bash
- cp -r . ~/.workbuddy/skills/mcdonalds
- ```
- 然后在「连接器 → 自定义连接器」中填入配置(参考 `mcp-config.example.json`),把 `${MCD_MCP_TOKEN}` 换成你自己的 Token。
- **方式 B:只用命令行通道(不需要任何 AI 客户端)**
- ```bash
- 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 解析顺序(任选其一即可):
- | 顺序 | 来源 |
- |:--:|---|
- | 1 | 环境变量 `MCD_MCP_TOKEN` |
- | 2 | 环境变量 `MCD_MCP_CONFIG` 指向的 JSON 文件 |
- | 3 | `~/.workbuddy/mcp.json` |
- | 4 | 项目根目录 / 当前目录下的 `mcp.json` |
- ### 第 3 步 · 用起来
- ```bash
- # 看有什么券,然后一键领掉
- 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
- ```
- ---
- ## 🧭 七大核心工作流
- | # | 工作流 | 工具链 |
- |:--:|---|---|
- | 0 | **入口 · 确认取餐方式** | 先问「到店自取 / 麦乐送 / 得来速」,再决定后续全部参数 |
- | 1 | 🎫 **领券** | `available-coupons` → `auto-bind-coupons` → `query-my-coupons` |
- | 2 | 🏪 **点餐(到店 / 得来速)** | `query-nearby-stores` → `query-meals` → `query-meal-detail` → `calculate-price` → `create-order` |
- | 3 | 🛵 **外送(麦乐送)** | `delivery-query-addresses` → `delivery-query-stores` → `query-meals` → `calculate-price` → `create-order` |
- | 4 | 🧸 **周边玩具雷达** | `campaign-calendar` + `mall-points-products(2>8)` + `query-meals` 组合拼出 |
- | 5 | 🎰 **积分抽奖 / 到期止损** | `query-my-account` → `query-lottery-info` → `draw-lottery` → `query-my-prizes` |
- | 6 | 🥗 **热量计算** | `list-nutrition-foods` / `query-meal-detail` |
- | 7 | 💰 **优惠计算器** | `query-store-coupons` → `calculate-price`(用券 / 不用券 两组对比)|
- > ⚠️ 工作流 4 需要特别说明:MCP **没有**原生"玩具"接口,这是**组合能力**。若接口未返回玩具字段,助手会如实说明「本期接口未返回玩具信息」,**不会编造款式**。
- ---
- ## 🛡️ 为什么它靠谱
- ### 14 条防错铁律(节选)
- | # | 规则 | 不遵守的后果 |
- |:--:|---|---|
- | 1 | `beType` 决定一切(1 自取 / 2 麦乐送 / 5 得来速 / 6 团餐)| 取餐方式错乱 |
- | 2 | `orderType`:到店类 = 1,外送类 = 2 | 下单到错误渠道 |
- | 3 | 到店自取**不传** `beCode`;得来速 / 外送**必传** | 直接报错 |
- | 4 | 菜单编码取 `data.categories[].meals[].code` | 会误取外层状态码 `200` |
- | 5 | 到店下单**必传** `takeWayCode`,只能来自 `calculate-price` | 下单失败 |
- | 6 | `searchType=2` 必须 `city` + `keyword` **同时传** | 报 `600058` |
- | 7 | **绝不臆造编码**,一切 code 来自上游返回 | 下单到不存在的商品 |
- | 8 | 下单前**必须**算价并让用户确认 | 花冤枉钱 |
- | 9 | 抽奖**两段式**:先看 `drawDecision` 再执行 | 误消耗积分 |
- | 10 | 判定成败看 `success` 字段,而非是否报错 | 把失败当成功 |
- 完整 14 条见 [`SKILL.md`](SKILL.md)。
- ### 三条设计原则
- ```text
- ① 绝不臆造编码 一切 code 必须来自上游工具的返回值
- ② 副作用必二次确认 下单前必算价;抽奖前必展示消耗明细
- ③ 消耗性取舍交用户 不替用户决定花多少积分、要不要溢出
- ```
- ### 💡 积分到期止损:一个具体例子
- 麦当劳积分会过期。实测扣减顺序是 **先扣将过期积分,不足才从其他积分扣**,所以:
- ```text
- 「是否溢出」 = 总消耗 > 「本月将过期积分」 (超出 1 分也算溢出)
- ```
- ```bash
- python scripts/points_expiry_draw.py # 默认 dry-run,列出两套方案的代价
- python scripts/points_expiry_draw.py --yes # 只花将过期积分
- python scripts/points_expiry_draw.py --yes --allow-overflow # 用户明确同意后才可溢出
- ```
- ```mermaid
- 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
- ```
- **把决定权留给你**,而不是"帮你想开一点"。
- ---
- ## 📂 项目结构
- ```text
- .
- ├── 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 数组构造
- ```
- ---
- ## 🔧 排障速查
- | 现象 | 原因与处理 |
- |---|---|
- | 工具不在可用列表里 | MCP 未信任。到「连接器管理」信任 `mcd-mcp`;或改用 `scripts/mcd_cli.py` |
- | `401` / 无工具返回 | Token 失效,到 <https://open.mcd.cn/mcp> 重新激活 |
- | `502` / 连接失败 | 多为系统代理拦截;`mcd_cli.py` 已默认绕过代理 |
- | 报 `600050` | 该 `beType` 无收藏餐厅 → 改用 `searchType=2` + `city` + `keyword` |
- | 报 `600058` | `searchType=2` 时 `city` 或 `keyword` 为空 |
- | 「操作太频繁」 | 抽奖频控,稍后再试,**不要重试轰炸** |
- | 菜单查不到某商品 | 促销品用 `query-meals` 全量兜底,`query-meal-detail` 可能取不到 |
- ---
- ## 🔐 安全与边界
- - **Token 即身份**:本项目**不保存、不打印**你的 Token。仓库中只保留 `mcp-config.example.json` 占位符示例,**不包含任何真实凭证**。
- - **有副作用的操作需明确确认**:下单、领券、抽奖、兑换均需用户确认后才执行。
- - **本项目非麦当劳官方产品**。餐品信息、价格与供应状态**以麦当劳官方渠道的实时结果为准**;项目输出仅供参考。
- ---
- ## 🏆 参与的活动
- 本项目为「**麦当劳程序员创意开发大赛(M-CODE 1024)**」参赛作品,由参赛者独立开发。
- 开发过程使用 **腾讯 WorkBuddy**,完整对话上下文见 [`workbuddy.md`](workbuddy.md)。
- ---
- <div align="center">
- <img src="assets/mascot.jpg" alt="McOmni 吉祥物" width="140">
- **如果这个项目对你有帮助,欢迎点一个 Star ⭐**
- </div>
- ## 📄 License
- [MIT](LICENSE)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.