M餐搭子 টিউটোরিয়াল: রিয়েল-টাইম মেনু, বাজেট ও পুষ্টির লক্ষ্য ব্যবহার করে ম্যাকডোনাল্ডসের তিনটি মিল পরিকল্পনা তৈরি

M餐搭子 কী

M餐搭子 হলো McDonald's MCP ডেটার ওপর ভিত্তি করে তৈরি একটি বুদ্ধিমান খাবার-কম্বো Skill। আপনাকে শুধু শহর, ল্যান্ডমার্ক, বাজেট, সর্বোচ্চ ক্যালরি এবং প্রোটিনের লক্ষ্য লিখতে হবে। এটি কাছাকাছি নিজে সংগ্রহ করা যায় এমন স্টোর খুঁজে বর্তমান মেনু ও পুষ্টি-তথ্য মিলিয়ে তিনটি ব্যবহারযোগ্য খাবার-কম্বো দেবে।

শুধু একটি পণ্য সুপারিশ করা টুলের তুলনায় M餐搭子 প্রতিটি কম্বোর দাম, ক্যালরি, প্রোটিন, বাজেট ব্যবহারের পরিমাণ, অবশিষ্ট ক্যালরি এবং সুপারিশের কারণ দেখায়। ব্যবহারকারী MCP কল চেইনও খুলে প্রতিটি Tool-এর অবস্থা ও সময় দেখতে পারেন।

প্রকল্পটি 2026 McDonald's প্রোগ্রামার ক্রিয়েটিভ ডেভেলপমেন্ট প্রতিযোগিতায় অংশ নিয়েছে, তবে এটি McDonald's-এর কোনো অফিসিয়াল পণ্য নয়। খাবারের সরবরাহ, দাম ও প্রচারণা McDonald's-এর অফিসিয়াল চ্যানেলের বাস্তব তথ্য অনুযায়ী বিবেচনা করতে হবে। প্রদত্ত ফলাফল চিকিৎসা বা পুষ্টি-সংক্রান্ত পেশাদার পরামর্শ নয়।

প্রকল্পটি কোন সমস্যার সমাধান করে

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

M餐搭子-এর পদ্ধতি হলো প্রথমে ব্যবহারকারীকে এই খাবারের সীমা নির্ধারণ করতে দেওয়া, তারপর বাস্তব মেনু থেকে ফলাফল গণনা করা; ব্যবহারকারীকে আগে নির্দিষ্ট পণ্য বেছে নিতে হয় না। এটি মেনুর দাম, পুষ্টি-তথ্য ও অফার একই ওয়ার্কবেঞ্চে একত্র করে, ফলে সুপারিশের প্রক্রিয়া বোঝা ও যাচাই করা সহজ হয়।

মূল সক্ষমতা

• রিয়েল-টাইম স্টোর অনুসন্ধান: query-nearby-stores-এর মাধ্যমে শহর ও ল্যান্ডমার্ক অনুযায়ী কাছাকাছি নিজে সংগ্রহ করা যায় এমন স্টোর খোঁজা।
• রিয়েল-টাইম মেনু পড়া: query-meals-এর মাধ্যমে বর্তমান স্টোরের দাম, মূল দাম, পণ্যের ছবি ও ট্যাগ সংগ্রহ করা।
• পুষ্টি মিল: list-nutrition-foods ব্যবহার করে মেনুর পণ্যকে ক্যালরি ও প্রোটিনের তথ্যের সঙ্গে মিলিয়ে নেওয়া।
• তিনটি খাবার-কম্বো ফলাফল: যথাক্রমে “ভারসাম্যপূর্ণ পছন্দ”, “প্রোটিন বাড়তি” এবং “সহজ কম্বো” দেওয়া হয়, যাতে শুধু একটি ব্ল্যাক-বক্স উত্তর না থাকে।
• ব্যাখ্যাযোগ্য সূচক: প্রতি ইউনিট মুদ্রায় প্রোটিন, বাজেট ব্যবহার, অবশিষ্ট ক্যালরি এবং অফারের পার্থক্য দেখানো।
• অফার ও প্রচারণা: available-coupons এবং campaign-calendar কল করে পাওয়া যায় এমন কুপন ও সাম্প্রতিক প্রচারণা এক জায়গায় দেখানো।
• কলের অনুসরণযোগ্যতা: ব্যবহারকারী MCP Tool-এর কলের অবস্থা ও সময় দেখতে পারেন।
• নিরাপদ বিকল্প ব্যবস্থা: Token কনফিগার করা না থাকলে বা Tool সাময়িকভাবে unavailable হলে, সিস্টেম স্পষ্টভাবে চিহ্নিত ডি-আইডেন্টিফায়েড ডেমো স্ন্যাপশট ব্যবহার করে।

