دليل M餐搭子: كيفاش تولّد 3 اقتراحات ديال وجبات ماكدونالدز باستعمال المينيو المباشر والميزانية والأهداف الغذائية

شنو هو M餐搭子

M餐搭子 هو Skill ذكي كيعتمد على بيانات MCP ديال ماكدونالدز باش يعاونك تركّب الوجبة. غير دخل المدينة، المعلم، الميزانية، الحد الأقصى للسعرات والهدف ديال البروتين، وغادي يقلب على أقرب مطاعم اللي كتوفر الاستلام، يطابق المينيو الحالي مع بيانات التغذية، ويخرج ليك ثلاثة اقتراحات عملية لتركيب الوجبة.

بخلاف الأدوات اللي كتقترح غير منتوج واحد، M餐搭子 كيعرض الثمن، السعرات، البروتين، شحال تستعملات من الميزانية، شحال بقا من السعرات، وسبب التوصية ديال كل تركيبة. وتقدر حتى تفتح سلسلة استدعاءات MCP وتشوف حالة كل Tool والمدة اللي خذات.

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

شنو المشكل اللي كيحلّو المشروع

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

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

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

• البحث الفوري على المطاعم: باستعمال query-nearby-stores، كيقلب على المطاعم القريبة اللي كتوفر الاستلام حسب المدينة والمعلم.
• قراءة المينيو بشكل فوري: باستعمال query-meals، كياخذ الثمن الحالي، الثمن الأصلي، صور المنتجات والوسوم ديال المطعم.
• مطابقة التغذية: باستعمال list-nutrition-foods، كيطابق منتجات المينيو مع بيانات السعرات والبروتين.
• ثلاثة اقتراحات لتركيب الوجبة: كيرجع «الاختيار المتوازن»، «زيادة البروتين» و«تركيبة مريحة»، باش ما يعطيش غير جواب واحد بحال الصندوق الأسود.
• مؤشرات قابلة للفهم: كيعرض البروتين لكل يوان، الميزانية المستعملة، السعرات الباقية وفرق التخفيض.
• العروض والحملات: كينادي على available-coupons وcampaign-calendar، وكيجمع القسائم المتاحة والحملات القريبة فبلاصة وحدة.
• إمكانية تتبع الاستدعاءات: المستخدم يقدر يشوف حالة ومدة استدعاء MCP Tool.
• التراجع الآمن: إلا ما كانش Token مكوّن أو كان Tool غير متاح مؤقتاً، النظام كيستعمل لقطة تجريبية منزوعة الحساسية ومعلّمة بوضوح.

التحضيرات قبل التشغيل

نسخة MCP الفورية كتحتاج خدمة Node الموجودة فالمستودع تخدم محلياً. قبل ما تبدا، وجد هاد البيئة:

• Node.js 20 أو نسخة أحدث
• npm 10 أو نسخة أحدث
• واحد MCP Token ديال ماكدونالدز؛ إلا كنت غير باغي تجرب البيانات التجريبية، ماشي ضروري توفره

إلا ما بغيتيش تثبت دابا، تقدر تزور العرض التجريبي على GitHub Pages. هاد النسخة عرض تجريبي فرونت-إند فقط، كتدعم تعديل الشروط والحساب الكامل لتركيب الوجبة، ولكن كتستعمل لقطة مينيو منزوعة الحساسية وماشي بيانات MCP فورية.

التثبيت والإعداد

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

نفّذ الأوامر التالية فالطرفية. عوّض العنوان المؤقت ديال المستودع بالعنوان الحقيقي:

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

الخطوة الثانية: إعداد متغيرات البيئة

حلّ ملف .env الموجود فالجذر ديال المشروع، وكتب فيه MCP Token ومنفذ الخدمة:

MCD_MCP_TOKEN=YOUR_MCD_MCP_TOKEN
PORT=8787

• MCD_MCP_TOKEN ماشي متغير إجباري. منين كتكوّنو كيتفعّل MCP الفوري؛ إلا ما كوّنتيهش كتستعمل البيانات التجريبية.
• PORT ماشي متغير إجباري، والقيمة الافتراضية ديالو هي 8787.

خاص MCP Token يبقى غير فمتغيرات البيئة ديال الخادم، وما خاصوش يتحط فالكود ديال الفرونت-إند ولا يتدفع لمستودع عمومي.

