McButler 教程：用麦当劳 MCP 完成推荐、营养分析、门店比价与团餐配置

McButler 是什么

McButler（麦当劳自助管家）是一个基于麦当劳官方 MCP 的点单辅助项目。它不是简单地按价格推荐套餐，而是尝试同时处理预算、健康、时间、忌口和个人偏好等约束。

项目既可以作为 WorkBuddy Skill 使用，也可以通过本地 CLI 运行内置演示数据。开发者还可以复用其数据解析与评分模块，将麦当劳 MCP 返回的数据接入自己的客户端。

项目仓库位于 GitHub，麦门小剧场也提供了在线体验页面。需要注意，McButler 是独立参赛作品，并非麦当劳官方产品。

六项核心能力

1. 每日推荐

recommend 支持省钱、健康和人气三种模式。它们使用不同的排序逻辑，而不是简单切换一个排序字段。

• 省钱模式：综合价格归一值、折扣力度和每 100 kcal 单价，避免小份餐品仅凭低总价排在前面。
• 健康模式：结合健康分与能量贴合度，并优先考虑拥有实测营养数据的候选。
• 人气模式：综合爆款标签、历史常点信息和折扣。

2. 健康体检

health 是项目的技术核心。由于营养接口提供的是单品数据，McButler 会先读取套餐详情，将套餐拆成默认子项，再逐项匹配营养表并汇总热量、蛋白质、脂肪、钠和钙等数据。

套餐详情
→ 读取默认组成
→ 匹配每个单品的营养数据
→ 汇总营养值
→ 计算健康分与扣分项

健康评分采用 100 分制，考虑能量区间、蛋白质、脂肪供能比、钠、糖油负担和蔬果加分。详细公式可以查看仓库中的 references/model-spec.md。

3. 门店全成本比价

stores 可以按最近、最便宜或综合全成本选择门店。综合模式不只看商品价格，还把往返距离、步行时间和排队时间折算成成本。

全成本 = 商品价
       + 距离成本（往返 0.5 元/km）
       + 时间成本（步行往返时间 + 排队时间）× 0.30 元/分钟

因此，最近的门店未必最划算。排队时间目前不是 MCP 接口直接提供的数据，需要由用户输入或估算。

4. 团餐配餐

bulk 面向行政、HR、班级和团队订餐场景。它能够按照人数、人均预算、不吃牛和不吃辣等条件分群配餐，并输出可继续传给算价流程的 orderItems。

结果会包含分群人数、套餐数量、总价、人均价格、节省金额和人均热量等信息。不过，“不吃牛”目前依赖菜名关键词过滤，无法保证识别菜单中没有明确标注成分的餐品。

5. 麦险分

credit 借鉴消费信贷评分卡，为账户和单笔订单计算 300 至 950 分的麦险分。六个维度包括履约稳定度、消费节律、预算纪律、优惠利用率、账户资产和口味多样性。

评分结果会展示各维度得分及其数据来源，而不是只输出一个无法解释的总分。该功能是趣味化消费分析，不代表真实金融信用评价。

6. 麦门小剧场

theater 会根据优惠券、麦险分和热量数据生成五个角色之间的点单争论，并输出一个单文件 HTML 页面。生成页面不需要额外依赖，可以直接在浏览器中打开。

准备运行环境

本地模式只需要 Python 3.8 或更高版本，并且仅使用 Python 标准库，不需要安装第三方包。在线 MCP 模式则需要可用的 MCP Token。

克隆仓库并运行自测

git clone https://github.com/jouaaaaaa/mcd-self-butler.git
cd mcd-self-butler
python scripts/selftest.py

自测包含 9 个离线用例，覆盖健康体检、三种推荐、账户与订单麦险分、团餐、门店比价和纯文本小剧场。全部通过后，说明本地环境和演示数据可以正常工作。

方式一：在 WorkBuddy 中安装为 Skill

1. 将仓库中的 SKILL.md、scripts/ 和 references/ 放入以下目录：

   ~/.workbuddy/skills/mcd-self-butler/

2. 在 WorkBuddy 中进入“专家·技能·连接器”，依次选择“连接器”“自定义连接器”和“配置 MCP”。

3. 填写麦当劳 MCP 的 Streamable HTTP 配置，并将占位符替换成自己的 Token：

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

4. 启用 mcd-mcp 连接器，然后用自然语言提出需求。

可以从以下请求开始：

• “我在南京西路，附近哪家麦当劳买巨无霸三件套最划算？”
• “帮我看看这个套餐多少卡，有没有更健康的换法。”
• “部门 30 人团餐，人均 30 元，5 个人不吃牛。”
• “我的麦险分是多少？”
• “等餐好无聊，让他们吵一架。”

方式二：使用本地 CLI

本地 CLI 使用仓库内的演示快照，不需要 Token，也不需要联网。六项能力统一通过 scripts/mcd_butler.py 调用。

检查套餐营养

python scripts/mcd_butler.py health \
  --nutrition demo/nutrition.txt \
  --combo demo/combo_9900011128.json

该命令会拆解套餐、匹配营养表并生成汇总结果。输出包括各组成项的营养数据、套餐合计、健康分和具体扣分原因。

