name: maimai-saver description: 麦麦省钱助手——基于麦当劳中国官方 MCP Server 的省钱点餐技能。当用户提到麦当劳、麦乐送、麦麦、点麦当劳、想省钱/薅羊毛/领券/优惠、查优惠怎么用、积分兑换、麦麦商城、积分抽奖、麦当劳活动，或询问"怎么点麦当劳最划算"时使用本技能。核心能力：在下单前自动完成"领券→选券→比价→积分抵扣评估"，用 35 个官方工具帮用户以最低价格吃到同样的麦当劳。 version: 2.2.1 license: MIT

麦麦省钱助手（McD Saver）

本技能通过麦当劳中国官方远程托管的 MCP Server（https://mcp.mcd.cn， Streamable HTTP 协议）为用户提供以省钱为核心目标的点餐、优惠、积分服务。

角色定位：你不是"点餐员"，而是"省钱顾问"——目标不是帮用户点餐， 而是帮用户用最少的钱吃到同样的餐。每一次报价都必须附带省钱明细 （原价、优惠、实付、节省金额）。

Agent 兼容性

本技能遵循开放的 Agent Skills 标准（SKILL.md + 目录结构），同一份文件可在 WorkBuddy（~/.workbuddy/skills/）、Claude Code（~/.claude/skills/ 或 .claude/skills/）、Cursor（.cursor/skills/ 或 ~/.cursor/skills/， 兼容 .agents/skills/）、OpenAI Codex（.agents/skills/ 或 ~/.agents/skills/）直接安装。各平台安装步骤、显式调用方式（/maimai-saver 或 $maimai-saver）与 MCP 配置位置见 references/agent-skill-installation.md。

⚠️ 本技能为社区开源项目，与麦当劳公司无关联、无官方背书。 使用麦当劳 MCP 服务须遵守麦当劳中国《使用条款》及《麦当劳 MCP 服务规则》， 且仅限中国大陆地区（不含港澳台）、非商业用途。

前置条件：申请 MCP Token

1. 打开麦当劳 MCP 开放平台：https://open.mcd.cn/mcp
2. 点击右上角【登录】，使用手机号验证登录
3. 点击右上角【控制台】→【激活】按钮，申请 MCP Token
4. 同意服务协议后，一键复制 Token

Token 安全铁律：

• 绝不将 Token 写入任何会提交到 GitHub 的文件（config/mcp.example.json 中的占位符除外）
• 绝不在对话回复、日志、异常信息中展示 Token
• 推荐通过环境变量 MCD_MCP_TOKEN 或本机文件 ~/.mcd_mcp_token 提供

接入方式（二选一）

方式 A：MCP 客户端直连（推荐）

将以下配置写入 MCP 客户端（WorkBuddy 的 ~/.workbuddy/mcp.json、Cursor 的 mcp.json 等），替换 YOUR_MCP_TOKEN：

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

接入后，客户端会自动暴露全部 35 个 mcp__mcd-mcp__* 工具，本技能的价值在于 省钱决策方法论：何时领券、如何选券、怎样比价、何时用积分 （见下文"省钱四步检查"与 references/money-saving-strategies.md）。

方式 B：本技能自带 CLI（无需 MCP 客户端支持）

scripts/mcd.py 直接通过 Streamable HTTP 调用 MCP Server，仅依赖 Python 3.9+ 标准库：

export MCD_MCP_TOKEN="你的Token"
python scripts/mcd.py check                              # 检查 Token 与连通性
python scripts/mcd.py tools                              # 列出全部工具
python scripts/mcd.py schema available-coupons           # 查看工具入参 Schema
python scripts/mcd.py call available-coupons             # 查可领的麦麦省券
python scripts/mcd.py call query-my-account              # 查积分余额

退出码：0 成功 / 1 工具错误 / 2 鉴权失败 / 3 限流 / 4 网络错误。

省钱工具地图（35 个，按省钱场景分组）

完整目录见 references/tools.md（2026-10-10 实测校准）。

入参不确定时：先执行 python scripts/mcd.py schema <tool>（方式 B）或 查看 MCP 客户端展示的工具 Schema（方式 A），不要凭空猜测参数名。

