跳到主要内容
AI教程

Oh-My-McDonald 教程：用 AI 查询麦当劳、比价并生成体素图

本教程介绍如何安装和配置 Oh-My-McDonald，通过麦当劳官方 MCP 查询门店、餐品、优惠和营养信息，并使用本地 Python 脚本完成报价、记录管理与体素风格 PNG 渲染。

AI我搜编辑部阅读约 12 分钟
Oh-My-McDonald 教程：用 AI 查询麦当劳、比价并生成体素图

Oh-My-McDonald 是什么

Oh-My-McDonald 是一个基于麦当劳官方 MCP 的对话驱动 AI Skill。你可以用自然语言告诉 AI 预算、口味和排除条件，让它查询真实餐品；也可以比较门店价格、查看优惠券与活动、计算营养数据，并在确认后记录吃过的餐品和去过的门店。

项目通过麦当劳官方 MCP 获取业务数据，再由本地 Python 脚本进行数据处理、记录保存和图片渲染。它不需要网页界面，也不依赖 OpenAI API 或其他图片生成 API。

访问 Oh-My-McDonald GitHub 仓库

项目能解决哪些问题

  • 在同一次对话中查询餐品、门店、价格、优惠和营养信息。
  • 根据预算、口味和排除条件，从 MCP 返回的真实候选餐品中进行选择。
  • 比较最多三家选定门店中同一商品、同一规格的报价。
  • 查看本人券包、优惠到期时间和已经发布的活动。
  • 计算准确匹配餐品的能量、蛋白质、脂肪、碳水化合物、钠和钙。
  • 在用户确认实际食用或到店后，保存餐品图鉴和探店记录。
  • 把查询结果转换成便于查看和分享的体素风格 PNG 图片。

四种体素可视化场景

项目内置 Python 体素渲染器，目前包含 43 个粗体素模型，并按照每格 8 像素的规则生成图片。

餐品图鉴

餐品图鉴使用分区展馆、转弯步道和餐品展台展示探索进度。只有实际吃过并确认保存的餐品才会点亮，未确认的餐品保持灰色。

餐品图鉴体素场景

优惠日历

优惠日历按本人券包的有效日期统计，重点显示今日有效券、近期到期券和已发布活动。完整明细可以放在续页中，避免信息全部挤在一张图片里。

优惠日历体素场景

门店比价

门店比价场景把选定门店排列在体素街道中，并在门口显示对应报价。这里的街道仅用于数据可视化，不代表真实道路或门店之间的地理关系。

门店比价体素场景

营养餐桌

营养场景把本餐食物放在同一餐盘中，并使用小票展示营养数据。蔬菜、水果和奶类属于餐外搭配参考，不会计入餐盘内食物的营养合计。

营养餐桌体素场景

安装前准备

开始前，请确认本机满足以下条件：

  • Python 3.11 或更高版本。
  • 能够正常创建和使用 Python 虚拟环境。
  • 安装支持中文的字体，推荐 Noto Sans CJK。
  • 如需实时查询，准备麦当劳官方 MCP 的访问凭据。

项目的主要依赖是 Pillow >=10,<13 和 NumPy >=1.24,<3，完整依赖已记录在 requirements.txt 中。

第一步：克隆项目

git clone https://github.com/xiaozhangup/Oh-My-McDonald.git
cd Oh-My-McDonald

第二步：创建虚拟环境

在 Linux 或 macOS 中执行：

python -m venv .venv
source .venv/bin/activate

Windows PowerShell 用户执行：

.venv\Scripts\Activate.ps1

第三步：安装依赖

python -m pip install -r requirements.txt

建议始终在已经激活的虚拟环境中安装依赖，避免与系统 Python 中的其他软件包冲突。

第四步：配置中文字体

体素图片包含中文餐品名、门店名和优惠标题，因此需要可用的中文字体。安装 Noto Sans CJK 后，可以通过 OMM_FONT 指定字体文件路径。

export OMM_FONT="/path/to/your/font.ttf"

请将示例路径替换成本机实际存在的字体文件。若图片中的中文无法正常显示，应首先检查该环境变量和字体路径。

第五步：查看命令帮助

python oh-my-mcdonald/scripts/oh_my_mcdonald.py --help

该命令会显示本地辅助脚本提供的子命令与参数。更完整的说明位于仓库中的 oh-my-mcdonald/references/commands.md。

接入麦当劳官方 MCP

获取 MCP Token

访问麦当劳 MCP 控制台，按照官方页面说明获取 MCP Token。凭据应保存在本机环境变量或 Codex 配置中，不要把真实 Token 写入项目文件或提交到 Git 仓库。

通过环境变量配置 Token

export MCD_MCP_TOKEN="YOUR_MCD_MCP_TOKEN"

通过 Codex 配置读取凭据

如果本机配置文件中已经包含 mcd-mcp 配置，可以使用 --codex-config 显式指定文件：

python oh-my-mcdonald/scripts/oh_my_mcdonald.py \
  --codex-config /本机/config.toml stores --city 武汉 --keyword 东澜岸

两种方法都只在本机读取凭据。完整接入过程可参考仓库根目录中的 MCP_INTEGRATION.md。

项目使用的 MCP 工具

  • query-nearby-stores：查询附近门店。
  • query-meals：查询餐品。
  • query-meal-detail：查询餐品详情。
  • query-store-coupons：查询门店优惠信息。
  • query-my-coupons：查询用户券包。
  • calculate-price：计算指定商品的价格。
  • campaign-calendar：查询活动日历。
  • list-nutrition-foods：获取营养计算所需的餐品数据。
  • order-list：查询订单记录。

基础用法一：查询门店

下面的命令查询武汉市名称或位置中与“东澜岸”相关的门店：

