McOracle مک ڈونلڈز فال نامہ ٹیوٹوریل: بے ترتیب فال سے حقیقی مینو کی سفارش اور محفوظ آرڈر تک

McOracle کیا ہے

McOracle (میک ڈوریکل) ایک خالص Skill پر مبنی AI فال بینی کا تجربہ ہے۔ صارف کوئی بھی سوال پوچھ سکتے ہیں، اور نظام Python کے secrets ماڈیول کے ذریعے 104 اصل چینی فالوں میں سے حقیقی طور پر بے ترتیب ایک جواب منتخب کرتا ہے۔ اس کے بعد McDonald's China کے سرکاری MCP سے حقیقی اسٹورز، دستیاب مینو اور قیمتیں حاصل کرکے ایک «میک گیٹ کی کتابِ ہدایت» اور قسمت کا کارڈ تیار کیا جاتا ہے۔

پروجیکٹ کا بنیادی اصول یہ ہے: فال بے ترتیب ہو سکتا ہے، مگر اشیا اور قیمتیں حقیقی ہونی چاہئیں۔ فال ریپوزٹری میں موجود مستقل ڈیٹا سے آتا ہے، ماڈل اسے عارضی طور پر ایجاد نہیں کرتا؛ کھانے، اسٹورز اور قیمتوں کے لیے صرف MCP سے موصولہ ڈیٹا استعمال ہوتا ہے؛ قیمت کی تصدیق نہ ہونے پر «قیمت کی تصدیق نہیں ہوئی» دکھایا جاتا ہے۔ صارف کی واضح تصدیق سے پہلے نظام آرڈر نہیں بنائے گا، اور آرڈر بن جانا ادائیگی کی کامیابی کے برابر نہیں ہے۔

مکمل ورک فلو

McOracle کا معیاری سلسلہ پانچ مراحل پر مشتمل ہے:

1. صارف سوال پوچھتا ہے یا براہِ راست میک گیٹ کی فال بینی کی درخواست کرتا ہے۔
2. scripts/draw-oracle.py، references/oracle-library.json سے فال کو حقیقی طور پر بے ترتیب منتخب کرتا ہے اور اس دور کا نتیجہ مقفل کر دیتا ہے۔
3. اگر صارف کھانے کی سفارش چاہے تو Skill، MCP کے ذریعے قریبی اسٹورز، دستیاب مینو اور کھانے کی تفصیلات دریافت کرتا ہے۔
4. calculate-price کے ذریعے قیمت کی تصدیق کی جاتی ہے، پھر scripts/generate-card.py سے 1200×1600 PNG قسمت کا کارڈ تیار کیا جاتا ہے۔
5. صرف صارف کے واضح جواب «آرڈر کی تصدیق کریں» کے بعد نظام آرڈر کی معلومات دوبارہ جانچتا ہے اور create-order کو کال کرتا ہے۔ اس کے بعد بھی صارف کو سرکاری انٹرفیس کے ذریعے خود ادائیگی کرنا ہوگی۔

اگر صارف صرف فال نکالنا چاہتا ہو تو عمل پہلے مرحلے پر ختم ہو جاتا ہے، مقام طلب نہیں کیا جاتا اور MCP کو کال نہیں کیا جاتا۔

بنیادی ماڈیولز اور پروجیکٹ کا ڈھانچہ

پروجیکٹ بنیادی طور پر درج ذیل ماڈیولز پر مشتمل ہے:

• Oracle Engine: draw-oracle.py اور فال لائبریری بے ترتیب انتخاب، نتیجے کو مقفل کرنے اور دوبارہ فال نکالنے کے کنٹرول کی ذمہ دار ہیں۔
• Recommendation Engine: recommendation-rules.md فال کے ٹیگز کو کھانے کی سمتوں سے ملاتا ہے اور حقیقی مینو و بجٹ کی بنیاد پر سفارش دیتا ہے۔
• MCP Adapter: SKILL.md اور MCP_INTEGRATION.md ٹول کالز کی ترتیب، پیرامیٹرز کے اصول اور خرابیوں سے نمٹنے کا طریقہ بیان کرتے ہیں۔
• Card Generator: generate-card.py Pillow کے ذریعے شرابی سرخ اور سنہری ٹیمپلیٹ بناتا ہے اور سرکاری مصنوعات کی تصاویر کو اس میں شامل کرتا ہے۔
• Order Safety Controller: validate-order.py اسٹیٹ مشین کے ذریعے تصدیقی عمل کو کنٹرول کرتا ہے تاکہ غیر مصدقہ آرڈر روکا جا سکے۔
• Skill Orchestrator: SKILL.md فعال ہونے کی شرائط، عمل کی ترتیب، آؤٹ پٹ فارمیٹ اور حفاظتی تقاضے متعین کرتا ہے۔

