Hướng dẫn Nhà sưu tầm thẻ McDonald's: rút thẻ, tra cứu dinh dưỡng và đặt món an toàn bằng WorkBuddy

Tổng quan dự án

Mã Thẻ Sưu Tầm (mcd-gacha-collector) là một WorkBuddy Skill được phát triển dựa trên MCP của McDonald's Trung Quốc. Công cụ chuyển các món ăn McDonald's thành những thẻ bài có thể quay thưởng và sưu tầm, đồng thời hiển thị giá, calo, protein, hàm lượng natri và mức độ lành mạnh trên thẻ.

Dự án sử dụng MCP để获取 thực đơn, dữ liệu dinh dưỡng, cửa hàng và giá theo thời gian thực, sau đó dùng công cụ Python cục bộ để chấm điểm sức khỏe, phân loại độ hiếm, lọc theo ngân sách và quay thưởng có trọng số. Sau khi quay được món hỗ trợ mua, người dùng còn có thể kiểm tra giá và xác nhận lần hai để tạo đơn hàng thực.

Dữ liệu dinh dưỡng trong kho bao phủ khoảng 160 món ăn; bể thẻ trên trang web hiện có 53 thẻ được tạo bằng thông tin thực từ thực đơn. Đây là sản phẩm dự thi, không phải sản phẩm chính thức của McDonald's.

Tính năng chính

• Quay thẻ theo ngân sách: Có thể đưa ra yêu cầu bằng ngôn ngữ tự nhiên như “quay một thẻ trong 50 nhân dân tệ”, hệ thống sẽ lọc theo giá trước rồi thực hiện quay có trọng số.
• Dinh dưỡng và mức độ lành mạnh: Tính mức độ lành mạnh từ 0 đến 100 dựa trên dữ liệu do MCP trả về, đồng thời hiển thị calo, protein, chất béo hoặc natri.
• Phân cấp SSR, UR, R: Độ hiếm được xác định dựa trên phân bố mức độ lành mạnh, không phải chỉ định thủ công. Cách phân cấp tương đối có thể thích ứng với cấu trúc thực đơn của các cửa hàng khác nhau.
• Sổ sưu tầm cục bộ: Lịch sử quay được lưu trong ledger.json; thẻ trùng sẽ cộng dồn số lần nhận và có thể tổng hợp lượng calo trung bình cùng mức độ lành mạnh trung bình.
• Cơ chế điểm: Skill tự động phục hồi 1 lượt quay mỗi 4 giờ; phiên bản web sử dụng cơ chế làm mới thủ công với thời gian chờ 60 giây.
• Đặt hàng thực: Trước tiên gọi MCP để kiểm tra giá, sau đó yêu cầu người dùng xác nhận rõ ràng, cuối cùng mới gọi create-order.
• Trải nghiệm ngoại tuyến: Kho đi kèm dữ liệu mẫu, có thể kiểm thử quay thẻ, sưu tầm và kết xuất thẻ HTML mà không cần cấu hình MCP Token.
• Không phụ thuộc bên thứ ba: Các tập lệnh cốt lõi sử dụng thư viện chuẩn Python, yêu cầu Python 3.8 trở lên.

Quy trình hoạt động

Dự án tuân theo tư duy thiết kế “giao việc lấy dữ liệu cho MCP, giao việc tính toán cho mã nguồn, giao việc diễn đạt cho Agent”. WorkBuddy Agent chịu trách nhiệm hiểu ý định người dùng, MCP của McDonald's cung cấp dữ liệu nghiệp vụ thực tế, còn gacha.py thực hiện các phép tính xác định.

Người dùng yêu cầu quay thẻ, tra cứu dinh dưỡng hoặc đặt hàng
→ WorkBuddy Agent gọi MCP của McDonald's
→ Lấy dữ liệu về thời gian, cửa hàng, thực đơn, giá và dinh dưỡng
→ gacha.py tính mức độ lành mạnh, độ hiếm và thực hiện quay thẻ
→ render.py tạo trang thẻ hoặc sổ sưu tầm
→ Người dùng chọn mua
→ calculate-price kiểm tra giá
→ Người dùng xác nhận lần hai
→ create-order tạo đơn hàng

