mcd-coupon-xray
麦门券力透视 —— 校验麦当劳优惠券在「具体门店 + 具体渠道」下到底能不能用,并算出券后实付。当用户问「我的券能用吗」「哪家店能用这张券」「附近哪家店用券最划算」「这个券值不值」时使用。核心是区分「已持有」与「可核销」两种状态。
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/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
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)
- ---
- name: mcd-coupon-xray
- description: 麦门券力透视 —— 校验麦当劳优惠券在「具体门店 + 具体渠道」下到底能不能用,并算出券后实付。当用户问「我的券能用吗」「哪家店能用这张券」「附近哪家店用券最划算」「这个券值不值」时使用。核心是区分「已持有」与「可核销」两种状态。
- ---
- # 麦门券力透视
- ## 这个 Skill 解决的认知断层
- 麦当劳 MCP 里有两个都叫「我的券」的接口,但语义完全不同:
- | 工具 | 语义 | 是否校验门店 |
- |---|---|---|
- | `query-my-coupons` | 用户卡包里**拥有**的券 | 否。官方文档明示「不进行门店、渠道、配送方式等下单规则校验,因此不承诺可用于当前订单」 |
- | `query-store-coupons` | 指定门店 + 指定订单类型下**可核销**的券 | 是 |
- 用户看到「我有 5 张券」,和「我能用掉其中几张」是两个数字。本 Skill 的工作就是把这两个数字之间的差额查清楚。
- ## 五条必须守住的事实(实测得出,不要重新假设)
- 1. **一张券要过三道门:领了 → 进包 → 今天能用。** 实测漏斗:领取 5 张全部成功 → 卡包只有 4 张(免费脆薯饼领取成功却没进包)→ 其中 2 张有效期 10-26 才开始,当天真正能核销的只有 2 张。向用户报「有几张券」时必须报 `query-store-coupons` 的数,不能报领取数。
- 2. **「一张券」的唯一标识是 couponId,不是券名。** 实测领取 5 条记录 = 5 张券(5 个不同 couponId),同名券是两个不同活动(一批 10-23 截止、一批 10-26 开始),各有真实券码。按券名去重会漏券。
- 3. **菜单编码 ≠ 计价编码。** 券的适用商品 `9900016534` 不在 `query-meals` 返回中,但 `calculate-price` 照常算出 23.8 → 19.9 元。不能用菜单存在性判断券可用性。
- 4. **卡包为空时,`query-store-coupons` 一定返回空数组 `[]`。** 它是在「已持有」的基础上叠门店过滤,不是返回该店全部可用券。必须**先领券再看门店**,顺序颠倒会得到全空的假结论。
- 5. **门店的 `longitude` / `latitude` 实测恒为 `0.0`,只有 `distance` 有值。** 不要尝试用坐标做距离计算或地图渲染,直接用 `distance`(单位:米)。
- ## 执行流程
- ### S1 · 领券入库
- 1. `available-coupons` 取麦麦省可领券。
- 2. 调用 `auto-bind-coupons` 一键领取。
- - **这是写操作**(写入用户卡包)。执行前用一句话告知用户即将领取哪些券。
- - 领取是纯新增,不消耗积分、不影响已有券。
- - **真实张数以本步返回的 `couponId` 数量为准**,不以 `available-coupons` 的条目数为准。实测 5 条记录 = 5 张券(5 个不同 couponId),同名券是两个不同活动。
- 3. `query-my-coupons` 复核卡包,`pageSize` 传 `"200"`,`page` 从 `"1"` 起。
- - **领取成功 ≠ 进入卡包。** 实测领 5 张,卡包只见 4 张。复核数与领取数不一致时如实告知差额,不要圆场。
- - 若复核后为空,说明用户未登录麦当劳账号或未开通麦享会,直接如实说明,不要继续往下编造数据。
- ### S2 · 定位门店(必须拿到 `storeCode`)
- 1. 先试收藏:`query-nearby-stores`,`searchType=1`、`beType=1`。
- 2. 若返回 `code=600050`(收藏餐厅列表为空),降级为位置搜索:`searchType=2`,必须同时给 `city` 和 `keyword`,`beType` 仍为 `1`。
- 3. 若用户没提供城市,向用户确认城市 + 地标。这是全流程中**唯一**需要反问用户的信息,因为位置不在任何接口的返回里。
- 4. 取前 5 家门店,逐个记录 `storeCode`(纯数字字符串,如 `1951066`)和 `distance`。
- 渠道参数对照(传错会导致查不到券,不是查不到就是返回空):
- | 用户场景 | `beType` | `orderType` | `beCode` |
- |---|---|---|---|
- | 到店自取 | `1` | `1` | 不传 |
- | 得来速 | `5` | `1` | 必传(来自 `query-nearby-stores`) |
- | 麦乐送 | `2` | `2` | 必传(来自 `delivery-query-stores`) |
- | 企业团餐 | `6` | `2` | 必传(来自 `delivery-query-stores`) |
- ### S3 · 逐店校验
- 对 S2 得到的每一家门店调用 `query-store-coupons`,参数 `storeCode` + `orderType=1` + `beType=1`。
- - 返回 `[]` → 该店在該渠道下无任何可核销券,标记为「不可用」,不要跳过(不可用本身是结论)。
- - 返回非空 → 按 `couponId` 分组。同一 `couponId` 下的多个 `couponCode` 表示多张同款券,展示时写「首个券码(共 N 张)」。
- ### S4 · 券后实付
- 只对 S3 中「有可用券」的门店继续,避免无意义的全量计算:
- 1. `query-meals`(`storeCode` + `orderType=1` + `beType=1`)取该店菜单。
- 2. 从 `query-store-coupons` 的 `products[].productCode` 中取出券的适用商品,与菜单的 `productCode` 对齐。
- 3. `calculate-price` 计算券前 / 券后金额与优惠额。
- 4. **菜单编码 ≠ 计价编码。** 券的适用商品可能不在 `query-meals` 返回里(实测 `9900016534` 不在菜单,但 `calculate-price` 照常算出 23.8 → 19.9 元)。所以不要用「菜单里没有」下「无货」的结论——直接调 `calculate-price`,它返回成功就以它为准。只有 `calculate-price` 本身报错时,才如实标注「该商品当前无法计价」,不要用其他商品代替。
- ### S5 · 输出
- 主表按「券后实付」升序:
- | 门店 | 距离 | 可用券 | 最优券 | 券前 | 券后 | 省 |
- |---|---:|---:|---|---:|---:|---:|
- 副表给出跨店可用性矩阵(行=券名,列=门店,格=`可用` / `—`),直接回答「同一张券哪家店认」。
- 最后一行给出可执行结论:**「去 X 店用 Y 券,实付 Z 元,省 W 元」**。
- ## 输出纪律
- - 券名、券 ID、券码、有效期、适用商品、商品编码一律完整展示,不省略、不改写。
- - 不承诺未验证的结果。任何一个环节接口返回空或报错,如实说明卡在哪一步,不要用推测填补。
- - `available-coupons` 的重复条目问题要在输出里点明一次,这是本 Skill 相对其他券类项目的核心差异点。
- ## 附带脚本
- `scripts/xray.py` 提供五个纯函数(无网络、无副作用),用于把工具返回的原始 JSON 转成上表:
- - `dedupe_coupons(raw)` —— 按券名去重,返回 `(去重后列表, 原始条目数, 重复条目数)`
- - `group_by_coupon_id(rows)` —— 同 `couponId` 多 `couponCode` 归并
- - `build_matrix(stores, store_coupons_map)` —— 生成跨店可用性矩阵
- - `rank_stores(stores, pricing)` —— 按券后实付升序,同价按省钱额降序,`after` 缺失排最后
- - `sort_stores_by_distance(stores)` —— 按 `distance`(米)升序,缺失距离的门店排最后
- 用法:`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)
- # 麦门券力透视 · mcd-coupon-xray
- > 麦麦省的券谁都能领,但**领了不等于你楼下那家店认**。
- >
- > 这个 Skill 一键领全,然后逐家门店校验:哪家店真的能核销、券后实付多少、同一张券在哪家店才用得掉。
- ## 它解决的问题
- 麦当劳 MCP 里有两个都叫「我的券」的接口,语义完全不同:
- | 接口 | 你看到的 | 它校验了什么 |
- |---|---|---|
- | `query-my-coupons` | 你**拥有**的券 | **什么都没校验** |
- | `query-store-coupons` | 某家店 + 某渠道下**能核销**的券 | 门店、渠道、下单规则 |
- 官方文档自己写得很清楚:
- > 该接口返回的是用户拥有的券,**不进行门店、渠道、配送方式等下单规则校验,因此不承诺可用于当前订单**。若业务目标是"当前门店/当前订单可用的券",请调用 `query-store-coupons`。
- 于是产生了一个几乎所有人都撞过的体验:卡包里躺着七八张券,兴冲冲走到楼下门店,点开一单,发现一张都用不上。
- **「能领」和「能用」之间的差额,就是这个 Skill 要查的东西。**
- ## 实测到的五个反直觉事实
- 这五个都是用真实 Token、自己的账号把整条链跑完后得出的(2026-10-23,北京三里屯 5 家门店):
- **1. 一张券要过三道门:领了 → 进包 → 今天能用**
- 实测漏斗:`auto-bind-coupons` 领取 **5 张全部成功** → `query-my-coupons` 卡包里只有 **4 张**(免费脆薯饼领取成功却没进包)→ 卡包 4 张里又有 2 张有效期从 10-26 才开始,`query-store-coupons` 返回的当天真正能核销的只有 **2 张**。
- 所以「我的券」这个数字,和「今天在楼下这家店能用掉几张」之间隔了两层,每一层都会安静地吃掉一部分。
- **2. 「一张券」的唯一标识是 couponId,不是券名**
- 领取返回的 5 条记录,去重后是 **5 张券、5 个不同 couponId**——「11.9 元麦辣鸡腿堡」出现两次,是两个不同活动:一批有效期到 10-23、一批从 10-26 开始,各有真实券码。
- 按券名去重会把两张真券合并成一张。这不是展示优化,是把钱算丢。(本项目早期版本犯过这个错,已修正。)
- **3. 菜单编码 ≠ 计价编码**
- 券的适用商品 `9900016534`(王牌炸鸡任选 2)**不在** `query-meals` 返回的菜单里,但 `calculate-price` 照样算出 23.8 → 19.9 元。
- 不能用「菜单里有没有这个商品」来判断券可不可用,应直接调 `calculate-price`。
- **4. 卡包是空的,按门店查也一定是空的**
- `query-store-coupons` 不是「返回该店全部可用券」,而是「在**你已持有**的券里筛出该店能用的」。实测:空卡包 + 有效门店 `1951066` → 返回 `[]`。
- 所以顺序必须是**先领券,再查门店**。反过来做,任何门店都是空的,会得出「这家店一张券都不支持」的错误结论。
- **5. 门店经纬度是废的**
- `query-nearby-stores` 每家店都返回 `longitude: 0.0`、`latitude: 0.0`,唯一有效的是 `distance`(米)。任何想拿坐标画地图或自己算距离的写法都会失败。
- ## 怎么用
- 在 WorkBuddy(或任何支持 MCP 的客户端)里配好麦当劳 MCP,然后直接说:
- ```
- 帮我看看我的券哪家店能用
- ```
- ```
- 我想在国贸附近吃,用券之后哪家最便宜
- ```
- Skill 会走完整条链:
- ```
- available-coupons 麦麦省可领券(按券名去重,报出真实张数)
- ↓
- auto-bind-coupons 一键领取(写入卡包,纯新增)
- ↓
- query-my-coupons 复核卡包,确认券真的进来了
- ↓
- query-nearby-stores 拿到 storeCode(收藏为空自动降级为城市+地标搜索)
- ↓
- query-store-coupons 逐店校验:这张券这家店认不认
- ↓
- query-meals 有可用券的店,取菜单
- ↓
- calculate-price 券前 / 券后 / 省多少
- ```
- 输出两张表。以下为 2026-10-23 在北京三里屯 5 家门店的**真实运行结果**:
- | 门店 | 距离 | 可用券 | 最优券 | 券前 | 券后 | 省 |
- |---|---:|---:|---|---:|---:|---:|
- | 麦当劳北京长虹桥餐厅 | 628m | 2 | 11.9 元麦辣鸡腿堡 | 22.5 | 11.9 | **10.6** |
- | 麦当劳北京团结湖餐厅 | 933m | 2 | 11.9 元麦辣鸡腿堡 | 22.5 | 11.9 | **10.6** |
- | …(本批 5 家店结果一致,券为通用券) | | | | | | |
- 外加一张跨店可用性矩阵,直接回答「同一张券哪家店认」。本批样本里 5 家店可用性完全一致——矩阵的价值在有门店限制的券上才会显现,但逻辑必须先在。
- 最后给一句能直接执行的话:**去长虹桥店用 11.9 元麦辣鸡腿堡券,券后 11.9 元,省 10.6 元。**
- ## 目标用户
- - 卡包里攒了一堆券、但从没搞清楚过能不能用的人
- - 在几个门店之间犹豫、想选最省钱那家的人
- - 公司楼下 / 家楼下有多家麦当劳、想知道哪家券覆盖更好的通勤族
- - 用企业团餐 / 得来速、渠道规则更绕的场景
- ## 安装
- **1. 申请 MCP Token**
- 打开 [open.mcd.cn/mcp](https://open.mcd.cn/mcp),手机号登录 → 右上「控制台」→「激活」→ 同意协议 → 复制 Token。
- **2. 配置 MCP 连接**
- 本仓库的 `mcp-config.example.json` 是脱敏模板,把 `YOUR_MCP_TOKEN` 换成你的真实 Token:
- ```json
- {
- "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. 自检脚本**
- ```bash
- python scripts/xray.py --selftest
- python -m pytest tests/ -v # 或 python tests/test_xray.py
- ```
- ## 在线演示
- 👉 **https://wahaha-potato.github.io/mcd-coupon-xray/**
- 页面里所有数字来自 2026-10-23 用真实账号跑完的整条链路,无一处虚构。
- ## 仓库结构
- ```
- mcd-coupon-xray/
- ├── SKILL.md Skill 主体:流程、渠道参数矩阵、输出纪律
- ├── README.md 本文件
- ├── CONTEST_DECLARATION.md 参赛声明(官方原文,未改动)
- ├── MCP_INTEGRATION.md 逐工具的调用链、参数、实测返回与业务价值
- ├── mcp-config.example.json 脱敏配置模板(仅环境变量占位符)
- ├── workbuddy.md WorkBuddy 开发过程对话上下文
- ├── docs/
- │ └── index.html 在线演示页(GitHub Pages,真实数据)
- ├── LICENSE MIT
- ├── .gitignore 挡住本地配置与凭据
- ├── scripts/
- │ └── xray.py 去重 / 归并 / 矩阵 / 排序(纯函数,无网络)
- └── tests/
- └── test_xray.py 18 个单元测试,覆盖上述五个纯函数
- ```
- ## 边界
- - 本项目的结论只对**调用当时**的券状态、门店库存、活动规则有效。券会过期、门店会调整。
- - 不构成任何价格承诺。最终价格以麦当劳官方点餐页为准。
- - 本项目为非官方作品,由参赛者独立开发,与麦当劳中国无隶属关系。
- ## 许可
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.