jumpersun / meal-puzzle

真实菜单 · 官方核价 · 按人分餐 
一起吃麦当劳，有人想喝咖啡，有人想吃汉堡，还有人只想分一份薯条。套餐拼图支持先说每个人的心愿，让系统推荐；也支持先挑套餐和单品，再分给大家。两种玩法都使用门店真实菜单，调用麦当劳 MCP 核清价格，最后得到一张清楚的餐单。
适合 **1–6 位朋友、同事或家人**一起商量到店自取餐单：一人操作，大家一起选。
两种玩法 · 真实案例 · 本地运行 · MCP 接入 · 参赛记录
## 两种玩法，一张餐桌
| 首页入口 | 适合什么情况 | 怎么走 |
| --- | --- | --- |
| **帮我们拼一桌** | 大家知道想吃什么，还没决定买哪些套餐 | 选门店 → 按人填心愿与可选预算 → 比较最多 3 个已核价方案 → 自动分到餐盘 |
| **我来挑，大家分** | 已经有喜欢的套餐或单品 | 选门店 → 直接挑餐品、换搭配 → 点“选好了，分给大家” → 分到餐盘 |
进入餐桌后，都可以点餐品改归属、换套餐搭配，再复制或下载带门店、选配、核价时间和优惠条件的清单。“待分配”表示还没安排，“大家一起吃”表示有意共享。
切换玩法保留已选餐品、分配和仍有效的报价；换搭配后重新核价，未变餐品保留归属。用推荐方案替换已有餐桌前，会先提示确认。
## 两条真实流程
以下为 **2026-10-14 上海黄浦华旭国际大厦餐厅**的验收快照：通过本地页面连接真实 MCP，当前菜单包含 115 款餐品。
| 流程 | 这次怎么选 | 换搭配与核价结果 |
| --- | --- | --- |
| **先说心愿** | 阿橙要鸡肉堡、薯条、咖啡；小蓝要牛肉堡、可乐；小满要麦乐鸡、薯条 | 三桌方案分别为 **¥79.40 / ¥91.00 / ¥96.50**，均满足 **7/7 份心愿**。选第一桌后，将汉堡包换成吉士汉堡包，重新核价 **¥80.40** |
| **先挑餐品** | 选开心亲子双人餐，把汉堡和可乐分别分给两人，其余 6 份留作“大家一起吃” | 原核价 **¥59.50**；将可乐换成冰美式后重新核价 **¥68.50**，未变餐品的归属保留 |
两条流程都完成了选餐、分配、换搭配、重新核价和分享清单检查，也验证了中途切换玩法保留餐桌。餐品和价格随门店、时段及权益变化；完整过程和早餐案例见验收记录。
## 立即在本地使用
准备 **Node.js 22+**。项目无第三方运行依赖，无需 `npm install`。
 [code] 
按官方 MCP 接入指引申请 Token，在本机 `.env` 的 `MCD_MCP_TOKEN=` 后填入并保存，然后启动：
 [code] 
打开 **http://127.0.0.1:4317**，从首页选择一种玩法：
- **先试推荐**：点“帮我们拼一桌” → 选餐厅 → “填入示例心愿” → “看看怎么拼”。示例会根据当前早餐或非早餐菜单切换。
- **直接选餐**：点“我来挑，大家分” → 选餐厅 → 挑套餐或单品 → “选好了，分给大家”。
Token 仅由服务端读取，`.env` 已被 Git 忽略。默认位置为可修改的“上海人民广场”；端口占用时可用 `PORT=4318 npm start`。
**无 Token 体验：** 保留 `.env` 中的空值，启动后打开趣味演示，体验拼餐、分餐和清单交互。演示使用虚构菜单与示例价格，真实菜单和官方核价需配置 Token。
## 怎么把这桌拼出来
前端收集心愿或用户自选的餐品，服务端通过四个麦当劳 MCP 工具获取真实数据：
| 环节 | MCP Tool | 用途 |
| --- | --- | --- |
| 找餐厅 | `query-nearby-stores` | 查询附近门店 |
| 看菜单 | `query-meals` | 获取当前餐品、商品图、展示价与优惠标记 |
| 选搭配 | `query-meal-detail` | 读取套餐选项、默认搭配与数量规则 |
| 核价格 | `calculate-price` | 获取整桌实际报价 |
心愿模式下，规划器最多读取 20 款相关产品的详情，综合套餐各组的可换选项与可增选份数，组合候选并核价；最多尝试 6 个候选，成功核价 3 个后停止，再按**心愿满足度、实际总价、额外份数**排序。组合与分配由 JavaScript 完成，无需额外大模型或提示词。自选模式直接读取菜单和搭配，选好后使用同一套核价与分餐逻辑。
菜单中的购卡条件价、促销标记与本次核价分别展示，方便判断优惠是否适用于这一桌。商品图片按官方编码对应，缺图时显示“暂无图片”。调用流程、参数校验与部署要求见 MCP_INTEGRATION.md。
## 使用说明
- **心愿范围**：支持鸡肉堡/卷、牛肉堡、薯条、麦乐鸡、可乐、咖啡、早餐堡/卷、薯饼、粥，共 9 类；每人每类最多 3 份，整桌最多 18 份。具体品名、冷热与杯型可在方案详情确认。
- **预算与选方案**：预算用于显示余量或超出金额，缺少和多出的餐品会明确列出。推荐来自有限候选范围，不保证全菜单最低价。
- **价格有效期**：改餐、换门店或刷新菜单后需重新核价。报价快照展示 2 分钟，到期隐藏金额并提示刷新；该时长为应用展示规则。
- **使用方式**：由一人在本机操作和记录餐盘确认，刷新页面会清空当前餐桌。支持到店自取餐单整理，采用门店默认特调；下单与支付需在官方渠道完成。
## 开发与验证
原生 JavaScript 前端 + Node.js 服务端，另提供 Worker 适配层。
| 代码 | 职责 |
| --- | --- |
| `public/journey.js` | 两个入口、步骤切换与下一步操作 |
| `public/wish-planner.js` | 心愿匹配、候选生成、按人分餐 |
| `public/wishes.js` / `public/live.js` | 心愿与方案界面、菜单、换搭配、餐单分享 |
| `public/live-state.js` | 共用餐单、报价有效性与分享清单 |
| `server/api.mjs` | MCP 会话、参数校验、候选核价与整单核价 |
| `server.mjs` / `worker/index.js` | 本地服务与 Worker 运行入口 |
 [code] 
本次上述 **42 项测试通过**，并完成内置浏览器连接真实 MCP 的两条流程验收及 390×844 手机布局检查。更多请求生命周期、图片与 CSP 回归位于 tests/；验证范围与部署记录见 docs/VERIFICATION.md。
## 文档与参赛
- MCP 接入说明与脱敏配置示例
- 参赛提交材料与演示脚本
- 官方参赛声明
- 参赛 Issue #592与官方成功确认
本项目为独立参赛作品，非麦当劳官方产品。原创代码采用 MIT License；商品图片、商标及官方声明的权利范围见素材说明。