跳到主要内容
AI教程

麦卡收藏家教程：用 WorkBuddy 抽麦当劳卡牌、查营养并安全下单

本教程带你安装并使用麦卡收藏家，通过麦当劳中国 MCP 获取实时菜单、价格与营养信息，将餐品转化为 SSR、UR、R 卡牌，并体验收藏册、积分、多抽、离线命令行测试及二次确认下单流程。

AI我搜编辑部阅读约 13 分钟
麦卡收藏家教程：用 WorkBuddy 抽麦当劳卡牌、查营养并安全下单

项目概览

麦卡收藏家（mcd-gacha-collector）是一款基于麦当劳中国 MCP 开发的 WorkBuddy Skill。它把麦当劳餐品转换成可以抽取和收藏的卡牌，并在卡面上展示价格、热量、蛋白质、钠含量与健康度。

项目会通过 MCP 获取实时菜单、营养数据、门店和价格，再由本地 Python 引擎完成健康度评分、稀有度划分、预算过滤与加权抽卡。抽到支持购买的餐品后，还能经过核价和二次确认创建真实订单。

仓库中的营养数据覆盖约 160 项餐品，当前网页卡池包含 53 张使用真实菜单信息生成的卡牌。项目为比赛参赛作品，并非麦当劳官方产品。

麦卡收藏家桌面首屏

核心功能

  • 预算抽卡：可以提出“50 元内抽一张”等自然语言要求，系统先过滤价格，再进行加权抽取。
  • 营养与健康度：根据 MCP 返回的数据计算 0 至 100 的健康度，并展示热量、蛋白质、脂肪或钠等信息。
  • SSR、UR、R 分级：稀有度由健康度分布确定，不是手工指定。相对分级可适应不同门店的菜单结构。
  • 本地收藏册：抽卡记录保存在 ledger.json，重复卡会累计获得次数，并可汇总平均热量与平均健康度。
  • 积分机制：Skill 每 4 小时自动恢复 1 次抽卡机会；网页版采用带 60 秒冷却的手动刷新机制。
  • 真实下单：先调用 MCP 核价，再要求用户明确确认，最后才调用 create-order。
  • 离线体验：仓库附带样例数据，不配置 MCP Token 也能测试抽卡、收藏和 HTML 卡面渲染。
  • 零第三方依赖：核心脚本使用 Python 标准库，要求 Python 3.8 或更高版本。

抽卡评分与下单原理图

运行流程

项目遵循“取数交给 MCP，算术交给代码，表达交给 Agent”的设计思路。WorkBuddy Agent 负责理解用户意图，麦当劳 MCP 提供真实业务数据，gacha.py负责确定性计算。

用户提出抽卡、查营养或下单请求
→ WorkBuddy Agent 调用麦当劳 MCP
→ 获取时间、门店、菜单、价格和营养数据
→ gacha.py 计算健康度、稀有度并执行抽卡
→ render.py 生成卡牌或收藏册页面
→ 用户选择购买
→ calculate-price 核价
→ 用户二次确认
→ create-order 创建订单

金额、健康度和稀有度不会交给大模型口算。价格由 MCP 返回，评分与抽卡由 Python 代码完成，从而降低计算漂移和错误风险。

开始前的准备

  • 安装 Python 3.8 或更高版本。
  • 安装并能够使用 WorkBuddy。
  • 准备可访问的麦当劳中国 MCP Token；只运行离线示例时不需要 Token。
  • 确保 WorkBuddy 能读取用户技能目录。

方式一：直接在线体验

如果只想查看界面和抽卡演示，可以打开麦卡收藏家在线页面。页面会尝试通过 IP 获取城市，再调用门店查询能力选择附近门店，无需手动输入地址。

麦卡收藏家移动端首屏

受部署环境限制，公网网页不能注入个人 MCP Token。在线版本适合体验定位、门店与卡牌界面；真实下单需要在本地后端或配置了连接器的 WorkBuddy Skill 中完成。

方式二：安装到 WorkBuddy

第一步：克隆仓库

git clone https://github.com/YOUR_GITHUB_USER/mcd-gacha-collector.git
cd mcd-gacha-collector

README 中的仓库地址使用了占位符。实际操作时，请将 YOUR_GITHUB_USER 替换为仓库所有者名称，或直接复制 GitHub 页面提供的克隆地址。

第二步：申请麦当劳 MCP Token

