demian-mo / mcd-dex

# 🎮 麦麦图鉴 McDex
> **把麦当劳菜单变成宝可梦图鉴。** 每个餐品都是一个物种，营养值就是种族值，套餐是组合技，限定品是闪光——吃饭就是抓宠，点单就是组队。
**麦当劳程序员节创意开发大赛参赛作品** ｜ 基于麦当劳 MCP 开发 ｜ 用 WorkBuddy 辅助开发
---
## 这是个啥
你有没有过这种时刻：打开麦当劳菜单，明明只是想吃个午饭，却感觉在看一张生物图鉴？
- 巨无霸明明就是经典线的最终形态（汉堡包 → 麦香鱼 → 巨无霸）；
- 小薯/中薯/大薯就是同一条进化链，进化只会长个；
- 圆筒冰淇淋会在草莓麦旋风和奥利奥麦旋风之间**分支进化**；
- 姜饼风味拿铁这种季节限定，就是**闪光个体**——错过了要再等一年。
**麦麦图鉴**把这一切做成了真的。它读取麦当劳 MCP 的官方餐品营养数据，把每样餐品编目成图鉴物种：科属、稀有度、进化线、种族值，一应俱全。你今天吃的每一顿，都是一次图鉴收集。
 [code] 
 [code] 
## 玩法
| 玩法 | 说明 |
|---|---|
| **🌲 出门觅食（主玩法）** | 随机遭遇战：草丛晃动，只露剪影——「???: 一阵特别的气息，像是限时活动才有的东西……」丢出薯条盒，三晃判定，稀有度越高越容易挣脱（闪光收服率仅约19%），逮到了图鉴卡当场展开 |
| **🎫 随机掉券** | 收服成功后 50% 概率草丛掉落一张真实麦麦省券（来自官方券池，只播报不代领） |
| **看图鉴** | 全物种列表、按科属/稀有度/关键词检索，未捕获的只有剪影 |
| **组队伍** | 把你今天点的东西加进队伍，捕获播报直接亮出每只的完整图鉴卡（种族值 + 官方营养原值） |
| **查合计** | 队伍总热量/蛋白质/脂肪/钠…对照每日参考值的百分比条 |
| **触发组合技** | 堡+薯+可乐=「经典铁三角」，双辣同场=「双辣共鸣」，限定品=「闪光捕获」……7 种组合技等你自己撞出来 |
| **集成就** | 初训师、闪光猎人、全图鉴…… 8 个成就，达成即时播报，存档自动记录 |
| **🎫 券感知**（需 Token） | 查当前麦麦省券池，自动匹配你图鉴里的物种——「你抓过的这只，今天有券」。**只读不领**，领券走官方渠道 |
| **✨ 闪光预报**（需 Token） | 解析官方活动日历，上新/限定/联名/回归动向提前预警——「错过再等一年」从文案变成行动提醒 |
**核心信条：吃饭就是抓宠，点单就是组队。**
遭遇战实况：
 [code] 
## 快速开始
**最省事**：克隆后双击 `开始图鉴.command`（macOS），菜单式交互，推荐从这进。
 [code] 
> 零第三方依赖，Python 3.9+ 直接跑。仓库自带的 `data/dex.json` 已是官方数据同步结果，开箱即玩。
## 数据来源与同步
图鉴数据**全部来自麦当劳 MCP 官方营养接口**（`list-nutrition-foods`），160 只麦麦的营养值（能量/蛋白质/脂肪/碳水/钠/钙）均为官方原值，项目不做任何数值编造。科属、稀有度、进化线是本项目的「编目规则」——公开、可改、欢迎拍砖。
想重新同步最新菜单（麦当劳上新即生效）：
 [code] 
## 种族值是怎么算的（半玩笑半认真）
| 属性 | 来源营养素 | 一本正经的理由 |
|---|---|---|
| HP | 能量 kcal | 血条厚度 |
| 攻击 | 蛋白质 | 力量来自蛋白 |
| 防御 | 脂肪 | 物理缓冲层 |
| 特攻 | 热量密度 | 能量轰炸 |
| 特防 | 钙 | 骨骼坚固 |
| 速度 | 碳水化合物 | 快充能量 |
数值全部来自麦当劳官方营养接口，映射规则公开在 `mcd_dex/dex_engine.py`，欢迎拍砖。
## 项目结构
 [code] 
## 已知边界
- 图鉴营养数值全部来自麦当劳 MCP 官方接口；「科属/稀有度/进化线/图鉴描述」为项目编目规则，非麦当劳官方分类；
- 队伍合计中的「每日参考值」为公开膳食指南的常用近似，仅供参考，不构成营养建议；
- 本作品为大赛参赛作品，非麦当劳官方产品；餐品信息以麦当劳官方渠道实时数据为准。
## License
MIT（麦当劳相关商标权利归麦当劳所有，本项目仅作大赛参赛用途）。