zcbacxc/mcd-party-planner

Project Overview

mcd‑party‑planner is a Python‑based command‑line tool (and a WorkBuddy Skill) that helps users organise group meals at McDonald’s restaurants in China. It talks directly to the official McDonald’s MCP (McDonald’s Cloud Platform) API, pulls live menu data, calculates real prices and even lets you reserve themed party slots.

What it does	How it works
Generate real‑time group‑meal proposals – you give a city, a location keyword, the number of people and a budget. The tool finds nearby open stores, fetches the current menu, builds economy / balanced / deluxe combos and returns at least two priced options with total, per‑person cost and a budget‑fit flag.	Calls up to 15 MCP “Tool” endpoints (store search, menu fetch, price calculation, etc.). A built‑in throttler (300 req/min) and exponential back‑off keep the API within its limits.
Book themed party events – birthday parties, tasting sessions, etc.	Chains five MCP queries (party product → city → store → date → session) and produces a ready‑to‑submit order payload. By default it runs in dry‑run mode; adding --confirm actually places the order.
Suggest timing via an activity calendar – shows upcoming McDonald’s promotions near the chosen stores and advises when to schedule the meal.	Merges calendar data with store proximity to output “today / future” suggestions and indicates whether corporate catering services (e.g., “保鲜速达”) are available.

The repository contains only standard‑library Python, a small CLI (src/cli.py), a thin MCP client (src/mcp_client.py) handling authentication, rate‑limiting and retry logic, and unit tests. A .env file supplies the required MCP token; no credentials are stored in the repo.

---

Who Might Use It

User	Typical scenario	Benefit
Team‑building or class organisers	Need a quick quote for 10‑30 people with a strict budget	Gets multiple real‑price plans in seconds, no manual menu hunting
Corporate catering admins	Want to know if nearby stores support the “group‑catering” service	Receives a single view of store availability and suggested dates
Parents or members planning a birthday party	Want to reserve a themed party slot without navigating several web pages	One‑click generation of a ready‑to‑order payload
Developers building MCP‑based agents	Need a concrete example of orchestrating many MCP tools	Re‑usable client layer with throttling, 429 back‑off and result normalisation

---

Quick Start (from the README)

1. Get an MCP token from the McDonald’s open platform.
2. Clone the repo and copy .env.example → .env, paste the token.
3. Run a self‑check: python -m src.cli selfcheck.
4. Use the CLI, e.g.:

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

   The output lists several priced meal plans and a recommendation.
5. For party booking:

   python -m src.cli party --city 成都市 --headcount 6   # dry‑run
   python -m src.cli party --city 成都市 --headcount 6 --confirm   # actually order
   

---

Technical Highlights

• Standard‑library only – no external dependencies, making deployment trivial.
• Rate‑limit aware – a sliding‑window limiter (default 300 calls/min) and exponential back‑off for HTTP 429 responses.
• Real‑time data – every plan is built from live MCP responses; the repo stores no static menus.
• Modular design – mcp_client.py abstracts HTTP calls, party_planner.py implements the three user‑facing scenarios, and cli.py wires everything together.
• Test coverage – ~40 unit tests covering the client and business logic, plus an optional smoke test that hits the live MCP service when a token is present.

---

License

MIT – you can freely use, modify and redistribute the code, provided you keep the original license notice.

---

This summary is based solely on the information provided in the repository’s README.