Giá tiền, mức độ lành mạnh và độ hiếm không được giao cho mô hình ngôn ngữ tự tính nhẩm. Giá do MCP trả về, còn việc chấm điểm và quay thẻ do mã Python thực hiện, qua đó giảm nguy cơ sai lệch và lỗi tính toán.

Chuẩn bị trước khi bắt đầu

• Cài đặt Python 3.8 trở lên.
• Cài đặt và có thể sử dụng WorkBuddy.
• Chuẩn bị MCP Token của McDonald's Trung Quốc có thể truy cập; chỉ chạy ví dụ ngoại tuyến thì không cần Token.
• Đảm bảo WorkBuddy có thể đọc thư mục skill của người dùng.

Cách một: Trải nghiệm trực tuyến ngay

Nếu chỉ muốn xem giao diện và bản trình diễn quay thẻ, hãy mở trang trực tuyến Mã Thẻ Sưu Tầm. Trang sẽ thử lấy thành phố thông qua IP, sau đó gọi chức năng tra cứu cửa hàng để chọn cửa hàng gần đó, không cần nhập địa chỉ thủ công.

Do hạn chế của môi trường triển khai, trang web công khai không thể chèn MCP Token cá nhân. Phiên bản trực tuyến phù hợp để trải nghiệm giao diện định vị, cửa hàng và thẻ; việc đặt hàng thực cần được thực hiện trong backend cục bộ hoặc WorkBuddy Skill đã cấu hình connector.

Cách hai: Cài đặt vào WorkBuddy

Bước một: Sao chép kho

git clone https://github.com/YOUR_GITHUB_USER/mcd-gacha-collector.git
cd mcd-gacha-collector

Địa chỉ kho trong README sử dụng biến giữ chỗ. Khi thao tác thực tế, hãy thay YOUR_GITHUB_USER bằng tên chủ sở hữu kho hoặc sao chép trực tiếp địa chỉ clone do trang GitHub cung cấp.

Bước hai: Đăng ký MCP Token của McDonald's

Truy cập Nền tảng mở MCP của McDonald's, đăng nhập bằng số điện thoại, kích hoạt dịch vụ trong bảng điều khiển và sao chép Token. Token là thông tin xác thực nhạy cảm; không ghi vào kho công khai và không commit vào lịch sử Git.

Bước ba: Cấu hình connector MCP

1. Mở “Chuyên gia · Skill · Connector” ở bên trái WorkBuddy.
2. Vào “Connector”, chọn “Connector tùy chỉnh” ở góc trên bên phải.
3. Chọn “Cấu hình MCP”.
4. Sao chép nội dung của mcp-config.example.json trong kho.
5. Thay ${MCD_MCP_TOKEN} bằng Token thực hoặc chèn thông qua biến môi trường.
6. Lưu cấu hình và bật connector.

Khuyến nghị sử dụng biến môi trường để quản lý Token. Dù sử dụng cách nào, không nên commit tệp cấu hình chứa thông tin xác thực thực vào hệ thống kiểm soát phiên bản.

Bước bốn: Sao chép Skill

Trên macOS hoặc Linux, thực hiện:

cp -r skills/mcd-gacha-collector ~/.workbuddy/skills/

Thư mục skill của người dùng WorkBuddy trên Windows là:

%USERPROFILE%\.workbuddy\skills\

Khi sao chép, cần giữ nguyên toàn bộ thư mục mcd-gacha-collector, bao gồm SKILL.md, các tập lệnh cốt lõi, tài liệu tham khảo và tệp tài nguyên.

Bước năm: Xác minh cài đặt

Quay lại hộp thoại WorkBuddy và nhập:

抽张麦当劳卡

Nếu Skill có thể gọi công cụ thực đơn và dinh dưỡng, đồng thời trả về kết quả thẻ có độ hiếm, giá và calo, nghĩa là cài đặt và kết nối MCP đã hoạt động.

Cách sử dụng cơ bản

Quay một thẻ theo ngân sách

