跳到主要内容
AI教程

M餐搭子教程：用实时菜单、预算与营养目标生成三套麦当劳搭餐方案

本教程介绍如何安装和运行 M餐搭子，配置麦当劳 MCP Token，并根据门店菜单、预算、热量上限和蛋白质目标生成三套可执行方案，同时讲解演示模式、Docker 部署、测试检查与安全实践。

AI我搜编辑部阅读约 10 分钟
M餐搭子教程：用实时菜单、预算与营养目标生成三套麦当劳搭餐方案

M餐搭子是什么

M餐搭子是一个基于麦当劳 MCP 数据的智能搭餐 Skill。你只需输入城市、地标、预算、热量上限和蛋白质目标，它就会查询附近可自取门店，将当前菜单与营养数据对齐，并输出三套可执行的搭餐组合。

与只推荐单个商品的工具不同，M餐搭子会展示每套组合的价格、热量、蛋白质、预算使用情况、热量余量和推荐理由。它还允许用户展开 MCP 调用链，查看各个 Tool 的状态与耗时。

项目参加 2026 麦当劳程序员创意开发大赛，但它并非麦当劳官方产品。餐品供应、价格和活动应以麦当劳官方渠道的实际信息为准，输出也不构成医疗或营养方面的专业建议。

M餐搭子桌面预览

项目解决了什么问题

点餐困难通常不是因为缺少选项，而是因为菜单、营养信息、优惠和个人目标分散在不同位置。用户既要控制预算和热量，又可能希望增加蛋白质，最后还要判断组合是否完整。

M餐搭子的思路是先让用户定义这一餐的边界，再从真实菜单中计算结果，而不是让用户提前决定具体商品。它将菜单价格、营养数据和优惠信息整合到同一个工作台中，使推荐过程更容易理解和验证。

核心能力

  • 实时门店查询：通过 query-nearby-stores，按照城市和地标查找附近可自取门店。
  • 实时菜单读取：通过 query-meals 获取当前门店的价格、原价、商品图片和标签。
  • 营养匹配：使用 list-nutrition-foods 将菜单商品与热量、蛋白质数据对齐。
  • 三套搭餐结果：分别返回“均衡首选”“蛋白加码”和“省心搭”，避免只给出一个黑盒答案。
  • 可解释指标：展示每元蛋白质、预算使用、热量余量以及优惠差额。
  • 优惠与活动：调用 available-coupons 和 campaign-calendar，集中展示可领取优惠券与近期活动。
  • 调用可追溯：用户可以查看 MCP Tool 的调用状态和耗时。
  • 安全降级：没有配置 Token 或 Tool 暂时不可用时，系统会使用明确标记的脱敏演示快照。

运行前的准备

实时 MCP 版本需要在本地运行仓库内的 Node 服务。开始之前，请准备以下环境：

  • Node.js 20 或更高版本
  • npm 10 或更高版本
  • 一个麦当劳 MCP Token；如果只体验演示数据，则可以不提供

如果暂时不想安装，也可以访问GitHub Pages 在线演示。该版本是纯前端演示，支持完整的条件调整与搭餐计算，但使用的是脱敏菜单快照，而不是实时 MCP 数据。

安装与配置

第一步：克隆并安装依赖

在终端中执行以下命令。请将仓库地址占位符替换为实际地址：

git clone <your-repository-url>
cd mcd-meal-mate
npm install
cp .env.example .env

第二步：配置环境变量

打开项目根目录中的 .env 文件，写入 MCP Token 和服务端口：

MCD_MCP_TOKEN=YOUR_MCD_MCP_TOKEN
PORT=8787
  • MCD_MCP_TOKEN不是强制变量。配置后启用实时 MCP；不配置则使用演示数据。
  • PORT不是强制变量，默认值为 8787。

MCP Token 只应放在服务端环境变量中，不要写进前端代码，也不要提交到公开仓库。

第三步：启动开发环境

npm run dev

启动后，在浏览器中访问 http://localhost:5173。开发命令会运行 Express API，并启用 Vite 热更新，适合调试界面和服务端逻辑。

不配置 Token 的演示模式

如果没有麦当劳 MCP Token，可以构建并启动生产版本：

npm install
npm run build
npm start

然后访问 http://localhost:8787。此时页面会明确显示“演示数据”，菜单、价格和活动来自脱敏快照。

演示模式适合检查交互流程、输入约束和三套搭餐结果，但不能代表当前门店的实时供应、价格或活动。实际使用时应以目标门店返回的数据为准。

基本使用：生成三套搭餐方案

第一步：选择偏好

进入工作台后，可以先选择“均衡”等偏好。偏好会参与组合评分，但结果仍会受到预算、热量和蛋白质目标约束。

第二步：填写用餐条件

可以从下面这组示例条件开始：

城市：上海市
商圈 / 地标：人民广场
预算：35 元
热量上限：700 kcal
蛋白目标：35 g

第三步：查看计算结果

