# 麦当劳 MCP 接入说明

套餐拼图支持“先填心愿找推荐”和“先挑餐品再分餐”两种入口，共用真实餐桌、官方核价与分享清单。真实菜单使用实际 MCP 响应；`/demo.html` 的虚构数据与真实链路分开。

## Server 与认证

- Server：`https://mcp.mcd.cn`
- 传输：Streamable HTTP，JSON-RPC 2.0，支持 JSON/SSE 响应。
- 握手：`initialize` → `notifications/initialized` → `tools/call`，协议版本 `2025-03-26`，保留服务端返回的会话标识。
- 认证：服务端读取 `MCD_MCP_TOKEN`，通过 Bearer 请求头发送。配置样例见 `mcp-config.example.json`，其中只有环境变量占位符。
- 本地实现直接由 `server/api.mjs` 连接 MCP，不要求用户另外启动通用 MCP 客户端。通用客户端是否展开 JSON 中的环境变量取决于客户端；不要把替换成真实凭证的文件提交。

## 实际调用的 Tool

| Tool | 输入与使用场景 | 用户得到什么 |
| --- | --- | --- |
| `query-nearby-stores` | 城市、附近关键词，`searchType: 2`、`beType: 1` | 选择营业中的真实餐厅 |
| `query-meals` | 门店编码、`orderType: 1`、`beType: 1` | 当前到店自取菜单、商品图、展示价及优惠标记 |
| `query-meal-detail` | 门店及餐品编码 | 每组选配的最少/最多数量、可替换餐品及默认特调 |
| `calculate-price` | 服务端重建的 `items`、`roundList` 和默认特调 | 整桌实际核价、行小计及接口返回的优惠金额 |

服务端仅允许以上四个 Tool，不提供任意 MCP 代理，不调用创建订单、支付、购卡、领券等能力。

## 从心愿到餐桌

1. 用户选择餐厅，为 1–6 位搭子填写餐品品类与数量，可填写整桌预算。名字不离开浏览器；规划接口收到匿名人物 ID 与数量。
2. `/api/plans` 重新查询当前菜单，挑选至多 20 款相关单品或套餐读取详情。详情按商品编码去重，最多 4 个并发查询，失效餐品会被跳过并显示提示；同次核价使用同一份商品详情。
3. 共享规划模块按品类匹配选配，构造“单品补齐”“套餐加单品”“重复套餐加单品”等候选。套餐内部每步最多保留 64 个搭配状态，综合考虑各组选项与有助于满足心愿的可增选份数，遵守官方数量限制。鸡肉早餐卷归鸡肉品类，其他可识别早餐堡归早餐品类；这不是配料或过敏原判断。
4. 在满足度、额外份数、参考价之间筛选最多 6 个候选，逐个调用 `calculate-price`；核价失败时尝试备选，成功 3 个后停止。**参考价只参与选候选，页面应付金额只来自官方核价。** 最终按满足度、官方总价、额外份数排序。
5. 方案展示还缺什么、多出什么、预算是否超出、具体杯型/冷热以及优惠条件。预算用于对比，不会为了预算偷偷删掉心愿；搜索有界，不承诺全菜单最优或最低价。
6. 选用方案时按心愿分到餐盘，多出部分留在待分配区，并通过 `/api/quote` 重新读取菜单与详情、再次核价。有已有餐单时，确认替换后才应用新方案。用户可把餐品留作“大家一起吃”，继续换搭配、手动改归属、撤销分配、生成餐单清单。

## 从挑餐品到餐桌

“我来挑，大家分”先通过 `/api/menu` 和 `/api/detail` 展示真实菜单与可选搭配，不要求填写心愿或调用规划接口。选好后进入共用餐桌，点餐品选择饭搭子，也可将剩余餐品一起放入“大家一起吃”。自选模式隐藏心愿满足度。

`public/journey.js` 只负责入口、当前步骤与下一步按钮；餐单、门店、归属和报价由两种流程共用。切换玩法不会清空这桌，也不会重新核价。连续增减份数在停止操作 350 毫秒后合并核价；换搭配后清除旧报价，按最新详情保留有效选项、清理失效项并限制数量，新增组选用门店默认。分享文本区分个人餐品、待分配餐品和共享餐品。

## 核价与图片的可信边界

- 前端不能指定价格、购买权益卡或优惠券参数。服务端验证门店、餐品编码、选配与数量，重建官方参数，并校验返回餐品与金额。
- 购卡条件展示价、促销标记和本次整单核价独立显示；不自动附加 `withOrder` 或指定优惠券。已持有权益的适用结果由官方接口决定。
- 报价绑定门店和餐单版本。改餐、换门店、刷新菜单会使旧价失效；应用展示快照 2 分钟后失效，该时长不是官方锁价承诺。
- 请求失败不会回退为演示价格；未成功核价的候选不允许选用。过期候选隐藏金额并要求重新生成。
- 服务端普通请求总时限为 40 秒，拼餐为 110 秒，每次 MCP 调用仍限 18 秒。请求取消与本机客户端断连会传递到上游；详情查询遇到凭证、限流或协议错误时取消同批任务。
- 真实餐品图使用接口返回的 `menu-img.mcd.cn` HTTPS 地址，按商品编码匹配；缺图或加载失败显示“暂无图片”，不猜图。

## 隐私与部署

本地只监听 `127.0.0.1`；静态目录只开放 `public/`。Token 位于忽略的 `.env` 或服务端运行时 secret。API 限制请求来源、请求体和餐单规模，错误文案不返回上游凭证。

现有 Sites 部署仅站点主人可访问。源码公开不等于共享凭证或公开这个实例；当前没有多租户凭证隔离与公开服务限流。其他开发者按 README 使用自己的 Token 在本地运行。名字、心愿、餐单均不持久化，刷新清空；餐盘确认是本机记录，不是在线多人签认。

## 业务价值与复核入口

“你想咖啡、我想薯条”常常要在单点、套餐和多人分享餐之间反复换算。本项目将这件事拆成可核对的心愿、真实选配、官方总价与实际归属，让用户能看懂为什么这桌适合、还差什么。

相关实现：`public/wish-planner.js`、`public/wishes.js`、`public/live.js`、`server/api.mjs`。自动化验证位于 `tests/planner.test.mjs`、`tests/live.test.mjs`、`tests/request-lifecycle.test.mjs` 和 `tests/selection-recovery.test.mjs`；实际验收记录见 `docs/VERIFICATION.md`。