Skip to content
Back to search

mcd-coupon-xray

SkillWorks with Claude CodeGitHub

麦门券力透视 —— 校验麦当劳优惠券在「具体门店 + 具体渠道」下到底能不能用,并算出券后实付。当用户问「我的券能用吗」「哪家店能用这张券」「附近哪家店用券最划算」「这个券值不值」时使用。核心是区分「已持有」与「可核销」两种状态。

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/wahaha-potato--mcd-coupon-xray/badge.svg)](/listings/wahaha-potato--mcd-coupon-xray)

HTML

<a href="/listings/wahaha-potato--mcd-coupon-xray"><img src="/api/listings/wahaha-potato--mcd-coupon-xray/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**1. 申请 MCP Token**

打开 [open.mcd.cn/mcp](https://open.mcd.cn/mcp),手机号登录 → 右上「控制台」→「激活」→ 同意协议 → 复制 Token。

**2. 配置 MCP 连接**

本仓库的 `mcp-config.example.json` 是脱敏模板,把 `YOUR_MCP_TOKEN` 换成你的真实 Token:

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

WorkBuddy 用户:左侧「专家·技能·连接器」→「连接器」→ 右上「自定义连接器」→「配置 MCP」→ 粘贴上面的 JSON → 保存 → 启用。

**3. 放入 Skill 目录**

把 `SKILL.md` 放到 `~/.workbuddy/skills/mcd-coupon-xray/` 下,重启会话即可。

**4. 自检脚本**

python scripts/xray.py --selftest
python -m pytest tests/ -v      # 或 python tests/test_xray.py

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 · 99 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: mcd-coupon-xray
  3. description: 麦门券力透视 —— 校验麦当劳优惠券在「具体门店 + 具体渠道」下到底能不能用,并算出券后实付。当用户问「我的券能用吗」「哪家店能用这张券」「附近哪家店用券最划算」「这个券值不值」时使用。核心是区分「已持有」与「可核销」两种状态。
  4. ---
  5. # 麦门券力透视
  6. ## 这个 Skill 解决的认知断层
  7. 麦当劳 MCP 里有两个都叫「我的券」的接口,但语义完全不同:
  8. | 工具 | 语义 | 是否校验门店 |
  9. |---|---|---|
  10. | `query-my-coupons` | 用户卡包里**拥有**的券 | 否。官方文档明示「不进行门店、渠道、配送方式等下单规则校验,因此不承诺可用于当前订单」 |
  11. | `query-store-coupons` | 指定门店 + 指定订单类型下**可核销**的券 | 是 |
  12. 用户看到「我有 5 张券」,和「我能用掉其中几张」是两个数字。本 Skill 的工作就是把这两个数字之间的差额查清楚。
  13. ## 五条必须守住的事实(实测得出,不要重新假设)
  14. 1. **一张券要过三道门:领了 → 进包 → 今天能用。** 实测漏斗:领取 5 张全部成功 → 卡包只有 4 张(免费脆薯饼领取成功却没进包)→ 其中 2 张有效期 10-26 才开始,当天真正能核销的只有 2 张。向用户报「有几张券」时必须报 `query-store-coupons` 的数,不能报领取数。
  15. 2. **「一张券」的唯一标识是 couponId,不是券名。** 实测领取 5 条记录 = 5 张券(5 个不同 couponId),同名券是两个不同活动(一批 10-23 截止、一批 10-26 开始),各有真实券码。按券名去重会漏券。
  16. 3. **菜单编码 ≠ 计价编码。** 券的适用商品 `9900016534` 不在 `query-meals` 返回中,但 `calculate-price` 照常算出 23.8 → 19.9 元。不能用菜单存在性判断券可用性。
  17. 4. **卡包为空时,`query-store-coupons` 一定返回空数组 `[]`。** 它是在「已持有」的基础上叠门店过滤,不是返回该店全部可用券。必须**先领券再看门店**,顺序颠倒会得到全空的假结论。
  18. 5. **门店的 `longitude` / `latitude` 实测恒为 `0.0`,只有 `distance` 有值。** 不要尝试用坐标做距离计算或地图渲染,直接用 `distance`(单位:米)。
  19. ## 执行流程
  20. ### S1 · 领券入库
  21. 1. `available-coupons` 取麦麦省可领券。
  22. 2. 调用 `auto-bind-coupons` 一键领取。
  23. - **这是写操作**(写入用户卡包)。执行前用一句话告知用户即将领取哪些券。
  24. - 领取是纯新增,不消耗积分、不影响已有券。
  25. - **真实张数以本步返回的 `couponId` 数量为准**,不以 `available-coupons` 的条目数为准。实测 5 条记录 = 5 张券(5 个不同 couponId),同名券是两个不同活动。
  26. 3. `query-my-coupons` 复核卡包,`pageSize` 传 `"200"`,`page` 从 `"1"` 起。
  27. - **领取成功 ≠ 进入卡包。** 实测领 5 张,卡包只见 4 张。复核数与领取数不一致时如实告知差额,不要圆场。
  28. - 若复核后为空,说明用户未登录麦当劳账号或未开通麦享会,直接如实说明,不要继续往下编造数据。
  29. ### S2 · 定位门店(必须拿到 `storeCode`)
  30. 1. 先试收藏:`query-nearby-stores`,`searchType=1`、`beType=1`。
  31. 2. 若返回 `code=600050`(收藏餐厅列表为空),降级为位置搜索:`searchType=2`,必须同时给 `city` 和 `keyword`,`beType` 仍为 `1`。
  32. 3. 若用户没提供城市,向用户确认城市 + 地标。这是全流程中**唯一**需要反问用户的信息,因为位置不在任何接口的返回里。
  33. 4. 取前 5 家门店,逐个记录 `storeCode`(纯数字字符串,如 `1951066`)和 `distance`。
  34. 渠道参数对照(传错会导致查不到券,不是查不到就是返回空):
  35. | 用户场景 | `beType` | `orderType` | `beCode` |
  36. |---|---|---|---|
  37. | 到店自取 | `1` | `1` | 不传 |
  38. | 得来速 | `5` | `1` | 必传(来自 `query-nearby-stores`) |
  39. | 麦乐送 | `2` | `2` | 必传(来自 `delivery-query-stores`) |
  40. | 企业团餐 | `6` | `2` | 必传(来自 `delivery-query-stores`) |
  41. ### S3 · 逐店校验
  42. 对 S2 得到的每一家门店调用 `query-store-coupons`,参数 `storeCode` + `orderType=1` + `beType=1`。
  43. - 返回 `[]` → 该店在該渠道下无任何可核销券,标记为「不可用」,不要跳过(不可用本身是结论)。
  44. - 返回非空 → 按 `couponId` 分组。同一 `couponId` 下的多个 `couponCode` 表示多张同款券,展示时写「首个券码(共 N 张)」。
  45. ### S4 · 券后实付
  46. 只对 S3 中「有可用券」的门店继续,避免无意义的全量计算:
  47. 1. `query-meals`(`storeCode` + `orderType=1` + `beType=1`)取该店菜单。
  48. 2. 从 `query-store-coupons` 的 `products[].productCode` 中取出券的适用商品,与菜单的 `productCode` 对齐。
  49. 3. `calculate-price` 计算券前 / 券后金额与优惠额。
  50. 4. **菜单编码 ≠ 计价编码。** 券的适用商品可能不在 `query-meals` 返回里(实测 `9900016534` 不在菜单,但 `calculate-price` 照常算出 23.8 → 19.9 元)。所以不要用「菜单里没有」下「无货」的结论——直接调 `calculate-price`,它返回成功就以它为准。只有 `calculate-price` 本身报错时,才如实标注「该商品当前无法计价」,不要用其他商品代替。
  51. ### S5 · 输出
  52. 主表按「券后实付」升序:
  53. | 门店 | 距离 | 可用券 | 最优券 | 券前 | 券后 | 省 |
  54. |---|---:|---:|---|---:|---:|---:|
  55. 副表给出跨店可用性矩阵(行=券名,列=门店,格=`可用` / `—`),直接回答「同一张券哪家店认」。
  56. 最后一行给出可执行结论:**「去 X 店用 Y 券,实付 Z 元,省 W 元」**。
  57. ## 输出纪律
  58. - 券名、券 ID、券码、有效期、适用商品、商品编码一律完整展示,不省略、不改写。
  59. - 不承诺未验证的结果。任何一个环节接口返回空或报错,如实说明卡在哪一步,不要用推测填补。
  60. - `available-coupons` 的重复条目问题要在输出里点明一次,这是本 Skill 相对其他券类项目的核心差异点。
  61. ## 附带脚本
  62. `scripts/xray.py` 提供五个纯函数(无网络、无副作用),用于把工具返回的原始 JSON 转成上表:
  63. - `dedupe_coupons(raw)` —— 按券名去重,返回 `(去重后列表, 原始条目数, 重复条目数)`
  64. - `group_by_coupon_id(rows)` —— 同 `couponId` 多 `couponCode` 归并
  65. - `build_matrix(stores, store_coupons_map)` —— 生成跨店可用性矩阵
  66. - `rank_stores(stores, pricing)` —— 按券后实付升序,同价按省钱额降序,`after` 缺失排最后
  67. - `sort_stores_by_distance(stores)` —— 按 `distance`(米)升序,缺失距离的门店排最后
  68. 用法:`python scripts/xray.py --selftest` 跑内置用例。
README.md · README · 176 lines

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

  1. # 麦门券力透视 · mcd-coupon-xray
  2. > 麦麦省的券谁都能领,但**领了不等于你楼下那家店认**。
  3. >
  4. > 这个 Skill 一键领全,然后逐家门店校验:哪家店真的能核销、券后实付多少、同一张券在哪家店才用得掉。
  5. ## 它解决的问题
  6. 麦当劳 MCP 里有两个都叫「我的券」的接口,语义完全不同:
  7. | 接口 | 你看到的 | 它校验了什么 |
  8. |---|---|---|
  9. | `query-my-coupons` | 你**拥有**的券 | **什么都没校验** |
  10. | `query-store-coupons` | 某家店 + 某渠道下**能核销**的券 | 门店、渠道、下单规则 |
  11. 官方文档自己写得很清楚:
  12. > 该接口返回的是用户拥有的券,**不进行门店、渠道、配送方式等下单规则校验,因此不承诺可用于当前订单**。若业务目标是"当前门店/当前订单可用的券",请调用 `query-store-coupons`。
  13. 于是产生了一个几乎所有人都撞过的体验:卡包里躺着七八张券,兴冲冲走到楼下门店,点开一单,发现一张都用不上。
  14. **「能领」和「能用」之间的差额,就是这个 Skill 要查的东西。**
  15. ## 实测到的五个反直觉事实
  16. 这五个都是用真实 Token、自己的账号把整条链跑完后得出的(2026-10-23,北京三里屯 5 家门店):
  17. **1. 一张券要过三道门:领了 → 进包 → 今天能用**
  18. 实测漏斗:`auto-bind-coupons` 领取 **5 张全部成功** → `query-my-coupons` 卡包里只有 **4 张**(免费脆薯饼领取成功却没进包)→ 卡包 4 张里又有 2 张有效期从 10-26 才开始,`query-store-coupons` 返回的当天真正能核销的只有 **2 张**。
  19. 所以「我的券」这个数字,和「今天在楼下这家店能用掉几张」之间隔了两层,每一层都会安静地吃掉一部分。
  20. **2. 「一张券」的唯一标识是 couponId,不是券名**
  21. 领取返回的 5 条记录,去重后是 **5 张券、5 个不同 couponId**——「11.9 元麦辣鸡腿堡」出现两次,是两个不同活动:一批有效期到 10-23、一批从 10-26 开始,各有真实券码。
  22. 按券名去重会把两张真券合并成一张。这不是展示优化,是把钱算丢。(本项目早期版本犯过这个错,已修正。)
  23. **3. 菜单编码 ≠ 计价编码**
  24. 券的适用商品 `9900016534`(王牌炸鸡任选 2)**不在** `query-meals` 返回的菜单里,但 `calculate-price` 照样算出 23.8 → 19.9 元。
  25. 不能用「菜单里有没有这个商品」来判断券可不可用,应直接调 `calculate-price`。
  26. **4. 卡包是空的,按门店查也一定是空的**
  27. `query-store-coupons` 不是「返回该店全部可用券」,而是「在**你已持有**的券里筛出该店能用的」。实测:空卡包 + 有效门店 `1951066` → 返回 `[]`。
  28. 所以顺序必须是**先领券,再查门店**。反过来做,任何门店都是空的,会得出「这家店一张券都不支持」的错误结论。
  29. **5. 门店经纬度是废的**
  30. `query-nearby-stores` 每家店都返回 `longitude: 0.0`、`latitude: 0.0`,唯一有效的是 `distance`(米)。任何想拿坐标画地图或自己算距离的写法都会失败。
  31. ## 怎么用
  32. 在 WorkBuddy(或任何支持 MCP 的客户端)里配好麦当劳 MCP,然后直接说:
  33. ```
  34. 帮我看看我的券哪家店能用
  35. ```
  36. ```
  37. 我想在国贸附近吃,用券之后哪家最便宜
  38. ```
  39. Skill 会走完整条链:
  40. ```
  41. available-coupons 麦麦省可领券(按券名去重,报出真实张数)
  42. ↓
  43. auto-bind-coupons 一键领取(写入卡包,纯新增)
  44. ↓
  45. query-my-coupons 复核卡包,确认券真的进来了
  46. ↓
  47. query-nearby-stores 拿到 storeCode(收藏为空自动降级为城市+地标搜索)
  48. ↓
  49. query-store-coupons 逐店校验:这张券这家店认不认
  50. ↓
  51. query-meals 有可用券的店,取菜单
  52. ↓
  53. calculate-price 券前 / 券后 / 省多少
  54. ```
  55. 输出两张表。以下为 2026-10-23 在北京三里屯 5 家门店的**真实运行结果**:
  56. | 门店 | 距离 | 可用券 | 最优券 | 券前 | 券后 | 省 |
  57. |---|---:|---:|---|---:|---:|---:|
  58. | 麦当劳北京长虹桥餐厅 | 628m | 2 | 11.9 元麦辣鸡腿堡 | 22.5 | 11.9 | **10.6** |
  59. | 麦当劳北京团结湖餐厅 | 933m | 2 | 11.9 元麦辣鸡腿堡 | 22.5 | 11.9 | **10.6** |
  60. | …(本批 5 家店结果一致,券为通用券) | | | | | | |
  61. 外加一张跨店可用性矩阵,直接回答「同一张券哪家店认」。本批样本里 5 家店可用性完全一致——矩阵的价值在有门店限制的券上才会显现,但逻辑必须先在。
  62. 最后给一句能直接执行的话:**去长虹桥店用 11.9 元麦辣鸡腿堡券,券后 11.9 元,省 10.6 元。**
  63. ## 目标用户
  64. - 卡包里攒了一堆券、但从没搞清楚过能不能用的人
  65. - 在几个门店之间犹豫、想选最省钱那家的人
  66. - 公司楼下 / 家楼下有多家麦当劳、想知道哪家券覆盖更好的通勤族
  67. - 用企业团餐 / 得来速、渠道规则更绕的场景
  68. ## 安装
  69. **1. 申请 MCP Token**
  70. 打开 [open.mcd.cn/mcp](https://open.mcd.cn/mcp),手机号登录 → 右上「控制台」→「激活」→ 同意协议 → 复制 Token。
  71. **2. 配置 MCP 连接**
  72. 本仓库的 `mcp-config.example.json` 是脱敏模板,把 `YOUR_MCP_TOKEN` 换成你的真实 Token:
  73. ```json
  74. {
  75. "mcpServers": {
  76. "mcd-mcp": {
  77. "type": "streamablehttp",
  78. "url": "https://mcp.mcd.cn",
  79. "headers": {
  80. "Authorization": "Bearer YOUR_MCP_TOKEN"
  81. }
  82. }
  83. }
  84. }
  85. ```
  86. WorkBuddy 用户:左侧「专家·技能·连接器」→「连接器」→ 右上「自定义连接器」→「配置 MCP」→ 粘贴上面的 JSON → 保存 → 启用。
  87. **3. 放入 Skill 目录**
  88. 把 `SKILL.md` 放到 `~/.workbuddy/skills/mcd-coupon-xray/` 下,重启会话即可。
  89. **4. 自检脚本**
  90. ```bash
  91. python scripts/xray.py --selftest
  92. python -m pytest tests/ -v # 或 python tests/test_xray.py
  93. ```
  94. ## 在线演示
  95. 👉 **https://wahaha-potato.github.io/mcd-coupon-xray/**
  96. 页面里所有数字来自 2026-10-23 用真实账号跑完的整条链路,无一处虚构。
  97. ## 仓库结构
  98. ```
  99. mcd-coupon-xray/
  100. ├── SKILL.md Skill 主体:流程、渠道参数矩阵、输出纪律
  101. ├── README.md 本文件
  102. ├── CONTEST_DECLARATION.md 参赛声明(官方原文,未改动)
  103. ├── MCP_INTEGRATION.md 逐工具的调用链、参数、实测返回与业务价值
  104. ├── mcp-config.example.json 脱敏配置模板(仅环境变量占位符)
  105. ├── workbuddy.md WorkBuddy 开发过程对话上下文
  106. ├── docs/
  107. │ └── index.html 在线演示页(GitHub Pages,真实数据)
  108. ├── LICENSE MIT
  109. ├── .gitignore 挡住本地配置与凭据
  110. ├── scripts/
  111. │ └── xray.py 去重 / 归并 / 矩阵 / 排序(纯函数,无网络)
  112. └── tests/
  113. └── test_xray.py 18 个单元测试,覆盖上述五个纯函数
  114. ```
  115. ## 边界
  116. - 本项目的结论只对**调用当时**的券状态、门店库存、活动规则有效。券会过期、门店会调整。
  117. - 不构成任何价格承诺。最终价格以麦当劳官方点餐页为准。
  118. - 本项目为非官方作品,由参赛者独立开发,与麦当劳中国无隶属关系。
  119. ## 许可
  120. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

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