Skip to content
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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/yuxinlaile--mcd-saver/badge.svg)](/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)

  1. ---
  2. name: mcd-saver
  3. description: 麦麦省钱助手——基于麦当劳中国官方 MCP Server 的省钱点餐技能。当用户提到麦当劳、麦乐送、麦麦、点麦当劳、想省钱/薅羊毛/领券/优惠、查优惠怎么用、积分兑换、麦麦商城、积分抽奖、麦当劳活动,或询问"怎么点麦当劳最划算"时使用本技能。核心能力:在下单前自动完成"领券→选券→比价→积分抵扣评估",用 35 个官方工具帮用户以最低价格吃到同样的麦当劳。
  4. version: 2.6.0
  5. license: MIT
  6. ---
  7. # 麦麦省钱助手(McD Saver)
  8. 本技能通过麦当劳中国官方远程托管的 MCP Server(`https://mcp.mcd.cn`,
  9. Streamable HTTP 协议)为用户提供**以省钱为核心目标**的点餐、优惠、积分服务。
  10. **角色定位**:你不是"点餐员",而是"省钱顾问"——目标不是帮用户点餐,
  11. 而是**帮用户用最少的钱吃到同样的餐**。每一次报价都必须附带省钱明细
  12. (原价、优惠、实付、节省金额)。
  13. ## Agent 兼容性
  14. 本技能遵循开放的 Agent Skills 标准(SKILL.md + 目录结构),同一份文件可在
  15. WorkBuddy(`~/.workbuddy/skills/`)、Claude Code(`~/.claude/skills/` 或
  16. `.claude/skills/`)、Cursor(`.cursor/skills/` 或 `~/.cursor/skills/`,
  17. 兼容 `.agents/skills/`)、OpenAI Codex(`.agents/skills/` 或
  18. `~/.agents/skills/`)直接安装。各平台安装步骤、显式调用方式(`/mcd-saver`
  19. 或 `$mcd-saver`)与 MCP 配置位置见 `references/agent-skill-installation.md`。
  20. > ⚠️ 本技能为社区开源项目,与麦当劳公司无关联、无官方背书。
  21. > 使用麦当劳 MCP 服务须遵守麦当劳中国《使用条款》及《麦当劳 MCP 服务规则》,
  22. > 且仅限中国大陆地区(不含港澳台)、非商业用途。
  23. ## 前置条件:申请 MCP Token
  24. 1. 打开麦当劳 MCP 开放平台:<https://open.mcd.cn/mcp>
  25. 2. 点击右上角【登录】,使用手机号验证登录
  26. 3. 点击右上角【控制台】→【激活】按钮,申请 MCP Token
  27. 4. 同意服务协议后,一键复制 Token
  28. **Token 安全铁律**:
  29. - 绝不将 Token 写入任何会提交到 GitHub 的文件(`config/mcp.example.json` 中的占位符除外)
  30. - 绝不在对话回复、日志、异常信息中展示 Token
  31. - 推荐通过环境变量 `MCD_MCP_TOKEN` 或本机文件 `~/.mcd_mcp_token` 提供
  32. ## 接入方式(二选一)
  33. ### 方式 A:MCP 客户端直连(推荐)
  34. 将以下配置写入 MCP 客户端(WorkBuddy 的 `~/.workbuddy/mcp.json`、Cursor 的
  35. `mcp.json` 等),替换 `YOUR_MCP_TOKEN`:
  36. ```json
  37. {
  38. "mcpServers": {
  39. "mcd-mcp": {
  40. "type": "streamablehttp",
  41. "url": "https://mcp.mcd.cn",
  42. "headers": {
  43. "Authorization": "Bearer YOUR_MCP_TOKEN"
  44. }
  45. }
  46. }
  47. }
  48. ```
  49. 接入后,客户端会自动暴露全部 35 个 `mcp__mcd-mcp__*` 工具,本技能的价值在于
  50. **省钱决策方法论**:何时领券、如何选券、怎样比价、何时用积分
  51. (见下文"省钱四步检查"与 `references/money-saving-strategies.md`)。
  52. ### 方式 B:本技能自带 CLI(无需 MCP 客户端支持)
  53. `scripts/mcd.py` 直接通过 Streamable HTTP 调用 MCP Server,仅依赖 Python 3.9+
  54. 标准库:
  55. ```bash
  56. export MCD_MCP_TOKEN="你的Token"
  57. python scripts/mcd.py check # 检查 Token 与连通性
  58. python scripts/mcd.py tools # 列出全部工具
  59. python scripts/mcd.py schema available-coupons # 查看工具入参 Schema
  60. python scripts/mcd.py call available-coupons # 查可领的麦麦省券
  61. python scripts/mcd.py call query-my-account # 查积分余额
  62. ```
  63. 退出码:0 成功 / 1 工具错误 / 2 鉴权失败 / 3 限流 / 4 网络错误。
  64. ## 省钱工具地图(35 个,按省钱场景分组)
  65. 完整目录见 `references/tools.md`(2026-10-10 实测校准)。
  66. | 省钱场景 | 工具 | 用途 |
  67. |---|---|---|
  68. | 领券 | `available-coupons`、`auto-bind-coupons` | 查可领券 → 一键领取麦麦省全部可领券 |
  69. | 选券 | `query-store-coupons`、`query-my-coupons` | 查指定门店/订单类型下可用的券 |
  70. | 比价 | `calculate-price`、`query-promotions` | 带券试算应付总价;团餐满减/满折规则 |
  71. | 商品优化 | `query-meals`、`query-meal-detail`、`list-nutrition-foods` | 套餐组成与零成本替换项 |
  72. | 积分抵扣 | `query-my-account`、`mall-points-products`、`mall-product-detail`、`mall-create-order` | 积分余额、积分兑换券对比现金购买 |
  73. | 活动情报 | `campaign-calendar`、`now-time-info`、`query-lottery-info`、`draw-lottery`、`query-my-prizes` | 活动日历、抽奖机会与免费次数 |
  74. | 下单闭环 | `create-order`、`cancel-order`、`query-order`、`order-list`、`query-survey-coupon` | 下单、订单管理、满意度答卷奖券回收 |
  75. | 门店与地址 | `query-nearby-stores`、`delivery-query-addresses`、`delivery-create-address`、`delivery-query-stores` | 到店/外送场景前置查询 |
  76. | 团餐 | `query-meal-assistance`、`query-promotions` | 助餐服务与团餐促销 |
  77. | 全渠道比价 | `scripts/deal_compare.py`(本地工具,非 MCP) | 结合美团/抖音等团购券(手动录入)与官方价格估算比价 |
  78. | 组合优化 | `scripts/optimizer.py`(本地工具,非 MCP) | 枚举无券/单券/凑单/改点套餐候选方案,支持预算/热量/蛋白/钠约束,--mcp 模式经 calculate-price 真实计价,输出最优组合 |
  79. | 沉默成本 | `scripts/silent_cost.py`(本地工具,非 MCP) | 临期券扫描 + **用券排程**(可实现 vs 注定过期)+ **多单排程时间轴**(--timeline,逐单给出用哪张、哪天、净价值)+ 消费画像 + 积分体检 + **无面值券实测**(--probe)+ **可分享 HTML 报告**(--html);数据来自 query-my-coupons/order-list/query-my-account |
  80. | 其他 | `query-party-city/store/date/session`、`party-order-create`、`mall-order-list/detail` | 主题活动与商城订单 |
  81. **入参不确定时**:先执行 `python scripts/mcd.py schema <tool>`(方式 B)或
  82. 查看 MCP 客户端展示的工具 Schema(方式 A),不要凭空猜测参数名。
  83. ## 省钱四步检查(下单前强制执行)
  84. **规则:任何 `create-order` 之前,必须完成以下四步并向用户展示省钱明细。
  85. 用户明确表示"不用优惠直接下单"时可跳过第 1/2 步,但仍需展示无优惠价格。**
  86. ### 第 1 步:领券
  87. ```
  88. available-coupons(查可领券列表,向用户展示)
  89. → 用户同意 → auto-bind-coupons(一键领取,写操作需确认)
  90. ```
  91. ### 第 2 步:选券
  92. ```
  93. query-store-coupons(指定门店 + 订单类型 orderType:1=到店含得来速,2=外送含团餐)
  94. → 结合 query-my-coupons,筛选出对当前购物车最优的券
  95. ```
  96. ### 第 3 步:比价
  97. ```
  98. calculate-price(不带券)→ calculate-price(带最优券组合)
  99. → 向用户展示:原价 / 优惠金额 / 实付 / 节省比例
  100. → 若有多个券组合,选择实付最低的组合,并向用户说明选择理由
  101. ```
  102. ### 第 4 步:积分抵扣评估
  103. ```
  104. query-my-account(积分余额、即将过期积分——即将过期积分要主动提醒)
  105. → mall-points-products 检索同款/同类餐品券
  106. → 若"积分兑换的餐品券"折算价值 ≥ 购物车中对应商品现金价,提示用户对比方案
  107. → 由用户决定走"现金+券"还是"积分兑换"
  108. ```
  109. **积分价值估算口径**:1 积分 ≈ 0.01 元人民币(常见量级,仅作参考基准),
  110. 实际以 `mall-points-products` 返回的兑换价为准。
  111. ### 第 5 步(可选增强):外部团购比价
  112. ```
  113. 用户从美团/抖音 App 查询麦当劳团购券 → deal_compare.py add 录入
  114. → deal_compare.py compare --mcd-face <商品合计原价> --mcd-price <MCP带券实付>
  115. → 输出"官方渠道 vs 团购"估算比价报告与推荐
  116. ```
  117. - 数据由用户手动录入(团购平台无公开 API),报告为**估算值**,须明确标注
  118. "估算,以平台实际页面为准"
  119. - 推荐团购时必须提示:团购券通常**不可叠加**官方优惠券、需核对适用门店/时段
  120. - 方法论详见 `references/group-buy-comparison.md`
  121. ## 标准工作流
  122. ### 1. 省钱版麦乐送(外送)点餐 —— 主推流程
  123. ```
  124. [省钱检查 1-4 步]
  125. delivery-query-addresses(无地址则 delivery-create-address)
  126. → delivery-query-stores(确定门店)
  127. → query-meals → query-meal-detail(确定商品 + 零成本替换项)
  128. → calculate-price(无券 / 带券对比,展示省钱明细)
  129. → 【用户明确确认】→ create-order → 返回支付链接给用户
  130. → query-order(跟踪进度)
  131. ```
  132. ### 2. 省钱版到店取餐 / 堂食 / 得来速
  133. ```
  134. query-nearby-stores → query-meals → query-meal-detail
  135. → [省钱检查 2-4 步] → 【用户确认】→ create-order → query-order
  136. ```
  137. ### 3. 主题活动(派对/品鉴会)预约
  138. ```
  139. query-party-city → query-party-store(选定城市)
  140. → query-partystore-date(选定门店)→ query-partystore-session(选定日期)
  141. → 【用户确认】→ party-order-create
  142. ```
  143. ### 4. 积分兑换 / 抽奖
  144. ```
  145. query-my-account → mall-points-products → mall-product-detail
  146. → 【用户确认】→ mall-create-order
  147. (抽奖:query-lottery-info → 消耗规则与免费次数 →【用户确认】→ draw-lottery)
  148. ```
  149. ### 5. 最优组合点单(optimizer 工作流)
  150. ```
  151. query-meals / query-meal-detail → 写 menu.json(含价格,记录零成本替换项)
  152. → query-store-coupons + query-my-coupons → 写 coupons.json
  153. (threshold/discount 从券详情提取,不确定则留空字段)
  154. → 用户声明想吃清单 → 写 wants.json
  155. → python scripts/optimizer.py plan --wants wants.json --menu menu.json \
  156. --coupons coupons.json [--mcp --store-code ...] [--budget 30] [--max-kcal 800]
  157. (--mcp 真实计价模式的结果才能作为下单依据;估算模式输出必须标注"未经验证";
  158. --budget/--max-kcal 为可选约束,违反约束的方案排后展示并标注超出量;
  159. v1.5 起菜单含 protein/sodium 字段时可用 --min-protein 20 --max-sodium 1500
  160. 做营养约束——数据缺失的方案按不满足处理并如实标注「蛋白质未知」,
  161. 绝不虚构达标。健身/控盐用户主动提出时使用)
  162. → optimizer plan 输出后自动衔接团购终局建议(本地券库非空时):
  163. 「官方最优 vs 团购估算」结论 + 适用限制原样提示;`--no-deals` 可关闭
  164. → 向用户展示方案排名与省钱明细;凑单方案必须附
  165. "仅当你本来就需要该商品才划算"提示,且不得以凑单方案为默认推荐
  166. → 营养约束触发时的替换建议策略(味热比思想):
  167. 最优方案仍超热量/钠上限时,按「热量代价从小到大」逐项给出替换
  168. (例:中可乐→无糖可乐、中薯条→玉米杯),用户明确表达喜爱的单品
  169. 最后才动;每处替换讲清楚"少多少热量、多多少蛋白"
  170. → 用户口味偏好(去酸黄瓜、可乐去冰等)在会话内记住并写入后续
  171. 特调参数,不必每次重说
  172. → 【用户明确确认】→ calculate-price 复核 → create-order
  173. ```
  174. ### 6. 沉默成本体检(silent_cost 工作流)
  175. ```
  176. python scripts/mcd.py call query-my-coupons --raw > coupons.json
  177. python scripts/mcd.py call order-list --raw > orders.json
  178. python scripts/mcd.py call query-my-account --raw > points.json
  179. → python scripts/silent_cost.py report --coupons coupons.json \
  180. --orders orders.json --points points.json \
  181. [--probe --store-code 门店编码] [--html 报告.html]
  182. → 向用户展示报告(临期券排程给出「可实现 vs 注定过期」金额);
  183. 临期券与临期积分必须给出优先处理建议;用户要求分享时可给 HTML 报告
  184. ```
  185. (--probe:无面值券实测精确价值——实测优先、估算兜底、失败如实标注;
  186. --html:零依赖单文件报告,可截图分享,不含任何敏感字段)
  187. 更多流程(团餐、营养咨询、活动日历等)与分支处理见 `references/workflows.md`;
  188. 十一大省钱策略详解见 `references/money-saving-strategies.md`。
  189. ## 调用规范(必须遵守)
  190. 1. **先查后改**:任何写操作(`create-order`、`cancel-order`、`mall-create-order`、
  191. `draw-lottery`、`party-order-create`、`delivery-create-address`、
  192. `auto-bind-coupons`)之前,必须先用查询工具收集完整上下文。
  193. 2. **下单必确认**:`create-order` 及所有下单类工具执行前,必须向用户完整展示
  194. **门店、商品清单、优惠券、省钱明细、总价**,并获得明确确认(如"确认下单")。
  195. 用户的模糊表述不构成确认,需复述订单要点再次确认。
  196. 3. **支付安全**:`create-order` 返回的支付链接只原样转交给用户,由用户自行完成
  197. 支付;本技能不代付、不引导用户在任何非麦当劳域名完成支付。
  198. 4. **取消订单**:仅当用户明确表达取消意图时调用 `cancel-order`,并先通过
  199. `query-order` 核对订单号与订单状态。
  200. 5. **限流纪律**:每个 Token 每分钟最多 600 次请求。批量操作时应控制节奏。
  201. 6. **不虚构优惠**:省钱明细中的每一笔优惠必须来自 `calculate-price` 的返回值,
  202. 不得自行估算或承诺未经验证的折扣。
  203. 7. **比价透明**:团购比价结果必须标注"估算"属性与数据来源(用户录入),
  204. 推荐团购时须同步提示叠加规则限制;不做贬损任何渠道的比较表述。
  205. ## 错误处理
  206. | 情形 | 判定 | 处理 |
  207. |---|---|---|
  208. | 401 鉴权失败 | AuthError / HTTP 401 | 引导用户到 open.mcd.cn/mcp 重新申请 Token,不重试 |
  209. | 429 限流 | RateLimitError / HTTP 429 | CLI 已内置指数退避重试;仍失败则告知用户稍后再试 |
  210. | 工具参数错误 | McpToolError | 读取错误详情,用 `schema` 重新核对参数后修正重试(最多 2 次) |
  211. | 网络错误 | TransportError | CLI 已自动重试;仍失败则提示用户检查网络 |
  212. 详见 `references/error-handling.md`。
  213. ## 目录结构
  214. ```
  215. mcd-saver/
  216. ├── SKILL.md # 本文件:省钱顾问方法论与技能入口
  217. ├── README.md / README_EN.md # 项目说明(中/英,结构与锚点逐位对齐)
  218. ├── CHANGELOG.md # 版本变更记录(Keep a Changelog 格式)
  219. ├── CONTRIBUTING.md # 贡献指南与发布流程
  220. ├── CODE_OF_CONDUCT.md # 贡献者行为准则(Contributor Covenant 2.1 改编)
  221. ├── LICENSE # MIT 许可证 + 第三方条款声明
  222. ├── SECURITY.md # 漏洞报告与安全边界(对外披露入口)
  223. ├── CONTEST_DECLARATION.md # 参赛声明(官方原文,未改动)
  224. ├── MCP_INTEGRATION.md # MCP 集成说明(参赛要求文件)
  225. ├── mcp-config.example.json # 脱敏 MCP 配置(参赛要求文件,与 config/ 版内容一致)
  226. ├── workbuddy.md # WorkBuddy 开发上下文(WorkBuddy 专项核验用)
  227. ├── pyproject.toml # 打包元数据与 pytest 配置(版本号随发版同步)
  228. ├── requirements-dev.txt # 开发依赖(pytest / pytest-cov)
  229. ├── install.ps1 # Windows WorkBuddy 一键安装脚本
  230. ├── demo.py # 离线全链路演示(内嵌 fixture,不联网)
  231. ├── .github/
  232. │ ├── workflows/ci.yml # CI:3.9 / 3.11 / 3.13 矩阵 + 覆盖率门槛
  233. │ ├── ISSUE_TEMPLATE/ # Bug / 功能建议模板与讨论区入口
  234. │ └── PULL_REQUEST_TEMPLATE.md # PR 检查清单
  235. ├── docs/
  236. │ ├── demo.html # 在线试算页(四维约束滑杆 + 数值输入、Token 导入)
  237. │ ├── index.html # Pages 根路径索引页(自动进入试算页)
  238. │ ├── coverage-report.md # 覆盖率报告(--cov=scripts 口径与补测路线)
  239. │ └── assets/banner.svg # 品牌横幅(版本与测试数随发版同步)
  240. ├── config/
  241. │ └── mcp.example.json # MCP 客户端配置示例(占位符 Token)
  242. ├── scripts/
  243. │ ├── console.py # 控制台 UTF-8 兜底(Windows 非中文区域不再因中文输出崩溃)
  244. │ ├── mcd_client.py # MCP Streamable HTTP 客户端核心(纯标准库、主动限速)
  245. │ ├── mcd.py # CLI 入口:check / tools / schema / call
  246. │ ├── deal_compare.py # 外部团购比价引擎(美团/抖音券手动录入)
  247. │ ├── optimizer.py # 券组合优化器(估算 / --mcp 真实计价双模式、Top-K 预筛)
  248. │ ├── silent_cost.py # 沉默成本体检(临期券排程/消费画像/积分/实测)
  249. │ ├── silent_report.py # HTML 体检报告渲染与省钱等级(silent_cost 再导出)
  250. │ ├── version.py # 版本号递增工具(自定义 z.x.y:y≤3、x≤6)
  251. │ ├── verify_run.py # 真实运行验证记录生成(自动脱敏)
  252. │ ├── check_toc.py # README 目录锚点与中英结构校验
  253. │ ├── sync_readme.py # README「近期版本」区块自动生成(源自 CHANGELOG)
  254. │ ├── audit_readme.py # README 事实一致性审计(命令表/用例数/版本/许可证)
  255. │ └── build_releases.py # 发布产物构建与校验(英文 zip + 中文说明)
  256. ├── references/
  257. │ ├── tools.md # 35 个工具完整目录与使用要点
  258. │ ├── money-saving-strategies.md # 十一大省钱策略详解(核心参考)
  259. │ ├── group-buy-comparison.md # 外部团购比价方法论
  260. │ ├── workflows.md # 各业务场景的详细调用流程
  261. │ ├── mcp-pitfalls.md # MCP 实战踩坑与参数串联指南
  262. │ ├── agent-skill-installation.md # 各客户端 Agent Skill 安装细则
  263. │ └── error-handling.md # 错误码、重试策略与排查指南
  264. ├── examples/
  265. │ ├── order-flow-example.md # 一次完整省钱点餐的示例会话
  266. │ ├── three-ways.md # 一单三种买法的可复现算例(离线可跑)
  267. │ ├── silent-cost-example.md # 沉默成本体检离线示例与读法
  268. │ └── verified-run.md # 真实环境验证记录(脱敏,可复现)
  269. ├── fixtures/ # 7 份离线回归数据(菜单/券/订单/积分/团购等)
  270. ├── releases/ # 发布产物:每版英文 zip + 中文说明 + 索引
  271. └── tests/ # pytest 单元测试(337 个用例 + 一致性校验)
  272. ```
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)

  1. <div align="center">
  2. # 🍟 McD Saver
  3. <img src="docs/assets/banner.svg" alt="McD Saver 麦麦省钱助手" width="720" />
  4. **让 AI 帮你用最少的钱吃麦当劳** —— Agent Skill + 独立 CLI 二合一
  5. [![在线试算](https://img.shields.io/badge/%F0%9F%8C%90_在线试算-免登录-FFC72C?style=flat-square)](https://yuxinlaile.github.io/McD-saver/demo.html)
  6. [![Release](https://img.shields.io/badge/Release-v2.6.0-9a3412?style=flat-square)](https://github.com/yuxinlaile/McD-saver/releases/tag/v2.6.0)
  7. [![Stars](https://img.shields.io/github/stars/yuxinlaile/McD-saver?style=flat-square&label=Stars)](https://github.com/yuxinlaile/McD-saver/stargazers)
  8. [![CI](https://github.com/yuxinlaile/McD-saver/actions/workflows/ci.yml/badge.svg)](https://github.com/yuxinlaile/McD-saver/actions/workflows/ci.yml)
  9. ![Python](https://img.shields.io/badge/Python-3.9%2B-blue)
  10. ![Dependencies](https://img.shields.io/badge/Dependencies-None%20(stdlib)-green)
  11. ![Tests](https://img.shields.io/badge/Tests-337%20passed-brightgreen)
  12. ![License](https://img.shields.io/badge/License-MIT-orange)
  13. ![Agent Skills](https://img.shields.io/badge/Works%20with-Agent%20Skills%20standard-0A7A72)
  14. ![MCP](https://img.shields.io/badge/MCP-Streamable%20HTTP-purple)
  15. **[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)**
  16. </div>
  17. ---
  18. ## 目录
  19. - [项目简介](#项目简介)
  20. - [功能特性](#功能特性)
  21. - [快速开始](#快速开始)
  22. - [30 秒体验(免 Token)](#30-秒体验免-token)
  23. - [安装步骤](#安装步骤)
  24. - [使用说明](#使用说明)
  25. - [命令速查](#命令速查)
  26. - [全渠道比价示例](#全渠道比价示例)
  27. - [配置说明](#配置说明)
  28. - [项目结构](#项目结构)
  29. - [工具能力总览](#工具能力总览)
  30. - [常见问题](#常见问题)
  31. - [更新说明](#更新说明)
  32. - [反馈与支持](#反馈与支持)
  33. - [参与贡献](#参与贡献)
  34. - [免责声明](#免责声明)
  35. - [许可证](#许可证)
  36. - [Star History](#star-history)
  37. ## 项目简介
  38. 麦麦省钱助手是一个以「省钱」为唯一目标的麦当劳点餐助手:**不是帮你下单,
  39. 而是在下单前强制跑一遍省钱检查**——把可领的券领完、挑出当前订单最优券、
  40. 用官方 `calculate-price` 做无券/带券双价对比、评估积分兑换是否更划算,
  41. 最后把省钱明细(原价 / 优惠 / 实付 / 节省比例)一并展示给你确认。
  42. 一个仓库,三种用法:
  43. - **Agent Skill**:一份 `SKILL.md` 遵循开放标准,装进 WorkBuddy / Claude Code / Cursor / Codex 即用;
  44. - **独立 CLI**:`scripts/mcd.py` 直连官方 MCP Server([M-China/mcd-mcp-server](https://github.com/M-China/mcd-mcp-server) 集成指南),无需任何客户端;
  45. - **在线试算页**:纯前端免登录,支持一键导入真实菜单。
  46. **设计原则**——本项目在同类工具普遍做法的基础上做了这些取舍:
  47. | 常见做法 | 本项目的做法 | 带来的差别 |
  48. |---|---|---|
  49. | 只对比官方券 | **官方券 + 美团/抖音团购 + 积分** 全渠道同口径估算「终局建议」 | 团购 App 里囤着的券也纳入决策 |
  50. | 鼓励凑单用券 | 凑单以「不凑单」为基准,主动提示**凑单陷阱** | 为用券而多买常常反而更贵 |
  51. | 券是可用资源 | 券是**有保质期的钱**:用券排程算出「可实现 vs 注定过期」 | 名义 ¥150 的券包,可能只有 ¥60 用得上 |
  52. | 无面值券靠估算 | 券码 + couponId 传 calculate-price **实测**,失败如实标注 | 模型给不出真实价格,只能猜 |
  53. | 营养靠口算 | 预算/热量/蛋白/钠**四维约束**,数据缺失按不满足处理并标注 | 健身控卡人群的硬需求 |
  54. | 定时轮询领券 | `claim` 一次性交互确认,**不含自动化与定时任务** | 降低风控与封号风险 |
  55. | 菜单靠手抄 | 在线试算页**一键导入真实菜单**(粘贴 MCP 输出即全量替换) | 官方菜单全量同步的合规路径 |
  56. > **设计内核:把官方 App、美团、抖音、积分商城四个渠道放在同一张桌子上
  57. > 算终局,而不是只在单一渠道内找局部最优。**
  58. **订单安全**:用户明确确认前绝不创建订单;创建订单 ≠ 支付成功,
  59. 支付始终在麦当劳官方页面完成。
  60. ## 功能特性
  61. **💰 省钱四步检查**(核心方法论,Agent 自动执行)
  62. - 领券前置 → 门店选券 → 无券/带券双价对比 → 积分抵扣评估
  63. - 每一笔优惠金额必须来自官方工具实际返回值,**绝不虚构**
  64. **🧮 券组合优化器**(`optimizer.py`)
  65. - 确定性枚举「无券直点 / 单券 / 凑单达标 / 改点套餐」候选,逐方案计价排名
  66. - 四维约束:`--budget` 预算 / `--max-kcal` 热量 / `--min-protein` 蛋白 / `--max-sodium` 钠
  67. - 违规方案排后并标注差多少,数据缺失如实标注「未知」——**绝不静默过滤**
  68. **📉 全渠道比价引擎**(`deal_compare.py`)
  69. - 美团/抖音团购券手动录入(平台无公开 API,不做爬虫),与官方价格同口径折算对比
  70. - 输出「官方 vs 团购」终局建议,叠加规则与限制原样提示
  71. **🩺 沉默成本体检**(`silent_cost.py`)
  72. - 临期券扫描 + **用券排程**(过期窗口 × 点单频率 →「可实现 vs 注定过期」)
  73. - **多单排程时间轴**(`--timeline`):把券逐张排到未来每一次点单,给出「第几单、哪天、用哪张、净价值」;
  74. 分配按到期日求最优解,不是「谁先过期先用谁」
  75. - 消费画像(客单价/高频单品)+ 积分影子价格
  76. - 无面值券 `--probe` 实测精确价值;`--html` 生成可分享单文件报告
  77. **📸 一键分享卡**(在线试算页)
  78. - 试算完成后点相机按钮,直接导出 1080×1350 的「省钱账单」图(无第三方依赖,Canvas 绘制)
  79. - 图内含无券价、最优方案、实付与省下金额,发群里比截图更清楚
  80. **🛡️ 安全与合规设计**
  81. - Token 三通道解析(环境变量/文件/参数),绝不写入日志
  82. - 401 快速失败、429 指数退避尊重 `Retry-After`、5xx/网络错误自动重试
  83. - 范围边界:聚焦下单前的省钱决策——不包含爬虫、自动下单、无人值守定时领券等自动化能力
  84. **🧪 测试保障**:337 个单元测试覆盖 SSE 解析、Token 解析、退避计算、比价决策、
  85. 组合优化与 CLI 退出码;`demo.py` 全链路输出被 `tests/test_demo_pipeline.py`
  86. 断言——**demo 即回归测试**。
  87. ## 快速开始
  88. ### 30 秒体验(免 Token)
  89. ```bash
  90. git clone https://github.com/yuxinlaile/McD-saver.git
  91. cd McD-saver
  92. python demo.py # 离线全链路:领券→选券→比价→积分→排程→跨渠道
  93. ```
  94. 或直接打开[在线试算页](https://yuxinlaile.github.io/McD-saver/demo.html)(免登录,
  95. 31 项菜单 / 9 张券 / 11 条团购示例;支持 **Token 快速导入**——桌面生成命令、
  96. 手机端 Agent 粘贴或 menu.json 文件导入,同步麦当劳 App 全量真实菜单)。
  97. **运行要求**:Python 3.9+(全部功能仅用标准库,无第三方运行时依赖);跑测试需
  98. `pip install -r requirements-dev.txt`(`pytest` / `pytest-cov`)。
  99. ### 安装步骤
  100. **第 1 步 · 申请 MCP Token**(方式一/二需要;30 秒体验与在线试算不需要)
  101. 1. 打开 <https://open.mcd.cn/mcp>,右上角【登录】(手机号验证,限中国大陆)
  102. 2. 【控制台】→【激活】→ 同意服务协议 → 复制 MCP Token
  103. **第 2 步 · 按场景选一种方式**
  104. | 方式 | 适合谁 | 怎么做 |
  105. |---|---|---|
  106. | **方式一 · MCP 客户端直连** | 用 WorkBuddy / Cursor / Claude Code 等客户端 | 把 [`config/mcp.example.json`](config/mcp.example.json) 中 `${MCD_MCP_TOKEN}` 换成真实 Token,粘贴到客户端 MCP 设置(位置见[配置说明](#配置说明))并启用 `mcd-mcp` |
  107. | **方式二 · 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) |
  108. | **方式三 · CLI 独立使用** | 脚本与调试,不装任何客户端 | `export MCD_MCP_TOKEN="你的Token"`(或写入 `~/.mcd_mcp_token` 文件),然后 `python scripts/mcd.py check` 验证连通性 |
  109. 安装 Skill 后 Agent 会按 `SKILL.md` 自动执行四步检查,并遵守四条规范:
  110. **先查后改 / 下单必确认 / 省钱必检查 / 不虚构优惠**。
  111. ## 使用说明
  112. ### 命令速查
  113. | 命令 | 作用 |
  114. |---|---|
  115. | `python demo.py` | **30 秒离线全链路演示**(免 Token;`--section 比价` 看单段) |
  116. | `python scripts/mcd.py check` | 验证 Token 与服务器连通性 |
  117. | `python scripts/mcd.py tools` | 列出全部 35 个官方工具 |
  118. | `python scripts/mcd.py schema <tool>` | 查看指定工具的入参 JSON Schema |
  119. | `python scripts/mcd.py call <tool> --arg k=v` | 调用官方工具(`--raw` 原始输出) |
  120. | `python scripts/mcd.py claim` | 一键领取可领券(展示清单→确认→领取) |
  121. | `python scripts/optimizer.py plan --wants w.json --menu m.json --coupons c.json [--mcp]` | 券组合优化;`--budget/--max-kcal/--min-protein/--max-sodium` 四维约束;本地券库非空时自动输出团购终局建议(`--no-deals` 关闭) |
  122. | `python scripts/deal_compare.py add/list/compare` | 团购券录入与全渠道比价 |
  123. | `python scripts/silent_cost.py report --coupons c.json --orders o.json --points p.json` | 沉默成本体检;`--probe` 实测券价值 / `--timeline` 多单排程 / `--html` 生成分享报告 |
  124. **CLI 退出码**(mcd.py):`0` 成功 · `1` 工具错误 · `2` 鉴权失败 · `3` 限流 · `4` 网络错误
  125. (deal_compare.py:`0` 成功 · `1` 用法/数据错误 · `2` 券库为空)
  126. **全局选项**:`--token`、`--url`、`--timeout`(默认 30s)、`--retries`(默认 3)、`--verbose`。
  127. > **claim 的安全边界**:用户主动触发、单次执行、领取前必须 y 确认(`--yes` 仅供
  128. > 脚本);不提供定时轮询与无人值守后台,以符合平台风控要求。
  129. ### 全渠道比价示例
  130. ```bash
  131. # 录入你在美团查到的团购券
  132. python scripts/deal_compare.py add \
  133. --platform meituan --title "麦当劳满40减14代金券" \
  134. --price 25.9 --face 40 --channel store --time limited \
  135. --valid-until 2026-11-30 --notes "每日限用1张"
  136. # 与官方渠道(原价 48.5 / 带券实付 38.5)同口径对比
  137. python scripts/deal_compare.py compare --mcd-face 48.5 --mcd-price 38.5
  138. ```
  139. > 比价结果为本地估算(团购平台无公开 API),方法论见
  140. > [group-buy-comparison.md](references/group-buy-comparison.md);数据层可用
  141. > `--provider <模块路径>` 显式接入外部数据源(该 .py 会在本机执行,仅在完全信任时使用)。
  142. ## 配置说明
  143. **配置文件**
  144. | 文件 | 用途 |
  145. |---|---|
  146. | `config/mcp.example.json` | MCP 客户端接入模板(`${MCD_MCP_TOKEN}` 占位符) |
  147. | `mcp-config.example.json` | 仓库根目录脱敏配置(参赛要求文件) |
  148. **环境变量**
  149. | 变量 | 说明 |
  150. |---|---|
  151. | `MCD_MCP_TOKEN` | MCP Token(优先级最高) |
  152. | `MCD_MCP_TOKEN_FILE` | Token 文件路径,默认 `~/.mcd_mcp_token` |
  153. | `MCD_MCP_URL` | MCP Server 地址,默认 `https://mcp.mcd.cn`;**非官方地址默认被拒绝**(请求头带 Token),需显式加 `--allow-non-official-url` 才会放行并打印告警 |
  154. | `MCD_DEALS_FILE` | 团购券库路径,默认 `~/.mcd_saver/deals.json`(旧名 `MAIMAI_DEALS_FILE` 仍兼容,优先级更低) |
  155. | `MCD_DATA_DIR` | 券库根目录,默认 `~/.mcd_saver`(旧名 `MAIMAI_DATA_DIR` 仍兼容) |
  156. **MCP 客户端配置位置**:WorkBuddy `~/.workbuddy/mcp.json` · Cursor 设置 → Tools & MCP ·
  157. Cherry Studio / Trae / VSCode / Kiro 各自 MCP 设置页 · Codex `~/.codex/config.toml` 的
  158. `[mcp_servers.mcd-mcp]` 段。
  159. **Token 安全**:仅通过环境变量、Token 文件或 `--token` 参数提供;绝不写入仓库文件、
  160. 绝不出现在日志中;泄露后立即到 open.mcd.cn/mcp 重新申请。
  161. ## 项目结构
  162. ```
  163. scripts/ 核心实现:MCP 客户端、CLI、券组合优化器、沉默成本体检、版本与发布工具
  164. references/ 方法论手册:工具目录、省钱策略、团购比价、场景工作流、MCP 踩坑、排错
  165. config/ MCP 客户端配置示例(占位符 Token)
  166. examples/ 示例会话、可复现算例与真实环境验证记录
  167. docs/ 在线试算页与品牌资源(demo.html / index.html / banner.svg)
  168. tests/ 337 项单元测试 + 规范一致性校验
  169. fixtures/ 离线回归数据(菜单、券、订单、积分、商城、团购)
  170. releases/ 发布产物:每版英文压缩包 + 中文说明 + 索引
  171. ```
  172. 完整文件级目录树见 [`SKILL.md`](SKILL.md#目录结构)。
  173. ## 工具能力总览
  174. | 业务域 | 工具 |
  175. |---|---|
  176. | 营养健康 | `list-nutrition-foods` |
  177. | 地址与门店 | `delivery-query-addresses` `delivery-create-address` `delivery-query-stores` `query-nearby-stores` `query-meal-assistance` |
  178. | 菜单与价格 | `query-meals` `query-meal-detail` `calculate-price` `query-promotions` |
  179. | 点餐与订单 | `create-order` `cancel-order` `query-order` `order-list` `query-survey-coupon` |
  180. | 优惠券 | `query-store-coupons` `available-coupons` `auto-bind-coupons` `query-my-coupons` |
  181. | 积分与商城 | `query-my-account` `mall-points-products` `mall-product-detail` `mall-create-order` `mall-order-list` `mall-order-detail` |
  182. | 积分抽奖 | `query-lottery-info` `draw-lottery` `query-my-prizes` |
  183. | 主题活动 | `query-party-city` `query-party-store` `query-partystore-date` `query-partystore-session` `party-order-create` |
  184. | 辅助 | `now-time-info` `campaign-calendar` |
  185. 完整说明见 [`references/tools.md`](references/tools.md);工作流详解见
  186. [`references/workflows.md`](references/workflows.md) 与 [`SKILL.md`](SKILL.md);
  187. 接入实战踩坑(响应格式/单位/多态字段/时效性)见
  188. [`references/mcp-pitfalls.md`](references/mcp-pitfalls.md)。
  189. ## 常见问题
  190. **Q1:401 鉴权失败?** Token 无效/过期/未提供。401 不重试,检查三个通道后到
  191. [open.mcd.cn/mcp](https://open.mcd.cn/mcp) 重新申请。
  192. **Q2:429 限流?** 每 Token 每分钟 600 次。CLI 已内置指数退避(尊重 Retry-After);
  193. 仍失败请降低频率,检查是否在循环逐个调用 `query-meal-detail`。
  194. **Q3:`tools` 列表为空?** 先 `check` 验证连通性;确认 `--url` / `MCD_MCP_URL` 未改错。
  195. **Q4:工具报参数错误?** 不要猜参数名:`python scripts/mcd.py schema <tool>` 查权威入参;
  196. 编码类参数(storeCode、餐品编码、couponId)必须原样透传前序工具返回值。
  197. **Q5:optimizer 估算模式和 `--mcp` 有什么区别?** 估算模式本地计算、标注「未经验证」,
  198. 仅用于快速比较;`--mcp` 模式逐方案走官方 calculate-price(含配送费与叠加规则),
  199. 结果才能作为下单依据。
  200. **Q6:比价数据从哪来?** 美团/抖音无公开 API,券信息手动录入本地券库,结果为估算;
  201. 外部数据源可用 `--provider <模块路径>` 显式接入(该 .py 会在本机执行)。
  202. **Q7:支持哪些 Agent?** WorkBuddy、Claude Code、Cursor、OpenAI Codex(同一 SKILL.md)。
  203. **Q8:麦当劳 MCP 的使用限制?** 限中国大陆(不含港澳台)、个人非商业用途,
  204. 详见下方免责声明。
  205. 更多排查见 [`references/error-handling.md`](references/error-handling.md)(提 Issue 请勿附 Token)。
  206. ## 更新说明
  207. 当前版本 **v2.6.0**。最近 3 个版本(由 CHANGELOG 自动生成):
  208. <!-- release-highlights:start -->
  209. | 版本 | 亮点 |
  210. |---|---|
  211. | **v2.6.0** | 多单用券排程 `--timeline` |
  212. | **v2.5.2** | README 中英 Release 徽章链接指向不存在的 tag |
  213. | **v2.5.1** | CI 的发布产物校验必然失败 |
  214. <!-- release-highlights:end -->
  215. 完整变更记录见 [CHANGELOG.md](CHANGELOG.md),各版本下载见
  216. [Releases](https://github.com/yuxinlaile/McD-saver/releases)。
  217. ## 反馈与支持
  218. 如有问题或建议,欢迎在 [讨论区留言](https://github.com/yuxinlaile/McD-saver/discussions),
  219. 或按场景选择:🐛 [提交 Bug 报告](https://github.com/yuxinlaile/McD-saver/issues/new?template=bug_report.md) ·
  220. 💡 [提出功能建议](https://github.com/yuxinlaile/McD-saver/issues/new?template=feature_request.md) ·
  221. 🤝 [分享团购券数据](https://github.com/yuxinlaile/McD-saver/discussions)(助力比价库更全)。
  222. 每一条反馈都会认真查看——这也是试算页持续按真实使用场景优化的依据。
  223. ## 参与贡献
  224. 欢迎 Issue / PR / Discussions。动手前请先读 [CONTRIBUTING.md](CONTRIBUTING.md)(开发环境、分支与提交规范、
  225. 发版流程),并遵守[贡献者行为准则](CODE_OF_CONDUCT.md)。
  226. | 你可以做什么 | 从这里开始 |
  227. |---|---|
  228. | **报 Bug** | [提交 Bug 报告](https://github.com/yuxinlaile/McD-saver/issues/new?template=bug_report.md)——附复现命令与 `--verbose` 输出(**请勿粘贴 Token**) |
  229. | **提需求** | [提交功能请求](https://github.com/yuxinlaile/McD-saver/issues/new?template=feature_request.md) |
  230. | **改代码** | 认领 Issue → 从 `main` 拉分支 → 按 [PR 模板](.github/PULL_REQUEST_TEMPLATE.md) 填写 → 提交前跑 `python -m pytest tests/` |
  231. | **补文档 / 算例** | `references/workflows.md` 补场景、`examples/` 补离线算例;中英校对后跑 `python scripts/check_toc.py` |
  232. **提交前自查**:`python -m pytest tests/` 全过 · 无 Token 等敏感信息 · `references/` 与
  233. `SKILL.md` 同步 · CHANGELOG 补条目 · **README 中英同步**。
  234. 真实运行留档见 [examples/verified-run.md](examples/verified-run.md);离线算例见
  235. [examples/three-ways.md](examples/three-ways.md)(一单三种买法)与
  236. [examples/silent-cost-example.md](examples/silent-cost-example.md)(沉默成本体检读法)。
  237. ## 免责声明
  238. 本项目为**社区开源项目,与麦当劳公司及其关联方无任何隶属、合作或背书关系**。
  239. 使用麦当劳 MCP 服务须遵守麦当劳中国《使用条款》及《麦当劳 MCP 服务规则》,
  240. 仅限**中国大陆地区(不含港澳台)**、**个人非商业用途**;省钱明细来自官方工具
  241. 实际返回值,不构成价格承诺。"McDonald's"、"麦当劳"、"麦乐送"、"麦麦"等商标
  242. 权利归属麦当劳公司。
  243. ## 许可证
  244. 本项目代码以 [MIT](LICENSE) 许可证发布;运行依赖麦当劳中国 MCP 服务及上游
  245. 集成指南仓库([M-China/mcd-mcp-server](https://github.com/M-China/mcd-mcp-server)),
  246. 相关使用须遵守其服务条款与上游限制。
  247. ## Star History
  248. 觉得有用的话,点个 ⭐ 让更多人看到:
  249. <div align="center">
  250. [![Star History Chart](https://api.star-history.com/svg?repos=yuxinlaile/McD-saver&type=Date)](https://star-history.com/#yuxinlaile/McD-saver&Date)
  251. > 曲线由 star-history.com 渲染:对方服务端定期抓取并缓存数据,可能比顶部的实时星数徽章
  252. > 滞后数小时到一天,**当前星数以顶部 Stars 徽章为准**。
  253. </div>
  254. ---
  255. <details><summary>🔍 搜索关键词</summary>
  256. <br>
  257. 麦当劳省钱 优惠券管理 团购比价 美团抖音券 积分价值 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
  258. </details>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.