Repo này làm gì, giải quyết vấn đề gì
Đây là một CLI Python đọc dữ liệu đơn hàng McDonald’s của bạn qua MCP API (McDonald’s Trung Quốc), rồi sinh ra ba thứ bằng code: một trang “niên báo” (annual report) dạng HTML có animation, một tấm danh thiếp (identity card), và một avatar. Cả ba đóng gói từ cùng một “danh tính” do hệ thống tự tính.
Vấn đề nó giải quyết khá rõ: lịch sử ăn uống của bạn là dữ liệu chết trong app, không ai muốn nhìn một bảng danh sách đơn hàng. Repo này biến dữ liệu đó thành một câu chuyện “tu tiên” phương Đông, với các cảnh giới như “初识” (mới biết), “宗师” (tông sư), “登仙” (lên tiên), “神境” (cảnh thần). Bạn nhận được một nhân vật nam hoặc nữ tương ứng cấp bậc, có “门 phái” (môn phái) tùy vào loại đồ ăn, và một tấm ảnh đại diện hoàn chỉnh.
Cơ chế tính “阅历” (kinh nghiệm) có công thức công khai:
阅历 = 完成订单数 × 2 + min(有记录月份, 12) + min(餐品种类, 12)
Chỉ đếm đơn đã hoàn thành, đã dedupe. Số tiền và giới tính không tham gia vào điểm. Các tác giả ghi thẳng trong README rằng đây là “quy tắc sinh điểm cho thế giới hư cấu, không phải đánh giá thực tế”. Kiểu minh bạch này đáng giữ.
Vì sao nó đang hot
Repo có 499 sao, tạo ngày 2026-10-19 và cập nhật cùng ngày. Nó mới ra lò, chưa có commit lịch sử dài. Gần 500 sao trong thời gian ngắn thường đến từ hai lý do: nội dung dễ lan truyền trên mạng xã hội, và bối cảnh “cuộc thi sáng tạo lập trình của McDonald’s” (theo README: 麦当劳程序员创意开发大赛独立参赛作品).
Khác với mấy repo “wrap API thành app” khác ở chỗ: 18 ảnh nhân vật (nam 9 cấp, nữ 9 cấp) đã được vẽ sẵn và đóng gói trong repo. Bạn dùng hàng ngày không cần gọi model sinh ảnh. Mỗi ảnh 1254×1254, theo phong cách “graffiti đỏ vàng, nét đen đậm”, áo có logo chữ M nhỏ. Ảnh cấp thấp thì đơn giản, cấp cao thì thêm phụ kiện tóc, dải bay, vòng sáng. Cái này tiết kiệm một mớ token và tránh được kiểu “mỗi lần một khuôn mặt khác nhau”.
Animation trong HTML làm bằng browser native (Intersection Observer, Web Animations API), không kéo GSAP. HTML tự chứa mọi thứ, không CDN, không font remote, mở offline double-click là chạy. Với dev khó tính, mấy chi tiết này tạo cảm giác người viết biết mình đang làm gì.
Cài đặt và dùng thử nhanh
Yêu cầu Python 3.9+, và Node 20+ nếu muốn xuất PNG:
npm ci
# Đã cài Chrome/Chromium thì bỏ qua; có thể set CHROME_PATH
npx playwright install chromiumToken lấy từ MCP open platform của McDonald’s Trung Quốc. Có thể điền vào .env:
MCD_MCP_TOKEN=YOUR_MCP_TOKENCác lệnh chính, giữ nguyên như README:
# Xem menu khi chưa có token
PYTHONPATH=src python3 -m mcd_life_kit.cli
# Sinh cả bộ ba, chỉ query data 1 lần, dùng chung identity
PYTHONPATH=src python3 -m mcd_life_kit.cli all --gender male --nickname 麦门同学
# Sinh lẻ
PYTHONPATH=src python3 -m mcd_life_kit.cli annual-report --gender female
PYTHONPATH=src python3 -m mcd_life_kit.cli identity-card --gender male
PYTHONPATH=src python3 -m mcd_life_kit.cli avatar --gender male
# Demo bằng synthetic data, không cần token
npm run visual:demo
# Bỏ qua bước screenshot HTML, không cần Node
PYTHONPATH=src python3 -m mcd_life_kit.cli all --html-only --mock --year 2026Output mặc định vào out/maimen/ với các file annual-report.html/.png, identity-card.html/.png, avatar.html/.png, kèm identity.json và report-data.json. PNG rộng 1080px, avatar giữ nguyên 1254×1254.
Về bảo mật, repo có mấy lựa chọn đáng dùng: --token-stdin để nhập token ẩn không ghi file, --env-file để cách ly tài khoản (không đọc fallback khi file chỉ định bị lỗi), và .env / mcd-token.env / out/ đều đã nằm trong .gitignore. Có kèm test cho HTML injection, điều mà nhiều repo demo bỏ qua.
Ai nên dùng, dùng thế nào
Đối tượng rõ ràng nhất: dev Việt (hoặc bất kỳ ai) đang dùng McDonald’s Trung Quốc qua app, tò mò không biết mình đã đặt bao nhiêu đơn, thích mấy kiểu “Wrapped của Spotify” nhưng muốn một bản cá nhân hóa sâu hơn. Bạn chạy lệnh, nhận về một trang HTML có animation cuộn mở, có parallax, có số liệu đếm lên, có biểu đồ, và một nhân vật đại diện. Share lên story hoặc gửi cho bạn bè.
Case thứ hai: làm quà tặng. Nếu bạn biết ai đó nghiện McDonald’s, chạy hộ họ, xuất identity card, in ra hoặc gửi file. Cái này dễ thương hơn một voucher.
Case thứ ba, dành cho ai quan tâm MCP: repo này là một ví dụ tham khảo khá đầy đủ về việc viết skill cho Agent dùng MCP. Có SKILL.md, có flow hỏi token, flow chọn nội dung, flow gender, và nguyên tắc “không tự bịa username khi API không trả về”. Đọc cho vui cũng học được cách thiết kế prompt flow cho agent.
Case thứ tư: nếu bạn muốn một ví dụ về “code generate design” (vẽ hamburger, vẽ crest bằng code, không dùng ảnh có sẵn trừ nhân vật) thì đây là tài liệu tham khảo tốt.
Ưu điểm và hạn chế
Ưu điểm đáng kể nhất: 18 ảnh nhân vật đóng gói sẵn, dùng không cần gọi model. HTML self-contained. Test coverage có nhiều lớp (npm test, test:report, test:visual). Có mock mode, không bắt buộc phải có token thật để thử. Có xử lý các case khó như package split, dedupe, precision của số tiền, HTML injection.
Hạn chế cần biết trước khi nhảy vào:
- License ghi “không rõ” trên GitHub, dù README có dòng “MIT” cuối bài và file
CONTEST_DECLARATION.md. Kiểu này hay gặp với repo dự thi, bạn nên liên hệ tác giả nếu định dùng thương mại. Đừng mặc định là MIT chỉ vì README ghi vậy. - Phụ thuộc MCP của McDonald’s Trung Quốc. Nếu API đổi shape, đổi auth, hoặc bạn không ở Trung Quốc thì gần như không dùng được với dữ liệu thật. Repo mới tạo ngày 2026-10-19, chưa có lịch sử chứng minh độ bền theo thời gian.
- Chỉ đọc được “đơn gần đây”, không đảm bảo đủ cả năm. README ghi thẳng “年份 chỉ là filter local, báo cáo ghi rõ ‘đơn hàng nhìn thấy lần này'”. Thành thật, nhưng người dùng cần hiểu trước khi khoe điểm “麦门真神”.
- Không có tính năng gợi ý món hay đặt hàng. Tác giả ghi rõ “chỉ làm visual identity, không cung cấp quyết định ăn uống hay giao dịch”. Đừng kỳ vọng nhiều hơn.
- Chưa có topics trên repo, chưa có release, chưa có issue history. Với dự án mới ra, đây là trạng thái bình thường, nhưng bạn nên tự đọc source trước khi chạy trên máy có dữ liệu thật.
Kết luận
Một dự án nhỏ, mục tiêu hẹp, nhưng làm kỹ ở đúng chỗ: 18 ảnh nhân vật đóng gói sẵn kèm manifest JSON, HTML không phụ thuộc mạng, có mock mode và test cho HTML injection. Nếu bạn ở Trung Quốc và dùng app McDonald’s, đây là cách rẻ nhất để biến lịch sử đơn hàng của mình thành thứ gì đó đáng nhìn. Nếu bạn ở nơi khác, đọc code để học cách viết skill cho MCP và cách generate report bằng Python vẫn đáng. Repo đây: timhengc/mai-shen-zai-ci.
