zcbacxc/mcd-party-planner

mcd-party-planner · 麦当劳聚会 / 团餐组织助手

基于 麦当劳 MCP 真实能力的 Skill：输入「城市 + 关键词 + 人数 + 预算」，

输出多套真实计价的团餐方案；串联主题活动（派对 / 品鉴会）预约链路；

结合活动日历与附近门店给出组织时机建议。

> 参赛作品 —— 麦当劳程序员节创意开发大赛（2026 · 1024 程序员节）。

---

一、项目介绍

组织一次多人麦当劳聚餐，真正麻烦的不是点什么，而是三件事同时算清楚：附近哪家门店能吃、多少人吃什么组合、总共花多少钱不超预算。

mcd-party-planner 把这三件事交给麦当劳 MCP 的真实数据（共接入 15 个 Tool）：

| 能力 | 说明 | |---|---| | 团餐方案生成 | 查附近营业中门店 → 拉真实菜单 → 按「经济型 / 均衡型 / 丰盛型」组装 → 用 calculate-price 真实计价，输出 ≥2 套含「合计 / 人均 / 是否超预算」的可比对方案 | | 主题活动预约 | 自动串联 派对商品 → 城市 → 门店 → 日期 → 场次 五级查询，输出可直接下单的载荷；默认 dry_run，不真实下单 | | 活动日历组织建议 | 活动日历（往期 / 今日 / 未来）× 附近门店交叉，给出组织时机建议，并提示企业团餐助餐服务可用性 |

设计原则：数据全部实时取自麦当劳 MCP，仓库内不含任何静态菜单或价格快照；用户输入（城市、关键词、人数、预算）仅存在于运行时内存，不落盘、不外发。

调用层内置滑动窗口节流器（默认 300 次/分钟，官方上限 600）与 429 指数退避，批量比对不会触发限流。

---

二、安装方法

1. 申请 MCP Token

访问 麦当劳 MCP 开放平台 → 手机号验证登录 → 右上角「控制台」→「激活」→ 同意服务协议 → 复制 Token。

2. 获取代码

git clone https://github.com/zcbacxc/mcd-party-planner.git
cd mcd-party-planner

3. 配置 Token

cp .env.example .env
编辑 .env，填入：MCD_MCP_TOKEN=你的Token

.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. 自检

python -m src.cli selfcheck

=== 环境自检 ===
MCD_MCP_TOKEN: 已配置
tokenLength: 32
MCD_MCP_ENDPOINT: https://mcp.mcd.cn
结论：Token 已就绪，可执行真实调用

---

三、使用示例

以下输出均为真实调用麦当劳 MCP 的结果（成都 · 春熙路，2026-10-16 实测）。

示例 1：8 人聚餐，预算 400 元

python -m src.cli plan --city 成都 --keyword 春熙路 --headcount 8 --budget 400

【团餐方案】
城市：成都　关键词：春熙路　人数：8　预算：¥400.0
已扫描门店：2　可选方案：4　预算内方案：1
1. [经济型] 麦当劳成都锦江总府路茂业百货餐厅　合计 ¥352.0　人均 ¥44.0　预算内
   构成：精选单人餐三件套×8、小杯鲜萃咖啡×8
2. [经济型] 麦当劳成都壹购广场餐厅　合计 ¥444.0　人均 ¥55.5　超预算
   构成：精选单人餐三件套×8、冰浓浓黑巧中杯×8
3. [均衡型] 麦当劳成都锦江总府路茂业百货餐厅　合计 ¥591.2　人均 ¥73.9　超预算
   构成：精选单人餐三件套×8、龙焰芝士棒鸡腿堡三件套×8、小杯鲜萃咖啡×8
4. [均衡型] 麦当劳成都壹购广场餐厅　合计 ¥683.2　人均 ¥85.4　超预算
   构成：精选单人餐三件套×8、龙焰芝士棒鸡腿堡三件套×8、冰浓浓黑巧中杯×8
推荐：[经济型] 麦当劳成都锦江总府路茂业百货餐厅，合计 ¥352.0，人均 ¥44.0
！提示：门店 … / 丰盛型 计价失败：每单限购1件，去看看其他餐品吧

--json 输出结构化结果；--store-limit 控制比对门店数。

注：部分餐品存在「每单限购 1 件」等业务限制，这类组合会以提示形式跳过，不编造价格。

示例 2：预约派对 / 品鉴会（默认不下单）

