شرح McButler: استعمل MCP ديال ماكدونالدز للتوصيات، تحليل القيمة الغذائية، مقارنة الأثمنة بين الفروع وتجهيز طلبات المجموعات

شنو هو McButler

McButler (الوكيل الذاتي ديال ماكدونالدز) هو مشروع كيساعد فاختيار الطلبات، مبني على MCP الرسمي ديال ماكدونالدز. ماشي غير كيقترح وجبات حسب الثمن، بل كيحاول يعالج فآن واحد قيود الميزانية، الصحة، الوقت، الممنوعات الغذائية والتفضيلات الشخصية.

المشروع يقدر يخدم كـ WorkBuddy Skill، ويقدر حتى يخدم عبر CLI محلي باستعمال بيانات العرض المدمجة. والمطورين يقدرو يعاودو يستعملو وحدات تحليل البيانات والتنقيط ديالو، ويدخلو البيانات اللي كيرجعها MCP ديال ماكدونالدز فعميل ديالهم.

مستودع المشروع كاين فـ GitHub، وصفحة التجربة على الإنترنت ديال مسرح ماك متوفرة حتى هي. خاص الانتباه أن McButler مشروع مستقل مشارك فالمسابقة، وماشي منتوج رسمي ديال ماكدونالدز.

ستة ديال القدرات الأساسية

1. الاقتراح اليومي

recommend كيدعم ثلاثة ديال الأوضاع: التوفير، الصحة والشعبية. كل وضع كيستعمل منطق مختلف فالترتيب، وماشي غير تبديل خانة وحدة ديال الترتيب.

• وضع التوفير: كيجمع بين القيمة الموحدة للثمن، نسبة التخفيض والثمن لكل 100 kcal، باش ما تطلعش الوجبات الصغيرة اللولة غير حيث الثمن الإجمالي ديالها منخفض.
• الوضع الصحي: كيجمع بين النقطة الصحية ومدى ملاءمة الطاقة، وكيعطي الأولوية للمرشحين اللي عندهم بيانات غذائية مقاسة فعلياً.
• وضع الشعبية: كيجمع بين وسم الوجبات الرائجة، معلومات الطلبات المتكررة تاريخياً والتخفيضات.

2. الفحص الصحي

health هو القلب التقني ديال المشروع. حيث إن واجهة التغذية كتقدم بيانات ديال كل منتوج بوحدو، McButler كيقرا الأول تفاصيل الوجبة، كيفككها للمكونات الافتراضية، ومن بعد كيطابق كل مكون مع جدول التغذية وكيجمع بيانات السعرات، البروتين، الدهون، الصوديوم والكالسيوم وغيرها.

تفاصيل الوجبة
→ قرا المكونات الافتراضية
→ طابق البيانات الغذائية ديال كل منتوج
→ جمع القيم الغذائية
→ حسب النقطة الصحية وعناصر الخصم

التنقيط الصحي كيعتمد على 100 نقطة، وكيحسب نطاق الطاقة، البروتين، نسبة الطاقة اللي جاية من الدهون، الصوديوم، عبء السكر والزيوت، وزيادة الخضر والفواكه. الصيغة المفصلة تقدر تلقاها فـ references/model-spec.md داخل المستودع.

3. مقارنة التكلفة الكاملة ديال المحلات

stores كيقدر يختار المحل حسب الأقرب، الأرخص أو التكلفة الكاملة الإجمالية. الوضع الشامل ما كيشوفش غير ثمن المنتوج، بل كيحوّل حتى مسافة الذهاب والإياب، وقت المشي ووقت الانتظار لتكلفة.

التكلفة الكاملة = ثمن المنتوج
       + تكلفة المسافة (0.5 يوان/km ذهاباً وإياباً)
       + تكلفة الوقت (وقت المشي ذهاباً وإياباً + وقت الانتظار) × 0.30 يوان/الدقيقة

لهذا، المحل الأقرب ماشي بالضرورة هو الأكثر توفيراً. وقت الانتظار ما كتقدموش حالياً واجهة MCP مباشرة، وخص المستخدم يدخلو أو يقدرو بالتخمين.