省钱四步检查（下单前强制执行）

规则：任何 create-order 之前，必须完成以下四步并向用户展示省钱明细。 用户明确表示"不用优惠直接下单"时可跳过第 1/2 步，但仍需展示无优惠价格。

第 1 步：领券

available-coupons（查可领券列表，向用户展示）
→ 用户同意 → auto-bind-coupons（一键领取，写操作需确认）

第 2 步：选券

query-store-coupons（指定门店 + 订单类型 orderType：1=到店含得来速，2=外送含团餐）
→ 结合 query-my-coupons，筛选出对当前购物车最优的券

第 3 步：比价

calculate-price（不带券）→ calculate-price（带最优券组合）
→ 向用户展示：原价 / 优惠金额 / 实付 / 节省比例
→ 若有多个券组合，选择实付最低的组合，并向用户说明选择理由

第 4 步：积分抵扣评估

query-my-account（积分余额、即将过期积分——即将过期积分要主动提醒）
→ mall-points-products 检索同款/同类餐品券
→ 若"积分兑换的餐品券"折算价值 ≥ 购物车中对应商品现金价，提示用户对比方案
→ 由用户决定走"现金+券"还是"积分兑换"

积分价值估算口径：1 积分 ≈ 0.01 元人民币（常见量级，仅作参考基准）， 实际以 mall-points-products 返回的兑换价为准。

第 5 步（可选增强）：外部团购比价

用户从美团/抖音 App 查询麦当劳团购券 → deal_compare.py add 录入
→ deal_compare.py compare --mcd-face <商品合计原价> --mcd-price <MCP带券实付>
→ 输出"官方渠道 vs 团购"估算比价报告与推荐

• 数据由用户手动录入（团购平台无公开 API），报告为估算值，须明确标注 "估算，以平台实际页面为准"
• 推荐团购时必须提示：团购券通常不可叠加官方优惠券、需核对适用门店/时段
• 方法论详见 references/group-buy-comparison.md

标准工作流

1. 省钱版麦乐送（外送）点餐 —— 主推流程

[省钱检查 1-4 步]
delivery-query-addresses（无地址则 delivery-create-address）
→ delivery-query-stores（确定门店）
→ query-meals → query-meal-detail（确定商品 + 零成本替换项）
→ calculate-price（无券 / 带券对比，展示省钱明细）
→ 【用户明确确认】→ create-order → 返回支付链接给用户
→ query-order（跟踪进度）

2. 省钱版到店取餐 / 堂食 / 得来速

query-nearby-stores → query-meals → query-meal-detail
→ [省钱检查 2-4 步] → 【用户确认】→ create-order → query-order

3. 主题活动（派对/品鉴会）预约

query-party-city → query-party-store（选定城市）
→ query-partystore-date（选定门店）→ query-partystore-session（选定日期）
→ 【用户确认】→ party-order-create

4. 积分兑换 / 抽奖

query-my-account → mall-points-products → mall-product-detail
→ 【用户确认】→ mall-create-order
（抽奖：query-lottery-info → 消耗规则与免费次数 →【用户确认】→ draw-lottery）

5. 最优组合点单（optimizer 工作流）

query-meals / query-meal-detail → 写 menu.json（含价格，记录零成本替换项）
→ query-store-coupons + query-my-coupons → 写 coupons.json
   （threshold/discount 从券详情提取，不确定则留空字段）
→ 用户声明想吃清单 → 写 wants.json
→ python scripts/optimizer.py plan --wants wants.json --menu menu.json \
     --coupons coupons.json [--mcp --store-code ...] [--budget 30] [--max-kcal 800]
   （--mcp 真实计价模式的结果才能作为下单依据；估算模式输出必须标注"未经验证"；
     --budget/--max-kcal 为可选约束，违反约束的方案排后展示并标注超出量；
     v1.5 起菜单含 protein/sodium 字段时可用 --min-protein 20 --max-sodium 1500
     做营养约束——数据缺失的方案按不满足处理并如实标注「蛋白质未知」，
     绝不虚构达标。健身/控盐用户主动提出时使用）
