دليل جامع بطاقات ماكدونالدز: استعمل WorkBuddy لسحب البطاقات، وفحص القيمة الغذائية، وطلب آمن

نظرة عامة على المشروع

جامع بطاقات ماكدونالدز (mcd-gacha-collector) هو WorkBuddy Skill مبني على MCP ديال ماكدونالدز الصين. كيحوّل وجبات ماكدونالدز لبطاقات تقدر تسحبها وتجمعها، وكيبيّن فالبطاقة الثمن، السعرات الحرارية، البروتين، الصوديوم ومستوى الصحة.

المشروع كيستعمل MCP باش يجيب المنيو، المعطيات الغذائية، المحلات والأثمنة فالحين، ومن بعد محرّك Python محلي كيدير تقييم الصحة، تقسيم الندرة، تصفية حسب الميزانية والسحب الموزون. منين كتسحب وجبة قابلة للشراء، تقدر حتى تدير التحقق من الثمن والتأكيد الثاني باش تنشئ طلب حقيقي.

المعطيات الغذائية فالمستودع كتشمل تقريباً 160 وجبة، وحالياً حوض البطاقات فالويب فيه 53 بطاقة مولّدة باستعمال معلومات حقيقية من المنيو. المشروع عمل مشارك فمسابقة، وماشي منتج رسمي ديال ماكدونالدز.

الوظائف الأساسية

• السحب حسب الميزانية: تقدر تطلب بلغة طبيعية بحال «سحب بطاقة وحدة فحدود 50 يوان»، والنظام كيصفّي الثمن قبل ما يدير السحب الموزون.
• التغذية ومستوى الصحة: كيحسب مستوى صحة من 0 حتى 100 اعتماداً على البيانات اللي كيرجعها MCP، وكيعرض السعرات والبروتين والدهون أو الصوديوم وغيرها.
• تصنيف SSR وUR وR: الندرة كتتحدد حسب توزيع مستويات الصحة، وماشي يدوياً. التصنيف النسبي كيقدر يتأقلم مع بنية المنيو ديال كل محل.
• دفتر الجمع المحلي: سجلات السحب كتتحفظ فـ ledger.json، والبطاقات المكررة كتزيد عدد مرات الحصول عليها، وتقدر تجمع متوسط السعرات ومتوسط مستوى الصحة.
• نظام النقط: الـSkill كيرجع تلقائياً فرصة سحب وحدة كل 4 ساعات؛ فالنسخة ديال الويب كاين تحديث يدوي مع فترة انتظار ديال 60 ثانية.
• الطلب الحقيقي: كيتستعمل MCP أولاً للتحقق من الثمن، ومن بعد كيطلب تأكيد واضح من المستخدم، وفالأخير فقط كيتستعمل create-order.
• الاستعمال بلا إنترنت: المستودع فيه بيانات نموذجية، وتقدر تجرّب السحب والجمع ورسم البطاقات بصيغة HTML حتى بلا إعداد MCP Token.
• بلا اعتماديات خارجية: السكريبتات الأساسية كتستعمل مكتبة Python القياسية، وكتحتاج Python 3.8 أو أحدث.

طريقة الاشتغال

المشروع كيتبع مبدأ «خلي MCP يجيب البيانات، وخلي الكود يدير الحسابات، وخلي الـAgent يعبّر». WorkBuddy Agent مسؤول على فهم نية المستخدم، وMCP ديال ماكدونالدز كيوفر البيانات الحقيقية، وgacha.py كيدير الحسابات بشكل حتمي.

المستخدم كيطلب السحب أو معلومات غذائية أو طلب
→ WorkBuddy Agent كيتصل بـMCP ديال ماكدونالدز
→ كيجمع الوقت، المحل، المنيو، الأثمنة والمعطيات الغذائية
→ gacha.py كيحسب مستوى الصحة والندرة وكيجري السحب
→ render.py كينشئ صفحة البطاقة أو دفتر الجمع
→ المستخدم كيختار الشراء
→ calculate-price كيتحقق من الثمن
→ المستخدم كيأكد مرة ثانية
→ create-order كينشئ الطلب