فال لائبریری میں 104 اصل مواد شامل ہیں، جو آٹھ اقسام کا احاطہ کرتے ہیں: اثباتی، نفی پر مبنی، انتظار پر مبنی، عملی، الٹ پھیر، خوش بختی، مزاحیہ اور میک گیٹ سے مخصوص۔ ہر فال میں نمبر، متن، قسم، ٹیگز، تشریح، عملی اشارہ، تجویز کردہ ٹیگز اور بصری تھیم شامل ہیں۔

Python کی dependencies انسٹال کرنا

پروجیکٹ کے لیے Python 3.9 یا اس سے جدید ورژن درکار ہے۔ ترقیاتی ماحول Python 3.13 استعمال کرتا ہے۔ رسمی قسمت کا کارڈ Pillow کے ذریعے ترتیب دیا جاتا ہے، اس لیے Pillow انسٹال کرنا ضروری ہے؛ فال نکالنے اور آرڈر کی حفاظت کے اسکرپٹس خود کسی image generation API پر منحصر نہیں ہیں۔

git clone <your-repo-url> McOracle
cd McOracle
pip install Pillow

macOS یا Linux پر چلانے کی صورت میں یقینی بنائیں کہ نظام میں چینی دکھانے والا فونٹ موجود ہے۔ اسکرپٹ امیدواروں کی فہرست سے دستیاب فونٹ منتخب کرے گا۔ رسمی کارڈ بنانے کے لیے image generation API Key درکار نہیں ہے۔

WorkBuddy Skill کے طور پر انسٹال کرنا

1. پروجیکٹ حاصل کریں اور dependencies انسٹال کریں۔
2. پورا McOracle/ فولڈر صارف کی سطح کی Skill ڈائریکٹری ~/.workbuddy/skills/McOracle/ میں، یا موجودہ ورک اسپیس کے {workspace}/.workbuddy/skills/McOracle/ میں نقل کریں۔
3. WorkBuddy کے کنیکٹرز میں McDonald's China MCP فعال کریں۔
4. گفتگو کھولیں اور «میک گیٹ کی فال»، «ایک فال نکالو»، «آج کی فال» جیسی عبارتوں سے Skill فعال کریں۔

آپ عام سوال بھی براہِ راست پوچھ سکتے ہیں، مثلاً «کیا مجھے استعفیٰ دینا چاہیے؟»۔ مکمل سلسلہ چلانے کے لیے کہہ سکتے ہیں: «مجھے آج کی مکمل میک گیٹ قسمت چاہیے»۔ WorkBuddy کے مختلف ورژنز میں Skill رجسٹریشن میٹا ڈیٹا کی ضروریات مختلف ہو سکتی ہیں، اس لیے مقامی ورژن کے مطابق متعلقہ configuration شامل کریں۔

McDonald's China کے سرکاری MCP کو ترتیب دینا

حقیقی اسٹورز، مینو اور قیمتوں پر مبنی سفارشات سے پہلے سرکاری MCP استعمال کی رہنما سے Token حاصل کرنے کا طریقہ معلوم کریں، پھر WorkBuddy کے «کنیکٹرز» → «حسبِ ضرورت کنیکٹر» → «MCP ترتیب دیں» میں configuration درج کریں۔

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

YOUR_MCP_TOKEN کو اپنے Token سے تبدیل کریں، اور Token کو ریپوزٹری میں جمع نہ کریں۔ پروجیکٹ میں شامل بنیادی ٹولز now-time-info، query-nearby-stores، query-meals، query-meal-detail اور calculate-price ہیں۔ آرڈر سے متعلق create-order صرف صارف کی واضح تصدیق کے بعد کال کیا جا سکتا ہے۔