50 元内抽一张

Skill sẽ lấy thực đơn và dữ liệu dinh dưỡng khả dụng của cửa hàng hiện tại, lọc các món có giá không vượt quá 50 nhân dân tệ, sau đó thực hiện quay thẻ có trọng số. Ví dụ thực tế trong README đã quay được Trà đen chanh Sunny cỡ vừa UR, giá 10 nhân dân tệ, 117 kcal và mức độ lành mạnh 63.4.

Kết quả thực tế phụ thuộc vào thực đơn cửa hàng, giá theo thời gian thực, cấu trúc bể thẻ và kết quả quay ngẫu nhiên; do đó không nên xem món ăn hoặc giá trong ví dụ là kết quả cố định.

Quay mười thẻ liên tiếp

来十连

Khi đủ điểm, Skill sẽ liên tiếp quay 10 thẻ và hiển thị kết quả theo dạng đầy đủ hơn. Khi không đủ điểm, Skill sẽ cho biết còn thiếu bao nhiêu lượt và thời điểm phục hồi tiếp theo.

Xem sổ sưu tầm

我的收藏册？

Dữ liệu sưu tầm được tổng hợp từ ledger.json cục bộ. Kết quả có thể bao gồm số thẻ đã thu thập, số lượng SSR, UR, R, số lần trùng, lượng calo trung bình và mức độ lành mạnh trung bình.

Tra cứu thông tin dinh dưỡng

巨无霸多少热量？

Skill sẽ tìm món ăn thông qua list-nutrition-foods. Kết quả ví dụ trong README là: Big Mac 513 kcal, 27 gram protein, 26 gram chất béo, 961 miligam natri, mức độ lành mạnh 32.2 và được xếp hạng R. Thông tin dinh dưỡng vẫn phải lấy dữ liệu chính thức do MCP trả về trong lần gọi đó làm chuẩn.

Tra cứu cửa hàng gần đây

附近麦当劳？

Hệ thống mặc định trước tiên định vị qua IP, lấy thành phố rồi gọi query-nearby-stores, đồng thời sắp xếp theo trường khoảng cách do MCP trả về. Vì kinh độ và vĩ độ trong giao diện cửa hàng có thể luôn là 0.0 khi kiểm thử thực tế, dự án không tự tính khoảng cách dựa trên các tọa độ này.

Xem số điểm còn lại

还有几次抽卡机会？

Skill sẽ đọc điểm trong sổ cái cục bộ và trả về số lượt hiện có cùng thời điểm tự động phục hồi tiếp theo. Điểm ở đây chỉ là cơ chế game hóa cục bộ của dự án, không liên quan đến tài khoản điểm chính thức của McDonald's.

Tạo đơn hàng thực một cách an toàn

Khi quay được thẻ yêu thích hoặc trực tiếp yêu cầu mua hàng, dự án không tạo đơn ngay mà áp dụng quy trình bắt buộc xác nhận lần hai:

1. Chọn cửa hàng và món ăn hoặc suất ăn có thể mua.
2. Gọi calculate-price để lấy giá theo thời gian thực và phương thức nhận hàng khả dụng.
3. Tạo quoteToken dùng một lần, có hiệu lực trong 15 phút.
4. Hiển thị kết quả kiểm tra giá cho người dùng và chờ xác nhận rõ ràng.
5. Backend xác minh Token, sau đó gọi create-order.
6. Trả về mã đơn hàng và liên kết thanh toán.

create-order bắt buộc phải kèm takeWayCode; giá trị này phải được lấy từ takeWayList do calculate-price trả về. Không được tự đoán hoặc bỏ qua, nếu không yêu cầu có thể trả về 400.

Món lẻ có thể không thể đặt riêng trong thực đơn kiểm thử. README ghi nhận 96 món lẻ có canWithOrder đều là false, vì vậy nhóm thẻ chính có thể đặt hàng thực tế là 18 thẻ suất ăn. Thẻ món lẻ vẫn có thể dùng để sưu tầm và hiển thị dinh dưỡng.

Trải nghiệm dòng lệnh không cần Token

