mcd-party-planner tự tính tiền ăn McDonald’s cho cả nhóm mà không cần lên app mò

Cái khó khi rủ 8 người đi ăn McDonald’s không phải là chọn món. Là làm sao biết chi nhánh nào gần nhất còn mở, gọi combo nào cho đủ no, và tổng bill có vượt 400 nghìn hay không. Thường anh em sẽ mở app, bấm thử vài combo, cộng nhẩm, rồi vẫn sợ sai.

zcbacxc/mcd-party-planner làm đúng việc đó bằng CLI. Bạn nhập thành phố, từ khóa khu vực, số người, ngân sách. Nó trả về nhiều phương án có giá thật, kèm tổng tiền, tiền mỗi người, và cái nào vượt ngân sách.

Nó làm gì cụ thể

Repo này là một Skill chạy trên WorkBuddy, gọi vào McDonald’s MCP server (repo M-China/mcd-mcp-server). Nó dùng 15 Tool từ phía server đó. Ba nhóm chức năng chính:

Tạo phương án tiệc nhóm: tìm chi nhánh đang mở gần khu vực, lấy menu thật, ghép theo ba mức “经济型 / 均衡型 / 丰盛型”, rồi gọi calculate-price để tính giá thật. Kết quả trả về tối thiểu 2 phương án để so sánh.
Đặt tiệc chủ đề (sinh nhật, party): nó tự nối chuỗi 5 bước từ sản phẩm, thành phố, cửa hàng, ngày, đến khung giờ. In ra payload sẵn sàng để đặt. Mặc định dry_run, không đặt thật.
Gợi ý thời điểm tổ chức: lấy lịch hoạt động (đã qua, hôm nay, sắp tới) đối chiếu với cửa hàng gần đó, kèm ghi chú dịch vụ tiệc doanh nghiệp nếu chi nhánh có hỗ trợ.

Điểm mình thích: không có menu hay bảng giá tĩnh nào nằm trong repo. Tất cả lấy realtime từ MCP. Input của người dùng chỉ nằm trong RAM, không ghi xuống đĩa.

Vì sao repo này đang được chú ý

501 sao sau 5 ngày (tạo 15/10, cập nhật 20/10) là con số khá với một dự án CLI thuần Python chỉ dùng thư viện chuẩn. Lý do hợp lý:

Đây là bài thi cho “Ngày hội lập trình viên McDonald’s 2026” (1024). Có bối cảnh cuộc thi, dân dev hay ghé xem.
Nhu cầu thật: đặt tiệc nhóm qua app vẫn là việc thủ công, tốn thời gian. Một CLI gọn nhẹ giải quyết đúng điểm đau.
Nó là ví dụ tốt về cách orchestrate nhiều MCP Tool. Nếu bạn đang tìm mẫu để học MCP thực chiến, đây là case khá đầy đủ: có throttle, có backoff, có xử lý lỗi 429.

Khác biệt so với mấy repo “gọi API demo”: nó có test (55 unit test không cần token), có smoke test thật, có CLI contract test, có tài liệu schema. Không phải kiểu bỏ lên GitHub rồi biến.

Cài và chạy thử

Yêu cầu Python 3.9+, không cần pip install gì cả. Chỉ cần token MCP của McDonald’s, lấy từ trang开放平台 của họ sau khi xác thực số điện thoại.

git clone https://github.com/zcbacxc/mcd-party-planner.git
cd mcd-party-planner
cp .env.example .env
# Mở .env, điền MCD_MCP_TOKEN=token_của_bạn

Kiểm tra môi trường:

python -m src.cli selfcheck

Ra được dòng “Token 已就绪” là chạy được. Giờ thử một kèo 8 người, ngân sách 400 tệ, ở khu Xuân Hy Lộ, Thành Đô:

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

Output ví dụ thật từ README:

已扫描门店：2　可选方案：4　预算内方案：1

1. [经济型] 麦当劳成都锦江总府路茂业百货餐厅　合计 ¥352.0　人均 ¥44.0　预算内
 构成：精选单人餐三件套×8、小杯鲜萃咖啡×8
2. [经济型] 麦当劳成都壹购广场餐厅　合计 ¥444.0　人均 ¥55.5　超预算
...

Muốn lấy kết quả dạng JSON cho tool khác ăn, thêm --json. Muốn giới hạn số cửa hàng đem so, dùng --store-limit.

Đặt tiệc sinh nhật, mặc định không đặt thật:

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

