🍟 McD Saver

让 AI 帮你用最少的钱吃麦当劳 —— Agent Skill + 独立 CLI 二合一 !Python !Dependencies-green) !Tests !License !Agent Skills !MCP English · 🎮 30 秒在线试算（免登录） · 📦 快速开始 · 💬 讨论区 · 🛍️ Also on Agensi

目录

• 项目简介
• 功能特性
• 快速开始

• 使用说明

• 配置说明
• 项目结构
• 工具能力总览
• 常见问题
• 更新说明
• 反馈与支持
• 参与贡献
• 免责声明
• 许可证
• Star History

项目简介

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

**设计内核：把官方 App、美团、抖音、积分商城四个渠道放在同一张桌子上

算终局，而不是只在单一渠道内找局部最优。**

功能特性

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

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

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

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

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

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

快速开始

30 秒体验（免 Token）

| 查看指定工具的入参 JSON Schema | | python scripts/mcd.py call --arg k=v | 调用官方工具（--raw 原始输出） | | python scripts/mcd.py claim | 一键领取可领券（展示清单→确认→领取） | | python scripts/optimizer.py plan --wants w.json --menu m.json --coupons c.json [--mcp] | 券组合优化；--budget/--max-kcal/--min-protein/--max-sodium 四维约束；本地券库非空时自动输出团购终局建议（--no-deals 关闭） | | python scripts/deal_compare.py add/list/compare | 团购券录入与全渠道比价 | | python scripts/silent_cost.py report --coupons c.json --orders o.json --points p.json | 沉默成本体检；--probe 实测券价值 / --html 生成分享报告 | CLI 退出码（mcd.py）：0 成功 · 1 工具错误 · 2 鉴权失败 · 3 限流 · 4 网络错误 （deal_compare.py：0 成功 · 1 用法/数据错误 · 2 券库为空） 全局选项：--token、--url、--timeout（默认 30s）、--retries（默认 3）、--verbose。

claim 的安全边界：用户主动触发、单次执行、领取前必须 y 确认（--yes 仅供

脚本）；不提供定时轮询与无人值守后台，以符合平台风控要求。

全渠道比价示例

`bash

录入你在美团查到的团购券

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 会在本机执行，仅在完全信任时使用）。

配置说明

配置文件 | 文件 | 用途 | |---|---| | config/mcp.example.json | MCP 客户端接入模板（${MCD_MCP_TOKEN} 占位符） | | mcp-config.example.json | 仓库根目录脱敏配置（参赛要求文件） | 环境变量 | 变量 | 说明 | |---|---| | MCD_MCP_TOKEN | MCP Token（优先级最高） | | MCD_MCP_TOKEN_FILE | Token 文件路径，默认 ~/.mcd_mcp_token | | MCD_MCP_URL | MCP Server 地址，默认 https://mcp.mcd.cn；非官方地址默认被拒绝（请求头带 Token），需显式加 --allow-non-official-url 才会放行并打印告警 | | MCD_DEALS_FILE | 团购券库路径，默认 ~/.mcd_saver/deals.json（旧名 MAIMAI_DEALS_FILE 仍兼容，优先级更低） | | MCD_DATA_DIR | 券库根目录，默认 ~/.mcd_saver（旧名 MAIMAI_DATA_DIR 仍兼容） | 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/ 317 项单元测试 + 规范一致性校验 fixtures/ 离线回归数据（菜单、券、订单、积分、商城、团购） releases/ 发布产物：每版英文压缩包 + 中文说明 + 索引 ` 完整文件级目录树见 SKILL.md。

工具能力总览

| 业务域 | 工具 | |---|---| | 营养健康 | list-nutrition-foods | | 地址与门店 | delivery-query-addresses delivery-create-address delivery-query-stores query-nearby-stores query-meal-assistance | | 菜单与价格 | query-meals query-meal-detail calculate-price query-promotions | | 点餐与订单 | create-order cancel-order query-order order-list query-survey-coupon | | 优惠券 | query-store-coupons available-coupons auto-bind-coupons query-my-coupons | | 积分与商城 | query-my-account mall-points-products mall-product-detail mall-create-order mall-order-list mall-order-detail | | 积分抽奖 | query-lottery-info draw-lottery query-my-prizes | | 主题活动 | query-party-city query-party-store query-partystore-date query-partystore-session party-order-create | | 辅助 | now-time-info campaign-calendar | 完整说明见 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 查权威入参； 编码类参数（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.4.2。最近 3 个版本（由 CHANGELOG 自动生成）： | 版本 | 亮点 | |---|---| | v2.4.2 | 退款与重试链路修复 | | v2.4.1 | Star History 图改回 star-history.com 渲染 | | v2.4.0 | CODE_OF_CONDUCT.md（改编自 Contributor Covenant 2.1）；README「参与 | 完整变更记录见 CHANGELOG.md，各版本下载见 Releases。

反馈与支持

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

参与贡献

欢迎 Issue / PR / Discussions。动手前请先读 CONTRIBUTING.md（开发环境、分支与提交规范、 发版流程），并遵守贡献者行为准则。 | 你可以做什么 | 从这里开始 | |---|---| | 报 Bug | 提交 Bug 报告——附复现命令与 --verbose 输出（请勿粘贴 Token） | | 提需求 | 提交功能请求 | | 改代码 | 认领 Issue → 从 main 拉分支 → 按 PR 模板 填写 → 提交前跑 python -m pytest tests/ | | 补文档 / 算例 | references/workflows.md 补场景、examples/ 补离线算例；中英校对后跑 python scripts/check_toc.py | 提交前自查：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）， 相关使用须遵守其服务条款与上游限制。

Star History

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

曲线由 star-history.com 渲染：对方服务端定期抓取并缓存数据，可能比顶部的实时星数徽章

滞后数小时到一天，当前星数以顶部 Stars 徽章为准。

---

🔍 搜索关键词

麦当劳省钱 优惠券管理 团购比价 美团抖音券 积分价值 Agent Skill MCP CLI 组合优化 净价值 沉默成本 营养约束 免登录试算 麦麦省钱助手 McD Saver 麦门 精算师 · McDonald's China, coupon optimizer, deal comparison, group-buy, points valuation, nutrition budget, silent cost audit, MCP agent skill, Claude, WorkBuddy, Cursor, Codex, online calculator