Hướng dẫn Oh-My-McDonald: Dùng AI tra cứu McDonald’s, so sánh giá và tạo ảnh voxel

Oh-My-McDonald là gì

Oh-My-McDonald là một AI Skill điều khiển bằng hội thoại, dựa trên MCP chính thức của McDonald's. Bạn có thể dùng ngôn ngữ tự nhiên để cho AI biết ngân sách, khẩu vị và các điều kiện loại trừ, từ đó tra cứu các món ăn thực tế; đồng thời so sánh giá tại các cửa hàng, xem phiếu ưu đãi và chương trình khuyến mãi, tính dữ liệu dinh dưỡng, cũng như ghi lại các món đã ăn và cửa hàng đã ghé sau khi xác nhận.

Dự án lấy dữ liệu nghiệp vụ thông qua MCP chính thức của McDonald's, sau đó dùng các tập lệnh Python cục bộ để xử lý dữ liệu, lưu bản ghi và kết xuất hình ảnh. Dự án không cần giao diện web, cũng không phụ thuộc vào OpenAI API hay các API tạo ảnh khác.

Truy cập kho GitHub của Oh-My-McDonald

Dự án giải quyết những vấn đề nào

• Tra cứu món ăn, cửa hàng, giá, ưu đãi và thông tin dinh dưỡng trong cùng một cuộc hội thoại.
• Lựa chọn từ các món ăn thực tế do MCP trả về dựa trên ngân sách, khẩu vị và điều kiện loại trừ.
• So sánh báo giá của cùng một sản phẩm, cùng một quy cách tại tối đa ba cửa hàng được chọn.
• Xem các phiếu trong kho phiếu cá nhân, thời hạn ưu đãi và các chương trình đã công bố.
• Tính chính xác năng lượng, protein, chất béo, carbohydrate, natri và canxi của các món ăn được khớp chính xác.
• Lưu bộ sưu tập món ăn và nhật ký ghé thăm cửa hàng sau khi người dùng xác nhận đã ăn hoặc đã đến cửa hàng.
• Chuyển kết quả tra cứu thành hình ảnh PNG phong cách voxel, thuận tiện xem và chia sẻ.

Bốn bối cảnh trực quan hóa voxel

Dự án tích hợp trình kết xuất voxel bằng Python, hiện có 43 mô hình voxel thô và tạo ảnh theo quy tắc mỗi ô rộng 8 pixel.

Bộ sưu tập món ăn

Bộ sưu tập món ăn dùng khu triển lãm phân khu, lối đi rẽ và quầy trưng bày món ăn để thể hiện tiến độ khám phá. Chỉ những món đã ăn thực tế và được xác nhận lưu mới được thắp sáng; các món chưa xác nhận vẫn giữ màu xám.

Lịch ưu đãi

Lịch ưu đãi thống kê theo ngày hiệu lực của kho phiếu cá nhân, tập trung hiển thị phiếu có hiệu lực hôm nay, phiếu sắp hết hạn và các chương trình đã công bố. Có thể đặt đầy đủ chi tiết ở các trang tiếp theo để tránh dồn toàn bộ thông tin vào một hình ảnh.

So sánh giá cửa hàng

Bối cảnh so sánh giá cửa hàng sắp xếp các cửa hàng được chọn trên một con phố voxel và hiển thị báo giá tương ứng trước cửa. Con phố ở đây chỉ dùng để trực quan hóa dữ liệu, không đại diện cho đường sá thực tế hay quan hệ địa lý giữa các cửa hàng.

Bàn ăn dinh dưỡng

Bối cảnh dinh dưỡng đặt các món ăn của bữa này trên cùng một đĩa và dùng hóa đơn để hiển thị dữ liệu dinh dưỡng. Rau, trái cây và sữa chỉ là gợi ý bổ sung ngoài bữa ăn, không được tính vào tổng dinh dưỡng của các món trên đĩa.

Chuẩn bị trước khi cài đặt

Trước khi bắt đầu, hãy xác nhận máy của bạn đáp ứng các điều kiện sau:

• Python 3.11 hoặc cao hơn.
• Có thể tạo và sử dụng môi trường ảo Python bình thường.
• Cài đặt phông chữ hỗ trợ tiếng Trung, khuyến nghị Noto Sans CJK.
• Nếu cần tra cứu thời gian thực, hãy chuẩn bị thông tin xác thực để truy cập MCP chính thức của McDonald's.