→ optimizer plan 输出后自动衔接团购终局建议（本地券库非空时）：
   「官方最优 vs 团购估算」结论 + 适用限制原样提示；`--no-deals` 可关闭
→ 向用户展示方案排名与省钱明细；凑单方案必须附
   "仅当你本来就需要该商品才划算"提示，且不得以凑单方案为默认推荐
→ 营养约束触发时的替换建议策略（味热比思想）：
   最优方案仍超热量/钠上限时，按「热量代价从小到大」逐项给出替换
   （例：中可乐→无糖可乐、中薯条→玉米杯），用户明确表达喜爱的单品
   最后才动；每处替换讲清楚"少多少热量、多多少蛋白"
→ 用户口味偏好（去酸黄瓜、可乐去冰等）在会话内记住并写入后续
   特调参数，不必每次重说
→ 【用户明确确认】→ calculate-price 复核 → create-order

6. 沉默成本体检（silent_cost 工作流）

python scripts/mcd.py call query-my-coupons --raw > coupons.json
python scripts/mcd.py call order-list --raw > orders.json
python scripts/mcd.py call query-my-account --raw > points.json
→ python scripts/silent_cost.py report --coupons coupons.json \
     --orders orders.json --points points.json \
     [--probe --store-code 门店编码] [--html 报告.html]
→ 向用户展示报告（临期券排程给出「可实现 vs 注定过期」金额）；
   临期券与临期积分必须给出优先处理建议；用户要求分享时可给 HTML 报告

（--probe：无面值券实测精确价值——实测优先、估算兜底、失败如实标注； --html：零依赖单文件报告，可截图分享，不含任何敏感字段）

更多流程（团餐、营养咨询、活动日历等）与分支处理见 references/workflows.md； 十一大省钱策略详解见 references/money-saving-strategies.md。

调用规范（必须遵守）

1. 先查后改：任何写操作（create-order、cancel-order、mall-create-order、 draw-lottery、party-order-create、delivery-create-address、 auto-bind-coupons）之前，必须先用查询工具收集完整上下文。
2. 下单必确认：create-order 及所有下单类工具执行前，必须向用户完整展示 门店、商品清单、优惠券、省钱明细、总价，并获得明确确认（如"确认下单"）。 用户的模糊表述不构成确认，需复述订单要点再次确认。
3. 支付安全：create-order 返回的支付链接只原样转交给用户，由用户自行完成 支付；本技能不代付、不引导用户在任何非麦当劳域名完成支付。
4. 取消订单：仅当用户明确表达取消意图时调用 cancel-order，并先通过 query-order 核对订单号与订单状态。
5. 限流纪律：每个 Token 每分钟最多 600 次请求。批量操作时应控制节奏。
6. 不虚构优惠：省钱明细中的每一笔优惠必须来自 calculate-price 的返回值， 不得自行估算或承诺未经验证的折扣。
7. 比价透明：团购比价结果必须标注"估算"属性与数据来源（用户录入）， 推荐团购时须同步提示叠加规则限制；不做贬损任何渠道的比较表述。

错误处理

详见 references/error-handling.md。

目录结构

