zcbacxc/mcd-party-planner

プロジェクト概要

mcd‑party‑planner は、Pythonベースのコマンドラインツール（およびWorkBuddy スキル）で、中国のマクドナルド店舗でのグループ食事の手配を支援します。公式の 麦当劳MCP（麦当劳云平台）APIに直接通信し、ライブメニューデータを取得し、実際の価格を計算し、テーマパーティーの予約も可能です。

機能	仕組み
リアルタイムのグループ食事提案を生成 – 都市、場所キーワード、人数、予算を指定します。ツールは近くの営業中の店舗を検索し、現在のメニューを取得し、経済 / バランス / デラックス の組み合わせを構築し、合計、一人当たりのコスト、予算適合フラグ付きの価格付きオプションを少なくとも2つ返します。	最大15個のMCP“ツール”エンドポイント（店舗検索、メニュー取得、価格計算など）を呼び出します。組み込みのスロットラー（300 req/min）と指数バックオフにより、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中提供的信息。