🍟 McD Saver

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

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

• 项目简介
• 功能特性
• 快速开始
  • 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/网络错误自动重试
• 范围边界：聚焦下单前的省钱决策——不包含爬虫、自动下单、无人值守定时领券等自动化能力

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

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

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

运行要求：Python 3.9+（全部功能仅用标准库，无第三方运行时依赖）；跑测试需 pip install -r requirements-dev.txt（pytest / pytest-cov）。

第 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；数据层可用 --provider <模块路径> 显式接入外部数据源（该 .py 会在本机执行，仅在完全信任时使用）。

配置文件

环境变量

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 踩坑、排错
config/      MCP 客户端配置示例（占位符 Token）
examples/    示例会话、可复现算例与真实环境验证记录
docs/        在线试算页与品牌资源（demo.html / index.html / banner.svg）
tests/       329 项单元测试 + 规范一致性校验
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，券信息手动录入本地券库，结果为估算； 外部数据源可用 --provider <模块路径> 显式接入（该 .py 会在本机执行）。

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

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

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

当前版本 v2.5.2。最近 3 个版本（由 CHANGELOG 自动生成）：

完整变更记录见 CHANGELOG.md，各版本下载见 Releases。

如有问题或建议，欢迎在 讨论区留言， 或按场景选择：🐛 提交 Bug 报告 · 💡 提出功能建议 · 🤝 分享团购券数据（助力比价库更全）。 每一条反馈都会认真查看——这也是试算页持续按真实使用场景优化的依据。

欢迎 Issue / PR / Discussions。动手前请先读 CONTRIBUTING.md（开发环境、分支与提交规范、 发版流程），并遵守贡献者行为准则。

提交前自查：python -m pytest tests/ 全过 · 无 Token 等敏感信息 · references/ 与 SKILL.md 同步 · CHANGELOG 补条目 · README 中英同步。

真实运行留档见 examples/verified-run.md；离线算例见 examples/three-ways.md（一单三种买法）与 examples/silent-cost-example.md（沉默成本体检读法）。

本项目为社区开源项目，与麦当劳公司及其关联方无任何隶属、合作或背书关系。 使用麦当劳 MCP 服务须遵守麦当劳中国《使用条款》及《麦当劳 MCP 服务规则》， 仅限中国大陆地区（不含港澳台）、个人非商业用途；省钱明细来自官方工具 实际返回值，不构成价格承诺。"McDonald's"、"麦当劳"、"麦乐送"、"麦麦"等商标 权利归属麦当劳公司。

本项目代码以 MIT 许可证发布；运行依赖麦当劳中国 MCP 服务及上游 集成指南仓库（M-China/mcd-mcp-server）， 相关使用须遵守其服务条款与上游限制。

觉得有用的话，点个 ⭐ 让更多人看到：