Muốn đặt thật thì thêm --confirm. Mình đánh giá cao việc họ để mặc định là dry_run=True, tránh tai nạn đặt nhầm 50 suất.

Xem lịch hoạt động và gợi ý thời điểm:

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

Cuối cùng, nếu bạn là dev MCP và muốn xem schema đầu vào thật của server:

python -m src.cli probe

Lệnh này kéo inputSchema về docs/mcp-schema.json. Rất tiện để debug khi server đổi field.

Ai nên dùng

Bốn nhóm mình thấy hợp:

Người tổ chức tiệc nhóm 10 đến 30 người có ngân sách cố định. Thay vì ngồi nhẩm, chạy một lệnh ra vài phương án để cân nhắc.
Hành chính công ty cần kiểm tra chi nhánh nào hỗ trợ tiệc đoàn (dịch vụ “giữ tươi tốc hành”, “chia phần chuyên trách”).
Phụ huynh muốn đặt tiệc sinh nhật cho con nhưng không rõ đường đi từ sản phẩm đến khung giờ. Tool nối sẵn 5 bước.
Dev đang học MCP, muốn xem cách một CLI wrap 15 Tool, có throttle và backoff ra sao.

Còn nếu bạn chỉ đặt 2 phần ăn cho gia đình, CLI này hơi quá tay. Mở app bấm nhanh hơn.

So với lựa chọn khác

Mình không biết repo nào tương đương cho thị trường Việt Nam, và cũng không có công cụ mã nguồn mở nào khác làm đúng việc tính tiền tiệc nhóm trên dữ liệu MCP của McDonald’s. Nên không so được. Trên góc độ kỹ thuật, nếu bạn đang tìm mẫu để viết CLI gọi MCP, có thể đối chiếu với các repo trong hệ sinh thái M-China hoặc MCP client mẫu của Anthropic. Nhưng đây là repo duy nhất mình thấy kết hợp cả ba việc: tính tiền thật, đặt tiệc, gợi ý thời điểm.

Ưu điểm, hạn chế, và mấy chỗ cần lưu ý

Ưu điểm rõ nhất là dùng thư viện chuẩn Python. Không dependency, không lo phiên bản lệch, không bị supply chain. Test có sẵn 55 cái, chạy offline không cần token. Tài liệu rõ: README, MCP_INTEGRATION.md, CONTRIBUTING, CHANGELOG đều có. Có cả cơ chế throttle 300 lần/phút (dưới ngưỡng 600 của server) và exponential backoff cho lỗi 429, cho thấy tác giả đã test thật chứ không đoán.

Hạn chế cần nói thẳng:

Dự án mới 5 ngày tuổi. Chưa ai kiểm chứng độ ổn định dài hạn. License MIT thì thoải mái, nhưng đừng kỳ vọng support.
Phụ thuộc vào MCP server của McDonald’s. Nếu server đổi field hay đổi Tool, repo này có thể gãy. Cái probe có thể giúp phát hiện, nhưng bạn phải chạy tay.
Vài combo bị chặn bởi business rule (ví dụ “mỗi đơn giới hạn 1 món”). Tool skip và in cảnh báo, không tự bịa giá. Đây là điểm cộng về honesty, nhưng nghĩa là không phải lúc nào cũng đủ 3 loại phương án.
Toàn bộ sample trong README là tiếng Trung, thành phố Trung Quốc. Nếu bạn ở Việt Nam thì repo này không dùng được với McDonald’s Việt Nam vì MCP server hiện tại phục vụ thị trường Trung Quốc.
README ghi rõ đây là bài dự thi, không phải sản phẩm chính thức của McDonald’s. Đừng hiểu nhầm.

Một điểm nhỏ về tài liệu: phần environments chỉ nói Python 3.9+, không nói Windows/macOS/Linux có chạy same same không. Mình đoán là có vì chỉ dùng stdlib, nhưng chưa kiểm chứng.

Kết

Nếu bạn là dev đang tìm một ví dụ hoàn chỉnh về cách orchestrate MCP Tool trong CLI Python, repo này đáng đọc. 500 sao trong 5 ngày, 15 Tool được gọi, 55 test offline, không một dependency ngoài. Còn nếu bạn ở Việt Nam và muốn dùng thật để đặt tiệc McDonald’s, hiện tại chưa được, vì MCP server chỉ phục vụ thị trường Trung Quốc.

Repo: zcbacxc/mcd-party-planner

Đăng ngày 20/10/2026