Các phụ thuộc chính của dự án là Pillow >=10,<13 và NumPy >=1.24,<3; toàn bộ phụ thuộc được ghi trong requirements.txt.

Bước 1: Sao chép dự án

git clone https://github.com/xiaozhangup/Oh-My-McDonald.git
cd Oh-My-McDonald

Bước 2: Tạo môi trường ảo

Thực hiện trên Linux hoặc macOS:

python -m venv .venv
source .venv/bin/activate

Người dùng Windows PowerShell thực hiện:

.venv\Scripts\Activate.ps1

Bước 3: Cài đặt phụ thuộc

python -m pip install -r requirements.txt

Luôn nên cài đặt phụ thuộc trong môi trường ảo đã kích hoạt để tránh xung đột với các gói khác trong Python hệ thống.

Bước 4: Cấu hình phông chữ tiếng Trung

Hình ảnh voxel chứa tên món ăn, tên cửa hàng và tiêu đề ưu đãi bằng tiếng Trung, vì vậy cần có phông chữ tiếng Trung khả dụng. Sau khi cài đặt Noto Sans CJK, bạn có thể dùng OMM_FONT để chỉ định đường dẫn tệp phông chữ.

export OMM_FONT="/path/to/your/font.ttf"

Hãy thay đường dẫn mẫu bằng đường dẫn đến tệp phông chữ thực sự tồn tại trên máy. Nếu tiếng Trung trong hình ảnh không hiển thị bình thường, trước tiên hãy kiểm tra biến môi trường và đường dẫn phông chữ này.

Bước 5: Xem trợ giúp lệnh

python oh-my-mcdonald/scripts/oh_my_mcdonald.py --help

Lệnh này hiển thị các lệnh con và tham số do tập lệnh hỗ trợ cục bộ cung cấp. Hướng dẫn đầy đủ hơn nằm trong oh-my-mcdonald/references/commands.md của kho lưu trữ.

Kết nối MCP chính thức của McDonald's

Lấy MCP Token

Truy cập bảng điều khiển MCP của McDonald's và làm theo hướng dẫn trên trang chính thức để lấy MCP Token. Thông tin xác thực nên được lưu trong biến môi trường cục bộ hoặc cấu hình Codex; không ghi Token thực vào tệp dự án hay commit vào kho Git.

Cấu hình Token qua biến môi trường

export MCD_MCP_TOKEN="YOUR_MCD_MCP_TOKEN"

Đọc thông tin xác thực qua cấu hình Codex

Nếu tệp cấu hình cục bộ đã có cấu hình mcd-mcp, bạn có thể dùng --codex-config để chỉ định rõ tệp:

python oh-my-mcdonald/scripts/oh_my_mcdonald.py \
  --codex-config /本机/config.toml stores --city 武汉 --keyword 东澜岸

Cả hai phương thức chỉ đọc thông tin xác thực trên máy cục bộ. Có thể tham khảo quy trình tích hợp đầy đủ trong MCP_INTEGRATION.md ở thư mục gốc của kho.

Các công cụ MCP được dự án sử dụng

• query-nearby-stores: Tra cứu các cửa hàng gần đó.
• query-meals: Tra cứu món ăn.
• query-meal-detail: Tra cứu chi tiết món ăn.
• query-store-coupons: Tra cứu ưu đãi của cửa hàng.
• query-my-coupons: Tra cứu kho phiếu của người dùng.
• calculate-price: Tính giá sản phẩm được chỉ định.
• campaign-calendar: Tra cứu lịch chương trình.
• list-nutrition-foods: Lấy dữ liệu món ăn cần cho việc tính dinh dưỡng.
• order-list: Tra cứu lịch sử đơn hàng.

Cách dùng cơ bản 1: Tra cứu cửa hàng

Lệnh dưới đây tra cứu các cửa hàng ở thành phố Vũ Hán có tên hoặc vị trí liên quan đến “东澜岸”:

python oh-my-mcdonald/scripts/oh_my_mcdonald.py stores \
  --city 武汉 \
  --keyword 东澜岸

Sau khi nhận được kết quả cửa hàng, bạn có thể dùng ID cửa hàng hợp lệ để tiếp tục tra cứu chi tiết món ăn và báo giá.

Cách dùng cơ bản 2: Tra cứu chi tiết món ăn

python oh-my-mcdonald/scripts/oh_my_mcdonald.py detail \
  --store 1960151 \
  --code 9900005456

• --store dùng để chỉ định ID cửa hàng.
• --code dùng để chỉ định mã món ăn.

