zcbacxc/mcd-party-planner

프로젝트 개요

mcd‑party‑planner는 중국의 맥도날드 레스토랑에서 단체 식사를 조직하는 데 도움이 되는 Python 기반 명령줄 도구（및 WorkBuddy 스킬）입니다. 공식 McDonald’s MCP（麦当劳云平台）API와 직접 통신하여 실시간 메뉴 데이터를 가져오고, 실제 가격을 계산하며, 테마 파티 슬롯을 예약할 수도 있습니다。

功能	工作原理
生成实时团体餐提案 – 您提供城市、位置关键词、人数和预算。该工具查找附近营业的餐厅，获取当前菜单，构建 经济 / 均衡 / 豪华 套餐，并返回至少两个带价格、人均费用和预算匹配标志的选项。	调用多达15个MCP“工具”端点（餐厅搜索、菜单获取、价格计算等）。内置限流器（300次/分钟）和指数退避确保API在限制范围内。
预订主题派对活动 – 生日派对、品鉴会等。	串联五个MCP查询（派对产品 → 城市 → 餐厅 → 日期 → 时段），并生成一个可直接提交的订单负载。默认以 dry‑run 模式运行；添加 --confirm 实际下单。
通过活动日历建议时间 – 显示所选餐厅附近即将到来的麦当劳促销活动，并建议何时安排用餐。	将日历数据与餐厅邻近度合并，输出“今天 / 未来”建议，并指示企业餐饮服务（例如“保鲜速达”）是否可用。

该仓库仅包含标准库Python、一个小型CLI（src/cli.py）、一个处理认证、速率限制和重试逻辑的轻量MCP客户端（src/mcp_client.py），以及单元测试。.env 文件提供所需的MCP令牌；仓库中不存储任何凭据。

---

可能的使用者

用户	典型场景	好处
团队建设或班级组织者	需要10‑30人、预算严格的快速报价	几秒钟内获得多个真实价格方案，无需手动搜索菜单
企业餐饮管理员	想知道附近餐厅是否支持“团体餐饮”服务	获得餐厅可用性和建议日期的单一视图
计划生日派对的家长或成员	想预订主题派对时段而无需浏览多个网页	一键生成可直接下单的负载
开发基于MCP的代理的开发者	需要一个编排多个MCP工具的具体示例	可复用的客户端层，具有限流、429退避和结果规范化功能

---

快速开始（来自README）

1. 从麦当劳开放平台获取MCP令牌。
2. 克隆仓库并将 .env.example 复制为 .env，粘贴令牌。
3. 运行自检：python -m src.cli selfcheck。
4. 使用CLI，例如：

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

   输出列出多个带价格的用餐方案和建议。
5. 派对预订：

   python -m src.cli party --city 成都市 --headcount 6   # dry‑run
   python -m src.cli party --city 成都市 --headcount 6 --confirm   # 实际下单
   

---

技术亮点

• 仅标准库 – 无外部依赖，部署简单。
• 速率限制感知 – 滑动窗口限流器（默认300次/分钟）和针对HTTP 429响应的指数退避。
• 实时数据 – 每个方案都基于实时MCP响应构建；仓库不存储静态菜单。
• 模块化设计 – mcp_client.py 抽象HTTP调用，party_planner.py 实现三个用户场景，cli.py 将所有部分连接起来。
• 测试覆盖 – 约40个单元测试覆盖客户端和业务逻辑，以及一个可选的冒烟测试，在存在令牌时访问实时MCP服务。

---

许可证

MIT – 您可以自由使用、修改和重新分发代码，前提是保留原始许可证声明。

---

此摘要仅基于仓库README中提供的信息。