Kho đi kèm sample_data, có thể xác minh toàn bộ logic quay thẻ ngoại tuyến trước. Đi vào thư mục tập lệnh:

cd skills/mcd-gacha-collector/scripts

Kiểm tra phân bố bể thẻ

python gacha.py sample_data --inspect --budget 50

Lệnh này kiểm tra bể thẻ mẫu với ngân sách 50 nhân dân tệ, phù hợp để xác nhận các thẻ có thể tham gia quay và phân bố độ hiếm.

Quay đơn và quay mười thẻ

python gacha.py sample_data --draw 1 --budget 50 --ledger /tmp/ledger.json
python gacha.py sample_data --draw 10 --budget 50 --ledger /tmp/ledger.json

--ledger chỉ định đường dẫn sổ cái. Sử dụng liên tục cùng một tệp sẽ giữ lại điểm và lịch sử sưu tầm.

Xem thống kê sưu tầm

python gacha.py sample_data --collection --ledger /tmp/ledger.json

Mô phỏng phân bố xác suất

python gacha.py sample_data --simulate 100 --seed 42

Phân bố mục tiêu của dữ liệu mẫu là SSR 5%, UR 20%, R 75%. --seed 42 giúp kết quả ngẫu nhiên có thể tái hiện, phù hợp để gỡ lỗi và so sánh đầu ra trước và sau khi sửa thuật toán.

Kết xuất HTML mặt thẻ

python render.py /tmp/ledger.json --out /tmp/cards.html --last-draw 1

Bộ kết xuất sẽ xuất dữ liệu sổ cái thành một tệp HTML duy nhất, thuận tiện để xem các thẻ được rút trong lần rút cuối trên trình duyệt.

Chạy tự kiểm tra

python selftest.py

Logic cốt lõi bao gồm 105 bài tự kiểm tra. Sau khi sửa điểm số, điểm tích lũy, độ hiếm hoặc mã rút thẻ, nên chạy lại lệnh này.

Tìm hiểu độ lành mạnh và độ hiếm

Độ lành mạnh của từng món được tính theo trọng số từ ba chiều:

• Mật độ protein chiếm 35%.
• Chỉ số ít calo chiếm 40%.
• Chỉ số ít natri chiếm 25%.

Độ hiếm sử dụng phương pháp phân hạng tương đối, thiết lập ngưỡng phân vị dựa trên phân bố dữ liệu hiện tại. Nhờ đó, một cửa hàng sẽ không hoàn toàn thiếu SSR chỉ vì không có các món đạt điểm cao như cà phê. Một pool thẻ được thử nghiệm trong README sau khi áp dụng phân vị có 3 thẻ SSR, 7 thẻ UR và 13 thẻ R.

Các suất ăn không áp dụng trực tiếp trọng số của từng món, vì tổng lượng calo của suất ăn vốn cao hơn. Dự án sử dụng thuật toán riêng cho suất ăn: mật độ protein 40%, mật độ natri 35%, tải lượng calo 25%, đồng thời tính ngưỡng phân vị riêng.

Độ lành mạnh và độ hiếm chỉ phục vụ mục đích so sánh thú vị, không cấu thành khuyến nghị y tế, dinh dưỡng hay chuyên môn khác.

Kỹ thuật phát triển nâng cao và xử lý sự cố

Phân tích đúng dữ liệu dinh dưỡng MCP

list-nutrition-foods có thể trả về data dưới dạng chuỗi CSV thay vì mảng JSON. Dự án cung cấp logic phân tích chuyên dụng parse_nutrition_csv. Khi mở rộng client, không được mặc định rằng giá trị này luôn là một danh sách.

Giải mã phong bì structuredContent

Dữ liệu nghiệp vụ MCP có thể nằm trong structuredContent.data, và các giá trị bên trong vẫn có thể là từ điển, danh sách hoặc chuỗi. Khi xử lý phản hồi, trước tiên cần giải mã lớp phong bì bên ngoài, sau đó phân luồng bộ phân tích theo kiểu dữ liệu thực tế.

Giữ thuật toán frontend và backend nhất quán