服务端会查找附近门店，读取菜单和营养数据，再返回三类方案：

  1. 方案 A：均衡首选。在预算和热量限制内提供主食与小食或饮品，并展示蛋白质、每元蛋白质和推荐理由。
  2. 方案 B：蛋白加码。优先提升蛋白质，同时尽量守住预算和热量限制。
  3. 方案 C：省心搭。提供价格更低但仍然完整的组合，适合更重视成本和选择效率的场景。

比较方案时，不要只看总蛋白质。还可以结合每元蛋白质、预算剩余、热量余量和优惠差额，判断哪个结果更符合当前需求。

第四步：检查 MCP 调用链

展开“MCP 调用链”，可以看到门店、菜单、营养、优惠和活动等 Tool 的状态与耗时。这有助于判断推荐是基于实时返回数据，还是因为 Token 缺失或 Tool 不可用而切换到了演示快照。

常用开发命令

  • npm run dev：启动 Express API 与 Vite 热更新。
  • npm run build：构建前端并编译服务端。
  • npm start：启动生产服务。
  • npm test：运行组合逻辑与营养解析测试。
  • npm run check：依次执行类型检查、服务端编译检查和测试。

在修改营养解析、菜单映射或搭餐规则之后，建议至少执行：

npm test
npm run check

这样可以尽早发现类型错误、编译问题，以及组合约束或营养解析方面的回归。

使用 Docker 部署

项目提供 Docker 构建方式。首先创建镜像：

docker build -t mcd-meal-mate .

然后将本机的 8787 端口映射到容器，并通过环境变量传入 Token：

docker run --rm -p 8787:8787 \
  -e MCD_MCP_TOKEN="YOUR_MCD_MCP_TOKEN" \
  mcd-meal-mate

容器启动后可访问 http://localhost:8787。如果省略 MCD_MCP_TOKEN，应用会使用演示数据。

理解项目结构

项目将 React 前端、Express 服务、MCP 调用、营养解析和组合规划拆分为不同模块：

src/
  App.tsx          React 工作台与响应式交互
  styles.css       编辑部菜单 × 小票视觉系统
server/
  index.ts         Express API、输入校验与静态资源
  mcp.ts           MCP JSON-RPC 客户端、Tool 编排与降级
  nutrition.ts     营养文本解析、菜单映射与商品角色识别
  planner.ts       组合约束、偏好评分与三方案选择
  demo-data.ts     脱敏演示快照
  planner.test.ts  营养与组合测试
shared/
  types.ts         前后端共享类型

server/mcp.ts负责 MCP JSON-RPC 通信、Tool 编排和失败降级；server/nutrition.ts处理营养文本与菜单商品的映射；server/planner.ts执行组合约束、偏好评分和三方案选择。前后端通用数据结构位于 shared/types.ts。

后端使用原生 fetch 与麦当劳 MCP Streamable HTTP Server 通信。生产构建中，同一个 Express 进程同时提供 API 和静态页面，并在内存中缓存菜单与营养结果。

进阶使用与开发建议

优先从约束条件排查结果

如果没有得到预期组合，可以先检查预算、热量上限和蛋白质目标是否过于严格。搭餐器需要同时满足多项边界，目标之间可能发生冲突。适当增加预算、提高热量上限或降低蛋白质目标，有助于获得更多可行组合。

区分实时数据与演示快照

调试时应确认页面是否显示“演示数据”，并查看 MCP 调用链。没有 Token、Tool 暂时不可用或运行纯前端 GitHub Pages 版本时，结果都可能来自脱敏快照。

保护服务端凭据

不要将 Token 注入浏览器端。项目已经通过 Express 服务读取环境变量，并由服务端调用 MCP，从架构上避免将 Token 暴露给前端。部署到服务器或容器时，也应通过安全的环境变量管理方式注入凭据。

修改规划逻辑后运行完整检查

如果调整了 planner.ts、nutrition.ts 或共享类型，应使用 npm run check进行类型、编译和测试检查。项目已有组合与营养解析测试，可以帮助验证修改是否影响已有行为。

查阅集成资料

仓库中的 MCP_INTEGRATION.md记录了完整 Tool、调用流程、业务价值和安全边界；mcp-config.example.json提供脱敏配置示例；workbuddy.md包含 WorkBuddy 联动上下文和可复现指令。接入其他 Agent 或 Skill 时，可以优先参考这些文件。

安全边界

  • 仓库不包含真实 Token、密码或账号凭据。
  • MCP Token 只从服务端环境变量读取。
  • 项目不调用下单、支付、抽奖或积分兑换 Tool。
  • 服务端不保存用户输入，也不建立用户画像。
  • 餐品供应、价格和活动以麦当劳官方渠道为准。
  • 推荐结果不构成医疗、营养或其他专业建议。

总结

M餐搭子把门店查询、实时菜单、营养匹配、优惠信息和组合规划整合为一个可解释的搭餐流程。配置 MCP Token 后，它可以使用当前门店数据；没有 Token 时，也能通过脱敏快照体验完整交互。

完成安装后，可以先用示例条件验证三套方案，再通过 MCP 调用链确认数据来源。开发者则可以从 mcp.ts、nutrition.ts和 planner.ts入手，理解实时数据编排、营养映射与约束计算的实现方式。