চালানোর আগে প্রস্তুতি

রিয়েল-টাইম MCP সংস্করণ চালাতে স্থানীয়ভাবে রিপোজিটরির Node সার্ভিস চালাতে হবে। শুরু করার আগে নিচের পরিবেশ প্রস্তুত করুন:

• Node.js 20 বা তার পরের সংস্করণ
• npm 10 বা তার পরের সংস্করণ
• একটি McDonald's MCP Token; শুধু ডেমো ডেটা ব্যবহার করলে এটি না দিলেও হবে

ইনস্টল করতে না চাইলে GitHub Pages অনলাইন ডেমো দেখতে পারেন। এটি একটি সম্পূর্ণ ফ্রন্টএন্ড ডেমো, যেখানে শর্ত পরিবর্তন ও খাবার-কম্বো গণনার সম্পূর্ণ সুবিধা আছে, তবে রিয়েল-টাইম MCP ডেটার বদলে ডি-আইডেন্টিফায়েড মেনু স্ন্যাপশট ব্যবহার করা হয়।

ইনস্টলেশন ও কনফিগারেশন

ধাপ 1: ক্লোন করে নির্ভরতা ইনস্টল করুন

টার্মিনালে নিচের কমান্ডগুলো চালান। রিপোজিটরি ঠিকানার placeholder-টি প্রকৃত ঠিকানা দিয়ে প্রতিস্থাপন করুন:

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

ধাপ 2: পরিবেশ ভেরিয়েবল কনফিগার করুন

প্রকল্পের root directory-র .env ফাইল খুলে MCP Token ও সার্ভার পোর্ট লিখুন:

MCD_MCP_TOKEN=YOUR_MCD_MCP_TOKEN
PORT=8787

• MCD_MCP_TOKEN বাধ্যতামূলক নয়। কনফিগার করলে রিয়েল-টাইম MCP চালু হবে; না করলে ডেমো ডেটা ব্যবহার হবে।
• PORT বাধ্যতামূলক নয়; ডিফল্ট মান 8787।

MCP Token শুধু সার্ভারের পরিবেশ ভেরিয়েবলে রাখা উচিত। এটি ফ্রন্টএন্ড কোডে লিখবেন না এবং পাবলিক রিপোজিটরিতে জমা দেবেন না।

ধাপ 3: ডেভেলপমেন্ট পরিবেশ চালু করুন

npm run dev

চালু হওয়ার পর ব্রাউজারে http://localhost:5173 খুলুন। ডেভেলপমেন্ট কমান্ডটি Express API চালায় এবং Vite hot reload সক্রিয় করে, যা ইন্টারফেস ও সার্ভার-সাইড লজিক ডিবাগ করার জন্য উপযোগী।

Token ছাড়া ডেমো মোড

McDonald's MCP Token না থাকলে production সংস্করণ build ও চালু করতে পারেন:

npm install
npm run build
npm start