maimai-saver/
├── SKILL.md                            # 本文件：省钱顾问方法论与技能入口
├── README.md / README_EN.md            # 项目说明（中/英，结构与锚点逐位对齐）
├── CHANGELOG.md                        # 版本变更记录（Keep a Changelog 格式）
├── CONTRIBUTING.md                     # 贡献指南与发布流程
├── LICENSE                             # MIT 许可证 + 第三方条款声明
├── SECURITY.md                         # 漏洞报告与安全边界（对外披露入口）
├── CONTEST_DECLARATION.md              # 参赛声明（官方原文，未改动）
├── MCP_INTEGRATION.md                  # MCP 集成说明（参赛要求文件）
├── mcp-config.example.json             # 脱敏 MCP 配置（参赛要求文件，与 config/ 版内容一致）
├── workbuddy.md                      # WorkBuddy 开发上下文（WorkBuddy 专项核验用）
├── pyproject.toml                      # 打包元数据与 pytest 配置（版本号随发版同步）
├── requirements-dev.txt                # 开发依赖（pytest / pytest-cov）
├── install.ps1                         # Windows WorkBuddy 一键安装脚本
├── demo.py                             # 离线全链路演示（内嵌 fixture，不联网）
├── .github/
│   ├── workflows/ci.yml                # CI：3.9 / 3.11 / 3.13 矩阵 + 覆盖率门槛
│   ├── ISSUE_TEMPLATE/                 # Bug / 功能建议模板与讨论区入口
│   └── PULL_REQUEST_TEMPLATE.md        # PR 检查清单
├── docs/
│   ├── demo.html                       # 在线试算页（四维约束滑杆 + 数值输入、Token 导入）
│   ├── index.html                      # Pages 根路径索引页（自动进入试算页）
│   ├── development-log.md              # 开发过程记录（WorkBuddy 专项奖励核验用）
│   ├── coverage-report.md              # 覆盖率报告（--cov=scripts 口径与补测路线）
│   └── assets/banner.svg               # 品牌横幅（版本与测试数随发版同步）
├── config/
│   └── mcp.example.json                # MCP 客户端配置示例（占位符 Token）
├── scripts/
│   ├── mcd_client.py                   # MCP Streamable HTTP 客户端核心（纯标准库、主动限速）
│   ├── mcd.py                          # CLI 入口：check / tools / schema / call
│   ├── deal_compare.py                 # 外部团购比价引擎（美团/抖音券手动录入）
│   ├── optimizer.py                    # 券组合优化器（估算 / --mcp 真实计价双模式、Top-K 预筛）
│   ├── silent_cost.py                  # 沉默成本体检（临期券排程/消费画像/积分/实测）
│   ├── silent_report.py                # HTML 体检报告渲染与省钱等级（silent_cost 再导出）
│   ├── version.py                      # 版本号递增工具（自定义 z.x.y：y≤3、x≤6）
│   ├── verify_run.py                   # 真实运行验证记录生成（自动脱敏）
│   ├── check_toc.py                    # README 目录锚点与中英结构校验
│   └── build_releases.py               # 发布产物构建与校验（英文 zip + 中文说明）
├── references/
│   ├── tools.md                        # 35 个工具完整目录与使用要点
│   ├── money-saving-strategies.md      # 十一大省钱策略详解（核心参考）
│   ├── group-buy-comparison.md         # 外部团购比价方法论
│   ├── workflows.md                    # 各业务场景的详细调用流程
│   ├── mcp-pitfalls.md                 # MCP 实战踩坑与参数串联指南
│   ├── agent-skill-installation.md     # 各客户端 Agent Skill 安装细则
│   └── error-handling.md               # 错误码、重试策略与排查指南
├── examples/
│   ├── order-flow-example.md           # 一次完整省钱点餐的示例会话
│   ├── three-ways.md                   # 一单三种买法的可复现算例（离线可跑）
│   ├── silent-cost-example.md          # 沉默成本体检离线示例与读法
│   └── verified-run.md                 # 真实环境验证记录（脱敏，可复现）
├── fixtures/                           # 7 份离线回归数据（菜单/券/订单/积分/团购等）
├── releases/                           # 发布产物：每版英文 zip + 中文说明 + 索引
└── tests/                              # pytest 单元测试（265 个用例 + 一致性校验）

🍟 McD Saver

让 AI 帮你用最少的钱吃麦当劳 —— Agent Skill + 独立 CLI 二合一

🎮 30 秒在线试算（免登录） · 📦 快速开始 · 💬 讨论区 · 🛍️ Also on Agensi · English

目录

• 项目简介
• 功能特性
• 快速开始
  • 30 秒体验（免 Token）
  • 安装步骤
• 使用说明
  • 命令速查
  • 全渠道比价示例
• 配置说明
• 项目结构
• 工具能力总览
• 常见问题
• 更新说明
• 发布产物与版本策略
• 反馈与支持
• 参与贡献
• 免责声明
• 许可证
• Star History

项目简介

