McValue Mate（麦麦精算师）

基于麦当劳中国官方 MCP 的智能餐品预算推荐工具

项目定位: 麦当劳中国 MCP 创意开发大赛参赛项目 技术栈: Python 3.13，零第三方依赖 版本: v1.0

麦麦精算师根据你的预算、用餐人数和餐品偏好，从麦当劳实时菜单中生成多个候选组合，并通过官方价格验证确认每个组合的实际总价，只推荐真正吃得起的方案。

问题: 麦当劳菜单品类丰富，用户想知道"我手里有 30 元，能买到什么组合"，但人工凑单费时费力，且门店实际价格可能与标价有差异。

目标用户:

• 学生、上班族等预算敏感的消费者
• 多人聚餐时需要快速分配预算的场景
• 对营养信息有了解需求的用户（数据覆盖有限，见"已知限制"）

1. 预算约束推荐: 输入预算（元）和人数，生成不超过预算的餐品组合。
2. 偏好筛选: 支持汉堡、鸡块、饮品、甜品、均衡搭配、不限六种偏好。
3. 多样性排序: 优先推荐品类丰富、重复度低的组合，避免全是酱料或全是饮料。
4. 官方价格验证: 每个候选组合通过麦当劳 MCP calculate-price 验证实际价格，过滤超预算方案。
5. 状态透明展示: 明确区分"验证通过""超预算拒绝""验证失败"三种状态，不伪装未验证方案。
6. 营养数据参考: 在数据可靠时显示热量、蛋白质等（覆盖率有限，见"已知限制"）。

$ python main.py
============================================================
  欢迎使用 麦麦精算师 (McValue Mate)
============================================================
请输入预算（元，例如 30）: 30
请输入用餐人数（默认 1）: 1
请选择偏好: 6. 不限
是否尽量推荐丰富的餐品组合？（y/n）: n

...正在获取菜单、匹配营养、生成候选、验证价格...

根据您的预算（30 元），为您推荐以下 3 个方案：
（以下方案已通过 MCP 价格验证，验证价不超过预算）

  [1] ✅ 已验证
      • 马苏里拉拉丝芝士条 × 2  (15.00 元/份，小计 30.00 元)
      验证总价: 30.00 元 | 预算剩余: 0.00 元 | 利用率: 100.0%

  [2] ✅ 已验证
      • 三文鱼双虾至尊月堡 × 1  (30.00 元/份，小计 30.00 元)
      验证总价: 30.00 元 | 预算剩余: 0.00 元 | 利用率: 100.0%

McValue Mate
├── src/
│   ├── config.py          # 环境变量配置（Token、URL）
│   ├── mcp_client.py      # MCP 客户端（只读白名单 + HTTP 通信）
│   ├── meal_model.py      # 餐品数据模型与 catalog 构建
│   ├── meal_matcher.py    # 营养数据匹配与餐品类型识别
│   ├── nutrition_parser.py # CSV 营养数据解析
│   ├── budget_planner.py  # 预算规划引擎（候选生成、排序、验证过滤）
│   └── price_verifier.py  # calculate-price 响应解析与验证
├── tests/                 # 320 个单元测试
├── main.py                # CLI 入口
├── acceptance_e2e.py      # 端到端 MCP 集成测试
└── .env.example           # 环境变量模板

MCP 作用: 项目通过麦当劳中国官方 MCP 获取实时菜单、营养数据和价格验证，所有价格信息以 MCP 返回为准，不做硬编码。

• Python 3.13（或 Python 3.9+）
• 网络连接（访问 https://mcp.mcd.cn）
• 麦当劳 MCP Bearer Token（从开发者平台获取）

零第三方依赖: 项目仅使用 Python 标准库（urllib, json, ssl, dataclasses, heapq 等），无需 pip install。

# 1. 克隆或下载项目
# 2. 设置环境变量
cp .env.example .env
# 编辑 .env，填入你的 MCP Token
export MCD_MCP_TOKEN="your_token_here"  # Linux/macOS
# 或 Windows PowerShell: $env:MCD_MCP_TOKEN="your_token_here"

# 3. 运行 CLI
python main.py

项目使用两阶段价格策略：

1. 估算阶段: 通过 query-meals 获取餐品当前价格，生成候选组合。
2. 验证阶段: 通过 calculate-price 向官方确认每个组合的实际总价。

验证失败时的行为:

• 验证价 超过预算: 明确拒绝，移至"仅供参考"区，展示实际验证价和差额。
• MCP 调用失败或商品详情不匹配: 移至"验证失败"区，明确提示"未确认最终价格"。
• 未通过验证的方案不会混入正式推荐。

1. 价格差异: query-meals 的估价与 calculate-price 的验证价可能存在差异（实测差额可达 13–35 元），这是 MCP 服务端数据不一致导致，项目已通过验证阶段过滤超预算方案。
2. 营养数据覆盖率: 当前仅约 23% 的菜单商品有可靠营养数据，大部分方案标记为"暂无可靠数据"。
3. 门店营业状态: query-nearby-stores 未返回目标门店时，项目使用已知门店代码继续执行，但不保证该门店当前营业。
4. 搜索范围: 受 max_candidates 限制，组合搜索可能被截断，结果标注 search_limited=True。
5. 餐品分类: 基于名称关键词的启发式分类，部分商品（如芝士条）可能无法准确归类。

# 运行全部单元测试
python -m unittest discover -s tests -v

# 运行端到端 MCP 集成测试（需要有效 Token）
python acceptance_e2e.py

本项目为麦当劳中国 MCP 创意开发大赛参赛作品，遵循比赛官方要求的许可证（待比赛主办方确认后更新）。

安全提示: MCP Token 仅通过环境变量 MCD_MCP_TOKEN 读取，不硬编码于源码，不输出到日志或报告。项目仅调用只读 MCP 工具，不执行下单、支付或修改账户状态的操作。