获取健康推荐

python scripts/mcd_butler.py recommend \
  --menu demo/menu_1450118.json \
  --nutrition demo/nutrition.txt \
  --mode healthy \
  --meal lunch \
  --budget 45 \
  --top 5 \
  --details demo/details.json

--mode healthy 表示使用健康模式，--meal lunch 指定午餐场景，--budget 45 将预算限制为 45 元，--top 5 返回前五项结果。

若要探索其他策略，可以根据 CLI 支持的模式改用省钱或人气逻辑。不同模式的结果可能明显不同，因为它们使用不同的价值函数。

计算麦险分

python scripts/mcd_butler.py credit \
  --orders demo/orders.json \
  --account demo/account.json \
  --coupons demo/coupons.md \
  --nutrition demo/nutrition.txt

该命令结合历史订单、账户信息、优惠券和营养数据，输出总分、评级以及六个维度的明细。演示数据中的示例结果为 771 分、巨无霸级，但实际得分取决于输入数据。

配置 30 人团餐

python scripts/mcd_butler.py bulk \
  --menu demo/menu_1450118.json \
  --nutrition demo/nutrition.txt \
  --headcount 30 \
  --budget 30 \
  --no-beef 5 \
  --no-spicy 4

这里设置了 30 人、人均预算 30 元、5 人不吃牛和 4 人不吃辣。程序会分群选择套餐，并生成数量可计算的订单项目。

比较门店全成本

python scripts/mcd_butler.py stores \
  --stores demo/stores.json \
  --mode balanced

balanced 模式会综合距离、时间与价格。使用自己的数据时，应明确提供或估算排队时间，不要把示例值当成实时结果。

生成麦门小剧场

python scripts/mcd_butler.py theater \
  --context demo/theater_context.json \
  --out theater.html

运行后会在当前目录生成 theater.html。直接用浏览器打开即可观看角色对话、逐字气泡和最终裁决效果。

方式三：接入自己的 MCP 客户端

开发者可以使用两种集成方法。

1. 保存原始响应：在 MCP 客户端中调用门店、菜单、详情、营养、订单或优惠券等工具，将原始响应保存成与 demo/ 示例相同用途的文件，再交给 CLI 处理。
2. 直接调用模块：导入 scripts/lib/ 中的函数，将 MCP 返回的 Python dict 直接传入。

数据载入层 mcdata.py 同时接受形如 {"success": true, "data": ...} 的 MCP 原始响应和人工精简格式。因此通常可以直接保存工具响应，无须先手工清洗。

理解项目架构

McButler 的处理流程可以概括为四层：

1. 客户端层：WorkBuddy Agent 或其他 MCP 客户端发起请求。
2. MCP 服务层：获取门店、菜单、详情、营养、算价、优惠券、积分和订单等数据。
3. 数据载入层：mcdata.py 负责解包、归一化和名称模糊匹配。
4. 业务模型层：health.py、credit.py、bulk.py、recommend.py 和 theater.py 分别执行评分、配餐、推荐和剧本生成。

mcd_butler.py 是统一 CLI 入口，可以输出 Markdown 或 JSON，适合人工查看，也便于接入后续程序。

高级使用技巧

优先提供套餐详情

营养接口只提供单品数据。分析套餐时，最好同时传入套餐详情，让程序根据默认组成逐项查表。若一条营养数据都没有匹配到，项目会将健康分显示为“—”，而不是编造一个结果。

根据场景选择推荐模式

• 预算严格时使用省钱模式，并关注每 100 kcal 单价。
• 减脂或健身场景使用健康模式，同时检查蛋白质、脂肪和钠的扣分明细。
• 希望结合热门餐品与个人历史偏好时使用人气模式。

保存 MCP 原始数据以便复现

调试推荐结果时，建议保存当次 MCP 原始响应。这样即使菜单、价格或供应状态之后发生变化，也能用同一份数据复现计算过程。

区分数据质量

McButler 使用三档数据标注：

• 实测：套餐拆解后逐项汇总得到的数据。
• 官方：直接来自单品营养表的数据。
• 估：缺少完整数据时的粗略估算，会明确标注。

在自动化展示结果时，不应删除这些标记。它们用于提醒用户区分数据来源和可信程度。

检查业务边界

当前团餐功能尚未接入企业团餐满减规则的叠加优化；不吃牛主要依据菜名关键词判断；排队时间也需要显式输入。将项目用于实际订单前，应通过麦当劳官方渠道再次确认价格、供应状态和餐品成分。

营养分析仅供参考，不构成医疗、营养或其他专业建议。涉及疾病、孕期或儿童饮食时，应咨询专业人士。

结语

McButler 展示了如何把 MCP 原始数据转化为可解释的消费决策：从套餐拆解、营养评分和门店全成本，到团餐分群、趣味评分与互动内容，都可以通过统一 CLI 或 WorkBuddy Skill 使用。

第一次体验建议先运行 python scripts/selftest.py，再依次尝试 health、recommend 和 stores。确认离线流程后，再配置 MCP Token 接入实时数据。