麦门券力透视 · 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