访问麦当劳 MCP 开放平台，使用手机号登录，在控制台激活服务并复制 Token。Token 属于敏感凭据，不要写入公开仓库，也不要提交到 Git 历史。

第三步：配置 MCP 连接器

  1. 打开 WorkBuddy 左侧的“专家·技能·连接器”。
  2. 进入“连接器”，选择右上角的“自定义连接器”。
  3. 选择“配置 MCP”。
  4. 复制仓库中 mcp-config.example.json 的内容。
  5. 把其中的 ${MCD_MCP_TOKEN} 替换为真实 Token，或者通过环境变量注入。
  6. 保存配置并启用连接器。

推荐使用环境变量管理 Token。无论采用哪种方式，都不应把含有真实凭据的配置文件提交到版本控制系统。

第四步：复制 Skill

在 macOS 或 Linux 中执行：

cp -r skills/mcd-gacha-collector ~/.workbuddy/skills/

Windows 的 WorkBuddy 用户技能目录为：

%USERPROFILE%\.workbuddy\skills\

复制时应保留整个 mcd-gacha-collector 目录，其中包括 SKILL.md、核心脚本、参考文档和资源文件。

第五步：验证安装

返回 WorkBuddy 对话框，输入：

抽张麦当劳卡

如果 Skill 能调用菜单和营养工具，并返回带有稀有度、价格及热量的卡牌结果，说明安装和 MCP 连接已经生效。

基础使用方法

按预算抽一张卡

50 元内抽一张

Skill 会获取当前门店的可用菜单和营养数据，过滤价格不超过 50 元的餐品，再执行加权抽卡。README 的实测示例抽中了 UR 阳光柠檬红茶中杯，价格为 10 元、热量为 117 kcal、健康度为 63.4。

实际结果取决于门店菜单、实时价格、卡池结构和随机抽取结果，因此不应把示例中的餐品或价格视为固定输出。

进行十连抽

来十连

积分足够时，Skill 会连续抽取 10 张卡，并以更完整的形式展示结果。积分不足时，它会说明还缺少多少次机会以及下一次恢复时间。

查看收藏册

我的收藏册？

收藏数据由本地 ledger.json 聚合。结果可以包含已收集卡牌数量、SSR、UR、R 的数量、重复次数、平均热量和平均健康度。

查询营养信息

巨无霸多少热量？

Skill 会通过 list-nutrition-foods 查找餐品。README 中的示例结果为：巨无霸 513 大卡、蛋白质 27 克、脂肪 26 克、钠 961 毫克、健康度 32.2，并被划入 R 档。营养信息仍应以 MCP 当次返回的官方数据为准。

查询附近门店

附近麦当劳？

系统默认先进行 IP 定位，取得城市后再调用 query-nearby-stores，并使用 MCP 返回的距离字段排序。由于实测中门店接口的经纬度可能恒为 0.0，项目不会依赖这些坐标自行计算距离。

查看剩余积分

移动全页

还有几次抽卡机会？

Skill 会读取本地账本中的积分，并返回当前可用次数及下一次自动恢复时间。这里的积分只是本项目的本地游戏化机制，与麦当劳官方积分账户无关。

安全地创建真实订单

当你抽到喜欢的卡牌或直接提出购买请求时，项目不会立即创建订单，而是采用强制二次确认流程：

  1. 选择门店和可购买的餐品或套餐。
  2. 调用 calculate-price 获取实时价格与可用取餐方式。
  3. 生成有效期为 15 分钟的一次性 quoteToken。
  4. 向用户展示核价结果并等待明确确认。
  5. 后端验证 Token，通过后调用 create-order。
  6. 返回订单号和支付链接。

create-order 必须携带 takeWayCode，这个值应从 calculate-price 返回的 takeWayList 中取得。不能自行猜测或省略，否则请求可能返回 400。

散单在实测菜单中可能无法独立下单。README 记录的 96 张单品其 canWithOrder 均为 false，因此真正可下单的主力是 18 张套餐卡。单品卡仍可用于收藏和营养展示。

无需 Token 的命令行体验

仓库自带 sample_data，可以先离线验证完整抽卡逻辑。进入脚本目录：

cd skills/mcd-gacha-collector/scripts

检查卡池分布

python gacha.py sample_data --inspect --budget 50

该命令会在 50 元预算条件下检查样例卡池，适合确认可参与抽取的卡牌及稀有度分布。

单抽与十连

python gacha.py sample_data --draw 1 --budget 50 --ledger /tmp/ledger.json
python gacha.py sample_data --draw 10 --budget 50 --ledger /tmp/ledger.json

