Hướng dẫn M餐搭子: Tạo ba phương án gọi món McDonald's dựa trên thực đơn theo thời gian thực, ngân sách và mục tiêu dinh dưỡng

M餐搭子 là gì

M餐搭子 là một Skill搭餐 thông minh dựa trên dữ liệu MCP của McDonald's. Bạn chỉ cần nhập thành phố, địa danh, ngân sách, giới hạn calo và mục tiêu protein; công cụ sẽ tìm các cửa hàng gần đó có thể tự nhận món, đối chiếu thực đơn hiện tại với dữ liệu dinh dưỡng và đưa ra ba组合搭餐 có thể thực hiện.

Khác với các công cụ chỉ đề xuất từng món riêng lẻ, M餐搭子 hiển thị giá, calo, protein, mức sử dụng ngân sách, lượng calo còn lại và lý do đề xuất của từng组合. Người dùng cũng có thể mở chuỗi gọi MCP để xem trạng thái và thời gian xử lý của từng Tool.

Dự án tham gia Cuộc thi phát triển sáng tạo dành cho lập trình viên McDonald's năm 2026, nhưng không phải là sản phẩm chính thức của McDonald's. Tình trạng cung ứng món, giá cả và chương trình khuyến mãi phải dựa trên thông tin thực tế từ các kênh chính thức của McDonald's; kết quả đầu ra cũng không cấu thành tư vấn chuyên môn về y tế hoặc dinh dưỡng.

Dự án giải quyết vấn đề gì

Khó khăn khi gọi món thường không đến từ việc thiếu lựa chọn, mà vì thực đơn, thông tin dinh dưỡng, ưu đãi và mục tiêu cá nhân nằm rải rác ở nhiều nơi. Người dùng vừa phải kiểm soát ngân sách và calo, vừa có thể muốn tăng lượng protein, rồi còn phải đánh giá xem组合 đã đầy đủ hay chưa.

Ý tưởng của M餐搭子 là trước tiên để người dùng xác định giới hạn cho bữa ăn, sau đó tính toán kết quả từ thực đơn thực tế, thay vì yêu cầu người dùng quyết định món cụ thể ngay từ đầu. Công cụ tích hợp giá thực đơn, dữ liệu dinh dưỡng và thông tin ưu đãi vào cùng một giao diện, giúp quá trình đề xuất dễ hiểu và dễ kiểm chứng hơn.

Năng lực cốt lõi

• Tra cứu cửa hàng theo thời gian thực: sử dụng query-nearby-stores để tìm các cửa hàng gần đó có thể tự nhận món theo thành phố và địa danh.
• Đọc thực đơn theo thời gian thực: sử dụng query-meals để lấy giá, giá gốc, hình ảnh món và nhãn của cửa hàng hiện tại.
• Đối chiếu dinh dưỡng: sử dụng list-nutrition-foods để đối chiếu món trong thực đơn với dữ liệu calo và protein.
• Ba kết quả搭餐: lần lượt trả về “Lựa chọn cân bằng”, “Tăng cường protein” và “搭餐 tiện lợi”, tránh chỉ đưa ra một đáp án hộp đen.
• Chỉ số dễ giải thích: hiển thị protein trên mỗi đơn vị tiền, mức sử dụng ngân sách, lượng calo còn lại và chênh lệch ưu đãi.
• Ưu đãi và chương trình: gọi available-coupons và campaign-calendar để tập trung hiển thị phiếu giảm giá có thể nhận và các chương trình sắp tới.
• Truy xuất được lịch sử gọi: người dùng có thể xem trạng thái và thời gian xử lý của MCP Tool.
• Hạ cấp an toàn: khi chưa cấu hình Token hoặc Tool tạm thời không khả dụng, hệ thống sẽ sử dụng ảnh chụp dữ liệu demo đã khử nhận dạng và được đánh dấu rõ ràng.

Chuẩn bị trước khi chạy

Phiên bản MCP thời gian thực cần chạy dịch vụ Node trong kho lưu trữ cục bộ. Trước khi bắt đầu, hãy chuẩn bị môi trường sau:

• Node.js 20 trở lên
• npm 10 trở lên
• Một MCP Token của McDonald's; nếu chỉ trải nghiệm dữ liệu demo thì không cần cung cấp

Nếu tạm thời không muốn cài đặt, bạn cũng có thể truy cập bản demo trực tuyến trên GitHub Pages. Đây là bản demo thuần frontend, hỗ trợ đầy đủ việc điều chỉnh điều kiện và tính toán搭餐, nhưng sử dụng ảnh chụp thực đơn đã khử nhận dạng thay vì dữ liệu MCP thời gian thực.

Cài đặt và cấu hình

Bước 1: Sao chép kho lưu trữ và cài đặt dependency

Thực thi các lệnh sau trong terminal. Hãy thay placeholder địa chỉ kho lưu trữ bằng địa chỉ thực tế:

git clone <your-repository-url>
cd mcd-meal-mate
npm install
cp .env.example .env

Bước 2: Cấu hình biến môi trường

Mở tệp .env trong thư mục gốc của dự án, rồi ghi MCP Token và cổng dịch vụ:

MCD_MCP_TOKEN=YOUR_MCD_MCP_TOKEN
PORT=8787

• MCD_MCP_TOKEN không bắt buộc. Sau khi cấu hình, MCP thời gian thực sẽ được bật; nếu không cấu hình thì sử dụng dữ liệu demo.
• PORT không bắt buộc, giá trị mặc định là 8787.

MCP Token chỉ nên được đặt trong biến môi trường phía máy chủ; không ghi vào mã frontend và không commit vào kho lưu trữ công khai.

Bước 3: Khởi động môi trường phát triển

npm run dev

Sau khi khởi động, truy cập http://localhost:5173 trong trình duyệt. Lệnh phát triển sẽ chạy Express API và bật tính năng cập nhật nóng của Vite, phù hợp để gỡ lỗi giao diện và logic phía máy chủ.

Chế độ demo không cấu hình Token

Nếu không có MCP Token của McDonald's, bạn có thể build và khởi động phiên bản production:

npm install
npm run build
npm start

Sau đó truy cập http://localhost:8787. Khi đó trang sẽ hiển thị rõ “Dữ liệu demo”; thực đơn, giá và chương trình đều lấy từ ảnh chụp dữ liệu đã khử nhận dạng.

Chế độ demo phù hợp để kiểm tra quy trình tương tác, các ràng buộc đầu vào và ba kết quả搭餐, nhưng không đại diện cho tình trạng cung ứng, giá hoặc chương trình theo thời gian thực của cửa hàng hiện tại. Khi sử dụng thực tế, cần lấy dữ liệu do cửa hàng mục tiêu trả về làm chuẩn.

Sử dụng cơ bản: Tạo ba phương án搭餐

Bước 1: Chọn tùy chọn

Sau khi vào giao diện làm việc, bạn có thể chọn tùy chọn như “Cân bằng”. Tùy chọn sẽ tham gia vào việc chấm điểm组合, nhưng kết quả vẫn chịu ràng buộc bởi ngân sách, calo và mục tiêu protein.

Bước 2: Nhập điều kiện dùng bữa

Bạn có thể bắt đầu với nhóm điều kiện mẫu sau:

Thành phố: Thượng Hải
Khu thương mại / Địa danh: Quảng trường Nhân Dân
Ngân sách: 35 nhân dân tệ
Giới hạn calo: 700 kcal
Mục tiêu protein: 35 g

Bước 3: Xem kết quả tính toán

Máy chủ sẽ tìm các cửa hàng gần đó, đọc thực đơn và dữ liệu dinh dưỡng, sau đó trả về ba loại phương án:

1. Phương án A: Lựa chọn cân bằng. Cung cấp món chính cùng món ăn nhẹ hoặc đồ uống trong giới hạn ngân sách và calo, đồng thời hiển thị protein, protein trên mỗi đơn vị tiền và lý do đề xuất.
2. Phương án B: Tăng cường protein. Ưu tiên tăng protein, đồng thời cố gắng duy trì giới hạn ngân sách và calo.
3. Phương án C: 搭餐 tiện lợi. Cung cấp组合 có giá thấp hơn nhưng vẫn đầy đủ, phù hợp với các tình huống coi trọng chi phí và hiệu quả lựa chọn hơn.