الخطوة الثالثة: تشغيل بيئة التطوير

npm run dev

من بعد التشغيل، دخل فالمتصفح لـ http://localhost:5173. أمر التطوير كيشغّل Express API وكيحوّل Vite للتحديث السريع، وهادشي مناسب لتصحيح الواجهة ومنطق الخادم.

الوضع التجريبي بلا Token

إلا ما عندكش MCP Token ديال ماكدونالدز، تقدر تبني وتشغّل نسخة الإنتاج:

npm install
npm run build
npm start

ومن بعد دخل لـ http://localhost:8787. فهاد الحالة الصفحة غادي تبين بوضوح «بيانات تجريبية»، والمينيو والأثمنة والحملات غادي يجيو من لقطة منزوعة الحساسية.

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

الاستعمال الأساسي: إنشاء ثلاثة اقتراحات لتركيب الوجبة

الخطوة الأولى: اختيار التفضيلات

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

الخطوة الثانية: إدخال شروط الوجبة

تقدر تبدا بهاد الشروط النموذجية:

المدينة:上海市
الحي التجاري / المعلم: 人民广场
الميزانية: 35 يوان
الحد الأقصى للسعرات: 700 kcal
هدف البروتين: 35 g

الخطوة الثالثة: مراجعة النتائج المحسوبة

الخادم غادي يقلب على المطاعم القريبة، يقرا المينيو وبيانات التغذية، ومن بعد يرجع ثلاثة أنواع ديال الاقتراحات:

1. الاقتراح A: الاختيار المتوازن. كيوفر طبقاً رئيسياً مع وجبة خفيفة أو مشروب داخل حدود الميزانية والسعرات، وكيعرض البروتين، البروتين لكل يوان وسبب التوصية.
2. الاقتراح B: زيادة البروتين. كيعطي الأولوية لرفع البروتين، مع محاولة الحفاظ قدر الإمكان على حدود الميزانية والسعرات.
3. الاقتراح C: تركيبة مريحة. كيوفر تركيبة أرخص ولكنها كاملة، ومناسبة للحالات اللي كتهمها التكلفة وسرعة الاختيار أكثر.

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

الخطوة الرابعة: فحص سلسلة استدعاءات MCP

منين كتفتح «سلسلة استدعاءات MCP»، تقدر تشوف حالة ومدة أدوات المطاعم، المينيو، التغذية، العروض والحملات. هادشي كيساعدك تعرف واش التوصية مبنية على بيانات راجعة بشكل فوري، ولا تبدلات للقطة تجريبية بسبب غياب Token أو عدم توفر Tool.

أوامر التطوير المستعملة بزاف

• npm run dev: تشغيل Express API وتحديث Vite السريع.
• npm run build: بناء الفرونت-إند وترجمة الخادم.
• npm start: تشغيل خدمة الإنتاج.
• npm test: تشغيل اختبارات منطق تركيب الوجبة وتحليل التغذية.
• npm run check: تنفيذ فحص الأنواع، فحص ترجمة الخادم والاختبارات بالتتابع.

من بعد تعديل تحليل التغذية، مطابقة المينيو أو قواعد تركيب الوجبة، من الأحسن تنفذ على الأقل:

npm test
npm run check

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

النشر باستعمال Docker

المشروع كيوفر طريقة البناء باستعمال Docker. أولاً أنشئ الصورة:

docker build -t mcd-meal-mate .

من بعد ربط المنفذ 8787 ديال الجهاز المحلي مع الحاوية، ودوز Token عبر متغير البيئة:

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

من بعد ما تبدا الحاوية، تقدر تدخل لـ http://localhost:8787. إلا حيدتي MCD_MCP_TOKEN، التطبيق غادي يستعمل البيانات التجريبية.

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

المشروع كيقسم فرونت-إند React، خدمة Express، استدعاءات MCP، تحليل التغذية وتخطيط التركيبة لوحدات مختلفة:

src/
  App.tsx          واجهة عمل React والتفاعل المتجاوب
  styles.css       نظام بصري ديال مينيو التحرير × الوصل