Phiên bản web sử dụng tính toán tại thời điểm build: tools/gen_web_data.py tạo dữ liệu, còn web/build.py nhúng dữ liệu vào trang đơn tệp. Frontend không triển khai lại một bộ thuật toán chấm điểm riêng, nhờ đó giảm vấn đề kết quả không nhất quán giữa hai phía.

Sau khi sửa phần tạo dữ liệu, ánh xạ trường hoặc mẫu trang web, có thể chạy tools/parity_check.py. Kho lưu trữ ghi nhận 99 lượt kiểm tra tính nhất quán, bao phủ HTML, JavaScript, phân bố pool thẻ và sự khớp trường dữ liệu.

Kiểm tra việc phân tích cửa hàng ở backend

Backend nằm trong thư mục server, sử dụng thư viện chuẩn Python để định vị IP, triển khai client MCP và giao diện đặt hàng. Logic phân tích cửa hàng có thêm 15 assertion. Kết hợp với 105 bài tự kiểm tra Skill và 99 lượt kiểm tra web, dự án ghi nhận tổng cộng 219 assertion.

Không phụ thuộc vào tọa độ cửa hàng

Theo kết quả thử nghiệm trong README, các trường kinh độ và vĩ độ do query-nearby-stores trả về có thể đều là 0.0. Chiến lược đáng tin cậy hơn là lấy thành phố qua IP trước, sau đó tìm kiếm theo thành phố và từ khóa địa điểm, rồi sắp xếp bằng trường distance do giao diện trả về.

Phân biệt thẻ hiển thị và thẻ có thể đặt hàng

Món ăn xuất hiện trong menu không nhất thiết có thể mua riêng. Khi xây dựng chức năng mua hàng, cần kiểm tra trạng thái có thể đặt hàng do MCP trả về và ưu tiên hướng dẫn người dùng chọn suất ăn hợp lệ; không được giả định rằng thẻ có thể hiển thị thì cũng có thể tạo đơn hàng.

Bảo vệ Token và thao tác đơn hàng

• Ưu tiên truyền Token qua biến môi trường.
• Không ghi Token thật vào mcp-config.example.json.
• Luôn tính lại giá trước khi đặt hàng.
• Xác thực quoteToken dùng một lần và thời hạn hiệu lực của token này.
• Chỉ gọi create-order sau khi người dùng xác nhận rõ ràng.
• Khi kiểm thử đơn hàng, cần xử lý thận trọng và xác nhận xem có cần hủy kịp thời hay không.

Phù hợp với những người dùng nào

• Các nhà phát triển muốn tìm hiểu quy trình gọi MCP của McDonald's.
• Những người thực hành muốn phát triển WorkBuddy Agent Skill.
• Người dùng yêu thích lối chơi sưu tầm thẻ, rút thẻ và bộ sưu tập.
• Dân văn phòng hoặc sinh viên muốn so sánh lượng calo và thành phần dinh dưỡng của món ăn theo cách nhẹ nhàng.
• Kỹ sư cần nghiên cứu quy trình phân tích dữ liệu MCP, tính lại giá và đặt hàng an toàn.

Tóm tắt

McDonald's Card Collector kết nối việc tra cứu menu, so sánh dinh dưỡng, sưu tầm và rút thẻ với đặt hàng thực tế thành một quy trình hoàn chỉnh. Khi bắt đầu sử dụng, bạn có thể tìm hiểu giao diện qua trang trực tuyến, sau đó chạy kiểm thử dòng lệnh bằng dữ liệu mẫu; sau khi xác nhận logic hoạt động chính xác, hãy cấu hình Token MCP của McDonald's và cài đặt Skill vào WorkBuddy.

Trong quá trình sử dụng thực tế, cần đặc biệt chú ý đến khác biệt về định dạng dữ liệu, giới hạn của giao diện cửa hàng, trạng thái có thể đặt hàng của suất ăn và cơ chế xác nhận lần hai. Mọi thông tin về giá, tình trạng cung ứng và món ăn đều phải căn cứ vào kết quả theo thời gian thực từ các kênh chính thức của McDonald's.