4. إعداد وجبات جماعية

bulk موجه لطلبات الإدارة، الموارد البشرية، الأقسام والفرق. كيقدر يقسم الناس لمجموعات ويختار ليهم الوجبات حسب العدد، ميزانية الفرد، اللي ما كياكلوش اللحم البقري واللي ما كياكلوش الحار، وكيخرج orderItems اللي يقدر يتبعث من بعد لمسار حساب الثمن.

النتيجة كتتضمن عدد الأشخاص فكل مجموعة، عدد الوجبات، الثمن الإجمالي، ثمن الفرد، مبلغ التوفير ومتوسط السعرات لكل فرد. ولكن شرط «ما كياكلش اللحم البقري» كيعتمد حالياً على تصفية الكلمات المفتاحية فأسامي الأطباق، وما كيضمنش التعرف على المكونات اللي ما مذكوراش بوضوح فالمنيو.

5. نقطة مخاطر ماك

credit مستوحى من بطاقات تنقيط الائتمان الاستهلاكي، وكيحسب للحساب ولكل طلب بوحدو نقطة مخاطر ماك بين 300 و950. الأبعاد الستة هي استقرار الوفاء بالطلبات، إيقاع الاستهلاك، الانضباط فالميزانية، الاستفادة من العروض، أصول الحساب وتنوع الأذواق.

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

6. مسرح ماك

theater كينشئ نقاشاً حول الطلب بين خمسة شخصيات اعتماداً على القسائم، نقطة مخاطر ماك وبيانات السعرات، وكيخرج صفحة HTML فملف واحد. الصفحة الناتجة ما كتحتاج حتى اعتماد إضافي، وتقدر تفتحها مباشرة فالمتصفح.

تحضير بيئة التشغيل

الوضع المحلي كيحتاج غير Python 3.8 أو نسخة أحدث، وكيستعمل مكتبة Python القياسية فقط، بلا ما تحتاج تثبت حزم خارجية. أما وضع MCP على الإنترنت فكيحتاج MCP Token صالح.

نسخ المستودع وتشغيل الاختبار الذاتي

git clone https://github.com/jouaaaaaa/mcd-self-butler.git
cd mcd-self-butler
python scripts/selftest.py

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

الطريقة الأولى: تثبيتو كـ Skill فـ WorkBuddy

1. حط SKILL.md وscripts/ وreferences/ ديال المستودع فالمجلد التالي:

   ~/.workbuddy/skills/mcd-self-butler/

2. فـ WorkBuddy دخل لـ «الخبراء·المهارات·الروابط»، ومن بعد اختار بالترتيب «الروابط» و«الروابط المخصصة» و«إعداد MCP».

3. عمر إعداد Streamable HTTP ديال MCP ديال ماكدونالدز، وبدل الرمز النائب بالتوكن ديالك:

   {
     "mcpServers": {
       "mcd-mcp": {
         "type": "streamablehttp",
         "url": "https://mcp.mcd.cn",
         "headers": {
           "Authorization": "Bearer 你的_MCP_TOKEN"
         }
       }
     }
   }

4. فعّل الرابط mcd-mcp، ومن بعد قدم الطلب ديالك باللغة الطبيعية.

تقدر تبدا بهاد الطلبات:

• «أنا فطريق نانجينغ الغربية، شنو هو أقرب ماكدونالدز اللي نقدر نشري منو وجبة بيغ ماك من ثلاثة أجزاء بأحسن ثمن؟»
• «عاونّي نشوف شحال من سعرة فهاد الوجبة، واش كاين تبديل صحي أكثر؟»
• «طلب جماعي للقسم فيه 30 شخص، 30 يوان للفرد، و5 أشخاص ما كياكلوش اللحم البقري.»
• «شحال هي نقطة مخاطر ماك ديالي؟»
• «ملّيت وأنا كنتسنى الوجبة، خليهم يتشاجرو شوية.»

الطريقة الثانية: استعمال CLI المحلي