الثمن ومستوى الصحة والندرة ما كيتحسبوش بالتقريب من طرف النموذج اللغوي. الثمن كيرجعو MCP، والتقييم والسحب كيديرهم كود Python، وبهذا كينقص خطر اختلاف الحسابات والأخطاء.

التحضيرات قبل البداية

• ثبّت Python 3.8 أو إصدار أحدث.
• ثبّت WorkBuddy وتأكد بلي تقدر تستعملو.
• وجّد MCP Token ديال ماكدونالدز الصين ويكون قابل للاستعمال؛ إلا كنت غادي تشغّل غير الأمثلة بلا إنترنت، ما ك تحتاجش Token.
• تأكد بلي WorkBuddy يقدر يقرا مجلدات المهارات ديال المستخدم.

الطريقة الأولى: التجربة مباشرة على الإنترنت

إلا كنت باغي غير تشوف الواجهة وتجربة السحب، حلّ صفحة جامع بطاقات ماكدونالدز على الإنترنت. الصفحة غادي تحاول تعرف المدينة من خلال IP، ومن بعد تستعمل خدمة البحث عن المحلات باش تختار محل قريب، بلا ما تحتاج تدخل العنوان يدوياً.

بسبب حدود بيئة الاستضافة، صفحة الويب العمومية ما كتقدرش تحقن MCP Token الشخصي. النسخة الموجودة على الإنترنت مناسبة لتجربة تحديد الموقع والمحلات وواجهة البطاقات؛ أما الطلب الحقيقي فخاصو يتدار فخلفية محلية أو داخل WorkBuddy Skill مكوّن بموصل.

الطريقة الثانية: التثبيت فـWorkBuddy

الخطوة الأولى: نسخ المستودع

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

عنوان المستودع فـREADME فيه اسم بديل. فالتطبيق الفعلي، عوّض YOUR_GITHUB_USER باسم مالك المستودع، أو نسخ مباشرة عنوان الاستنساخ اللي كيعطيه GitHub.

الخطوة الثانية: طلب MCP Token ديال ماكدونالدز

دخل لـمنصة MCP المفتوحة ديال ماكدونالدز، سجّل الدخول برقم الهاتف، فعّل الخدمة من لوحة التحكم ونسخ Token. الـToken معلومة سرية، ما تكتبوش فمستودع عمومي وما ترفعوش لتاريخ Git.

الخطوة الثالثة: إعداد موصل MCP

1. حلّ «الخبراء·المهارات·الموصلات» فالجهة اليسرى ديال WorkBuddy.
2. دخل لـ«الموصلات» واختار «موصل مخصص» من الفوق على اليمين.
3. اختار «إعداد MCP».
4. نسخ محتوى mcp-config.example.json من المستودع.
5. عوّض ${MCD_MCP_TOKEN} بالـToken الحقيقي، أو حقنو باستعمال متغير بيئي.
6. حفظ الإعداد وفعّل الموصل.

من الأحسن تستعمل متغيراً بيئياً لتدبير الـToken. كيفما كانت الطريقة، ما خاصكش ترفع ملف إعداد فيه بيانات اعتماد حقيقية لنظام التحكم فالإصدارات.

الخطوة الرابعة: نسخ الـSkill

فـmacOS أو Linux نفّذ:

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

مجلد مهارات المستخدمين فـWorkBuddy على Windows هو:

%USERPROFILE%\.workbuddy\skills\

وقت النسخ، خاصك تخلي مجلد mcd-gacha-collector كامل، بما فيه SKILL.md والسكريبتات الأساسية والوثائق المرجعية وملفات الموارد.

الخطوة الخامسة: التحقق من التثبيت

رجع لمربع الحوار ديال WorkBuddy وكتب:

سحب ليا بطاقة ديال ماكدونالدز

إلا قدر الـSkill يستعمل أدوات المنيو والتغذية ورجع بطاقة فيها الندرة والثمن والسعرات، فهذا كيعني بلي التثبيت والربط بـMCP خدامين.

طريقة الاستعمال الأساسية

سحب بطاقة حسب الميزانية

سحب ليا وحدة فحدود 50 يوان