Các ID trong ví dụ chỉ nhằm minh họa định dạng tham số. Khi sử dụng thực tế, hãy dùng ID cửa hàng và mã món ăn hợp lệ được trả về trong kết quả tra cứu hiện tại của MCP.

Cách dùng cơ bản 3: Tra cứu báo giá giỏ hàng

Nội dung giỏ hàng được cung cấp qua tệp JSON; dự án sẽ tính báo giá theo cửa hàng được chỉ định và phương án kiểm thử hiện tại.

python oh-my-mcdonald/scripts/oh_my_mcdonald.py quote \
  --store 1960151 \
  --basket examples/basket.json

Khi so sánh giá giữa các cửa hàng, cần bảo đảm đang so sánh cùng một sản phẩm và cùng một quy cách. Dự án so sánh tối đa ba cửa hàng được chọn và không suy đoán giá của các cửa hàng khác từ kết quả của một phần cửa hàng.

Cách dùng cơ bản 4: Xem mô hình voxel ngoại tuyến

Nếu hiện chưa có MCP Token, bạn vẫn có thể kiểm tra môi trường kết xuất cục bộ và xem các mô hình tích hợp:

python oh-my-mcdonald/scripts/oh_my_mcdonald.py \
  --out output models

Kết quả tạo ra sẽ được ghi vào thư mục output. Bước này phù hợp để kiểm tra Pillow, NumPy và phông chữ tiếng Trung đã được cấu hình đúng hay chưa.

Sử dụng Skill trong ứng dụng khách AI

Dự án cung cấp oh-my-mcdonald/SKILL.md để mô tả khả năng, quy trình thao tác và giới hạn của dự án cho các ứng dụng khách AI hỗ trợ Skill. Ứng dụng khách cũng cần có khả năng kết nối MCP và thực thi lệnh cục bộ.

Một quy trình điển hình như sau:

1. Người dùng đưa ra yêu cầu bằng ngôn ngữ tự nhiên về ngân sách, khẩu vị, cửa hàng, ưu đãi hoặc dinh dưỡng.
2. AI chọn công cụ MCP tương ứng để lấy dữ liệu nghiệp vụ thực tế.
3. AI lọc kết quả trả về theo ngân sách và điều kiện loại trừ.
4. Khi cần, gọi tập lệnh Python cục bộ để xử lý dữ liệu.
5. Khi cần trực quan hóa, trình kết xuất cục bộ tạo ảnh PNG.
6. Đối với bản ghi ăn uống hoặc ghé cửa hàng, phải chờ người dùng xác nhận rõ ràng trước khi ghi vào bản ghi.

Có thể đưa ra các yêu cầu tương tự sau cho AI:

• Hôm nay ngân sách 35 tệ, không ăn cay, có món nào được đề xuất không?
• Chọn ngẫu nhiên một món ăn thực tế đáp ứng điều kiện.
• So sánh giá suất ăn này tại ba cửa hàng gần đây.
• Xem các phiếu tôi có thể dùng hôm nay và những chương trình gần đây.
• Tính năng lượng và protein của bữa ăn này.
• Tôi xác nhận vừa ăn chiếc hamburger này, hãy giúp tôi ghi lại.
• Tạo một bộ sưu tập hình ảnh từ các món tôi đã ăn.

Các món ăn ứng viên phải đến từ kết quả tra cứu MCP, AI không được tự tạo. Mỗi lần chọn ngẫu nhiên chỉ được sử dụng tối đa sáu tổ hợp món ăn ứng viên.

Mẹo nâng cao và nguyên tắc sử dụng

Trước tiên xác định rõ cửa hàng, sản phẩm và quy cách

Giá chịu ảnh hưởng bởi cửa hàng, quy cách sản phẩm và phương án ưu đãi. Trước khi so sánh, cần cố định sản phẩm và quy cách, đồng thời yêu cầu AI liệt kê rõ các cửa hàng được chọn lần này. Chỉ như vậy kết quả mới có thể so sánh được.

Xử lý nghiêm ngặt dữ liệu dinh dưỡng bị thiếu

Việc tính dinh dưỡng chỉ sử dụng các món ăn được khớp chính xác. Nếu thiếu một số trường dinh dưỡng, cần đánh dấu riêng các mục bị thiếu; không được coi giá trị thiếu là 0, cũng không được dùng sản phẩm có tên tương tự nhưng chưa thể xác nhận để thay thế.

Phân biệt thống kê trong bữa ăn và gợi ý ngoài bữa ăn