Khi so sánh các phương án, đừng chỉ nhìn vào tổng lượng protein. Bạn cũng có thể kết hợp protein trên mỗi đơn vị tiền, ngân sách còn lại, lượng calo còn lại và chênh lệch ưu đãi để đánh giá kết quả nào phù hợp hơn với nhu cầu hiện tại.

Bước 4: Kiểm tra chuỗi gọi MCP

Mở “Chuỗi gọi MCP” để xem trạng thái và thời gian xử lý của các Tool về cửa hàng, thực đơn, dinh dưỡng, ưu đãi và chương trình. Điều này giúp xác định đề xuất dựa trên dữ liệu trả về theo thời gian thực hay đã chuyển sang ảnh chụp dữ liệu demo do thiếu Token hoặc Tool không khả dụng.

Các lệnh phát triển thường dùng

• npm run dev: khởi động Express API và cập nhật nóng của Vite.
• npm run build: build frontend và biên dịch phía máy chủ.
• npm start: khởi động dịch vụ production.
• npm test: chạy các bài kiểm tra logic组合 và phân tích dinh dưỡng.
• npm run check: lần lượt thực hiện kiểm tra kiểu, kiểm tra biên dịch phía máy chủ và kiểm thử.

Sau khi sửa phần phân tích dinh dưỡng, ánh xạ thực đơn hoặc quy tắc搭餐, nên ít nhất thực thi:

npm test
npm run check

Nhờ đó có thể sớm phát hiện lỗi kiểu, vấn đề biên dịch cũng như hồi quy trong các ràng buộc组合 hoặc phân tích dinh dưỡng.

Triển khai bằng Docker

Dự án cung cấp cách build bằng Docker. Trước tiên hãy tạo image:

docker build -t mcd-meal-mate .

Sau đó ánh xạ cổng 8787 của máy chủ vào container và truyền Token qua biến môi trường:

docker run --rm -p 8787:8787 \
  -e MCD_MCP_TOKEN="YOUR_MCD_MCP_TOKEN" \
  mcd-meal-mate

Sau khi container khởi động, có thể truy cập http://localhost:8787. Nếu bỏ qua MCD_MCP_TOKEN, ứng dụng sẽ sử dụng dữ liệu demo.

Tìm hiểu cấu trúc dự án

Dự án tách frontend React, dịch vụ Express, lệnh gọi MCP, phân tích dinh dưỡng và lập kế hoạch组合 thành các module khác nhau:

src/
  App.tsx          Giao diện làm việc React và tương tác responsive
  styles.css       Hệ thống giao diện thực đơn biên tập × hóa đơn
server/
  index.ts         Express API, kiểm tra đầu vào và tài nguyên tĩnh
  mcp.ts           MCP JSON-RPC client, điều phối Tool và hạ cấp
  nutrition.ts     Phân tích văn bản dinh dưỡng, ánh xạ thực đơn và nhận diện vai trò món
  planner.ts       Ràng buộc组合, chấm điểm tùy chọn và lựa chọn ba phương án
  demo-data.ts     Ảnh chụp dữ liệu demo đã khử nhận dạng
  planner.test.ts  Kiểm thử dinh dưỡng và组合
shared/
  types.ts         Kiểu dùng chung giữa frontend và backend

server/mcp.ts phụ trách giao tiếp MCP JSON-RPC, điều phối Tool và hạ cấp khi lỗi; server/nutrition.ts xử lý ánh xạ giữa văn bản dinh dưỡng và món trong thực đơn; server/planner.ts thực hiện các ràng buộc组合, chấm điểm tùy chọn và lựa chọn ba phương án. Cấu trúc dữ liệu dùng chung giữa frontend và backend nằm trong shared/types.ts.

Backend sử dụng fetch gốc để giao tiếp với McDonald's MCP Streamable HTTP Server. Trong bản build production, cùng một tiến trình Express đồng thời cung cấp API và trang tĩnh, đồng thời lưu bộ nhớ đệm kết quả thực đơn và dinh dưỡng trong bộ nhớ.