الـSkill كيجمع المنيو المتوفر والمعطيات الغذائية ديال المحل الحالي، وكيصفي الوجبات اللي ثمنها ما كيتجاوزش 50 يوان، ومن بعد كيدير السحب الموزون. فالمثال العملي المذكور فـREADME، تْسحبات UR شاي الليمون الأحمر بنكهة الشمس، الحجم المتوسط، بثمن 10 يوان، و117 kcal، ومستوى صحة 63.4.

النتيجة الفعلية كتعلق بمنيو المحل، والثمن الآني، وبنية حوض البطاقات ونتيجة السحب العشوائي، لذلك ما خاصش تعتبر الوجبة أو الثمن اللي فالمثال نتيجة ثابتة.

دير سحب عشرة بطاقات

بغيت عشرة دفعة وحدة

إلا كانت النقط كافية، الـSkill غادي يسحب 10 بطاقات متتابعة ويعرض النتيجة بشكل أكثر تفصيلاً. إلا ما كانوش النقط كافيين، غادي يوضح شحال ناقص من فرصة ووقت الاسترجاع الجاي.

شوف دفتر الجمع

فين هو دفتر الجمع ديالي؟

بيانات الجمع كتتجمع محلياً من ledger.json. النتيجة تقدر تشمل عدد البطاقات المجموعة، وعدد SSR وUR وR، وعدد التكرارات، ومتوسط السعرات ومتوسط مستوى الصحة.

البحث عن المعلومات الغذائية

شحال من سعرة فـBig Mac؟

الـSkill كيقلب على الوجبة باستعمال list-nutrition-foods. النتيجة النموذجية فـREADME هي: Big Mac فيه 513 kcal، و27 غرام بروتين، و26 غرام دهون، و961 مليغرام صوديوم، ومستوى الصحة 32.2، وتصنّف فدرجة R. المعلومات الغذائية خاصها تبقى دائماً معتمدة على البيانات الرسمية اللي كيرجعها MCP فداك الوقت.

البحث عن المحلات القريبة

كاين شي ماكدونالدز قريب؟

النظام كيبدا افتراضياً بتحديد الموقع عبر IP، ومن بعد كيتصل بـquery-nearby-stores بعدما يعرف المدينة، وكيصنف النتائج حسب خانة المسافة اللي كيرجعها MCP. حيث فالتجارب إحداثيات المحلات ممكن تبقى دائماً 0.0، فالمشروع ما كيعتمدش على هاد الإحداثيات باش يحسب المسافة بوحدو.

شوف شحال بقات من نقطة

شحال بقات ليا من فرصة للسحب؟

الـSkill كيقرا النقط من الدفتر المحلي، وكيعطيك العدد المتاح حالياً ووقت الاسترجاع التلقائي الجاي. هاد النقط غير آلية محلية للّعب فهاد المشروع، وما عندها حتى علاقة بحساب النقط الرسمي ديال ماكدونالدز.

إنشاء طلب حقيقي بطريقة آمنة

إلا عجباتك بطاقة سحبتها أو طلبتي الشراء مباشرة، المشروع ما كينشئش الطلب فوراً، بل كيتبع مسار إجباري فيه تأكيد ثاني:

1. اختار المحل والوجبة أو العرض القابل للشراء.
2. استعمل calculate-price باش تجيب الثمن الآني وطرق الاستلام المتاحة.
3. نشئ quoteToken صالح لمدة 15 دقيقة ولمرة وحدة.
4. عرض نتيجة التحقق من الثمن وتسنى تأكيد واضح من المستخدم.
5. الخلفية كتتحقق من الـToken، ومن بعد كتستعمل create-order.
6. رجّع رقم الطلب ورابط الأداء.

create-order خاصو يحمل takeWayCode، وهاد القيمة خاصها تجي من takeWayList اللي كيرجعها calculate-price. ما يمكنش تخمّنها بوحدك أو تحيدها، وإلا ممكن الطلب يرجع 400.

الوجبات الفردية ممكن ما تكونش قابلة للطلب بوحدها فالقائمة اللي تجرّبات. الـREADME كيسجل أن canWithOrder ديال 96 منتج فردي كاملين هو false، لذلك البطاقات الأساسية القابلة للطلب فعلياً هي 18 بطاقة ديال عروض. بطاقات المنتجات الفردية باقية مفيدة للجمع وعرض المعلومات الغذائية.