پہلا استعمال: فال نکالنا

پروجیکٹ کی جڑ میں درج ذیل کمانڈ چلائیں تاکہ مخصوص سوال کے لیے ایک فال نکالی جا سکے:

python scripts/draw-oracle.py --question 'آج کیا کھاؤں؟'

فال کا نتیجہ scripts/_oracle_state.json میں لکھا جائے گا اور اس دور کے لیے مقفل ہو جائے گا۔ اس طرح بعد کی تشریح، سفارش اور قسمت کا کارڈ اسی فال کا حوالہ دیں گے اور متعدد بار پڑھنے سے نتیجہ غیر ارادی طور پر تبدیل نہیں ہوگا۔

موجودہ مقفل نتیجہ دیکھنے یا دوبارہ فال نکالنے کی درخواست کے لیے:

python scripts/draw-oracle.py --peek
python scripts/draw-oracle.py --redraw

--redraw صرف صارف کی واضح درخواست پر استعمال ہونا چاہیے۔ نظام تشریح یا قسمت کا کارڈ تیار کرتے وقت خود فال تبدیل نہیں کرے گا۔

قسمت کا کارڈ تیار کرنا

قسمت کا کارڈ ایک مستقل شرابی سرخ اور سنہری بصری ٹیمپلیٹ استعمال کرتا ہے اور image generation سروس پر منحصر نہیں ہے۔ پس منظر میں گہرا شرابی سرخ gradient، سنہری دوہرا فریم، مرکز میں روشن دائرہ اور ستاروں کی آرائش شامل ہے؛ متن Pillow کے ذریعے ترتیب دیا جاتا ہے تاکہ چینی متن، نمبرز اور قیمتیں خراب یا فریم سے باہر نہ ہوں۔

جب MCP سرکاری مصنوعات کی تصویر فراہم کرے اور قیمت کی calculate-price کے ذریعے تصدیق ہو جائے تو رسمی کارڈ اس طرح تیار کیا جا سکتا ہے:

python scripts/generate-card.py \
  --oracle-id 'NO.021' \
  --answer 'رات گئے فیصلہ نہ کریں۔' \
  --interpretation 'رات ایک بجے کا آپ اور صبح دس بجے کا آپ ایک ہی شخص نہیں ہیں۔' \
  --item-name 'گرلڈ چکن برگر کومبو' \
  --item-price 34.5 \
  --price-verified \
  --item-image-url 'https://menu-img.mcd.cn/.../MS_9900005462_320.png' \
  --out examples/oracle-card-NO021-official.png

رسمی آؤٹ پٹ کا سائز 1200×1600 PNG ہے۔ --price-verified صرف اس وقت استعمال کیا جا سکتا ہے جب قیمت کی MCP کے ذریعے واقعی تصدیق ہو چکی ہو؛ مثال کی قیمت کو حقیقی وقت کی قیمت نہ سمجھیں۔

تصویری مواد کے لیے fallback حکمتِ عملی

مصنوعات کے مرکزی حصے کو درج ذیل ترجیح کے ساتھ ہینڈل کیا جاتا ہے:

1. پہلے query-meals یا query-meal-detail سے موصولہ سرکاری مصنوعات کی تصویر استعمال کریں۔
2. سرکاری تصویر نہ ہو تو --item-image کے ذریعے الگ تصوراتی illustration دی جا سکتی ہے، اور اسے حقیقت کے مطابق تصوراتی illustration کے طور پر لیبل کیا جائے۔
3. اگر بیرونی مواد دستیاب نہ ہو تو اسکرپٹ میں شامل برگر، فرائز اور کولا کی پروگراماتی illustrations استعمال کی جائیں گی۔
4. تمام مواد دستیاب نہ ہو تو «کھانے کی بصری تصویر دستیاب نہیں» والا fallback کارڈ تیار ہوگا اور exit code 2 اور JSON ok=false کے ذریعے ناکامی رپورٹ کی جائے گی۔