তারপর http://localhost:8787 খুলুন। এই সময় পেজে স্পষ্টভাবে “ডেমো ডেটা” দেখানো হবে এবং মেনু, দাম ও প্রচারণা ডি-আইডেন্টিফায়েড স্ন্যাপশট থেকে নেওয়া হবে।

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

মৌলিক ব্যবহার: তিনটি খাবার-কম্বো তৈরি

ধাপ 1: পছন্দ নির্বাচন

ওয়ার্কবেঞ্চে প্রবেশের পর প্রথমে “ভারসাম্যপূর্ণ” ধরনের পছন্দ বেছে নিতে পারেন। পছন্দটি কম্বোর স্কোরে প্রভাব ফেলবে, তবে ফলাফল বাজেট, ক্যালরি ও প্রোটিনের লক্ষ্য দ্বারা সীমাবদ্ধ থাকবে।

ধাপ 2: খাবারের শর্ত পূরণ করুন

নিচের উদাহরণ শর্তগুলো দিয়ে শুরু করতে পারেন:

শহর: সাংহাই শহর
ব্যবসায়িক এলাকা / ল্যান্ডমার্ক: পিপলস স্কয়ার
বাজেট: 35 ইউয়ান
সর্বোচ্চ ক্যালরি: 700 kcal
প্রোটিনের লক্ষ্য: 35 g

ধাপ 3: গণনার ফলাফল দেখুন

সার্ভার কাছাকাছি স্টোর খুঁজে মেনু ও পুষ্টি-তথ্য পড়ে তিন ধরনের পরিকল্পনা ফেরত দেবে:

1. পরিকল্পনা A: ভারসাম্যপূর্ণ পছন্দ। বাজেট ও ক্যালরির সীমার মধ্যে প্রধান খাবারের সঙ্গে স্ন্যাকস বা পানীয় দেবে এবং প্রোটিন, প্রতি ইউনিট মুদ্রায় প্রোটিন ও সুপারিশের কারণ দেখাবে।
2. পরিকল্পনা B: প্রোটিন বাড়তি। বাজেট ও ক্যালরির সীমা যতটা সম্ভব বজায় রেখে প্রোটিন বাড়ানোকে অগ্রাধিকার দেবে।
3. পরিকল্পনা C: সহজ কম্বো। কম দামের, তবে সম্পূর্ণ কম্বো দেবে; খরচ ও বাছাইয়ের দক্ষতাকে বেশি গুরুত্ব দেওয়া পরিস্থিতির জন্য উপযোগী।

পরিকল্পনা তুলনা করার সময় শুধু মোট প্রোটিন দেখবেন না। প্রতি ইউনিট মুদ্রায় প্রোটিন, অবশিষ্ট বাজেট, অবশিষ্ট ক্যালরি এবং অফারের পার্থক্যও বিবেচনা করে কোন ফলাফলটি বর্তমান প্রয়োজনের সঙ্গে বেশি সামঞ্জস্যপূর্ণ তা নির্ধারণ করুন।

ধাপ 4: MCP কল চেইন পরীক্ষা করুন

“MCP কল চেইন” খুললে স্টোর, মেনু, পুষ্টি, অফার ও প্রচারণার Tool-এর অবস্থা ও সময় দেখা যাবে। এতে বোঝা যায় সুপারিশটি রিয়েল-টাইম ডেটার ওপর ভিত্তি করে তৈরি হয়েছে, নাকি Token না থাকা বা Tool unavailable হওয়ার কারণে ডেমো স্ন্যাপশটে পরিবর্তিত হয়েছে।

প্রচলিত ডেভেলপমেন্ট কমান্ড

• npm run dev: Express API ও Vite hot reload চালু করে।
• npm run build: ফ্রন্টএন্ড build এবং সার্ভার-সাইড compile করে।
• npm start: production সার্ভিস চালু করে।
• npm test: কম্বো লজিক ও পুষ্টি বিশ্লেষণ পরীক্ষা চালায়।
• npm run check: ধারাবাহিকভাবে type check, সার্ভার compile check ও test চালায়।