تجربة سطر الأوامر بلا Token

المستودع فيه sample_data، وتقدر تبدأ بالتحقق من منطق السحب كامل بلا إنترنت. دخل لمجلد السكريبتات:

cd skills/mcd-gacha-collector/scripts

فحص توزيع حوض البطاقات

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

هاد الأمر كيفحص حوض البطاقات النموذجي بميزانية 50 يوان، ومناسب باش تتأكد من البطاقات القابلة للسحب وتوزيع الندرة.

السحب الفردي والعشرة

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 كيحدد مسار الدفتر. إلا استعملتي نفس الملف بشكل متتابع، تقدر تحافظ على النقط وسجل الجمع.

عرض إحصائيات الجمع

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

محاكاة توزيع الاحتمالات

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

التوزيع المستهدف فالعينة هو SSR بنسبة 5%، وUR بنسبة 20%، وR بنسبة 75%. --seed 42 كيخلي النتيجة العشوائية قابلة لإعادة الإنتاج، وهادشي مناسب لتصحيح الأخطاء ومقارنة المخرجات قبل وبعد تعديل الخوارزمية.

رسم HTML ديال البطاقة

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

الـrenderer كيحوّل معطيات الدفتر لملف HTML واحد، باش تقدر تشوف فالمتصفح الكارطات اللي تخرجو فآخر سحب.

تشغيل الاختبار الذاتي

python selftest.py

المنطق الأساسي فيه 105 اختبارات ذاتية. من بعد أي تعديل فالتنقيط أو النقط أو الندرة أو كود سحب الكارطات، خاصك تعاود تشغّل هاد الأمر.

فهم الصحة والندرة

الصحة ديال كل منتوج كتتحسب بوزن ثلاثة ديال الأبعاد:

• كثافة البروتين كتمثل 35%.
• مؤشر السعرات الحرارية المنخفضة كيمثل 40%.
• مؤشر الصوديوم المنخفض كيمثل 25%.

الندرة كتستعمل تصنيف نسبي، وكتحدد عتبات المئينات حسب توزيع المعطيات الحالي. بهاد الطريقة، ماكيبقاش شي محل بلا حتى SSR غير حيث ماعندوش منتوجات عالية التنقيط بحال القهوة. فواحد من مجموعات السحب اللي تقاست فـREADME، من بعد تطبيق المئينات، خرجات 3 ديال SSR و7 ديال UR و13 ديال R.

الوجبات المركبة ماكتستعملش أوزان المنتوجات المفردة مباشرة، حيث مجموع السعرات ديالها كيكون بطبيعتو أعلى. المشروع كيستعمل خوارزمية مستقلة للوجبات المركبة: كثافة البروتين 40%، كثافة الصوديوم 35%، وحمولة السعرات 25%، وكيحسب ليها عتبات المئينات بوحدها.

الصحة والندرة غير للمقارنة والترفيه، وماشي نصيحة طبية أو غذائية أو مهنية من أي نوع.

التطوير المتقدم وتقنيات تصحيح الأخطاء

تحليل معطيات التغذية ديال MCP بالشكل الصحيح

الـdata اللي كيرجعو list-nutrition-foods يقدر يكون نص CSV، وماشي مصفوفة JSON. المشروع كيوفر منطق مخصص للتحليل سميتو parse_nutrition_csv. ملي كتوسّع العميل، ماتفرضش مباشرة باللي القيمة ديما لائحة.

فك غلاف structuredContent

معطيات الأعمال ديال MCP تقدر تكون داخل structuredContent.data، وحتى القيم اللي فيها تقدر تكون قاموس أو لائحة أو نص. ملي كتتعامل مع الرد، خاصك أولاً تحل الغلاف الخارجي، ومن بعد توجّه التحليل حسب النوع الفعلي.

الحفاظ على نفس الخوارزمية بين الواجهة والخلفية

