把每一顿麦当劳, 变成一次勇者冒险。
基于麦当劳中国 MCP Server(33 个工具)的游戏化点餐 Skill
1024 程序员节 · 麦当劳程序员创意开发大赛参赛作品
你有脑洞, Buddy 有能力。McQuest 把麦当劳 MCP 的 33 个工具编排成一套 RPG 化的 点餐体验: 你的消费历史是一张勇者角色卡, 每一次点餐是一次副本攻略, 每一天有 专属麦运, 每个月有一份可分享的战报。好玩的外壳下, 菜单、计价、优惠券、营养、 活动全部来自 MCP 实时数据——玩梗不造假。
| 命令 | 玩法 | 数据链路 |
|---|---|---|
mcquest hero |
⚔️ 勇者名册 | order-list + query-my-account + query-my-coupons → RPG 角色卡: 等级 / 职业 / 四维属性 / 称号 / 装备栏(优惠券) |
mcquest quest |
🗺️ 副本攻略 | now-time-info → query-nearby-stores → query-meals → query-meal-detail → list-nutrition-foods → 本地组合求解 → calculate-price + query-store-coupons 比价 → 确认后 create-order |
mcquest fortune |
🎋 今日麦运 | now-time-info + campaign-calendar + query-my-coupons + query-lottery-info + query-my-account → 宜忌 / 幸运餐品 / 活动提醒 / 券到期 / 抽奖建议 |
mcquest report |
📜 月度战报 | order-list + list-nutrition-foods → 出战统计 / 招牌武器 / 战场分布 / 营养汇总 / 成就, 一键分享 |
- Python 3.9+(零第三方依赖, 纯标准库)
- 一个麦当劳 MCP Token(前往 https://open.mcd.cn/mcp 手机号登录申请)
git clone https://github.com/fangjian-bit/mcquest.git
cd mcquest
pip install -e . # 或免安装: PYTHONPATH=src python -m mcquestexport MCD_MCP_TOKEN=你的Token # Windows PowerShell: $env:MCD_MCP_TOKEN="..."mcquest --demo hero # 全部命令都支持 --demo, 使用本地模拟数据$ mcquest hero
╭──────────────────────────────────────────────────╮
│ 麦门勇者传说 · 勇者名册 │
├──────────────────────────────────────────────────┤
│ 勇者 麦门勇者 │
│ 等级 Lv.4 ██████░░░░ │
│ 职业 狂战士 · 肉食是浪漫, 双倍牛肉是信仰 │
├──────────────────────────────────────────────────┤
│ ⚔ 力量 ████████ 99 │
│ 🧠 智慧 ████████ 99 │
│ 💰 财富 ██████░░ 77 │
│ 🍀 幸运 █████░░░ 66 │
├──────────────────────────────────────────────────┤
│ 🏅 称号 │
│ · 百战勇者 · 深夜食堂行者 · 晨曦早鸟 │
│ · 团餐指挥官 · 麦乐送常客 · 券多不压身 │
├──────────────────────────────────────────────────┤
│ 📜 战绩: 8 场战斗 / 累计 683.50 金币 │
│ 🗡 招牌武器: 薯条(大) / 巨无霸 / 板烧鸡腿堡 │
├──────────────────────────────────────────────────┤
│ 🎒 装备栏(可用优惠券) │
│ · 巨无霸套餐立减 6 元 [6.00元 · 2026-10-22 到期] │
│ · 麦乐鸡(5块)买一送一 [13.00元 · 2026-10-31 到期] │
│ · 早餐时段 8 折 [4.00元 · 2026-11-05 到期] │
╰──────────────────────────────────────────────────╯$ mcquest quest --scenario 加班 --budget 40 --kcal 800
╭────────────────────────────────────────────────────────────╮
│ 副本攻略 · 点餐方案 │
├────────────────────────────────────────────────────────────┤
│ 场景 加班 · 1 人 │
│ 餐段 午市 │
│ 门店 麦当劳(未来科技城餐厅) │
│ 预算 ¥40.00 │
│ 热量目标 800 kcal │
├────────────────────────────────────────────────────────────┤
│ 方案1 巨无霸 单点 + 麦乐鸡(5块) │
│ 原价 ¥38.50 → 到手 ¥25.50 · 省 34% · 784 kcal │
│ 方案2 巨无霸 单点 + 薯条(中) │
│ 原价 ¥37.00 → 到手 ¥31.00 · 省 16% · 815 kcal │
│ 方案3 巨无霸套餐 标准配置 │
│ 原价 ¥37.50 → 到手 ¥31.50 · 省 16% · 547 kcal │
├────────────────────────────────────────────────────────────┤
│ 🏷 最优用券: 麦乐鸡(5块)买一送一(已省 ¥13.00) │
╰────────────────────────────────────────────────────────────╯
$ mcquest quest --scenario 一人食 --budget 35 --confirm
📦 订单已创建(Agent 只建单, 付款由你扫码完成):
订单号: 2026102410300012
支付链接: https://wpa.mcd.cn/pay/xxxx
⚠️ 安全约定:create-order是真实写操作。不加--confirm时只出方案; 加上后才会真正建单。Agent 只建单, 付款由你扫码完成——资金永远不过 AI 的手。
$ mcquest fortune
╭────────────────────────────────────────────────────────╮
│ 今日麦运 · 每日一签 │
├────────────────────────────────────────────────────────┤
│ 日期 2026-10-19 星期一 │
│ 麦运 【中吉】 │
│ 幸运餐品 可口可乐(大) ¥12.00 │
├────────────────────────────────────────────────────────┤
│ ✅ 宜 │
│ · 稳中带皮的一天, 标准配置就很好 │
│ · 今日活动: 麦麦省会员日: 巨无霸套餐立减 6 元 │
│ · 有 1 张券即将到期(巨无霸套餐立减 6 元), 尽快安排 │
│ · 300 积分即将过期, 可考虑抽奖或商城兑换 │
├────────────────────────────────────────────────────────┤
│ ❌ 忌 │
│ · 忌放着积分过期 │
├────────────────────────────────────────────────────────┤
│ 🎰 抽奖建议: 积分余额 1540, 可抽 30 次, 手气正旺不妨一试 │
╰────────────────────────────────────────────────────────╯
$ mcquest report --share
⚔️ 麦门勇者传说 · 月度战报
📅 统计周期: 本月
🛡 出战次数: 8 场
💰 金币消耗: ¥683.50
🗡 招牌武器: 薯条(大)×11 / 巨无霸×8 / 板烧鸡腿堡×6
🔥 摄入热量: 11806 kcal
💪 摄入蛋白: 584.0 g
🏅 新成就: 暗夜骑士 ×2; 晨曦先驱 ×1; 军团统帅
—— 来自 McQuest · 把每一顿麦当劳变成一次冒险| 坑 | 对策 |
|---|---|
list-nutrition-foods 返回 TOON 文本而非 JSON, 字段可能含逗号/null |
src/mcquest/toon.py: 带引号状态机的 CSV 解析, 绝不按固定列位 split |
价格单位不一致: query-meals 返回元(字符串), calculate-price 返回分(整数) |
src/mcquest/money.py: 统一归一化为元, 杜绝"贵一百倍的价格" |
| 套餐替换只能同一轮次(round)内进行 | build_candidates() 只在单轮内替换, 按 deltaPrice 计差价 |
| 限流 600 次/分钟, 经不起穷举 | 组合枚举全部本地完成, 只对 Top-8 候选调 calculate-price; 客户端内置节流 + 429 退避 |
create-order 真实建单 |
必须显式 --confirm; 未确认只输出方案; 支付由用户扫码 |
| Token 即会员账号钥匙 | 只从环境变量读取; 仓库仅占位符; .env 已 gitignore |
mcquest/
├── src/mcquest/
│ ├── mcp_client.py # Streamable HTTP 客户端(协议协商/SSE解析/节流重试)
│ ├── toon.py # TOON 营养数据解析器
│ ├── money.py # 金额单位归一化(元/分)
│ ├── models.py # 防御式领域模型(字段多候选键名)
│ ├── hero.py # 勇者名册: 订单历史 → RPG 角色卡
│ ├── quest.py # 副本攻略: 点餐编排引擎(枚举/比价/下单)
│ ├── fortune.py # 今日麦运
│ ├── report.py # 月度战报 + 分享卡片
│ ├── engine.py # 编排引擎(真实 MCP / 演示模式同一代码路径)
│ ├── demo_data.py # 本地模拟数据(无需 Token 完整体验)
│ ├── render.py # CJK 宽度感知的 ASCII 卡片渲染
│ └── cli.py # 命令行入口
├── skill/SKILL.md # WorkBuddy Skill 定义(Agent 编排规则)
├── tests/ # 24 个单元测试(python -m unittest discover -s tests)
└── scripts/make_demo_svg.py
作为 Agent Skill 使用: McQuest 同时是一份 WorkBuddy Skill 定义
(skill/SKILL.md), 规定了 MCP 编排铁律(写操作确认、单位归一、TOON 解析、
同轮替换、限流保护、Token 安全)。把 skill/ 目录接入 WorkBuddy 后, 直接在
对话框里说"帮我用麦门勇者规划今天的加班餐, 预算 40", Agent 会按同一套规则编排。
{
"mcpServers": {
"mcd-mcp": {
"type": "streamablehttp",
"url": "https://mcp.mcd.cn",
"headers": { "Authorization": "Bearer ${MCD_MCP_TOKEN}" }
}
}
}详见 MCP_INTEGRATION.md: 使用的 14 个工具、完整调用链路、 六项工程对策与业务价值分析。
- 本项目为参赛作品, 非麦当劳官方产品; 餐品信息、价格与供应状态以麦当劳 官方实时接口为准, 输出不构成医疗或营养建议。
- 只读工具(菜单/券/积分/订单/活动)随时可调; 写工具(下单/撤单/兑换/抽奖/领券) 必须用户显式确认。
- 严禁把 MCP Token 提交到任何公开仓库——它等于你的麦当劳会员账号钥匙。
- 赛事: 1024 程序员节 · 麦当劳程序员创意开发大赛(主办方: 金拱门(中国)有限公司)
- 官方仓库: https://github.com/M-China/mcd-developer-innovation-challenge
- 时间: 2026-10-09 10:30 — 10-25 23:59(北京时间), 按 GitHub 公开 Star 数排名
- 开发伙伴: 腾讯 WorkBuddy(官方合作伙伴, 本作品使用 WorkBuddy 开发)
MIT
如果这个项目让你会心一笑, 点个 Star ⭐ —— 每一个 Star 都是勇者的一块经验值。
🍔 麦门永存 ⚔️