الـ CLI المحلي كيستعمل لقطة العرض الموجودة فالمستودع، وما كيحتاج لا Token لا اتصال بالإنترنت. القدرات الستة كاملين كيتستدعاو عبر scripts/mcd_butler.py.

فحص القيمة الغذائية ديال الوجبة

python scripts/mcd_butler.py health \
  --nutrition demo/nutrition.txt \
  --combo demo/combo_9900011128.json

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

الحصول على اقتراح صحي

python scripts/mcd_butler.py recommend \
  --menu demo/menu_1450118.json \
  --nutrition demo/nutrition.txt \
  --mode healthy \
  --meal lunch \
  --budget 45 \
  --top 5 \
  --details demo/details.json

--mode healthy كيعني استعمال الوضع الصحي، و--meal lunch كيعين سياق الغداء، و--budget 45 كيحدد الميزانية فـ 45 يوان، و--top 5 كيرجع أول خمس نتائج.

إلى بغيتي تجرب استراتيجيات أخرى، تقدر تبدل لمنطق التوفير أو الشعبية حسب الأوضاع اللي كيدعمها CLI. النتائج ديال الأوضاع المختلفة تقدر تختلف بشكل واضح، حيث كل واحد كيستعمل دالة قيمة مختلفة.

حساب نقطة مخاطر ماك

python scripts/mcd_butler.py credit \
  --orders demo/orders.json \
  --account demo/account.json \
  --coupons demo/coupons.md \
  --nutrition demo/nutrition.txt

هاد الأمر كيجمع بين الطلبات السابقة، معلومات الحساب، القسائم والبيانات الغذائية، وكيخرج المجموع، التصنيف وتفاصيل الأبعاد الستة. النتيجة النموذجية فبيانات العرض هي 771 نقطة، بتصنيف مستوى بيغ ماك، ولكن النقطة الفعلية كتتوقف على البيانات المدخلة.

إعداد وجبات جماعية لـ 30 شخص

python scripts/mcd_butler.py bulk \
  --menu demo/menu_1450118.json \
  --nutrition demo/nutrition.txt \
  --headcount 30 \
  --budget 30 \
  --no-beef 5 \
  --no-spicy 4

هنا تحدد 30 شخص، ميزانية 30 يوان للفرد، 5 أشخاص ما كياكلوش اللحم البقري و4 ما كياكلوش الحار. البرنامج كيقسم الناس لمجموعات وكيختار الوجبات، وكيولد عناصر طلب يمكن حساب الكميات ديالها.

مقارنة التكلفة الكاملة ديال المحلات

python scripts/mcd_butler.py stores \
  --stores demo/stores.json \
  --mode balanced

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

توليد مسرح ماك

python scripts/mcd_butler.py theater \
  --context demo/theater_context.json \
  --out theater.html

من بعد التشغيل، غادي يتولد theater.html فالمجلد الحالي. فتحو مباشرة فالمتصفح باش تشوف حوار الشخصيات، فقاعات الكلام كلمة بكلمة والقرار النهائي.

الطريقة الثالثة: الربط بعميل MCP ديالك

المطورين يقدرو يستعملو جوج طرق للدمج.

1. حفظ الاستجابة الأصلية: عيط فعميل MCP على أدوات المحلات، المنيو، التفاصيل، التغذية، حساب الثمن، القسائم أو الطلبات، وحفظ الاستجابة الأصلية فملفات كتستعمل لنفس الغرض ديال أمثلة demo/، ومن بعد خلي CLI يعالجها.
2. استدعاء الوحدات مباشرة: استورد الدوال الموجودة فـ scripts/lib/، ودوز ليها مباشرة كائن Python dict اللي رجعو MCP.

طبقة تحميل البيانات mcdata.py كتقبل فآن واحد الاستجابة الأصلية ديال MCP اللي على شكل {"success": true, "data": ...} والصيغة المختصرة اليدوية. لذلك غالباً تقدر تحفظ استجابة الأداة مباشرة، بلا ما تحتاج تنقيها يدوياً قبل.