--ledger 指定账本路径。连续使用同一个文件，可以保留积分与收藏记录。

查看收藏统计

python gacha.py sample_data --collection --ledger /tmp/ledger.json

模拟概率分布

python gacha.py sample_data --simulate 100 --seed 42

样例目标分布为 SSR 5%、UR 20%、R 75%。--seed 42让随机结果可以复现，适合调试和比较算法修改前后的输出。

渲染卡面 HTML

python render.py /tmp/ledger.json --out /tmp/cards.html --last-draw 1

渲染器会将账本数据输出成单文件 HTML，便于在浏览器中查看最后一次抽取的卡牌。

运行自测

python selftest.py

核心逻辑包含 105 项自测。修改评分、积分、稀有度或抽卡代码后，应重新运行该命令。

理解健康度与稀有度

单品的健康度由三个维度加权计算：

  • 蛋白质密度占 35%。
  • 低热量指标占 40%。
  • 低钠指标占 25%。

稀有度使用相对分级思路，根据当前数据分布设置分位阈值。这样可以避免某个门店因为缺少咖啡等高分单品而完全没有 SSR。README 的一个实测卡池在应用分位数后得到 SSR 3 张、UR 7 张、R 13 张。

套餐不会直接沿用单品权重，因为套餐的总热量天然更高。项目为套餐采用独立算法：蛋白质密度 40%、钠密度 35%、热量载荷 25%，并单独计算分位阈值。

健康度和稀有度只用于趣味比较，不构成医疗、营养或其他专业建议。

进阶开发与排错技巧

正确解析 MCP 营养数据

list-nutrition-foods 返回的 data 可能是 CSV 字符串，而不是 JSON 数组。项目提供了专用的 parse_nutrition_csv 解析逻辑。扩展客户端时，不要直接假设它一定是列表。

解开 structuredContent 信封

MCP 业务数据可能位于 structuredContent.data 中，而且其中的值仍可能是字典、列表或字符串。处理响应时，应先解开外层信封，再根据实际类型分派解析器。

保持前后端算法一致

网页版采用构建期计算：tools/gen_web_data.py生成数据，web/build.py将数据内联到单文件页面。前端不重新实现一套评分算法，从而减少两端结果不一致的问题。

修改数据生成、字段映射或网页模板后，可运行 tools/parity_check.py。仓库记录了 99 项一致性校验，覆盖 HTML、JavaScript、卡池分布和字段对齐。

验证后端门店解析

后端位于 server 目录，使用 Python 标准库实现 IP 定位、MCP 客户端和下单接口。门店解析逻辑另有 15 项断言。结合 105 项 Skill 自测和 99 项网页校验，项目共记录 219 项断言。

不要依赖门店经纬度

根据 README 的实测结果，query-nearby-stores 返回的经纬度字段可能都是 0.0。更稳妥的策略是先通过 IP 获取城市，再以城市和地点关键词搜索，并使用接口返回的 distance 排序。

区分展示卡与可下单卡

菜单中出现的餐品不一定都能独立购买。构建购买功能时，应检查 MCP 返回的可下单状态，并优先引导用户选择合法套餐，不能因为卡牌可展示就假定它可以创建订单。

保护 Token 与订单操作

  • 优先通过环境变量注入 Token。
  • 不要把真实 Token 写入 mcp-config.example.json。
  • 下单前始终重新核价。
  • 验证一次性 quoteToken及其有效期。
  • 只有在用户明确确认后才调用 create-order。
  • 测试订单时应谨慎处理，并确认是否需要及时取消。

适合哪些用户

  • 希望学习麦当劳 MCP 调用流程的开发者。
  • 想开发 WorkBuddy Agent Skill 的实践者。
  • 喜欢卡牌收集、抽卡和图鉴玩法的用户。
  • 希望用轻量方式比较餐品热量与营养构成的上班族或学生。
  • 需要研究 MCP 数据解析、核价和安全下单流程的工程师。

总结

麦卡收藏家把菜单查询、营养比较、抽卡收藏和真实下单串成了一条完整流程。初次使用时，可以先通过在线页面了解界面，再用样例数据运行命令行测试；确认逻辑无误后，配置麦当劳 MCP Token 并把 Skill 安装到 WorkBuddy。

实际使用时，应特别注意数据格式差异、门店接口限制、套餐可下单状态和二次确认机制。所有价格、供应状态和餐品信息均应以麦当劳官方渠道的实时结果为准。