麦麦省钱助手是一个以「省钱」为唯一目标的麦当劳点餐助手：不是帮你下单， 而是在下单前强制跑一遍省钱检查——把可领的券领完、挑出当前订单最优券、 用官方 calculate-price 做无券/带券双价对比、评估积分兑换是否更划算， 最后把省钱明细（原价 / 优惠 / 实付 / 节省比例）一并展示给你确认。

一个仓库，三种用法：

• Agent Skill：一份 SKILL.md 遵循开放标准，装进 WorkBuddy / Claude Code / Cursor / Codex 即用；
• 独立 CLI：scripts/mcd.py 直连官方 MCP Server（M-China/mcd-mcp-server 集成指南），无需任何客户端；
• 在线试算页：纯前端免登录，支持一键导入真实菜单。

设计原则——本项目在同类工具普遍做法的基础上做了这些取舍：

设计内核：把官方 App、美团、抖音、积分商城四个渠道放在同一张桌子上 算终局，而不是只在单一渠道内找局部最优。

订单安全：用户明确确认前绝不创建订单；创建订单 ≠ 支付成功， 支付始终在麦当劳官方页面完成。

功能特性

💰 省钱四步检查（核心方法论，Agent 自动执行）

• 领券前置 → 门店选券 → 无券/带券双价对比 → 积分抵扣评估
• 每一笔优惠金额必须来自官方工具实际返回值，绝不虚构

🧮 券组合优化器（optimizer.py）

• 确定性枚举「无券直点 / 单券 / 凑单达标 / 改点套餐」候选，逐方案计价排名
• 四维约束：--budget 预算 / --max-kcal 热量 / --min-protein 蛋白 / --max-sodium 钠
• 违规方案排后并标注差多少，数据缺失如实标注「未知」——绝不静默过滤

📉 全渠道比价引擎（deal_compare.py）

• 美团/抖音团购券手动录入（平台无公开 API，不做爬虫），与官方价格同口径折算对比
• 输出「官方 vs 团购」终局建议，叠加规则与限制原样提示

🩺 沉默成本体检（silent_cost.py）

• 临期券扫描 + 用券排程（过期窗口 × 点单频率 →「可实现 vs 注定过期」）
• 消费画像（客单价/高频单品）+ 积分影子价格
• 无面值券 --probe 实测精确价值；--html 生成可分享单文件报告

📸 一键分享卡（在线试算页）

• 试算完成后点相机按钮，直接导出 1080×1350 的「省钱账单」图（无第三方依赖，Canvas 绘制）
• 图内含无券价、最优方案、实付与省下金额，发群里比截图更清楚

🛡️ 安全与合规设计

• Token 三通道解析（环境变量/文件/参数），绝不写入日志
• 401 快速失败、429 指数退避尊重 Retry-After、5xx/网络错误自动重试
• 范围边界：聚焦下单前的省钱决策——不包含爬虫、自动下单、无人值守定时领券等自动化能力

🧪 测试保障：265 个单元测试覆盖 SSE 解析、Token 解析、退避计算、比价决策、 组合优化与 CLI 退出码；demo.py 全链路输出被 tests/test_demo_pipeline.py 断言——demo 即回归测试。

快速开始

30 秒体验（免 Token）

git clone https://github.com/yuxinlaile/McD-saver.git
cd McD-saver
python demo.py          # 离线全链路：领券→选券→比价→积分→排程→跨渠道

或直接打开在线试算页（免登录， 31 项菜单 / 9 张券 / 11 条团购示例；支持 Token 快速导入——桌面生成命令、 手机端 Agent 粘贴或 menu.json 文件导入，同步麦当劳 App 全量真实菜单）。

安装步骤

第 1 步 · 申请 MCP Token（方式一/二需要；30 秒体验与在线试算不需要）

1. 打开 https://open.mcd.cn/mcp，右上角【登录】（手机号验证，限中国大陆）
2. 【控制台】→【激活】→ 同意服务协议 → 复制 MCP Token

第 2 步 · 按场景选一种方式

安装 Skill 后 Agent 会按 SKILL.md 自动执行四步检查，并遵守四条规范： 先查后改 / 下单必确认 / 省钱必检查 / 不虚构优惠。

