🍔 麦麦省钱点单助手 · mcd-savings-assistant

会算账的麦当劳点单专家：一键领券 · 自动用最优券 · 智能搭配 · 省钱榜单 · 卡路里可视 · 附近门店导航 · DIY 自由搭 · 一键下单

基于 麦当劳中国 MCP（https://mcp.mcd.cn）能力开发的可交互可视化 Skill。
它不只是一个聊天机器人——它会把 MCP 返回的真实菜单、优惠券、营养与门店数据，渲染成一个可点击、可勾选、实时算价算热量的 HTML 可视化点单助手。

✨ 核心能力

一切数据来自 MCP 实时返回，零编造。

🎯 目标用户

一句话：给「想吃麦当劳但不想多花钱、也不想动脑算」的人，一个会算账的点单助手。

🎨 视觉与交互

方向：Retro-futuristic Terminal HUD（复古未来 / 终端风）

• 配色：近黑蓝底 #070B10（60%）+ 表面层 #0E141C（30%）+ 麦当劳黄 #FFC72C 作唯一强调色（10%）；青色 #00E5FF 专用于数据读数，红色 #FF5A5A 仅用于告警。
• 字体：Space Mono（展示字，等宽终端感）+ JetBrains Mono（等宽数字 tabular-nums）+ Noto Sans SC（中文正文）。
• CSS 3D：perspective + transform-style: preserve-3d，卡片悬停沿 X/Y 轴倾斜、按下物理回弹，祝福卡 rotateY(180deg) 翻转。
• 氛围层：四层叠加——网格底纹 + 径向霓虹光晕 + CRT 扫描线 + 暗角。
• 入场编排：一次性错峰揭示序列（3–6 组，间隔 90ms），而非零散微交互。

交互约定：

⚠️ 数据口径说明：麦当劳 MCP 的 list-nutrition-foods 只覆盖约 158 种常见餐品，新品/组合餐（如「龙焰芝士棒鸡腿堡」「奶香大米派」「BFF 四宫格小食盘」）无官方热量数据。匹配分三档，页面如实标注——不编造任何营养数据：

档位	规则	页面显示	实测数量
精确	名称归一化后完全一致/互相包含	🔥 391 kcal	53 / 100
近似匹配	先做规格归一（去掉「中杯/大杯/热/冰/™」），仍不中再用 2-gram 相似度 ≥ 0.45 兜底（如「灰焰圆筒」→「圆筒冰淇淋」）	🔥 ≈93 kcal	7 / 100
未匹配	三档皆不中	热量待核	40 / 100

💡 「原价 / 立省 / 应付」的口径（页面底部 HUD 与省钱榜单同一套算法）：
原价 = MCP 返回的划线原价（origin，没有划线价时用现价）；
应付 = 现价合计 − 券抵扣 + 配送费；
立省 = 原价 − 实付商品金额，同时包含官方直降与券（所以套餐类商品的立省会明显大于券面额）。
券的面额由券 Title 解析，是预估值，最终以 calculate-price 核价为准。

🚀 安装与使用（3 步）

第 1 步：申请 MCP Token

1. 打开 https://open.mcd.cn/mcp ，点击右上角【登录】
2. 使用手机号验证码登录
3. 点击右上角【控制台】→【激活】，申请 MCP Token
4. 同意服务协议后即可一键复制 Token

第 2 步：配置 MCP 连接器

在任意支持 Streamable HTTP 的 MCP Client（推荐 WorkBuddy、Cursor、Cherry Studio、Trae）中填入：

{
  "mcpServers": {
    "mcd-mcp": {
      "type": "streamablehttp",
      "url": "https://mcp.mcd.cn",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

⚠️ 记得把 YOUR_MCP_TOKEN 替换为你的真实 Token，并妥善保管，切勿提交到任何仓库。

第 3 步：安装 Skill 并说话

把本仓库 SKILL.md 放入你的 Skill 目录，然后直接说：

📁 项目结构

mcd-savings-skill/
├── SKILL.md                     # Skill 主文件（触发词 + 九阶段工作流 + 35 Tool 速查）
├── README.md                    # 本文件
├── CONTEST_DECLARATION.md       # 参赛声明（官方文件，内容未改动）
├── MCP_INTEGRATION.md           # MCP 集成说明（Server / Tools / 流程 / 价值）
├── mcp-config.example.json      # 脱敏 MCP 配置示例（仅环境变量占位符）
├── workbuddy.md                 # WorkBuddy 开发对话上下文（专项奖必需）
├── ROADMAP.md                   # 待办节点与迭代计划
├── CONTEST_SUBMIT.md            # 参赛提交状态与操作手册
├── .gitignore                   # 排除 .env / *.token / __pycache__ 等
├── assets/
│   ├── order-assistant.html     # 可视化交互点单页（券开关/热量条/DIY勾选/门店导航）
│   └── data.js                  # MCP 真实数据快照（由 build_data.py 生成）
└── scripts/
    ├── build_data.py            # MCP 数据管道（门店/菜单/券/营养/活动/订单）
    ├── mcp_call.sh              # 命令行调任意 MCP Tool
    └── push_to_github.sh        # 一键推送（含密钥扫描）

🏗️ 技术实现

• Skill 层：SKILL.md 定义触发词与九阶段工作流（定位 → 领券 → 菜单/营养取数 → 场景搭配 → 省钱榜单 → 提醒 → 拼单 → 下单 → 商城订单），约束模型必须真实调用 MCP、禁止臆造数据。
• 数据层：每次会话拉取一次 query-meals + list-nutrition-foods，合并为本地缓存映射。
• 推荐算法：预算/热量约束下的组合枚举（贪心 + 剪枝），本地初筛后仅对 Top 3 调用 calculate-price 精算，单次会话 MCP 调用 < 10 次，规避 600 次/分钟限流。
• 省钱榜单算法：build_savings() 用「现价 / 划线原价 / 券规则」三件套枚举主餐 × 饮品（× 小食），
  逐条套最优券后按 5 个维度排序；券规则统一解析为可计算对象（满减 / 折扣 / 直减 / 特价 N 元购 / N 元任选 M 件 / 免费换购），
  解析不出来的（如买一送一）宁可不进榜。支持 build_data.py --rank 离线重算，不联网、不产生编造数据。
• 可视化层：单页 HTML，纯原生 JS 实现状态驱动渲染——选品、券开关、模式切换、门店选择全部实时联动「原价 / 立省 / 应付 / 总热量」。
• 闭环：用户确认 → create-order → 麦当劳官方支付链接（本项目不接触任何支付信息）。

⚠️ 免责声明

• 本项目为「麦当劳程序员创意开发大赛」参赛作品，由参赛者独立开发，非麦当劳官方产品；
• 营养数据来自麦当劳 MCP，仅供参考，不构成医疗或营养建议；
• 餐品信息、价格及供应状态以麦当劳官方渠道的实时结果为准；
• 使用麦当劳 MCP 服务须遵守《麦当劳 MCP 服务规则》及《使用条款》。

© 2026 McDonald's. All Rights Reserved. 本项目仅用于参赛与技术交流。