McOracle ম্যাকডোরাকল ওরাকল টিউটোরিয়াল: এলোমেলো ওরাকল থেকে বাস্তব মেনু সুপারিশ ও নিরাপদ অর্ডার

McOracle কী

McOracle (ম্যাকডোরাকল) হলো সম্পূর্ণ Skill-ভিত্তিক একটি AI ওরাকল অভিজ্ঞতা। ব্যবহারকারী যেকোনো প্রশ্ন করতে পারেন। সিস্টেমটি ১০৪টি মৌলিক চীনা ওরাকল থেকে Python-এর secrets মডিউল ব্যবহার করে সত্যিকারের র‍্যান্ডমভাবে একটি উত্তর বেছে নেয়। এরপর 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 ট্রিগারের শর্ত, কার্যপ্রবাহ, আউটপুট ফরম্যাট ও নিরাপত্তার প্রয়োজনীয়তা নির্ধারণ করে।

ওরাকল লাইব্রেরিতে ১০৪টি মৌলিক বিষয়বস্তু রয়েছে। এগুলো ইতিবাচক, নেতিবাচক, অপেক্ষা, পদক্ষেপ, মোড় পরিবর্তন, সৌভাগ্য, হাস্যরস এবং ম্যাকডো-নির্দিষ্ট—এই আটটি শ্রেণি জুড়ে বিস্তৃত। প্রতিটি ওরাকলে নম্বর, মূল বক্তব্য, শ্রেণি, ট্যাগ, ব্যাখ্যা, পদক্ষেপের পরামর্শ, সুপারিশের ট্যাগ এবং ভিজ্যুয়াল থিম রয়েছে।

Python নির্ভরতা ইনস্টল করা

প্রকল্পটির জন্য Python 3.9 বা তার পরের সংস্করণ প্রয়োজন। ডেভেলপমেন্ট পরিবেশে Python 3.13 ব্যবহার করা হয়। অফিসিয়াল ভাগ্য কার্ড Pillow দিয়ে সাজানো হয়, তাই Pillow ইনস্টল করতে হবে। ওরাকল নির্বাচন ও অর্ডার নিরাপত্তার স্ক্রিপ্টগুলোর নিজস্ব কোনো ইমেজ জেনারেশন API প্রয়োজন নেই।

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

macOS বা Linux-এ চালালে সিস্টেমে চীনা অক্ষর প্রদর্শন করতে পারে এমন ফন্ট আছে কি না নিশ্চিত করুন। স্ক্রিপ্টটি প্রার্থীদের তালিকা থেকে ব্যবহারযোগ্য ফন্ট বেছে নেবে। অফিসিয়াল কার্ড তৈরি করতে কোনো ইমেজ জেনারেশন API Key কনফিগার করতে হয় না।

WorkBuddy Skill হিসেবে ইনস্টল করা

1. প্রকল্পটি সংগ্রহ করে নির্ভরতাগুলো ইনস্টল করুন।
2. সম্পূর্ণ McOracle/ ডিরেক্টরিটি ব্যবহারকারীর Skill ডিরেক্টরি ~/.workbuddy/skills/McOracle/-তে, অথবা বর্তমান ওয়ার্কস্পেসের {workspace}/.workbuddy/skills/McOracle/-তে কপি করুন।
3. WorkBuddy-এর কানেক্টরে McDonald's China MCP সক্রিয় করুন।
4. কথোপকথন খুলে «ম্যাকডো ওরাকল», «একটি ভাগ্যফল বেছে দাও», «আজকের ওরাকল» ইত্যাদি বললে Skill ট্রিগার হবে।

সাধারণ প্রশ্নও সরাসরি করা যায়, যেমন «আমার কি চাকরি ছেড়ে দেওয়া উচিত?»। সম্পূর্ণ প্রক্রিয়া চালাতে চাইলে বলতে পারেন «আমি আজকের সম্পূর্ণ ম্যাকডো ভাগ্য চাই»। WorkBuddy-এর বিভিন্ন সংস্করণে Skill রেজিস্ট্রেশনের মেটাডেটার প্রয়োজনীয়তা ভিন্ন হতে পারে; স্থানীয় সংস্করণ অনুযায়ী প্রয়োজনীয় কনফিগারেশন যোগ করুন।