পুষ্টি বিশ্লেষণ, মেনু mapping বা খাবার-কম্বো নিয়ম পরিবর্তনের পর অন্তত নিচের কমান্ডগুলো চালানোর পরামর্শ দেওয়া হয়:

npm test
npm run check

এতে type error, compile সমস্যা এবং কম্বো সীমা বা পুষ্টি বিশ্লেষণ-সংক্রান্ত regression দ্রুত ধরা যায়।

Docker ব্যবহার করে ডেপ্লয়

প্রকল্পটি Docker build সমর্থন করে। প্রথমে image তৈরি করুন:

docker build -t mcd-meal-mate .

এরপর স্থানীয় 8787 পোর্টটি container-এ map করে environment variable-এর মাধ্যমে Token দিন:

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

Container চালু হলে http://localhost:8787 খোলা যাবে। MCD_MCP_TOKEN বাদ দিলে অ্যাপ্লিকেশন ডেমো ডেটা ব্যবহার করবে।

প্রকল্পের কাঠামো বোঝা

প্রকল্পটি React ফ্রন্টএন্ড, Express সার্ভার, MCP কল, পুষ্টি বিশ্লেষণ ও কম্বো পরিকল্পনাকে আলাদা মডিউলে ভাগ করেছে:

src/
  App.tsx          React ওয়ার্কবেঞ্চ ও responsive interaction
  styles.css       সম্পাদকীয় মেনু × রসিদ-ভিত্তিক ভিজ্যুয়াল সিস্টেম
server/
  index.ts         Express API, ইনপুট যাচাই ও static resource
  mcp.ts           MCP JSON-RPC client, Tool orchestration ও fallback
  nutrition.ts     পুষ্টি টেক্সট parsing, মেনু mapping ও পণ্যের ভূমিকা শনাক্তকরণ
  planner.ts       কম্বো সীমা, পছন্দের স্কোরিং ও তিন পরিকল্পনা নির্বাচন
  demo-data.ts     ডি-আইডেন্টিফায়েড ডেমো স্ন্যাপশট
  planner.test.ts  পুষ্টি ও কম্বো পরীক্ষা
shared/
  types.ts         ফ্রন্টএন্ড ও ব্যাকএন্ডের shared type

server/mcp.ts MCP JSON-RPC যোগাযোগ, Tool orchestration ও ব্যর্থতার fallback পরিচালনা করে; server/nutrition.ts পুষ্টি টেক্সট ও মেনু পণ্যের mapping করে; server/planner.ts কম্বো সীমা, পছন্দের স্কোরিং ও তিন পরিকল্পনা নির্বাচন সম্পন্ন করে। ফ্রন্টএন্ড ও ব্যাকএন্ডের সাধারণ data structure shared/types.ts-এ রয়েছে।

ব্যাকএন্ড native fetch ব্যবহার করে McDonald's MCP Streamable HTTP Server-এর সঙ্গে যোগাযোগ করে। Production build-এ একই Express process API ও static page দুটিই সরবরাহ করে এবং memory-তে মেনু ও পুষ্টির ফলাফল cache করে।

উন্নত ব্যবহার ও ডেভেলপমেন্ট পরামর্শ

প্রথমে সীমা থেকে ফলাফল যাচাই করুন

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

রিয়েল-টাইম ডেটা ও ডেমো স্ন্যাপশট আলাদা করুন

ডিবাগ করার সময় পেজে “ডেমো ডেটা” দেখাচ্ছে কি না এবং MCP কল চেইন পরীক্ষা করুন। Token না থাকা, Tool সাময়িকভাবে unavailable হওয়া বা pure frontend GitHub Pages সংস্করণ চালানোর ক্ষেত্রে ফলাফল ডি-আইডেন্টিফায়েড স্ন্যাপশট থেকে আসতে পারে।