Sử dụng nâng cao và đề xuất phát triển

Ưu tiên kiểm tra kết quả từ các điều kiện ràng buộc

Nếu không nhận được组合 như mong đợi, trước tiên hãy kiểm tra xem ngân sách, giới hạn calo và mục tiêu protein có quá nghiêm ngặt hay không. Công cụ搭餐 phải đồng thời đáp ứng nhiều giới hạn, nên các mục tiêu có thể xung đột với nhau. Tăng ngân sách, nâng giới hạn calo hoặc giảm mục tiêu protein phù hợp sẽ giúp có thêm nhiều组合 khả thi.

Phân biệt dữ liệu thời gian thực và ảnh chụp demo

Khi gỡ lỗi, cần xác nhận trang có hiển thị “Dữ liệu demo” hay không và xem chuỗi gọi MCP. Khi không có Token, Tool tạm thời không khả dụng hoặc chạy phiên bản GitHub Pages thuần frontend, kết quả đều có thể đến từ ảnh chụp dữ liệu đã khử nhận dạng.

Bảo vệ thông tin xác thực phía máy chủ

Không đưa Token vào trình duyệt. Dự án đã đọc biến môi trường thông qua dịch vụ Express và gọi MCP từ phía máy chủ, qua đó tránh để Token bị lộ cho frontend ở cấp độ kiến trúc. Khi triển khai lên máy chủ hoặc container, cũng cần truyền thông tin xác thực thông qua phương thức quản lý biến môi trường an toàn.

Chạy kiểm tra đầy đủ sau khi sửa logic lập kế hoạch

Nếu điều chỉnh planner.ts, nutrition.ts hoặc kiểu dùng chung, hãy sử dụng npm run check để kiểm tra kiểu, biên dịch và kiểm thử. Dự án đã có các bài kiểm tra组合 và phân tích dinh dưỡng, giúp xác minh thay đổi có ảnh hưởng đến hành vi hiện có hay không.

Tham khảo tài liệu tích hợp

MCP_INTEGRATION.md trong kho lưu trữ ghi lại đầy đủ các Tool, quy trình gọi, giá trị nghiệp vụ và ranh giới an toàn; mcp-config.example.json cung cấp ví dụ cấu hình đã khử nhận dạng; workbuddy.md chứa ngữ cảnh liên kết WorkBuddy và các lệnh có thể tái hiện. Khi tích hợp Agent hoặc Skill khác, có thể ưu tiên tham khảo các tệp này.

Ranh giới an toàn

• Kho lưu trữ không chứa Token, mật khẩu hoặc thông tin xác thực tài khoản thực.
• MCP Token chỉ được đọc từ biến môi trường phía máy chủ.
• Dự án không gọi các Tool đặt hàng, thanh toán, rút thăm hoặc đổi điểm.
• Máy chủ không lưu dữ liệu người dùng nhập và không xây dựng hồ sơ người dùng.
• Tình trạng cung ứng món, giá cả và chương trình được xác định theo các kênh chính thức của McDonald's.
• Kết quả đề xuất không cấu thành tư vấn chuyên môn về y tế, dinh dưỡng hoặc lĩnh vực khác.

Tổng kết

M餐搭子 tích hợp tra cứu cửa hàng, thực đơn theo thời gian thực, đối chiếu dinh dưỡng, thông tin ưu đãi và lập kế hoạch kết hợp thành một quy trình chọn món có thể giải thích. Sau khi cấu hình MCP Token, công cụ có thể sử dụng dữ liệu cửa hàng hiện tại; khi không có Token, bạn vẫn có thể trải nghiệm đầy đủ tương tác thông qua bản chụp nhanh đã khử định danh.

Sau khi cài đặt xong, bạn có thể bắt đầu bằng cách dùng các điều kiện mẫu để kiểm tra ba phương án, sau đó xác nhận nguồn dữ liệu thông qua chuỗi gọi MCP. Các nhà phát triển có thể bắt đầu từ mcp.ts, nutrition.ts và planner.ts để tìm hiểu cách triển khai điều phối dữ liệu thời gian thực, ánh xạ dinh dưỡng và tính toán ràng buộc.