فهم بنية المشروع

مسار معالجة McButler يمكن نلخصوه فـ أربعة طبقات:

1. طبقة العميل: WorkBuddy Agent أو أي عميل MCP آخر كيبدا الطلب.
2. طبقة خدمة MCP: كتجيب بيانات المحلات، المنيو، التفاصيل، التغذية، حساب الثمن، القسائم، النقاط والطلبات وغيرها.
3. طبقة تحميل البيانات: mcdata.py مسؤولة على فك التغليف، التوحيد والمطابقة التقريبية للأسامي.
4. طبقة نماذج الأعمال: health.py وcredit.py وbulk.py وrecommend.py وtheater.py كتنفذ على التوالي التنقيط، إعداد الوجبات، الاقتراح وتوليد السيناريو.

mcd_butler.py هو المدخل الموحد ديال CLI، ويقدر يخرج Markdown أو JSON، وهادشي مناسب للمشاهدة اليدوية وكذلك للربط مع برامج لاحقة.

تقنيات متقدمة للاستعمال

عطي الأولوية لتفاصيل الوجبة

واجهة التغذية كتقدم غير بيانات ديال كل منتوج بوحدو. منين كتحلل وجبة، من الأحسن تدخل حتى تفاصيل الوجبة، باش البرنامج يقلب على كل مكون حسب التركيبة الافتراضية. إلا ما تطابقت حتى معلومة غذائية وحدة، المشروع كيعرض النقطة الصحية على شكل «—»، وما كيخترعش نتيجة.

اختار وضع الاقتراح حسب السياق

• إلى كانت الميزانية محدودة بزاف، استعمل وضع التوفير وركز على الثمن لكل 100 kcal.
• فحالات إنقاص الدهون أو الرياضة، استعمل الوضع الصحي، وراجع كذلك تفاصيل الخصم ديال البروتين، الدهون والصوديوم.
• إلى بغيتي تجمع بين الوجبات الرائجة والتفضيلات الشخصية السابقة، استعمل وضع الشعبية.

حفظ المعطيات الأصلية ديال MCP باش تعاود التجربة

ملي كتدبّگ فنتائج التوصيات، من الأحسن تحفظ الاستجابة الأصلية ديال MCP ديال داك الوقت. بهاد الطريقة، حتى إلا تبدلات من بعد المينيو ولا الثمن ولا حالة التوفّر، تقدر تعاود نفس عملية الحساب باستعمال نفس المعطيات.

فرّق بين جودة المعطيات

McButler كيستعمل ثلاثة ديال مستويات التوسيم ديال المعطيات:

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

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

راجع الحدود العملية

دابا خاصية الوجبات الجماعية مازال ما مدموجاش فيها التحسين التراكمي ديال قواعد التخفيض الخاصة بالطلبات الجماعية ديال الشركات؛ وشرط «ما كناكلش البقر» كيعتمد أساساً على الكلمات المفتاحية فاسم الطبق؛ ومدة الانتظار خاصها حتى هي إدخال صريح. قبل ما تستعمل المشروع فطلبات حقيقية، خاصك تعاود تأكد عبر القنوات الرسمية ديال ماكدونالدز من الثمن، وحالة التوفّر، ومكوّنات الوجبات.

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

الخلاصة

McButler كيبين كيفاش نْحوّلو المعطيات الأصلية ديال MCP لقرار استهلاكي ساهل يتفهم: من تفكيك العروض، والتنقيط الغذائي، والحساب الكامل لتكلفة المحل، حتى لتقسيم مجموعات الوجبات، والتنقيط الترفيهي، والمحتوى التفاعلي؛ وكلشي تقدر تستعملو عبر CLI موحّد ولا WorkBuddy Skill.

فالتجربة اللولة، من الأحسن تشغّل python scripts/selftest.py، ومن بعد تجرّب بالترتيب health وrecommend وstores. منين تتأكد من الخدمة بلا اتصال، عاد كوّن MCP Token باش تربط المعطيات المباشرة.