使用说明

命令速查

CLI 退出码（mcd.py）：0 成功 · 1 工具错误 · 2 鉴权失败 · 3 限流 · 4 网络错误 （deal_compare.py：0 成功 · 1 用法/数据错误 · 2 券库为空）

全局选项：--token、--url、--timeout（默认 30s）、--retries（默认 3）、--verbose。

claim 的安全边界：用户主动触发、单次执行、领取前必须 y 确认（--yes 仅供 脚本）；不提供定时轮询与无人值守后台，以符合平台风控要求。

全渠道比价示例

# 录入你在美团查到的团购券
python scripts/deal_compare.py add \
    --platform meituan --title "麦当劳满40减14代金券" \
    --price 25.9 --face 40 --channel store --time limited \
    --valid-until 2026-11-30 --notes "每日限用1张"

# 与官方渠道（原价 48.5 / 带券实付 38.5）同口径对比
python scripts/deal_compare.py compare --mcd-face 48.5 --mcd-price 38.5

比价结果为本地估算（团购平台无公开 API），方法论见 group-buy-comparison.md；数据层预留 MAIMAI_DEALS_PROVIDER 插件接口。

配置说明

配置文件

环境变量

MCP 客户端配置位置：WorkBuddy ~/.workbuddy/mcp.json · Cursor 设置 → Tools & MCP · Cherry Studio / Trae / VSCode / Kiro 各自 MCP 设置页 · Codex ~/.codex/config.toml 的 [mcp_servers.mcd-mcp] 段。

Token 安全：仅通过环境变量、Token 文件或 --token 参数提供；绝不写入仓库文件、 绝不出现在日志中；泄露后立即到 open.mcd.cn/mcp 重新申请。

项目结构

scripts/     核心实现：MCP 客户端、CLI、券组合优化器、沉默成本体检、版本与发布工具
references/  方法论手册：工具目录、省钱策略、团购比价、场景工作流、MCP 踩坑、排错
docs/        在线试算页与品牌资源（demo.html / index.html / banner.svg）
tests/       265 项单元测试 + 规范一致性校验
fixtures/    离线回归数据（菜单、券、订单、积分、商城、团购）
releases/    发布产物：每版英文压缩包 + 中文说明 + 索引

完整文件级目录树见 SKILL.md。

工具能力总览

完整说明见 references/tools.md；工作流详解见 references/workflows.md 与 SKILL.md； 接入实战踩坑（响应格式/单位/多态字段/时效性）见 references/mcp-pitfalls.md。

常见问题

Q1：401 鉴权失败？ Token 无效/过期/未提供。401 不重试，检查三个通道后到 open.mcd.cn/mcp 重新申请。

Q2：429 限流？ 每 Token 每分钟 600 次。CLI 已内置指数退避（尊重 Retry-After）； 仍失败请降低频率，检查是否在循环逐个调用 query-meal-detail。

Q3：tools 列表为空？ 先 check 验证连通性；确认 --url / MCD_MCP_URL 未改错。

Q4：工具报参数错误？ 不要猜参数名：python scripts/mcd.py schema <tool> 查权威入参； 编码类参数（storeCode、餐品编码、couponId）必须原样透传前序工具返回值。

Q5：optimizer 估算模式和 --mcp 有什么区别？ 估算模式本地计算、标注「未经验证」， 仅用于快速比较；--mcp 模式逐方案走官方 calculate-price（含配送费与叠加规则）， 结果才能作为下单依据。

Q6：比价数据从哪来？ 美团/抖音无公开 API，券信息手动录入本地券库，结果为估算； 外部数据源可经 MAIMAI_DEALS_PROVIDER 接入。

Q7：支持哪些 Agent？ WorkBuddy、Claude Code、Cursor、OpenAI Codex（同一 SKILL.md）。

Q8：麦当劳 MCP 的使用限制？ 限中国大陆（不含港澳台）、个人非商业用途， 详见下方免责声明。

更多排查见 references/error-handling.md（提 Issue 请勿附 Token）。

更新说明

当前版本 v2.2.1。近期版本要点：