پروجیکٹ خالی دائرے کو کھانے کی نمائندگی کے طور پر استعمال نہیں کرے گا، اور تصوراتی illustration کو سرکاری حقیقی تصویر کے طور پر پیش نہیں کرے گا۔

گفتگو میں مکمل تجربہ

ایک عام گفتگو اس طرح ہو سکتی ہے:

آپ: میک گیٹ کی فال، کیا آج استعفیٰ دینا مناسب ہے؟
McOracle: فال نکالی گئی، متن، تشریح، عملی اشارہ اور اہم امور کی تنبیہ واپس کی گئی، اور آج کا لازمی انتخاب بھی فراہم کیا جا سکتا ہے۔

آپ: آرڈر کی تیاری کریں
McOracle: اسٹور، وصولی کا طریقہ، اشیا اور قیمتوں پر مشتمل آرڈر کا خلاصہ دکھایا جائے گا اور آپ سے تصدیق طلب کی جائے گی۔

آپ: آرڈر کی تصدیق کریں
McOracle: قیمت دوبارہ جانچنے کے بعد create-order کو کال کیا جائے گا اور حقیقی آرڈر نمبر و سرکاری ادائیگی کا انٹرفیس واپس کیا جائے گا۔

«دیکھیں»، «سفارش کریں» اور «آرڈر کی تیاری کریں» حتمی تصدیق نہیں ہیں۔ آرڈر کا عمل صرف صارف کے واضح جواب «آرڈر کی تصدیق کریں» کے بعد جاری ہو سکتا ہے۔

آرڈر کی حفاظتی مشینری

آرڈر کا حفاظتی کنٹرولر آرڈر کی حالت اور اہم پیرامیٹرز کی جانچ کرتا ہے۔ جیسے ہی اسٹور، اشیا، مقدار، قیمت یا وصولی کا طریقہ تبدیل ہو، سابقہ تصدیق غیر مؤثر ہو جاتی ہے؛ نظام کو خلاصہ دوبارہ دکھا کر دوبارہ تصدیق طلب کرنا ہوگی۔

پروجیکٹ خودکار ادائیگی نہیں کرتا، نہ جعلی آرڈر نمبر یا آرڈر کی کامیابی کا پیغام بناتا ہے۔ آرڈر بننے کے بعد بھی یہ سرکاری ادائیگی کے عمل سے باہر زیرِ ادائیگی مرحلے میں رہتا ہے، اور صارف کو سرکاری صفحے کے ذریعے خود ادائیگی مکمل کرنا ہوگی۔ اسٹور سے وصولی اور Drive-Thru کے لیے orderType=1، جبکہ ڈیلیوری کے لیے orderType=2 اور ترسیل کا پتہ درکار ہے؛ دونوں اقسام کے پیرامیٹرز کو ملایا نہیں جا سکتا۔

آرڈر حفاظتی demonstration کو الگ چلانا

آرڈر اسکرپٹ خالص منطقی Mock demonstration فراہم کرتا ہے، جو حقیقی آرڈر نہیں بناتا:

python scripts/validate-order.py demo

یہ demonstration حقیقی MCP سے منسلک کرنے سے پہلے تصدیقی اصول جانچنے کے لیے موزوں ہے، جن میں غیر مصدقہ آرڈر پر پابندی، مبہم عبارت کا تصدیق نہ شمار ہونا، آرڈر پیرامیٹرز کی تبدیلی سے تصدیق کا غیر مؤثر ہونا، اور آرڈر بننے کا ادائیگی کی کامیابی کے برابر نہ ہونا شامل ہیں۔

ٹیسٹ چلانا

پروجیکٹ میں تین ٹیسٹ گروپس شامل ہیں، جو بالترتیب فال کی منطق، قسمت کا کارڈ تیار کرنے اور آرڈر کی حفاظتی اسٹیٹ مشین کا احاطہ کرتے ہیں:

python tests/test-oracle.py
python tests/test-card.py
python tests/test-order-safety.py