McDonald's China-এর অফিসিয়াল MCP কনফিগার করা

বাস্তব স্টোর, মেনু ও দামের সুপারিশ ব্যবহারের আগে অফিসিয়াল MCP ব্যবহার নির্দেশিকা থেকে Token পাওয়ার পদ্ধতি জেনে নিন। এরপর WorkBuddy-এর «কানেক্টর» → «কাস্টম কানেক্টর» → «MCP কনফিগার করুন»-এ কনফিগারেশন পূরণ করুন।

{
  "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 ব্যবহার করা উচিত। ব্যাখ্যা বা ভাগ্য কার্ড তৈরি করার সময় সিস্টেম নিজে থেকে ওরাকল পরিবর্তন করবে না।

ভাগ্য কার্ড তৈরি করা

ভাগ্য কার্ড নির্দিষ্ট বারগান্ডি-সোনালি ভিজ্যুয়াল টেমপ্লেট ব্যবহার করে এবং ইমেজ জেনারেশন পরিষেবার ওপর নির্ভর করে না। পটভূমিতে গাঢ় বারগান্ডি গ্রেডিয়েন্ট, সোনালি দ্বিস্তরীয় বর্ডার, কেন্দ্রীয় আলোকিত বলয় ও তারার বিন্দু রয়েছে। চীনা অক্ষর, নম্বর ও দাম যাতে বিকৃত বা উপচে না যায়, সে জন্য 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 দিয়ে দাম সত্যিই যাচাই করার পর ব্যবহার করা যাবে; উদাহরণের দামকে বাস্তব সময়ের দাম হিসেবে ব্যবহার করা যাবে না।

ছবির উপকরণের বিকল্প ব্যবস্থা

প্রধান খাবারের ছবি নিচের অগ্রাধিকার অনুযায়ী পরিচালিত হয়:

1. প্রথমে query-meals বা query-meal-detail থেকে পাওয়া অফিসিয়াল পণ্যের ছবি ব্যবহার করা হয়।
2. অফিসিয়াল ছবি না থাকলে --item-image দিয়ে আলাদা ধারণামূলক ইলাস্ট্রেশন নির্ধারণ করা যায় এবং সেটিকে যথাযথভাবে ধারণামূলক ইলাস্ট্রেশন হিসেবে চিহ্নিত করতে হবে।
3. বাহ্যিক উপকরণ ব্যবহার করা না গেলে স্ক্রিপ্টে থাকা বার্গার, ফ্রাই ও কোলার প্রোগ্রাম্যাটিক ইলাস্ট্রেশন ব্যবহার করা হয়।
4. সব উপকরণ অনুপলব্ধ হলে «খাবারের ভিজ্যুয়াল উপকরণ অনুপস্থিত» বিকল্প কার্ড তৈরি হয় এবং exit code 2 ও JSON ok=false দিয়ে ব্যর্থতার প্রতিবেদন দেওয়া হয়।

প্রকল্পটি খালি বলয়কে খাবার হিসেবে দেখাবে না এবং ধারণামূলক ইলাস্ট্রেশনকে অফিসিয়াল বাস্তব ছবি হিসেবে চিহ্নিত করবে না।

কথোপকথনে সম্পূর্ণ অভিজ্ঞতা সম্পন্ন করা

একটি সাধারণ কথোপকথন এভাবে হতে পারে:

আপনি: ম্যাকডো ওরাকল, আজ কি চাকরি ছাড়ার উপযুক্ত সময়?
McOracle: ওরাকল বেছে নিয়ে মূল বক্তব্য, ব্যাখ্যা, পদক্ষেপের পরামর্শ ও গুরুত্বপূর্ণ বিষয়ের সতর্কতা দেবে এবং আজকের অবশ্যই খাওয়ার মতো খাবারও সুপারিশ করতে পারে।

আপনি: অর্ডারের জন্য প্রস্তুত
McOracle: স্টোর, সংগ্রহের পদ্ধতি, পণ্য ও দামসহ অর্ডারের সারাংশ দেখাবে এবং আপনার নিশ্চিতকরণ চাইবে।

আপনি: অর্ডার নিশ্চিত করুন
McOracle: দাম পুনরায় যাচাই করে create-order কল করবে এবং বাস্তব অর্ডার নম্বর ও অফিসিয়াল পেমেন্ট প্রবেশপথ ফেরত দেবে।

«দেখি», «সুপারিশ করুন» এবং «অর্ডারের জন্য প্রস্তুত»—কোনোটিই চূড়ান্ত নিশ্চিতকরণ নয়। ব্যবহারকারী স্পষ্টভাবে «অর্ডার নিশ্চিত করুন» বলার পরেই অর্ডার প্রক্রিয়া এগোতে পারে।

অর্ডার নিরাপত্তা ব্যবস্থা

অর্ডার নিরাপত্তা নিয়ন্ত্রক অর্ডারের অবস্থা ও গুরুত্বপূর্ণ প্যারামিটার পরীক্ষা করে। স্টোর, পণ্য, পরিমাণ, দাম বা সংগ্রহের পদ্ধতিতে সামান্য পরিবর্তন হলেও আগের নিশ্চিতকরণ বাতিল হয়ে যাবে। সিস্টেমকে আবার সারাংশ দেখিয়ে নিশ্চিতকরণ চাইতে হবে।

প্রকল্পটি স্বয়ংক্রিয়ভাবে পেমেন্ট করবে না এবং ভুয়া অর্ডার নম্বর বা অর্ডার সফল হওয়ার বার্তা তৈরি করবে না। অর্ডার তৈরি হওয়ার পরও সেটি অফিসিয়াল পেমেন্ট প্রক্রিয়ার বাইরের পেমেন্ট-বাকি অবস্থায় থাকে; ব্যবহারকারীকে অফিসিয়াল পেজের মাধ্যমে নিজে পেমেন্ট সম্পন্ন করতে হবে। স্টোর থেকে সংগ্রহ ও McDrive-এর জন্য orderType=1, আর ডেলিভারির জন্য orderType=2 এবং ডেলিভারি ঠিকানা প্রয়োজন। দুই ধরনের প্যারামিটার একসঙ্গে ব্যবহার করা যাবে না।

আলাদাভাবে অর্ডার নিরাপত্তা ডেমো চালানো

অর্ডার স্ক্রিপ্টে সম্পূর্ণ লজিকের Mock ডেমো রয়েছে, যা কোনো বাস্তব অর্ডার তৈরি করে না:

python scripts/validate-order.py demo

বাস্তব MCP যুক্ত করার আগে নিশ্চিতকরণের নিয়ম পরীক্ষা করার জন্য এই ডেমো উপযোগী। এতে নিশ্চিতকরণ ছাড়া অর্ডার নিষিদ্ধ, অস্পষ্ট বক্তব্য নিশ্চিতকরণ হিসেবে গণ্য না হওয়া, অর্ডারের প্যারামিটার বদলালে নিশ্চিতকরণ বাতিল হওয়া এবং অর্ডার তৈরি হওয়া পেমেন্ট সফল হওয়ার সমান নয়—এসব পরীক্ষা করা যায়।

টেস্ট চালানো

প্রকল্পে তিনটি টেস্ট সেট রয়েছে, যা যথাক্রমে ওরাকল লজিক, ভাগ্য কার্ড তৈরি এবং অর্ডার নিরাপত্তা স্টেট মেশিন পরীক্ষা করে:

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

README-তে নথিভুক্ত বর্তমান ফলাফল হলো ২৪টি টেস্টই সফল। ওরাকল টেস্টে ১০৪টি ডেটা, অনন্য নম্বর, আটটি শ্রেণি, র‍্যান্ডমনেস ও স্টেট লক যাচাই করা হয়। ভাগ্য কার্ড টেস্টে বাস্তব PNG, মাপ, উপকরণ অনুপস্থিতির বিকল্প ব্যবস্থা, যাচাই না-করা দামের শাখা এবং দীর্ঘ লেখার বিন্যাস যাচাই করা হয়। অর্ডার টেস্ট Mock ব্যবহার করে নিরাপদ স্টেট পরিবর্তন যাচাই করে; এটি বাস্তব MCP কল করে না এবং কোনো অর্ডার তৈরি করে না।

উন্নত ব্যবহারের পরামর্শ

বিনোদনমূলক ওরাকল এবং বাস্তব সিদ্ধান্ত আলাদা রাখুন

ওরাকল কেবল বিনোদন ও অনুপ্রেরণার জন্য; এটি ভবিষ্যদ্বাণী নয় এবং বাস্তব বিচারবুদ্ধির বিকল্পও নয়। চাকরি ছাড়া, বিনিয়োগ, স্বাস্থ্য, আইন বা অর্থসংক্রান্ত প্রশ্নে বাস্তব পরিস্থিতি বিবেচনা করুন এবং পেশাদারের পরামর্শ নিন।

যাচাই করা দাম ও উদাহরণের দাম সবসময় আলাদা রাখুন

MCP থেকে পাওয়া দামের একক «সেন্ট»; প্রদর্শনের আগে 100 দিয়ে ভাগ করতে হবে। তাছাড়া দামের কার্যকারিতা সময়সাপেক্ষ। বাস্তব সময়ে যাচাই সম্পন্ন না হলে «দাম যাচাই করা হয়নি» দেখাতে হবে। কার্ড বা কথোপকথনে বাস্তব সময়ের দামের বদলে উদাহরণের দাম দেখাবেন না।

প্রমাণপত্র ও গোপনীয়তা পরিচালনা

Token ও API Key কেবল কানেক্টর কনফিগারেশন বা পরিবেশ ভেরিয়েবল থেকে পড়া যাবে; সোর্স কোডে লেখা বা রিপোজিটরিতে কমিট করা যাবে না। প্রকল্পে ব্যবহারকারীর গোপনীয় তথ্য, Cookie, অর্ডার নম্বর বা ব্যক্তিগত প্রমাণপত্র সংরক্ষণ করা উচিত নয়। Issue বা Pull Request জমা দেওয়ার সময়ও এসব সংবেদনশীল তথ্য অন্তর্ভুক্ত করবেন না।

বর্তমান সক্ষমতার সীমা বোঝা

স্টোর查询, মেনু查询, খাবারের বিবরণ, দাম গণনা, অফিসিয়াল ছবি ডাউনলোড এবং ভাগ্য কার্ড তৈরি—এসবের বাস্তব যাচাইয়ের রেকর্ড রয়েছে। সম্পূর্ণ «অর্ডার—পেমেন্ট—স্ট্যাটাস পুনরায়查询» চক্র, McDelivery প্রক্রিয়া এবং কুপন সংগ্রহ ও ব্যবহার করার ধাপ এখনো সম্পূর্ণভাবে বাস্তবে পরীক্ষা করা হয়নি। তাই এগুলোকে প্রান্ত-থেকে-প্রান্ত সফলভাবে যাচাই করা হয়েছে বলে বর্ণনা করা যাবে না।

উপসংহার

McOracle নির্দিষ্ট ওরাকল ডেটা, সত্যিকারের র‍্যান্ডম নির্বাচন, অফিসিয়াল MCP রিয়েল-টাইম মেনু এবং প্রোগ্রামেটিক ছবি বিন্যাস একত্র করে একটি মজার WorkBuddy Skill তৈরি করেছে। আপনি চাইলে প্রথমে শুধু ওরাকল স্ক্রিপ্ট ব্যবহার করতে পারেন, অথবা MCP কনফিগার করে দোকান, খাবার ও দামের সুপারিশ পেতে পারেন। বাস্তব ব্যবহারের সময় তিনটি নীতি মনে রাখুন: ওরাকল বিনোদনের জন্য, দাম অবশ্যই রিয়েল-টাইমে যাচাই করতে হবে, এবং ব্যবহারকারী স্পষ্টভাবে নিশ্চিত না করা পর্যন্ত কখনো অর্ডার তৈরি করবেন না।

ভাগ্য এলোমেলো হতে পারে, কিন্তু দাম অবশ্যই সত্য হতে হবে।