内容
# 麦麦轻松点 McEasy
**想吃什么，慢慢选。**
把麦当劳官方实时菜单变成看得清、选得明白的大字菜单。用编号表达想吃的餐品，核对份数与预算，再把一张大字沟通卡交给店员看。
面向长辈、偏好文字沟通的用户，以及希望界面更简洁的每一个人。
## 为什么做 McEasy
菜单太密、字太小、套餐组成看不明白，或者现场说不清想吃什么——点餐这件小事，也可能需要一些帮助。
McEasy 以 **易读与沟通** 为核心：一次展示 6 个选项，编号不随翻页变化；一份一份调整数量；用官方工具核对金额；生成能展示、打印的大字清单。让用户按自己的节奏完成选择。
## 功能
- **大字菜单**：响应式界面、大字切换、高对比、键盘操作、屏幕阅读器标签。本机有中文语音时可朗读当前页；没有本机语音时给出明确提示。
- **真实供应**：官方门店搜索与即时到店自取菜单，保留官方餐品名称，支持分类、名称搜索与分页。
- **稳定编号**：每个菜单快照内唯一编号；筛选、翻页后，编号仍对应同一餐品。
- **默认搭配看得明白**：读取套餐默认组成；缺少默认搭配时停止核价并提示到官方渠道确认。
- **官方核价**：`calculate-price` 返回合计，整数分计算；区别菜单参考价、商品小计与整单优惠；可选预算校验。
- **大字沟通卡**：餐品、份数、默认搭配、门店、核价时间与合计，可直接打印或保存 PDF。明确标注尚未下单。
- **7 个 MCP 工具 + Agent Skill**：可在支持本地 stdio MCP 的客户端中用自然语言完成相同流程。
- **无需 Token 的离线演示**：使用明确标注的合成样例，完整体验选餐与卡片流程。
## 3 分钟开始
需要 **Node.js 22+**。
```bash
git clone https://github.com/wangqifei2/mcd-easy-order.git
cd mcd-easy-order
npm ci
npm run build
npm run web
```
打开 <http://127.0.0.1:3741>。默认进入离线演示，不需要登录或 Token。
也可仅生成一张独立演示卡：
```bash
npm run demo
# 用浏览器打开 output/demo-card.html
```
演示数据不是当前供应或报价。
## 接入真实麦当劳 MCP
1. 在[麦当劳官方开放平台](https://open.mcd.cn/mcp)登录并申请 Token，阅读并同意平台协议。
2. 在项目根目录新建 `.env`，仅在本机填入 `MCD_MCP_TOKEN` 的实际值。`.env` 已被 Git 忽略；不要上传、截图或放入聊天记录。
3. 重新执行 `npm run web`，选择“查询真实门店”，输入城市和公共地点，选择营业门店。
示例配置见 [mcp-config.example.json](mcp-config.example.json)，所有敏感配置仅使用环境变量占位符。不同客户端对 `${VAR}` 的替换支持不同，请用客户端的环境变量/密钥配置能力完成注入；不能直接把未替换的占位符当作 Token。
## 在 Agent 中使用
先完成 `npm ci && npm run build`。配置本地 MCP（`MCEASY_PROJECT_DIR` 指向项目绝对路径），让该进程从客户端环境获取 `MCD_MCP_TOKEN`。客户端也可直接将 `args` 中的路径替换为自己的本地绝对路径。
将 [skills/mcd-easy-order](skills/mcd-easy-order) 文件夹放入客户端支持的 Skill 目录，或在支持导入 Skill 的客户端中选择其 `SKILL.md`。WorkBuddy 可通过自定义 MCP 与技能功能接入；本作品未使用 WorkBuddy 开发，不申请其专项奖励。
自然语言示例：
> 帮我看上海人民广场附近的麦当劳，我想到店。把菜单字放大一些，每次看6个。
> 1号一份、5号两份，预算50元。先告诉我套餐里有什么，再核对金额。
> 帮我做一张给店员看的大字沟通卡，我想打印。
MCP 工具：
| 工具 | 用途 |
|---|---|
| `mceasy_find_stores` | 公共地点搜索门店 |
| `mceasy_open_menu` | 获取实时菜单与 `menu_id` |
| `mceasy_demo_menu` | 获取离线演示菜单 |
| `mceasy_list_menu` | 分类、搜索和稳定编号分页 |
| `mceasy_meal_detail` | 官方详情与默认套餐组成 |
| `mceasy_quote` | 按编号和份数官方核价，返回 `quote_id` |
| `mceasy_render_card` | 从有效核价记录生成独立 HTML 沟通卡 |
MCP 响应同时含文本与结构化 `data`；`response_format` 可选择 `markdown` 或 `json`。菜单与核价记录保存在当前进程内，重启后重新查询。
## 验证
```bash
npm test # 编译 + 18项单元/stdio/Web测试
npm run inspect:official # 使用本机Token读取5个官方工具schema
npm run test:live # 真实公共门店→菜单→单品/套餐→核价→沟通卡
```
- 18 项测试覆盖金额单位、稳定编号、套餐默认搭配、报价缺项/数量不符、过期、HTML 转义、stdio 协议全链路和 Web 跨源防护。
- **2026-10-09 实测**：上海人民广场公共地点，官方门店 `1450713`，读取 **97** 个去重后的菜单餐品，完成单品与套餐的真实核价及卡片生成。结果见 [脱敏验证记录](docs/live-validation.json)。菜单数量与供应会随时间变化。
- [10 个稳定离线评测场景](evals/evaluation.xml) 用于验证 Agent 多步工具使用。它们是评测题与已验证标准答案，不代表已经运行额外模型评测。
## 支持范围
目前支持 **即时到店自取、官方默认搭配、查询/核价/沟通卡**。特调、更换套餐搭配、预约、麦乐送、创建订单和支付请使用官方渠道。工具不会自动领券、兑换积分或修改账户。
菜单 30 分钟、核价 5 分钟过期；修改清单或预算后必须重新核价。官方核价可能含账号专属权益，柜台或其他账号可能不同价；卡片仅供沟通，应在购买时再次确认。
本机 Web 服务仅监听 `127.0.0.1`，Token 留在服务端；拒绝跨源写请求，不加载第三方统计、远程字体或外部脚本。导出卡片仅含选餐所需信息，注意按自己的意愿分享。
## 项目结构
```text
src/ MCP Server、官方客户端、点餐引擎、卡片与Web服务
web/ 大字点餐界面
skills/mcd-easy-order/Agent Skill
test/ 自动化测试
docs/ 界面截图与脱敏真实验证
evals/ 多步工具评测场景
```
## 参赛信息与许可
麦当劳程序员创意开发大赛参赛作品，非麦当劳官方产品。项目说明、声明、接入文档、脱敏配置及源码按官方规范提供。详见 [MCP_INTEGRATION.md](MCP_INTEGRATION.md) 和原样保留的 [CONTEST_DECLARATION.md](CONTEST_DECLARATION.md)。
原创源码采用 [MIT License](LICENSE)。第三方 SDK、官方服务与官方声明分别适用其自身许可及服务规则；本项目许可不授予麦当劳商标、官方资料或服务的权利。
MCP 市场