README میں درج موجودہ نتیجے کے مطابق تمام 24 ٹیسٹ کامیاب ہیں۔ فال کے ٹیسٹ 104 ڈیٹا اندراجات، منفرد نمبرز، آٹھ اقسام، بے ترتیب پن اور حالت کے مقفل ہونے کی جانچ کرتے ہیں؛ قسمت کے کارڈ کے ٹیسٹ حقیقی PNG، سائز، مواد کی عدم دستیابی کا fallback، غیر مصدقہ قیمت کی شاخ اور طویل متن کی ترتیب کی جانچ کرتے ہیں؛ آرڈر کے ٹیسٹ Mock کے ذریعے حفاظتی حالت کی تبدیلیوں کی تصدیق کرتے ہیں، حقیقی MCP کو کال نہیں کرتے اور آرڈر نہیں بناتے۔

اعلیٰ سطحی استعمال کی تجاویز

تفریحی فال اور حقیقی فیصلوں میں فرق کریں

فال صرف تفریح اور تحریک کے لیے ہے، مستقبل کی پیش گوئی نہیں اور حقیقی فیصلہ سازی کا متبادل بھی نہیں۔ استعفیٰ، سرمایہ کاری، صحت، قانون یا مالیات سے متعلق سوالات میں معروضی حالات کو مدِنظر رکھیں اور ماہرین سے مشورہ کریں۔

ہمیشہ تصدیق شدہ قیمت اور مثال کی قیمت میں فرق رکھیں

MCP سے موصولہ قیمت کی اکائی «سینٹ» ہے، جسے دکھانے سے پہلے 100 سے تقسیم کرنا ضروری ہے، اور قیمت وقت کے ساتھ بدل سکتی ہے۔ حقیقی وقت کی تصدیق مکمل نہ ہو تو «قیمت کی تصدیق نہیں ہوئی» دکھائیں؛ کارڈ یا گفتگو میں مثال کی قیمت کو حقیقی وقت کی قیمت کے متبادل کے طور پر پیش نہ کریں۔

اسناد اور رازداری کا انتظام

Token اور API Key صرف کنیکٹر configuration یا environment variables کے ذریعے پڑھے جانے چاہئیں، انہیں source code میں نہیں لکھنا چاہیے اور نہ ریپوزٹری میں جمع کرنا چاہیے۔ پروجیکٹ کو صارف کی نجی معلومات، Cookie، آرڈر نمبر یا ذاتی اسناد محفوظ نہیں کرنی چاہئیں۔ Issue یا Pull Request جمع کرتے وقت بھی یہ حساس معلومات شامل نہ کریں۔

موجودہ صلاحیتوں کی حدود سمجھیں

اسٹور کی تلاش، مینو کی تلاش، کھانے کی تفصیلات، قیمت کا حساب، سرکاری تصاویر ڈاؤن لوڈ کرنا اور قسمت کا کارڈ تیار کرنا عملی طور پر جانچے جا چکے ہیں۔ مکمل «آرڈر—ادائیگی—حالت کی دوبارہ جانچ» سلسلہ، McDelivery کا عمل، اور coupon حاصل کرنے و استعمال کرنے کا عمل اب بھی مکمل طور پر حقیقی ماحول میں نہیں جانچا گیا؛ اس لیے انہیں end-to-end کامیاب طور پر تصدیق شدہ بیان نہیں کیا جا سکتا۔

اختتامیہ

McOracle نے مقررہ غیبی ڈیٹا، حقیقی بے ترتیب انتخاب، آفیشل MCP کے ریئل ٹائم مینو اور پروگرام کے ذریعے تصویری لے آؤٹ کو ملا کر ایک دلچسپ WorkBuddy Skill تیار کیا ہے۔ آپ پہلے صرف غیبی اسکرپٹ استعمال کر سکتے ہیں، یا MCP کو ترتیب دے کر اسٹورز، کھانوں اور قیمتوں کی مزید سفارشات حاصل کر سکتے ہیں۔ عملی استعمال کے دوران تین اصول ہمیشہ یاد رکھیں: غیب کا استعمال تفریح کے لیے ہے، قیمت کی ریئل ٹائم تصدیق ضروری ہے، اور صارف کی واضح منظوری کے بغیر کبھی بھی آرڈر نہ بنائیں۔

قسمت بے ترتیب ہو سکتی ہے، قیمت حقیقی ہونی چاہیے۔