McButler là gì
McButler (trợ lý tự phục vụ McDonald's) là một dự án hỗ trợ đặt món dựa trên MCP chính thức của McDonald's. Dự án không chỉ đề xuất suất ăn theo giá, mà còn cố gắng đồng thời xử lý các ràng buộc về ngân sách, sức khỏe, thời gian, thực phẩm cần tránh và sở thích cá nhân.
Dự án có thể được sử dụng như một WorkBuddy Skill hoặc chạy dữ liệu trình diễn tích hợp thông qua CLI cục bộ. Nhà phát triển cũng có thể tái sử dụng các mô-đun phân tích dữ liệu và chấm điểm để đưa dữ liệu do MCP của McDonald's trả về vào ứng dụng khách của mình.
Mã nguồn dự án nằm trên GitHub, còn sân khấu nhỏ McDonald's cung cấp trang trải nghiệm trực tuyến. Lưu ý rằng McButler là tác phẩm dự thi độc lập, không phải sản phẩm chính thức của McDonald's.
Sáu năng lực cốt lõi
1. Đề xuất hằng ngày
recommend hỗ trợ ba chế độ: tiết kiệm, lành mạnh và phổ biến. Mỗi chế độ sử dụng logic sắp xếp khác nhau, thay vì chỉ đơn giản chuyển đổi một trường sắp xếp.
- Chế độ tiết kiệm: kết hợp giá trị giá đã chuẩn hóa, mức giảm giá và đơn giá trên mỗi 100 kcal, tránh để món phần nhỏ chỉ nhờ tổng giá thấp mà đứng đầu.
- Chế độ lành mạnh: kết hợp điểm sức khỏe và mức độ phù hợp năng lượng, đồng thời ưu tiên các ứng viên có dữ liệu dinh dưỡng đo thực tế.
- Chế độ phổ biến: kết hợp nhãn món bán chạy, thông tin món thường được gọi trong lịch sử và mức giảm giá.
2. Kiểm tra sức khỏe
health là phần cốt lõi về kỹ thuật của dự án. Vì giao diện dinh dưỡng chỉ cung cấp dữ liệu từng món, McButler trước tiên sẽ đọc chi tiết suất ăn, tách suất ăn thành các thành phần mặc định, sau đó đối chiếu từng món với bảng dinh dưỡng và tổng hợp dữ liệu về calo, protein, chất béo, natri, canxi cùng các chỉ số khác.
Chi tiết suất ăn
→ Đọc thành phần mặc định
→ Đối chiếu dữ liệu dinh dưỡng của từng món
→ Tổng hợp giá trị dinh dưỡng
→ Tính điểm sức khỏe và các mục bị trừ điểmĐiểm sức khỏe sử dụng thang 100 điểm, xét đến khoảng năng lượng, protein, tỷ lệ năng lượng từ chất béo, natri, lượng đường và dầu, cùng điểm cộng rau quả. Có thể xem công thức chi tiết trong references/model-spec.md của kho mã nguồn.
3. So sánh tổng chi phí giữa các cửa hàng
stores có thể chọn cửa hàng theo khoảng cách gần nhất, giá rẻ nhất hoặc tổng chi phí cân bằng. Chế độ cân bằng không chỉ xét giá sản phẩm, mà còn quy đổi khoảng cách khứ hồi, thời gian đi bộ và thời gian xếp hàng thành chi phí.
Tổng chi phí = Giá sản phẩm
+ Chi phí khoảng cách (khứ hồi 0.5 nhân dân tệ/km)
+ Chi phí thời gian (thời gian đi bộ khứ hồi + thời gian xếp hàng) × 0.30 nhân dân tệ/phútVì vậy, cửa hàng gần nhất chưa chắc là lựa chọn tiết kiệm nhất. Hiện tại, thời gian xếp hàng không phải dữ liệu được MCP cung cấp trực tiếp, mà cần do người dùng nhập hoặc ước tính.
4. Lập suất ăn nhóm
bulk hướng đến các tình huống đặt đồ ăn cho phòng hành chính, HR, lớp học và nhóm. Công cụ có thể chia nhóm và lập suất ăn theo số người, ngân sách bình quân đầu người, điều kiện không ăn thịt bò và không ăn cay, đồng thời xuất orderItems để tiếp tục truyền vào quy trình tính giá.
Kết quả bao gồm số người trong từng nhóm, số suất ăn, tổng giá, giá bình quân đầu người, số tiền tiết kiệm và lượng calo bình quân đầu người. Tuy nhiên, điều kiện “không ăn thịt bò” hiện dựa vào bộ lọc từ khóa trong tên món, nên không thể đảm bảo nhận diện các món không ghi rõ thành phần trên thực đơn.
5. Điểm rủi ro McDonald's
credit lấy cảm hứng từ thẻ điểm tín dụng tiêu dùng, tính điểm rủi ro McDonald's từ 300 đến 950 điểm cho tài khoản và từng đơn hàng. Sáu khía cạnh gồm mức độ ổn định khi thực hiện đơn, nhịp độ tiêu dùng, kỷ luật ngân sách, tỷ lệ sử dụng ưu đãi, tài sản tài khoản và sự đa dạng khẩu vị.
Kết quả chấm điểm sẽ hiển thị điểm của từng khía cạnh cùng nguồn dữ liệu, thay vì chỉ xuất ra một tổng điểm không thể giải thích. Đây là tính năng phân tích tiêu dùng mang tính giải trí, không đại diện cho đánh giá tín dụng tài chính thực tế.
6. Sân khấu nhỏ McDonald's
theater tạo ra cuộc tranh luận đặt món giữa năm nhân vật dựa trên phiếu ưu đãi, điểm rủi ro McDonald's và dữ liệu calo, sau đó xuất một trang HTML một tệp. Trang được tạo không cần thêm phụ thuộc và có thể mở trực tiếp trong trình duyệt.
Chuẩn bị môi trường chạy
Chế độ cục bộ chỉ cần Python 3.8 trở lên và chỉ sử dụng thư viện chuẩn của Python, không cần cài đặt gói bên thứ ba. Chế độ MCP trực tuyến cần một MCP Token khả dụng.
Sao chép kho mã nguồn và chạy tự kiểm tra
git clone https://github.com/jouaaaaaa/mcd-self-butler.git
cd mcd-self-butler
python scripts/selftest.pyTự kiểm tra bao gồm 9 trường hợp ngoại tuyến, bao phủ kiểm tra sức khỏe, ba kiểu đề xuất, điểm rủi ro McDonald's cho tài khoản và đơn hàng, suất ăn nhóm, so sánh cửa hàng và sân khấu nhỏ dạng văn bản thuần túy. Khi tất cả đều đạt, điều đó cho thấy môi trường cục bộ và dữ liệu trình diễn có thể hoạt động bình thường.
Cách một: Cài đặt dưới dạng Skill trong WorkBuddy
Đặt
SKILL.md,scripts/vàreferences/trong kho mã nguồn vào thư mục sau:~/.workbuddy/skills/mcd-self-butler/Trong WorkBuddy, vào “Chuyên gia · Kỹ năng · Trình kết nối”, lần lượt chọn “Trình kết nối”, “Trình kết nối tùy chỉnh” và “Cấu hình MCP”.
Điền cấu hình Streamable HTTP của MCP McDonald's và thay thế phần giữ chỗ bằng Token của bạn:
{ "mcpServers": { "mcd-mcp": { "type": "streamablehttp", "url": "https://mcp.mcd.cn", "headers": { "Authorization": "Bearer 你的_MCP_TOKEN" } } } }Bật trình kết nối
mcd-mcp, sau đó đưa ra yêu cầu bằng ngôn ngữ tự nhiên.
Có thể bắt đầu bằng các yêu cầu sau:
- “Tôi đang ở đường Nam Kinh Tây, cửa hàng McDonald's nào gần đây mua bộ ba Big Mac sẽ tiết kiệm nhất?”
- “Giúp tôi xem suất ăn này có bao nhiêu calo và có cách đổi nào lành mạnh hơn không?”
- “Đặt suất ăn nhóm cho 30 người trong phòng ban, 30 nhân dân tệ/người, 5 người không ăn thịt bò.”
- “Điểm rủi ro McDonald's của tôi là bao nhiêu?”
- “Chờ đồ ăn chán quá, để họ tranh luận một trận đi.”
Cách hai: Sử dụng CLI cục bộ
CLI cục bộ sử dụng ảnh chụp dữ liệu trình diễn trong kho mã nguồn, không cần Token và không cần kết nối mạng. Sáu năng lực đều được gọi thống nhất thông qua scripts/mcd_butler.py.
Kiểm tra dinh dưỡng suất ăn
python scripts/mcd_butler.py health \
--nutrition demo/nutrition.txt \
--combo demo/combo_9900011128.jsonLệnh này sẽ phân tích suất ăn, đối chiếu với bảng dinh dưỡng và tạo kết quả tổng hợp. Đầu ra bao gồm dữ liệu dinh dưỡng của từng thành phần, tổng suất ăn, điểm sức khỏe và lý do bị trừ điểm cụ thể.
Lấy đề xuất lành mạnh
python scripts/mcd_butler.py recommend \
--menu demo/menu_1450118.json \
--nutrition demo/nutrition.txt \
--mode healthy \
--meal lunch \
--budget 45 \
--top 5 \
--details demo/details.json--mode healthy cho biết sử dụng chế độ lành mạnh, --meal lunch chỉ định bối cảnh bữa trưa, --budget 45 giới hạn ngân sách ở mức 45 nhân dân tệ, còn --top 5 trả về 5 kết quả đầu tiên.
Nếu muốn khám phá các chiến lược khác, có thể chuyển sang logic tiết kiệm hoặc phổ biến tùy theo các chế độ CLI hỗ trợ. Kết quả giữa các chế độ có thể khác biệt rõ rệt vì chúng sử dụng các hàm giá trị khác nhau.
Tính điểm rủi ro McDonald's
python scripts/mcd_butler.py credit \
--orders demo/orders.json \
--account demo/account.json \
--coupons demo/coupons.md \
--nutrition demo/nutrition.txtLệnh này kết hợp đơn hàng trong lịch sử, thông tin tài khoản, phiếu ưu đãi và dữ liệu dinh dưỡng để xuất tổng điểm, xếp hạng và chi tiết của sáu khía cạnh. Kết quả ví dụ trong dữ liệu trình diễn là 771 điểm, cấp Big Mac; điểm thực tế phụ thuộc vào dữ liệu đầu vào.
Thiết lập suất ăn nhóm 30 người
python scripts/mcd_butler.py bulk \
--menu demo/menu_1450118.json \
--nutrition demo/nutrition.txt \
--headcount 30 \
--budget 30 \
--no-beef 5 \
--no-spicy 4Ở đây thiết lập 30 người, ngân sách bình quân đầu người 30 nhân dân tệ, 5 người không ăn thịt bò và 4 người không ăn cay. Chương trình sẽ chia nhóm để chọn suất ăn và tạo các mục đơn hàng có thể tính số lượng.
So sánh tổng chi phí giữa các cửa hàng
python scripts/mcd_butler.py stores \
--stores demo/stores.json \
--mode balancedChế độ balanced kết hợp khoảng cách, thời gian và giá. Khi sử dụng dữ liệu của riêng mình, nên cung cấp hoặc ước tính rõ thời gian xếp hàng, không coi giá trị ví dụ là kết quả theo thời gian thực.
Tạo sân khấu nhỏ McDonald's
python scripts/mcd_butler.py theater \
--context demo/theater_context.json \
--out theater.htmlSau khi chạy, chương trình sẽ tạo theater.html trong thư mục hiện tại. Chỉ cần mở trực tiếp bằng trình duyệt để xem cuộc đối thoại giữa các nhân vật, bong bóng lời thoại theo từng chữ và hiệu ứng phán quyết cuối cùng.
Cách ba: Tích hợp với MCP client của riêng bạn
Nhà phát triển có thể sử dụng hai phương pháp tích hợp.
- Lưu phản hồi gốc: Gọi các công cụ về cửa hàng, thực đơn, chi tiết, dinh dưỡng, đơn hàng hoặc phiếu ưu đãi trong MCP client, lưu phản hồi gốc thành các tệp có mục đích tương tự ví dụ trong
demo/, rồi giao cho CLI xử lý. - Gọi trực tiếp mô-đun: Nhập các hàm trong
scripts/lib/và truyền trực tiếpdictPython do MCP trả về.
Lớp tải dữ liệu mcdata.py đồng thời chấp nhận phản hồi gốc MCP có dạng {"success": true, "data": ...} và định dạng rút gọn thủ công. Vì vậy, thông thường có thể lưu trực tiếp phản hồi công cụ mà không cần làm sạch thủ công trước.
Tìm hiểu kiến trúc dự án
Quy trình xử lý của McButler có thể khái quát thành bốn lớp:
- Lớp client: WorkBuddy Agent hoặc MCP client khác gửi yêu cầu.
- Lớp dịch vụ MCP: Lấy dữ liệu về cửa hàng, thực đơn, chi tiết, dinh dưỡng, tính giá, phiếu ưu đãi, điểm thưởng và đơn hàng.
- Lớp tải dữ liệu:
mcdata.pychịu trách nhiệm giải gói, chuẩn hóa và đối chiếu tên gần đúng. - Lớp mô hình nghiệp vụ:
health.py,credit.py,bulk.py,recommend.pyvàtheater.pylần lượt thực hiện chấm điểm, lập suất ăn, đề xuất và tạo kịch bản.
mcd_butler.py là điểm vào CLI thống nhất, có thể xuất Markdown hoặc JSON, phù hợp để xem thủ công cũng như tích hợp vào các chương trình tiếp theo.
Mẹo sử dụng nâng cao
Ưu tiên cung cấp chi tiết suất ăn
Giao diện dinh dưỡng chỉ cung cấp dữ liệu từng món. Khi phân tích suất ăn, tốt nhất nên truyền đồng thời chi tiết suất ăn để chương trình tra cứu từng thành phần theo cấu tạo mặc định. Nếu không đối chiếu được bất kỳ dữ liệu dinh dưỡng nào, dự án sẽ hiển thị điểm sức khỏe là “—” thay vì bịa ra một kết quả.
Chọn chế độ đề xuất theo tình huống
- Khi ngân sách nghiêm ngặt, sử dụng chế độ tiết kiệm và chú ý đến đơn giá trên mỗi 100 kcal.
- Trong bối cảnh giảm mỡ hoặc tập thể hình, sử dụng chế độ lành mạnh, đồng thời kiểm tra chi tiết điểm bị trừ do protein, chất béo và natri.
- Khi muốn kết hợp các món phổ biến với sở thích cá nhân trong lịch sử, sử dụng chế độ phổ biến.
Lưu dữ liệu thô MCP để tái hiện
Khi gỡ lỗi kết quả đề xuất, bạn nên lưu phản hồi MCP thô của lần đó. Nhờ vậy, ngay cả khi thực đơn, giá hoặc tình trạng cung ứng thay đổi sau này, bạn vẫn có thể dùng cùng một bộ dữ liệu để tái hiện quá trình tính toán.
Phân biệt chất lượng dữ liệu
McButler sử dụng ba mức đánh dấu dữ liệu:
- Đã đo: dữ liệu được tổng hợp từng mục sau khi phân rã suất ăn.
- Chính thức: dữ liệu lấy trực tiếp từ bảng dinh dưỡng của từng món.
- Ước tính: ước tính sơ bộ khi thiếu dữ liệu đầy đủ và sẽ được đánh dấu rõ ràng.
Khi tự động hiển thị kết quả, không nên xóa các nhãn này. Chúng giúp nhắc người dùng phân biệt nguồn gốc và mức độ đáng tin cậy của dữ liệu.
Kiểm tra ranh giới nghiệp vụ
Tính năng đặt suất ăn theo nhóm hiện chưa tích hợp tối ưu hóa cộng dồn quy tắc giảm giá theo mức chi tiêu dành cho suất ăn doanh nghiệp; tùy chọn không ăn thịt bò chủ yếu được xác định bằng từ khóa trong tên món; thời gian xếp hàng cũng cần được nhập rõ ràng. Trước khi sử dụng dự án cho đơn hàng thực tế, cần xác nhận lại giá, tình trạng cung ứng và thành phần món ăn thông qua các kênh chính thức của McDonald's.
Phân tích dinh dưỡng chỉ mang tính tham khảo, không cấu thành tư vấn y tế, dinh dưỡng hoặc chuyên môn khác. Khi liên quan đến bệnh lý, thai kỳ hoặc chế độ ăn của trẻ em, hãy tham khảo ý kiến chuyên gia.
Lời kết
McButler cho thấy cách chuyển đổi dữ liệu thô MCP thành quyết định tiêu dùng dễ giải thích: từ phân rã suất ăn, chấm điểm dinh dưỡng và tổng chi phí tại cửa hàng, đến phân nhóm suất ăn, chấm điểm thú vị và nội dung tương tác, tất cả đều có thể được sử dụng thông qua CLI thống nhất hoặc WorkBuddy Skill.
Để trải nghiệm lần đầu, bạn nên chạy python scripts/selftest.py trước, sau đó lần lượt thử health, recommend và stores. Sau khi xác nhận quy trình ngoại tuyến hoạt động, hãy cấu hình MCP Token để kết nối dữ liệu thời gian thực.