Bàn ăn dinh dưỡng có thể hiển thị các gợi ý bổ sung như rau, trái cây và sữa, nhưng giá trị dinh dưỡng của bữa ăn chỉ thống kê các món trên đĩa. Khi diễn giải hình ảnh được tạo, không được cộng các mục tham khảo ngoài bữa ăn vào tổng số.

Yêu cầu người dùng xác nhận trước khi ghi

Lịch sử đơn hàng chỉ có thể được xem là thông tin chờ xác nhận, không thể trực tiếp chứng minh người dùng đã ăn một món nào đó. Chỉ sau khi người dùng xác nhận rõ ràng đã ăn thực tế, dự án mới được lưu bản ghi và thắp sáng bộ sưu tập; bản ghi ghé cửa hàng cũng tuân theo nguyên tắc tương tự.

Hiểu đúng về lịch ưu đãi

Lịch thống kê số lượng phiếu theo ngày hiệu lực của kho phiếu cá nhân. Việc phiếu có thể được sử dụng vào thời gian, tại cửa hàng hoặc cho sản phẩm cụ thể nào vẫn phải dựa trên các điều kiện cụ thể do MCP trả về.

Bảo vệ thông tin xác thực cục bộ

Ưu tiên đọc Token thông qua biến môi trường MCD_MCP_TOKEN hoặc cấu hình Codex cục bộ; không ghi thông tin xác thực vào tập lệnh, JSON mẫu, ảnh chụp màn hình hay tệp được quản lý bởi hệ thống kiểm soát phiên bản.

Chạy kiểm thử tự động

Dự án sử dụng Python unittest, có thể thực thi tại thư mục gốc của kho mã:

python -m unittest discover -s tests -v

README ghi nhận tổng cộng 51 bài kiểm thử hiện có, sử dụng dữ liệu tổng hợp để xác minh logic xử lý nghiệp vụ, đầu ra và kết xuất. Tình trạng xác minh cũng như các giới hạn của truy vấn MCP thực tế được ghi trong docs/VALIDATION.md.

Các giới hạn triển khai cần biết

• Dự án không hỗ trợ tự động đặt hàng, thanh toán hoặc nhận coupon.
• Dự án không cung cấp đồng bộ đám mây và cơ chế truy vấn nền.
• So sánh giá chỉ bao phủ tối đa ba cửa hàng được chọn, và chỉ áp dụng cho cùng một sản phẩm, cùng quy cách và phương án kiểm thử hiện tại.
• Đường phố voxel là bối cảnh minh họa, không bao gồm đường sá thực tế hoặc quan hệ vị trí địa lý.
• Dữ liệu MCP thực tế trong bản xem trước là ảnh chụp tại một ngày cụ thể, không đại diện cho kết quả thời gian thực sau đó.
• Ghi chép ăn uống và ghi chép khám phá cửa hàng đều phải được người dùng xác nhận.

Tổng quan nhanh về cấu trúc dự án

• oh-my-mcdonald/SKILL.md: tệp mô tả Skill dành cho ứng dụng khách AI.
• oh-my-mcdonald/scripts/oh_my_mcdonald.py: tập lệnh hỗ trợ cục bộ và điểm vào lệnh chính.
• oh-my-mcdonald/references/commands.md: tài liệu tham khảo lệnh chi tiết.
• docs/images/: hình ảnh xem trước bối cảnh.
• docs/VALIDATION.md: kết quả xác minh truy vấn thực tế và các giới hạn.
• examples/basket.json: ví dụ JSON giỏ hàng.
• MCP_INTEGRATION.md: mô tả quy trình tích hợp và gọi MCP.
• tests/: kiểm thử tự động.

Lời kết

Oh-My-McDonald kết hợp MCP chính thức của McDonald's, tương tác bằng ngôn ngữ tự nhiên và kết xuất voxel cục bộ, vừa hỗ trợ chọn món, so sánh giá và phân tích dinh dưỡng, vừa xây dựng nhật ký khám phá cá nhân sau khi được xác nhận. Nên hoàn tất kết xuất mô hình ngoại tuyến và kiểm thử trước, sau đó mới cấu hình MCP Token; khi涉及 đến giá, ưu đãi và dinh dưỡng, luôn lấy dữ liệu thực tế do MCP hiện tại trả về làm chuẩn.

Dự án được phát hành mã nguồn mở theo MIT License. Bạn có thể phản hồi vấn đề qua GitHub Issues hoặc gửi Pull Request để tham gia cải thiện.