server/
  index.ts         Express API، التحقق من الإدخال والموارد الثابتة
  mcp.ts           عميل MCP JSON-RPC، تنسيق Tools والتراجع
  nutrition.ts     تحليل نص التغذية، مطابقة المينيو والتعرف على أدوار المنتجات
  planner.ts       قيود التركيبة، تنقيط التفضيلات واختيار ثلاثة اقتراحات
  demo-data.ts     لقطة تجريبية منزوعة الحساسية
  planner.test.ts  اختبارات التغذية والتركيب
shared/
  types.ts         الأنواع المشتركة بين الفرونت-إند والخادم

server/mcp.ts مسؤول على تواصل MCP JSON-RPC، تنسيق Tools والتراجع من بعد الفشل؛ وserver/nutrition.ts كيعالج مطابقة نصوص التغذية مع منتجات المينيو؛ وserver/planner.ts كينفذ قيود التركيبة، تنقيط التفضيلات واختيار ثلاثة اقتراحات. هياكل البيانات المشتركة بين الفرونت-إند والخادم موجودة فـ shared/types.ts.

الخلفية كتستعمل fetch الأصلي باش تتواصل مع McDonald's MCP Streamable HTTP Server. فبناء الإنتاج، نفس عملية Express كتقدم API والصفحة الثابتة، وكتخزن مؤقتاً نتائج المينيو والتغذية فالذاكرة.

الاستعمال المتقدم ونصائح التطوير

بدا بتفقد الشروط اللي كتقيّد النتيجة

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

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

فوقت التصحيح، تأكد واش الصفحة كتعرض «بيانات تجريبية»، وراجع سلسلة استدعاءات MCP. إلا ما كانش Token، أو كان Tool غير متاح مؤقتاً، أو كنت كتستعمل نسخة GitHub Pages اللي خدامة بالفرونت-إند فقط، فالنتائج تقدر تكون جاية من لقطة منزوعة الحساسية.

حمي بيانات الدخول ديال الخادم

ما تحطش Token فالمتصفح. المشروع كيقرا متغيرات البيئة عبر خدمة Express، والخادم هو اللي كينادي على MCP، وبهذا كيتفادى كشف Token للفرونت-إند من ناحية البنية. منين كتنشر فخادم أو حاوية، خاصك حتى نتا تدخل بيانات الدخول باستعمال طريقة آمنة لإدارة متغيرات البيئة.

من بعد تعديل منطق التخطيط، دير الفحص الكامل

إلا عدلتي planner.ts أو nutrition.ts أو الأنواع المشتركة، استعمل npm run check باش تدير فحص الأنواع، الترجمة والاختبارات. المشروع فيه اختبارات ديال التركيب وتحليل التغذية، وهادشي كيعاونك تتحقق واش التعديل أثر على السلوك الموجود.

راجع وثائق التكامل

الملف MCP_INTEGRATION.md الموجود فالمستودع كيسجل جميع Tools، مسار الاستدعاء، القيمة العملية وحدود الأمان؛ وmcp-config.example.json كيعطي مثالاً على إعداد منزوعة الحساسية؛ وworkbuddy.md فيه سياق الربط مع WorkBuddy وتعليمات قابلة لإعادة التنفيذ. منين كتربط Agent أو Skill آخر، من الأحسن ترجع لهاد الملفات أولاً.

حدود الأمان

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

الخلاصة

‏M餐搭子 كيجمع البحث على المحلات، المينيو فالحين، المطابقة الغذائية، معلومات التخفيضات والتخطيط ديال المجموعات فمسار واحد وواضح لاختيار الماكلة. من بعد إعداد MCP Token، يقدر يستعمل معطيات المحل الحالي؛ وإلا ماكانش Token، تقدر حتى تستعمل التفاعل كامل عبر نسخة منزوعة البيانات الحساسة.

من بعد ما تكمل التثبيت، تقدر تبدا بتجريب الشروط النموذجية باش تتحقق من ثلاث حلول، ومن بعد تستعمل سلسلة استدعاءات MCP باش تأكد مصدر المعطيات. وبالنسبة للمطورين، يقدرو يبداو من mcp.ts وnutrition.ts وplanner.ts باش يفهمو كيفاش كيتنظم المعطى الآني، وكيفاش كتدار المطابقة الغذائية والحسابات ديال القيود.