zcbacxc / mcd-party-planner

# mcd-party-planner · 麦当劳聚会 / 团餐组织助手
> 基于 **麦当劳 MCP** 真实能力的 Skill：输入「城市 + 关键词 + 人数 + 预算」，
> 输出多套**真实计价**的团餐方案；串联主题活动（派对 / 品鉴会）预约链路；
> 结合活动日历与附近门店给出组织时机建议。
>
> 参赛作品 —— 麦当劳程序员节创意开发大赛（2026 · 1024 程序员节）。
---
## 30 秒看懂
**一句话**：你说「成都春熙路，8 个人，预算 400」，它去麦当劳 MCP 查附近营业门店、拉真实菜单、用官方计价接口算钱，给你几套含人均的可比对方案——顺手把派对场次和附近活动也查了。
 [code] 
 [code] 
> 上为 **2026-10-20 真实调用**输出（有删节）。服务端菜单与价格按日轮换，复跑结果会不同——这属正常，不是模拟数据。
三个场景如何串联：
 [code] 
- **不编价格**：金额一律来自 `calculate-price`，遇限购等业务限制就跳过并提示；
- **不误下单**：主题预约默认 `dry_run`，只给可下单载荷，加 `--confirm` 才真实下单；
- **不重复下单**：写操作（下单 / 建址 / 取消）遇 5xx 不自动重试，只对 429 重试；
- **零依赖**：纯 Python 标准库，Python 3.9+，不需要 `pip install`。
---
## 一、项目介绍
组织一次多人麦当劳聚餐，真正麻烦的不是点什么，而是三件事同时算清楚：**附近哪家门店能吃、多少人吃什么组合、总共花多少钱不超预算**。
`mcd-party-planner` 把这三件事交给麦当劳 MCP 的真实数据（共接入 **15 个 Tool**）：
| 能力 | 说明 |
|---|---|
| **团餐方案生成** | 查附近营业中门店 → 拉真实菜单 → 按「经济型 / 均衡型 / 丰盛型」组装 → 用 `calculate-price` 真实计价，输出 ≥2 套含「合计 / 人均 / 是否超预算」的可比对方案 |
| **主题活动预约** | 自动串联 `派对商品 → 城市 → 门店 → 日期 → 场次` 五级查询，输出可直接下单的载荷；**默认 dry_run，不真实下单** |
| **活动日历组织建议** | 活动日历（往期 / 今日 / 未来）× 附近门店交叉，给出组织时机建议，并提示企业团餐助餐服务可用性 |
设计原则：**数据全部实时取自麦当劳 MCP，仓库内不含任何静态菜单或价格快照**；用户输入（城市、关键词、人数、预算）仅存在于运行时内存，不落盘、不外发。
> 调用层内置滑动窗口节流器（默认 300 次/分钟，官方上限 600）与 429 指数退避，批量比对不会触发限流。
---
## 二、安装方法
### 1. 申请 MCP Token
访问 麦当劳 MCP 开放平台 → 手机号验证登录 → 右上角「控制台」→「激活」→ 同意服务协议 → 复制 Token。
### 2. 获取代码
 [code] 
### 3. 配置 Token
 [code] 
> `.env` 已被 `.gitignore` 排除，**绝不会提交到仓库**。仓库中的 `mcp-config.example.json` 只含环境变量占位符。
### 4. 在 WorkBuddy 中使用（可选）
本项目主交付形态即 WorkBuddy Skill（见 `skill/SKILL.md`）。按 `mcp-config.example.json` 在 WorkBuddy 的【自定义连接器】中启用 `mcd-mcp` 后，直接用自然语言描述聚餐需求即可。
### 5. 环境要求
- Python 3.9 及以上，**仅依赖标准库，无需 pip 安装任何包**。
### 6. 自检
 [code] 
 [code] 
---
## 三、使用示例
> 以下输出均为**真实调用麦当劳 MCP** 的结果（成都 · 春熙路）。
> **服务端商品与价格按日轮换**，因此每条示例都标注了实测日期——复跑结果与示例不同属正常现象，不是模拟数据。
### 示例 1：8 人聚餐，预算 400 元（2026-10-16 实测）
 [code] 
 [code] 
> `--json` 输出结构化结果；`--store-limit` 控制比对门店数。
> 注：部分餐品存在「每单限购 1 件」等业务限制，这类组合会以提示形式跳过，不编造价格。
### 示例 2：预约派对 / 品鉴会（默认不下单，2026-10-16 实测）
 [code] 
 [code] 
需真实下单时显式确认：
 [code] 
### 示例 3：活动日历 × 附近门店（2026-10-16 实测）
 [code] 
 [code] 
### 示例 4：校准工具入参（开发者，命令与当前版本一致）
 [code] 
---
## 四、目标用户
| 用户 | 场景 | 得到的价值 |
|---|---|---|
| **团建 / 班级活动组织者** | 10–30 人聚餐，有明确预算上限 | 十几秒内得到多套含人均对比的真实报价方案，不再手工凑单 |
| **企业行政 / 团餐负责人** | 需确认门店是否支持团餐助餐服务 | 一次查询拿到附近门店的助餐服务可用性（保鲜速达 / 专人分餐等）与组织建议 |
| **想办派对的家长 / 会员** | 生日派对、品鉴会预约路径深 | 自动串联五级查询，输出可下单的场次与余位 |
| **MCP / Agent 开发者** | 想看一个 Skill 如何真实编排 15 个 MCP Tool | 可复用的调用层：节流、退避、结果解析、字段归一化与单一校准点 |
---
## 五、目录结构
 [code] 
## 六、运行测试
 [code] 
> **CI 覆盖范围（请勿误读绿勾）**：GitHub Actions 在 Python 3.9–3.13 上执行上述**离线单元测试**；
> 真实 MCP 冒烟需要仓库配置 `MCD_MCP_TOKEN` Secret，未配置时该步骤会被跳过，
> 汇总门禁会以 warning 标注「本次仅验证离线单测」。
> 因此「CI 绿」= 单元测试通过，**不等于**真实链路已验证；后者以本地 `tests/smoke.py` 为准。
开发设置、代码风格与提交约定见 `docs/CONTRIBUTING.md`；
版本变更记录见 `CHANGELOG.md`。
## 七、说明与免责
- 本项目为麦当劳程序员节创意开发大赛参赛作品，由参赛者独立开发，**非麦当劳官方产品**；
- 餐品信息、价格及供应状态以麦当劳官方渠道的实时结果为准；涉及营养或热量的输出仅供参考，**不构成医疗、营养或其他专业建议**；
- 部分餐品存在限购等业务限制，相关组合会被跳过并提示，不会输出估算价格；
- 使用本项目须遵守《麦当劳 MCP 服务规则》及麦当劳中国《使用条款》。
## 八、许可证
MIT，见 LICENSE。