النسخة ديال الويب كتستعمل الحساب فمرحلة البناء: tools/gen_web_data.py كيولّد المعطيات، وweb/build.py كيدمجها داخل صفحة واحدة. الواجهة الأمامية ماكتعاودش تطبق خوارزمية تنقيط أخرى، وبهذا كينقص احتمال الاختلاف بين نتائج الجهتين.

من بعد تعديل توليد المعطيات أو مطابقة الحقول أو قالب الصفحة، تقدر تشغّل tools/parity_check.py. المستودع فيه 99 اختبار ديال التطابق، كيغطي HTML وJavaScript وتوزيع مجموعة السحب وتطابق الحقول.

التحقق من تحليل المحلات فالخلفية

الخلفية كاينة فدليل server، وكتستعمل المكتبة القياسية ديال Python لتحديد الموقع عبر IP، وعميل MCP، وواجهة الطلب. منطق تحليل المحلات عندو حتى هو 15 تأكيد. مع 105 اختبارات ذاتية ديال Skill و99 اختبار ديال الويب، المشروع فيه فالمجموع 219 تأكيد.

ماتعتمدش على إحداثيات المحل

حسب النتائج العملية المذكورة فـREADME، الحقول ديال خطوط العرض والطول اللي كيرجعها query-nearby-stores تقدر تكون كلها 0.0. الاستراتيجية الأكثر أماناً هي تاخذ المدينة أولاً عبر IP، ومن بعد تقلب بالمدينة وكلمات مفتاحية ديال المكان، وترتّب باستعمال distance اللي كترجعها الواجهة.

فرّق بين كارطة للعرض وكارطة قابلة للطلب

الماكلة اللي باينة فالقائمة ماشي بالضرورة تقدر تشريها بوحدها. ملي كتبني وظيفة الشراء، خاصك تتحقق من الحالة القابلة للطلب اللي كيرجعها MCP، ويفضّل توجّه المستخدم لاختيار وجبة مركبة قانونية. ماتستنتجش غير حيث الكارطة قابلة للعرض بأنها تقدر تنشئ طلب.

حماية Token وعمليات الطلب

• الأفضل تدخل Token عبر متغيرات البيئة.
• ماتكتبش Token حقيقي داخل mcp-config.example.json.
• عاود ديما تحسب الثمن قبل إنشاء الطلب.
• تحقق من quoteToken ديال الاستعمال الواحد ومن مدة الصلاحية ديالو.
• عيّط لـcreate-order غير من بعد ما يأكد المستخدم بشكل واضح.
• تعامل بحذر مع الطلبات التجريبية، وتأكد واش خاص تلغيها بسرعة.

شكون مناسب ليه هاد المشروع؟

• المطورين اللي باغين يتعلمو طريقة استعمال MCP ديال ماكدونالدز.
• الممارسين اللي باغين يطوّرو WorkBuddy Agent Skill.
• المستخدمين اللي كيعجبهم جمع الكارطات والسحب ولعبات الألبوم.
• الموظفين أو الطلبة اللي باغين يقارنو السعرات والتركيبة الغذائية ديال الماكلة بطريقة خفيفة.
• المهندسين اللي محتاجين يدرسو تحليل معطيات MCP، وإعادة حساب الثمن، ومسار الطلب الآمن.

الخلاصة

جامع كارطات ماك كيربط البحث فالقائمة، والمقارنة الغذائية، وجمع الكارطات، وإنشاء طلب حقيقي فمسار كامل. فالأول، تقدر تشوف الواجهة عبر الصفحة المتصلة، ومن بعد تشغّل اختبارات سطر الأوامر بمعطيات نموذجية؛ ومنين تتأكد باللي المنطق خدام مزيان، جهّز Token ديال MCP ديال ماكدونالدز وثبّت الـSkill فـWorkBuddy.

فالاستخدام الفعلي، خاصك تنتبه بزاف لاختلاف صيغ المعطيات، والقيود ديال واجهة المحلات، وحالة الوجبة المركبة القابلة للطلب، وآلية التأكيد الثاني. جميع الأثمنة وحالة التوفر ومعلومات الماكلة خاصها تكون دائماً حسب النتائج الآنية من القنوات الرسمية ديال ماكدونالدز.