python oh-my-mcdonald/scripts/oh_my_mcdonald.py stores \
  --city 武汉 \
  --keyword 东澜岸

获得门店结果后，可以使用有效的门店 ID 继续查询餐品详情和报价。

基础用法二：查询餐品详情

python oh-my-mcdonald/scripts/oh_my_mcdonald.py detail \
  --store 1960151 \
  --code 9900005456
  • --store 用于指定门店 ID。
  • --code 用于指定餐品代码。

示例中的 ID 仅用于说明参数格式。实际使用时，应采用 MCP 当前查询结果中返回的有效门店 ID 和餐品代码。

基础用法三：查询购物篮报价

购物篮内容通过 JSON 文件提供，项目会按照指定门店和当前测试方案计算报价。

python oh-my-mcdonald/scripts/oh_my_mcdonald.py quote \
  --store 1960151 \
  --basket examples/basket.json

进行门店比价时，应确保比较的是同一商品和同一规格。项目最多比较三家选定门店，不会根据部分门店结果推断其他门店的价格。

基础用法四：离线查看体素模型

如果暂时没有 MCP Token，也可以先验证本地渲染环境并查看内置模型：

python oh-my-mcdonald/scripts/oh_my_mcdonald.py \
  --out output models

生成结果会写入 output 目录。这个步骤适合检查 Pillow、NumPy 和中文字体是否配置正确。

在 AI 客户端中使用 Skill

项目提供了 oh-my-mcdonald/SKILL.md，用于向支持 Skill 的 AI 客户端描述项目能力、操作流程和限制。客户端还需要具备 MCP 接入能力和执行本地命令的能力。

一个典型流程如下：

  1. 用户用自然语言提出预算、口味、门店、优惠或营养需求。
  2. AI 选择对应的 MCP 工具获取真实业务数据。
  3. AI 根据预算和排除条件筛选返回结果。
  4. 按需调用本地 Python 脚本处理数据。
  5. 需要可视化时，由本地渲染器生成 PNG。
  6. 涉及食用或探店记录时，先等待用户明确确认，再写入记录。

可以向 AI 提出类似下面的请求：

  • 今天预算 35 元，不要辣的，有什么推荐？
  • 从符合条件的真实餐品中随机选一个。
  • 比较这份套餐在附近三家门店的价格。
  • 查看我今天可用的券和最近的活动。
  • 计算这顿饭的能量和蛋白质。
  • 我确认刚刚吃过这个汉堡，请帮我记录。
  • 把我吃过的餐品生成一张图鉴。

候选餐品必须来自 MCP 查询结果，不能由 AI 虚构。单次随机抽选最多使用六个候选餐品组合。

高级技巧与使用原则

先明确门店、商品和规格

价格会受到门店、商品规格和优惠方案影响。进行比较前，应固定商品与规格，并让 AI 清楚列出本次选择的门店。这样得到的结果才具有可比性。

严格处理营养数据缺失

营养计算只使用准确匹配的餐品。如果某些营养字段缺失，应单独标注缺失项，不能将缺失值当作零，也不能用名称相似但无法确认的商品代替。

区分餐内统计与餐外建议

营养餐桌可以展示蔬菜、水果和奶类等补充建议，但本餐营养值只统计餐盘中的食物。解读生成图片时，不应把餐外参考项目加入合计。

记录前要求用户确认

订单记录只能作为待确认信息，不能直接证明用户已经吃过某个餐品。只有用户明确确认实际食用后，项目才应保存记录并点亮图鉴；探店记录也遵循同样原则。

正确理解优惠日历

日历按照本人券包的有效日期统计券数。优惠券是否能在某个时段、门店或商品上使用，仍应以 MCP 返回的具体条件为准。

保护本地凭据

优先通过 MCD_MCP_TOKEN 环境变量或本机 Codex 配置读取 Token，不要把凭据写入脚本、示例 JSON、截图或版本控制文件。

运行自动化测试

项目使用 Python unittest，可以在仓库根目录执行：

python -m unittest discover -s tests -v

README 记录的现有测试共 51 项，使用合成数据验证业务处理、输出和渲染逻辑。真实 MCP 查询的验证情况及限制记录在 docs/VALIDATION.md 中。

需要了解的实现边界

  • 项目不支持自动下单、付款或领取优惠券。
  • 项目不提供云端同步和后台轮询。
  • 价格比较最多覆盖三家选定门店，仅针对同一商品、同一规格和当前测试方案。
  • 体素街道是示意场景，不包含真实道路或地理位置关系。
  • 预览中的真实 MCP 数据是特定日期的快照，不代表后续实时结果。
  • 食用记录和探店记录都必须经过用户确认。

项目目录速览

  • oh-my-mcdonald/SKILL.md：AI 客户端的 Skill 描述文件。
  • oh-my-mcdonald/scripts/oh_my_mcdonald.py：本地辅助脚本和主要命令入口。
  • oh-my-mcdonald/references/commands.md：详细命令参考。
  • docs/images/：场景预览图片。
  • docs/VALIDATION.md：真实查询验证结果和限制。
  • examples/basket.json：购物篮 JSON 示例。
  • MCP_INTEGRATION.md：MCP 接入和调用流程说明。
  • tests/：自动化测试。

结语

Oh-My-McDonald 把麦当劳官方 MCP、自然语言交互和本地体素渲染结合在一起，既能辅助选餐、比价和营养分析，也能建立经过确认的个人探索记录。建议先完成离线模型渲染和测试，再配置 MCP Token；涉及价格、优惠和营养时，始终以当前 MCP 返回的真实数据为准。

项目基于 MIT License 开源，可通过 GitHub Issues 反馈问题，也可以提交 Pull Request 参与改进。