python -m src.cli party --city 成都市 --headcount 6

【主题活动预约】
主题：麦当劳奇妙生日派对（spuId=1779）
城市：成都市　门店：麦当劳成都高新区大魔方餐厅（3450261）
日期：2026-10-16　场次：12:00-13:30　余位：12　价格：¥50.0
调用链路：mall-points-products → query-party-city → query-party-store
          → query-party-store-date → query-party-store-session
下单载荷：{'partyType': 1, 'spuId': 1779, 'skuId': 2027, 'storeCode': '3450261', …}
dry_run=True：未真实下单，仅输出可下单载荷

需真实下单时显式确认：

python -m src.cli party --city 成都市 --headcount 6 --confirm

示例 3：活动日历 × 附近门店

python -m src.cli calendar --city 成都 --keyword 春熙路

【活动日历组织建议】
城市：成都　关键词：春熙路　附近门店：2
· 2026-10-25　2026年10月25日
  活动：🫐一口爆汁！蓝莓爆爆珠麦旋风上新
  建议：未来活动，建议提前 3–5 天预约主题活动场次并预排团餐
· 2026-10-16　2026年10月16日 今日
  活动：麦当劳 X PEACEMINUSONE
  建议：今日可参与，建议立即组织；优先锁定 2 家附近门店的团餐方案
企业团餐助餐服务：
· 麦当劳成都府青路(恒大)餐厅：支持 保鲜速达
· 麦当劳成都三友路得来速餐厅：支持 保鲜速达

示例 4：校准工具入参（开发者）

python -m src.cli probe    # 拉取服务端 inputSchema → docs/mcp-schema.json

---

四、目标用户

| 用户 | 场景 | 得到的价值 | |---|---|---| | 团建 / 班级活动组织者 | 10–30 人聚餐，有明确预算上限 | 十几秒内得到多套含人均对比的真实报价方案，不再手工凑单 | | 企业行政 / 团餐负责人 | 需确认门店是否支持团餐助餐服务 | 一次查询拿到附近门店的助餐服务可用性（保鲜速达 / 专人分餐等）与组织建议 | | 想办派对的家长 / 会员 | 生日派对、品鉴会预约路径深 | 自动串联五级查询，输出可下单的场次与余位 | | MCP / Agent 开发者 | 想看一个 Skill 如何真实编排 15 个 MCP Tool | 可复用的调用层：节流、退避、结果解析、字段归一化与单一校准点 |

---

五、目录结构

mcd-party-planner/
├── README.md                  # 项目介绍、安装、示例、目标用户
├── CONTEST_DECLARATION.md     # 参赛声明（官方原文，内容不可改动）
├── MCP_INTEGRATION.md         # MCP Server / Tool / 调用流程 / 业务价值
├── mcp-config.example.json    # 脱敏 MCP 配置示例（仅占位符）
├── workbuddy.md               # WorkBuddy 开发对话上下文
├── skill/SKILL.md             # WorkBuddy Skill 定义
├── src/
│   ├── mcp_client.py          # MCP 调用层：streamablehttp + Bearer + 节流 + 429 退避
│   ├── party_planner.py       # 业务逻辑层：三个核心场景
│   ├── config.py              # 本地配置读取（Token 不入仓）
│   └── cli.py                 # 命令行入口
└── tests/
    ├── test_mcp_client.py     # 调用层单元测试
    ├── test_party_planner.py  # 业务层单元测试
    └── smoke.py               # 真实 MCP 端到端冒烟（Token 缺失时自动跳过）

六、运行测试

python -m unittest discover -s tests -p "test_*.py"   # 单元测试 40 项（无需 Token）
python tests/smoke.py                                  # 端到端冒烟（需真实 Token）

开发设置、代码风格与提交约定见 docs/CONTRIBUTING.md； 版本变更记录见 CHANGELOG.md。

七、说明与免责

• 本项目为麦当劳程序员节创意开发大赛参赛作品，由参赛者独立开发，非麦当劳官方产品；
• 餐品信息、价格及供应状态以麦当劳官方渠道的实时结果为准；涉及营养或热量的输出仅供参考，不构成医疗、营养或其他专业建议；
• 部分餐品存在限购等业务限制，相关组合会被跳过并提示，不会输出估算价格；
• 使用本项目须遵守《麦当劳 MCP 服务规则》及麦当劳中国《使用条款》。

八、许可证

MIT，见 LICENSE。