সার্ভার-সাইড credential সুরক্ষিত রাখুন

Token ব্রাউজার প্রান্তে inject করবেন না। প্রকল্পটি ইতিমধ্যেই Express সার্ভিসের মাধ্যমে environment variable পড়ে এবং সার্ভার থেকেই MCP কল করে, ফলে architecture-এর দিক থেকে Token ফ্রন্টএন্ডে প্রকাশ পায় না। সার্ভার বা container-এ ডেপ্লয় করার সময়ও নিরাপদ environment variable management পদ্ধতিতে credential inject করুন।

পরিকল্পনার লজিক পরিবর্তনের পর সম্পূর্ণ check চালান

planner.ts, nutrition.ts বা shared type পরিবর্তন করলে type, compile ও test check-এর জন্য npm run check ব্যবহার করুন। প্রকল্পে কম্বো ও পুষ্টি বিশ্লেষণের পরীক্ষা রয়েছে, যা পরিবর্তনটি বিদ্যমান আচরণে প্রভাব ফেলেছে কি না যাচাই করতে সাহায্য করে।

ইন্টিগ্রেশন তথ্য দেখুন

রিপোজিটরির MCP_INTEGRATION.md সম্পূর্ণ Tool, কলের প্রবাহ, ব্যবসায়িক মূল্য ও নিরাপত্তা সীমা নথিভুক্ত করে; mcp-config.example.json ডি-আইডেন্টিফায়েড configuration-এর উদাহরণ দেয়; workbuddy.md-তে WorkBuddy সংযোগের context ও পুনরুৎপাদনযোগ্য নির্দেশনা রয়েছে। অন্য Agent বা Skill যুক্ত করার সময় আগে এই ফাইলগুলো দেখুন।

নিরাপত্তার সীমা

• রিপোজিটরিতে প্রকৃত Token, password বা account credential নেই।
• MCP Token শুধু সার্ভারের environment variable থেকে পড়া হয়।
• প্রকল্পটি অর্ডার, payment, lottery বা points exchange Tool কল করে না।
• সার্ভার ব্যবহারকারীর input সংরক্ষণ করে না এবং user profile তৈরি করে না।
• খাবারের সরবরাহ, দাম ও প্রচারণার ক্ষেত্রে McDonald's-এর অফিসিয়াল চ্যানেলকে অগ্রাধিকার দিতে হবে।
• সুপারিশের ফলাফল চিকিৎসা, পুষ্টি বা অন্য কোনো পেশাদার পরামর্শ নয়।

সারসংক্ষেপ

M餐搭子 দোকান খোঁজা, রিয়েল-টাইম মেনু, পুষ্টি মিল, অফারের তথ্য এবং কম্বিনেশন পরিকল্পনাকে একটি ব্যাখ্যাযোগ্য খাবার-সমন্বয় প্রক্রিয়ায় একত্রিত করে। MCP Token কনফিগার করার পর এটি বর্তমান দোকানের ডেটা ব্যবহার করতে পারে; Token না থাকলেও ডেটা গোপনীয়তা-রক্ষিত স্ন্যাপশটের মাধ্যমে সম্পূর্ণ ইন্টারঅ্যাকশন অভিজ্ঞতা নেওয়া যায়।

ইনস্টলেশন সম্পন্ন হলে, প্রথমে উদাহরণ শর্ত ব্যবহার করে তিনটি পরিকল্পনা যাচাই করা যায়, এরপর MCP কল চেইনের মাধ্যমে ডেটার উৎস নিশ্চিত করা যায়। ডেভেলপাররা mcp.ts, nutrition.ts এবং planner.ts থেকে শুরু করে রিয়েল-টাইম ডেটা অর্কেস্ট্রেশন, পুষ্টি ম্যাপিং এবং সীমাবদ্ধতা গণনার বাস্তবায়ন পদ্ধতি বুঝতে পারেন।