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

麦门券力透视

这个 Skill 解决的认知断层

麦当劳 MCP 里有两个都叫「我的券」的接口，但语义完全不同：

用户看到「我有 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。

渠道参数对照（传错会导致查不到券，不是查不到就是返回空）：

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 跑内置用例。

麦门券力透视 · mcd-coupon-xray

麦麦省的券谁都能领，但领了不等于你楼下那家店认。

这个 Skill 一键领全，然后逐家门店校验：哪家店真的能核销、券后实付多少、同一张券在哪家店才用得掉。

它解决的问题

麦当劳 MCP 里有两个都叫「我的券」的接口，语义完全不同：

官方文档自己写得很清楚：

该接口返回的是用户拥有的券，不进行门店、渠道、配送方式等下单规则校验，因此不承诺可用于当前订单。若业务目标是"当前门店/当前订单可用的券"，请调用 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 家门店的真实运行结果：

外加一张跨店可用性矩阵，直接回答「同一张券哪家店认」。本批样本里 5 家店可用性完全一致——矩阵的价值在有门店限制的券上才会显现，但逻辑必须先在。

最后给一句能直接执行的话：去长虹桥店用 11.9 元麦辣鸡腿堡券，券后 11.9 元，省 10.6 元。

目标用户

• 卡包里攒了一堆券、但从没搞清楚过能不能用的人
• 在几个门店之间犹豫、想选最省钱那家的人
• 公司楼下 / 家楼下有多家麦当劳、想知道哪家券覆盖更好的通勤族
• 用企业团餐 / 得来速、渠道规则更绕的场景

安装

1. 申请 MCP Token

打开 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

在线演示

👉 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