Back to search
mcd-saver
SkillWorks with Claude CodeGitHub
麦麦省钱助手——基于麦当劳中国官方 MCP Server 的省钱点餐技能。当用户提到麦当劳、麦乐送、麦麦、点麦当劳、想省钱/薅羊毛/领券/优惠、查优惠怎么用、积分兑换、麦麦商城、积分抽奖、麦当劳活动,或询问"怎么点麦当劳最划算"时使用本技能。核心能力:在下单前自动完成"领券→选券→比价→积分抵扣评估",用 35 个官方工具帮用户以最低价格吃到同样的麦当劳。
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/yuxinlaile--mcd-saver)HTML
<a href="/listings/yuxinlaile--mcd-saver"><img src="/api/listings/yuxinlaile--mcd-saver/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 319 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- name: mcd-saver
- description: 麦麦省钱助手——基于麦当劳中国官方 MCP Server 的省钱点餐技能。当用户提到麦当劳、麦乐送、麦麦、点麦当劳、想省钱/薅羊毛/领券/优惠、查优惠怎么用、积分兑换、麦麦商城、积分抽奖、麦当劳活动,或询问"怎么点麦当劳最划算"时使用本技能。核心能力:在下单前自动完成"领券→选券→比价→积分抵扣评估",用 35 个官方工具帮用户以最低价格吃到同样的麦当劳。
- version: 2.6.0
- 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/`)直接安装。各平台安装步骤、显式调用方式(`/mcd-saver`
- 或 `$mcd-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`:
- ```json
- {
- "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+
- 标准库:
- ```bash
- 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 实测校准)。
- | 省钱场景 | 工具 | 用途 |
- |---|---|---|
- | 领券 | `available-coupons`、`auto-bind-coupons` | 查可领券 → 一键领取麦麦省全部可领券 |
- | 选券 | `query-store-coupons`、`query-my-coupons` | 查指定门店/订单类型下可用的券 |
- | 比价 | `calculate-price`、`query-promotions` | 带券试算应付总价;团餐满减/满折规则 |
- | 商品优化 | `query-meals`、`query-meal-detail`、`list-nutrition-foods` | 套餐组成与零成本替换项 |
- | 积分抵扣 | `query-my-account`、`mall-points-products`、`mall-product-detail`、`mall-create-order` | 积分余额、积分兑换券对比现金购买 |
- | 活动情报 | `campaign-calendar`、`now-time-info`、`query-lottery-info`、`draw-lottery`、`query-my-prizes` | 活动日历、抽奖机会与免费次数 |
- | 下单闭环 | `create-order`、`cancel-order`、`query-order`、`order-list`、`query-survey-coupon` | 下单、订单管理、满意度答卷奖券回收 |
- | 门店与地址 | `query-nearby-stores`、`delivery-query-addresses`、`delivery-create-address`、`delivery-query-stores` | 到店/外送场景前置查询 |
- | 团餐 | `query-meal-assistance`、`query-promotions` | 助餐服务与团餐促销 |
- | 全渠道比价 | `scripts/deal_compare.py`(本地工具,非 MCP) | 结合美团/抖音等团购券(手动录入)与官方价格估算比价 |
- | 组合优化 | `scripts/optimizer.py`(本地工具,非 MCP) | 枚举无券/单券/凑单/改点套餐候选方案,支持预算/热量/蛋白/钠约束,--mcp 模式经 calculate-price 真实计价,输出最优组合 |
- | 沉默成本 | `scripts/silent_cost.py`(本地工具,非 MCP) | 临期券扫描 + **用券排程**(可实现 vs 注定过期)+ **多单排程时间轴**(--timeline,逐单给出用哪张、哪天、净价值)+ 消费画像 + 积分体检 + **无面值券实测**(--probe)+ **可分享 HTML 报告**(--html);数据来自 query-my-coupons/order-list/query-my-account |
- | 其他 | `query-party-city/store/date/session`、`party-order-create`、`mall-order-list/detail` | 主题活动与商城订单 |
- **入参不确定时**:先执行 `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. **比价透明**:团购比价结果必须标注"估算"属性与数据来源(用户录入),
- 推荐团购时须同步提示叠加规则限制;不做贬损任何渠道的比较表述。
- ## 错误处理
- | 情形 | 判定 | 处理 |
- |---|---|---|
- | 401 鉴权失败 | AuthError / HTTP 401 | 引导用户到 open.mcd.cn/mcp 重新申请 Token,不重试 |
- | 429 限流 | RateLimitError / HTTP 429 | CLI 已内置指数退避重试;仍失败则告知用户稍后再试 |
- | 工具参数错误 | McpToolError | 读取错误详情,用 `schema` 重新核对参数后修正重试(最多 2 次) |
- | 网络错误 | TransportError | CLI 已自动重试;仍失败则提示用户检查网络 |
- 详见 `references/error-handling.md`。
- ## 目录结构
- ```
- mcd-saver/
- ├── SKILL.md # 本文件:省钱顾问方法论与技能入口
- ├── README.md / README_EN.md # 项目说明(中/英,结构与锚点逐位对齐)
- ├── CHANGELOG.md # 版本变更记录(Keep a Changelog 格式)
- ├── CONTRIBUTING.md # 贡献指南与发布流程
- ├── CODE_OF_CONDUCT.md # 贡献者行为准则(Contributor Covenant 2.1 改编)
- ├── 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 根路径索引页(自动进入试算页)
- │ ├── coverage-report.md # 覆盖率报告(--cov=scripts 口径与补测路线)
- │ └── assets/banner.svg # 品牌横幅(版本与测试数随发版同步)
- ├── config/
- │ └── mcp.example.json # MCP 客户端配置示例(占位符 Token)
- ├── scripts/
- │ ├── console.py # 控制台 UTF-8 兜底(Windows 非中文区域不再因中文输出崩溃)
- │ ├── 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 目录锚点与中英结构校验
- │ ├── sync_readme.py # README「近期版本」区块自动生成(源自 CHANGELOG)
- │ ├── audit_readme.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 单元测试(337 个用例 + 一致性校验)
- ```
README.md · README · 358 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <div align="center">
- # 🍟 McD Saver
- <img src="docs/assets/banner.svg" alt="McD Saver 麦麦省钱助手" width="720" />
- **让 AI 帮你用最少的钱吃麦当劳** —— Agent Skill + 独立 CLI 二合一
- [](https://yuxinlaile.github.io/McD-saver/demo.html)
- [](https://github.com/yuxinlaile/McD-saver/releases/tag/v2.6.0)
- [](https://github.com/yuxinlaile/McD-saver/stargazers)
- [](https://github.com/yuxinlaile/McD-saver/actions/workflows/ci.yml)
- 
- -green)
- 
- 
- 
- 
- **[English](README_EN.md) · [🎮 30 秒在线试算(免登录)](https://yuxinlaile.github.io/McD-saver/demo.html) · [📦 快速开始](#快速开始) · [💬 讨论区](https://github.com/yuxinlaile/McD-saver/discussions) · [🛍️ Also on Agensi](https://www.agensi.io/skills/mcd-saver-mcdonald-s-china-order-savings-check)**
- </div>
- ---
- ## 目录
- - [项目简介](#项目简介)
- - [功能特性](#功能特性)
- - [快速开始](#快速开始)
- - [30 秒体验(免 Token)](#30-秒体验免-token)
- - [安装步骤](#安装步骤)
- - [使用说明](#使用说明)
- - [命令速查](#命令速查)
- - [全渠道比价示例](#全渠道比价示例)
- - [配置说明](#配置说明)
- - [项目结构](#项目结构)
- - [工具能力总览](#工具能力总览)
- - [常见问题](#常见问题)
- - [更新说明](#更新说明)
- - [反馈与支持](#反馈与支持)
- - [参与贡献](#参与贡献)
- - [免责声明](#免责声明)
- - [许可证](#许可证)
- - [Star History](#star-history)
- ## 项目简介
- 麦麦省钱助手是一个以「省钱」为唯一目标的麦当劳点餐助手:**不是帮你下单,
- 而是在下单前强制跑一遍省钱检查**——把可领的券领完、挑出当前订单最优券、
- 用官方 `calculate-price` 做无券/带券双价对比、评估积分兑换是否更划算,
- 最后把省钱明细(原价 / 优惠 / 实付 / 节省比例)一并展示给你确认。
- 一个仓库,三种用法:
- - **Agent Skill**:一份 `SKILL.md` 遵循开放标准,装进 WorkBuddy / Claude Code / Cursor / Codex 即用;
- - **独立 CLI**:`scripts/mcd.py` 直连官方 MCP Server([M-China/mcd-mcp-server](https://github.com/M-China/mcd-mcp-server) 集成指南),无需任何客户端;
- - **在线试算页**:纯前端免登录,支持一键导入真实菜单。
- **设计原则**——本项目在同类工具普遍做法的基础上做了这些取舍:
- | 常见做法 | 本项目的做法 | 带来的差别 |
- |---|---|---|
- | 只对比官方券 | **官方券 + 美团/抖音团购 + 积分** 全渠道同口径估算「终局建议」 | 团购 App 里囤着的券也纳入决策 |
- | 鼓励凑单用券 | 凑单以「不凑单」为基准,主动提示**凑单陷阱** | 为用券而多买常常反而更贵 |
- | 券是可用资源 | 券是**有保质期的钱**:用券排程算出「可实现 vs 注定过期」 | 名义 ¥150 的券包,可能只有 ¥60 用得上 |
- | 无面值券靠估算 | 券码 + couponId 传 calculate-price **实测**,失败如实标注 | 模型给不出真实价格,只能猜 |
- | 营养靠口算 | 预算/热量/蛋白/钠**四维约束**,数据缺失按不满足处理并标注 | 健身控卡人群的硬需求 |
- | 定时轮询领券 | `claim` 一次性交互确认,**不含自动化与定时任务** | 降低风控与封号风险 |
- | 菜单靠手抄 | 在线试算页**一键导入真实菜单**(粘贴 MCP 输出即全量替换) | 官方菜单全量同步的合规路径 |
- > **设计内核:把官方 App、美团、抖音、积分商城四个渠道放在同一张桌子上
- > 算终局,而不是只在单一渠道内找局部最优。**
- **订单安全**:用户明确确认前绝不创建订单;创建订单 ≠ 支付成功,
- 支付始终在麦当劳官方页面完成。
- ## 功能特性
- **💰 省钱四步检查**(核心方法论,Agent 自动执行)
- - 领券前置 → 门店选券 → 无券/带券双价对比 → 积分抵扣评估
- - 每一笔优惠金额必须来自官方工具实际返回值,**绝不虚构**
- **🧮 券组合优化器**(`optimizer.py`)
- - 确定性枚举「无券直点 / 单券 / 凑单达标 / 改点套餐」候选,逐方案计价排名
- - 四维约束:`--budget` 预算 / `--max-kcal` 热量 / `--min-protein` 蛋白 / `--max-sodium` 钠
- - 违规方案排后并标注差多少,数据缺失如实标注「未知」——**绝不静默过滤**
- **📉 全渠道比价引擎**(`deal_compare.py`)
- - 美团/抖音团购券手动录入(平台无公开 API,不做爬虫),与官方价格同口径折算对比
- - 输出「官方 vs 团购」终局建议,叠加规则与限制原样提示
- **🩺 沉默成本体检**(`silent_cost.py`)
- - 临期券扫描 + **用券排程**(过期窗口 × 点单频率 →「可实现 vs 注定过期」)
- - **多单排程时间轴**(`--timeline`):把券逐张排到未来每一次点单,给出「第几单、哪天、用哪张、净价值」;
- 分配按到期日求最优解,不是「谁先过期先用谁」
- - 消费画像(客单价/高频单品)+ 积分影子价格
- - 无面值券 `--probe` 实测精确价值;`--html` 生成可分享单文件报告
- **📸 一键分享卡**(在线试算页)
- - 试算完成后点相机按钮,直接导出 1080×1350 的「省钱账单」图(无第三方依赖,Canvas 绘制)
- - 图内含无券价、最优方案、实付与省下金额,发群里比截图更清楚
- **🛡️ 安全与合规设计**
- - Token 三通道解析(环境变量/文件/参数),绝不写入日志
- - 401 快速失败、429 指数退避尊重 `Retry-After`、5xx/网络错误自动重试
- - 范围边界:聚焦下单前的省钱决策——不包含爬虫、自动下单、无人值守定时领券等自动化能力
- **🧪 测试保障**:337 个单元测试覆盖 SSE 解析、Token 解析、退避计算、比价决策、
- 组合优化与 CLI 退出码;`demo.py` 全链路输出被 `tests/test_demo_pipeline.py`
- 断言——**demo 即回归测试**。
- ## 快速开始
- ### 30 秒体验(免 Token)
- ```bash
- git clone https://github.com/yuxinlaile/McD-saver.git
- cd McD-saver
- python demo.py # 离线全链路:领券→选券→比价→积分→排程→跨渠道
- ```
- 或直接打开[在线试算页](https://yuxinlaile.github.io/McD-saver/demo.html)(免登录,
- 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 步 · 按场景选一种方式**
- | 方式 | 适合谁 | 怎么做 |
- |---|---|---|
- | **方式一 · MCP 客户端直连** | 用 WorkBuddy / Cursor / Claude Code 等客户端 | 把 [`config/mcp.example.json`](config/mcp.example.json) 中 `${MCD_MCP_TOKEN}` 换成真实 Token,粘贴到客户端 MCP 设置(位置见[配置说明](#配置说明))并启用 `mcd-mcp` |
- | **方式二 · Agent Skill 安装** | 想让 Agent 自动触发省钱检查 | `git clone https://github.com/yuxinlaile/McD-saver.git ~/.claude/skills/mcd-saver`(Cursor: `~/.cursor/skills/` · Codex: `~/.agents/skills/` · WorkBuddy: `~/.workbuddy/skills/`,Windows 可直接运行仓库内 `install.ps1`),另按方式一配置 MCP 连接;各平台细节见 [agent-skill-installation.md](references/agent-skill-installation.md) |
- | **方式三 · CLI 独立使用** | 脚本与调试,不装任何客户端 | `export MCD_MCP_TOKEN="你的Token"`(或写入 `~/.mcd_mcp_token` 文件),然后 `python scripts/mcd.py check` 验证连通性 |
- 安装 Skill 后 Agent 会按 `SKILL.md` 自动执行四步检查,并遵守四条规范:
- **先查后改 / 下单必确认 / 省钱必检查 / 不虚构优惠**。
- ## 使用说明
- ### 命令速查
- | 命令 | 作用 |
- |---|---|
- | `python demo.py` | **30 秒离线全链路演示**(免 Token;`--section 比价` 看单段) |
- | `python scripts/mcd.py check` | 验证 Token 与服务器连通性 |
- | `python scripts/mcd.py tools` | 列出全部 35 个官方工具 |
- | `python scripts/mcd.py schema <tool>` | 查看指定工具的入参 JSON Schema |
- | `python scripts/mcd.py call <tool> --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` 实测券价值 / `--timeline` 多单排程 / `--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](references/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 踩坑、排错
- config/ MCP 客户端配置示例(占位符 Token)
- examples/ 示例会话、可复现算例与真实环境验证记录
- docs/ 在线试算页与品牌资源(demo.html / index.html / banner.svg)
- tests/ 337 项单元测试 + 规范一致性校验
- fixtures/ 离线回归数据(菜单、券、订单、积分、商城、团购)
- releases/ 发布产物:每版英文压缩包 + 中文说明 + 索引
- ```
- 完整文件级目录树见 [`SKILL.md`](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/tools.md);工作流详解见
- [`references/workflows.md`](references/workflows.md) 与 [`SKILL.md`](SKILL.md);
- 接入实战踩坑(响应格式/单位/多态字段/时效性)见
- [`references/mcp-pitfalls.md`](references/mcp-pitfalls.md)。
- ## 常见问题
- **Q1:401 鉴权失败?** Token 无效/过期/未提供。401 不重试,检查三个通道后到
- [open.mcd.cn/mcp](https://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`](references/error-handling.md)(提 Issue 请勿附 Token)。
- ## 更新说明
- 当前版本 **v2.6.0**。最近 3 个版本(由 CHANGELOG 自动生成):
- <!-- release-highlights:start -->
- | 版本 | 亮点 |
- |---|---|
- | **v2.6.0** | 多单用券排程 `--timeline` |
- | **v2.5.2** | README 中英 Release 徽章链接指向不存在的 tag |
- | **v2.5.1** | CI 的发布产物校验必然失败 |
- <!-- release-highlights:end -->
- 完整变更记录见 [CHANGELOG.md](CHANGELOG.md),各版本下载见
- [Releases](https://github.com/yuxinlaile/McD-saver/releases)。
- ## 反馈与支持
- 如有问题或建议,欢迎在 [讨论区留言](https://github.com/yuxinlaile/McD-saver/discussions),
- 或按场景选择:🐛 [提交 Bug 报告](https://github.com/yuxinlaile/McD-saver/issues/new?template=bug_report.md) ·
- 💡 [提出功能建议](https://github.com/yuxinlaile/McD-saver/issues/new?template=feature_request.md) ·
- 🤝 [分享团购券数据](https://github.com/yuxinlaile/McD-saver/discussions)(助力比价库更全)。
- 每一条反馈都会认真查看——这也是试算页持续按真实使用场景优化的依据。
- ## 参与贡献
- 欢迎 Issue / PR / Discussions。动手前请先读 [CONTRIBUTING.md](CONTRIBUTING.md)(开发环境、分支与提交规范、
- 发版流程),并遵守[贡献者行为准则](CODE_OF_CONDUCT.md)。
- | 你可以做什么 | 从这里开始 |
- |---|---|
- | **报 Bug** | [提交 Bug 报告](https://github.com/yuxinlaile/McD-saver/issues/new?template=bug_report.md)——附复现命令与 `--verbose` 输出(**请勿粘贴 Token**) |
- | **提需求** | [提交功能请求](https://github.com/yuxinlaile/McD-saver/issues/new?template=feature_request.md) |
- | **改代码** | 认领 Issue → 从 `main` 拉分支 → 按 [PR 模板](.github/PULL_REQUEST_TEMPLATE.md) 填写 → 提交前跑 `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/verified-run.md);离线算例见
- [examples/three-ways.md](examples/three-ways.md)(一单三种买法)与
- [examples/silent-cost-example.md](examples/silent-cost-example.md)(沉默成本体检读法)。
- ## 免责声明
- 本项目为**社区开源项目,与麦当劳公司及其关联方无任何隶属、合作或背书关系**。
- 使用麦当劳 MCP 服务须遵守麦当劳中国《使用条款》及《麦当劳 MCP 服务规则》,
- 仅限**中国大陆地区(不含港澳台)**、**个人非商业用途**;省钱明细来自官方工具
- 实际返回值,不构成价格承诺。"McDonald's"、"麦当劳"、"麦乐送"、"麦麦"等商标
- 权利归属麦当劳公司。
- ## 许可证
- 本项目代码以 [MIT](LICENSE) 许可证发布;运行依赖麦当劳中国 MCP 服务及上游
- 集成指南仓库([M-China/mcd-mcp-server](https://github.com/M-China/mcd-mcp-server)),
- 相关使用须遵守其服务条款与上游限制。
- ## Star History
- 觉得有用的话,点个 ⭐ 让更多人看到:
- <div align="center">
- [](https://star-history.com/#yuxinlaile/McD-saver&Date)
- > 曲线由 star-history.com 渲染:对方服务端定期抓取并缓存数据,可能比顶部的实时星数徽章
- > 滞后数小时到一天,**当前星数以顶部 Stars 徽章为准**。
- </div>
- ---
- <details><summary>🔍 搜索关键词</summary>
- <br>
- 麦当劳省钱 优惠券管理 团购比价 美团抖音券 积分价值 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
- </details>
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.