项目简介
麦麦省钱助手（mcd-coupon-strategist）是一款基于麦当劳中国 MCP 构建的点餐成本助手。它不仅回答“这一单怎么点最省”，还会分析历史订单与优惠券库存，告诉你有哪些即将过期的优惠正在变成实际损失。
项目将省钱问题拆成两条链路：
- 短期优化：读取当前门店菜单和账户可用券，枚举单品、套餐、用券及凑单方案，再通过
calculate-price逐一获得真实价格。 - 长期审计：通过
order-list与query-my-coupons分析支出、客单价、高频商品和即将过期的券。
项目的核心视角不是单纯帮助用户继续消费，而是先找出正在发生的损失。
核心功能与工作原理
基于当前门店的真实计价
不同门店的价格和供应状态可能不同，因此项目不会写死菜单价格。候选方案最终都交给 MCP 的 calculate-price 计价，而不是让模型猜测金额。
输出不仅包含最低实付，还会解释价差来自套餐结构、优惠券还是凑单商品。例如，三件套可能比单点汉堡和薯条两件商品更便宜，这种情况下系统会明确推荐套餐，并说明省下多少钱。
识别凑单陷阱
优惠券不一定用了就更省。假设原计划购买的商品为 46.5 元，为使用“满 50 减 12”而增加 3.5 元商品，用券后实付为 38 元；如果同类套餐只需 33.5 元，那么凑单方案仍然贵 4.5 元。
项目会比较最终实付，而不是只看优惠券标注的减免额。除非凑单商品本来就是用户需要的，否则会主动劝退这种方案。
计算优惠券的沉默成本
“券的沉默成本”是即将过期但尚未使用的优惠价值。由于 MCP 返回的券可能只有名称，项目会结合当前门店菜单反查其价值：
- 满减券：“满 50 减 12”直接按 12 元计算。
- 买一送一券：“中薯条买一送一”按对应商品的菜单单价计算。
- 固定价券：“9.9 元中杯冰美式”按菜单原价减去 9.9 元计算。
如果菜单中找不到对应商品，项目会将券价值记为 0，并在报告中标注。它不会填入一个看似合理但没有依据的估算值。
分析长期消费习惯
审计模块可以从历史订单中汇总订单数、总支出、客单价和高频单品，并给出结构性建议。例如，如果多次单点同一种汉堡，系统可能提示对比对应套餐，因为每次改为套餐通常可能减少支出。整单退款会被过滤，避免将退款订单计入消费。
准备工作
使用在线 MCP 功能前，需要准备以下环境：
- 支持 MCP 自定义连接器的客户端，例如 README 中演示的 WorkBuddy。
- 从麦当劳 MCP 开放平台申请的 Token。
- 如果需要运行本地测试，则准备 Python 3.8 或更高版本。
本地四套测试不需要 MCP Token；但查询真实菜单、账户优惠券和历史订单时需要有效 Token。
申请并配置 MCP Token
第一步：申请 Token
访问麦当劳 MCP 开放平台，使用手机号登录，在控制台激活并复制 MCP Token。
第二步：创建 MCP 配置
仓库提供了脱敏配置文件 mcp-config.example.json。配置结构如下：
{
"mcpServers": {
"mcd-mcp": {
"type": "streamablehttp",
"url": "https://mcp.mcd.cn",
"headers": {
"Authorization": "Bearer ${MCD_MCP_TOKEN}"
}
}
}
}将 ${MCD_MCP_TOKEN} 替换为自己的 Token，然后写入 MCP Client 配置。不要把真实 Token 提交到公开仓库，也不要在截图、日志或问题反馈中暴露它。
第三步：在 WorkBuddy 中启用
- 打开 WorkBuddy，在左侧进入“专家、技能、连接器”，选择“连接器”页签。
- 点击“自定义连接器”，再选择“配置 MCP”。
- 粘贴替换过 Token 的 JSON 配置并保存。
- 返回自定义连接器列表，将
mcd-mcp设置为启用。
基本使用方法
示例一：按预算寻找组合
先选定门店，再清楚说明预算、需要的餐品类型和比较数量。可以直接发送：
我在麦当劳点外卖，门店选好之后帮我算一下：
我手里有券，想吃一个汉堡 + 一份薯条 + 一杯饮料，预算 40 元，
怎么点最省钱？给我两个方案对比。助手会读取当前门店菜单与可用券，生成候选组合，并使用 MCP 真实计价。一个典型结果可能是推荐 33.5 元的麦辣鸡腿堡三件套，并将其与 37 元的汉堡加薯条单点方案比较。
示例二：限制主食和配餐
预算 35 元，想吃鸡类主食和一个配餐。
请查询当前门店可售商品，给出推荐、备选和不推荐方案，
并说明每个方案为什么更省或更贵。这类提示能让助手同时考虑预算、饱腹需求和商品类别，避免只推荐绝对价格最低但不满足需求的选项。
示例三：判断是否值得凑单
我有一张“满 50 减 12”的券。
请按当前购物需求比较直接购买、凑单用券和改买套餐的最终实付，
如果凑单反而更贵，请明确提醒我。比较时应重点看最终实付，而不是券面减免额。项目会把新增商品成本纳入计算，并指出套餐是否比凑单更划算。
示例四：审计近期消费
请分析我最近几个月的麦当劳订单：
统计订单数、总支出和客单价，找出高频商品；
同时列出即将过期的优惠券、预计价值和剩余天数，
最后告诉我本月最应该先处理什么。这会触发长期审计链路。输出重点包括即将过期券的总价值、消费习惯以及可以执行的结构性建议，而不只是某一单的最低价格。
运行本地测试
取得项目源码后，在仓库根目录使用 Python 3.8 或更高版本运行以下测试：
python src/test_saver.py
python src/test_auditor.py
python src/test_adapter.py
python src/test_order_adapter.pytest_saver.py：验证方案枚举、排序和凑单陷阱识别。test_auditor.py：验证沉默成本、消费习惯和日期临界值。test_adapter.py：验证单位换算与 MCP 响应解析。test_order_adapter.py：验证订单、优惠券解析、退款过滤和券价值推算。
这四套测试均为纯本地运行，不需要配置 MCP Token。README 未列出额外的软件包安装命令，因此应以仓库中的实际代码和集成文档为准。
理解项目架构
项目通过适配层将 MCP 原始响应和业务算法隔离，主要模块如下：
src/saver.py：负责单次省钱链路，枚举候选组合并比较真实实付。src/auditor.py：负责长期审计，计算优惠券沉默成本并生成消费画像。src/mcd_adapter.py：负责字段映射、退款过滤、券价值反查，以及唯一一次“分到元”的换算。MCP_INTEGRATION.md：记录 MCP Server、工具、调用流程和实测调用契约。SKILL.md：描述 Skill 定义及整体工作流。
算法层不直接接触原始 MCP 响应，有助于避免字段差异和金额单位混乱。尤其需要注意，不同接口可能存在“分”和“元”方向不一致的问题，应统一通过适配层处理。
进阶使用技巧
先明确“吃什么”，再比较价格
最低价格不一定是合适方案。提示词中应写明主食、配餐、饮料、人数、预算和最低需求，让系统在满足同等需求的方案之间比较。
要求展示省钱归因
可以要求输出“使用了哪张券、换成了什么套餐、增加了什么凑单品，以及相对基准方案节省多少”。这样不仅得到结论，也能判断推荐是否符合自己的真实需求。
区分券面价值与实际收益
一张券理论上值 12 元，不代表当前订单一定能省 12 元。门槛、适用门店、可用商品和凑单成本都会改变实际收益。应同时查看券面价值和最终实付。
优先处理临近过期且价值明确的券
长期审计时，可以按剩余天数和可确认价值排序。菜单中无法反查原价的券应继续标记为未知或 0，不应为了形成完整报告而猜测金额。
每次都使用当前门店数据
不要复用其他门店或历史订单中的价格。菜单、供应状态和券适用范围可能变化，每次决策都应以当前门店的官方实时结果为准。
保护账户凭据
建议始终使用环境变量或客户端安全配置保存 Token。公开分享配置时，只保留 ${MCD_MCP_TOKEN} 之类的占位符。
设计边界与注意事项
- 所有价格应以 MCP
calculate-price的实际返回为准。 - 无法从菜单确认的券价值按 0 处理并标注，不进行推测。
- 退款订单不计入消费支出。
- 项目不会为了使用优惠券而鼓励不必要的加购。
- 餐品、价格、供应状态和优惠券适用范围以麦当劳官方渠道实时结果为准。
- 该项目是独立开发的比赛作品，并非麦当劳官方产品。
- 输出仅供消费决策参考，不构成医疗、营养或其他专业建议。
总结
麦麦省钱助手把实时点餐优化与长期消费审计结合起来：短期通过真实计价选择套餐、单品和优惠券组合，长期则通过订单与券库存发现客单价偏高、重复单点和优惠券过期等隐性损失。
完成 MCP Token 配置后，可以先从一条带有预算和餐品需求的点餐请求开始，再逐步尝试凑单比较和月度消费审计。对于开发者，saver.py、auditor.py 与 mcd_adapter.py 的分层也提供了一个清晰的双链路 MCP 编排参考。