MCP কানেক্ট করা অ্যাপ ইন্টিগ্রেশন স্ট্যান্ডার্ড

MCP সার্ভার, Connected Apps Platform-এর সাথে আপনার অ্যাপের ফাংশন (MCP টুল) কানেক্ট করার জন্য ফ্রেমওয়ার্ক তৈরি করে। আপনার পরিষেবার ফলাফল আরও নির্ভরযোগ্যভাবে বেছে নিতে, কল করতে এবং প্রসেস করতে, আপনার MCP কনফিগারেশনকে অবশ্যই নিম্নলিখিত স্ট্যান্ডার্ডগুলি কঠোরভাবে মেনে চলতে হবে।

নির্দেশক নীতি

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

ভার্সনিং

স্কেলেবল ও শক্তিশালী MCP ডিপ্লয়মেন্টে সহায়তা করতে, পাথ-ভিত্তিক ভার্সনিং ব্যবহার করে এমন স্ট্রাকচার্ড URI আর্কিটেকচার গ্রহণ করুন—যেমন, /v1, /v2। এটি করলে, আপনি ব্যাকওয়ার্ড কম্প্যাটিবিলিটি বজায় রাখতে এবং নতুন ফিচার গেট করতে পারবেন। প্রোভাইডার-নির্দিষ্ট সাবডোমেন, যেমন https://gemini.mcp.company.com/mcp/v1-এর সাথে এটি পরিপূরক হিসেবে ব্যবহার করলে, গ্র্যানুলার ট্রাফিক ম্যানেজমেন্ট এবং বিভিন্ন AI মডেলের অনন্য প্রসঙ্গ ও প্রসেসিং আচরণের সাথে মানানসই টুল সংজ্ঞার অপ্টিমাইজেশন সম্ভব হয়।

MCP প্রোটোকল ভার্সনের কম্প্যাটিবিলিটি

Connected Apps Platform ভার্সন 2025-11-25 পর্যন্ত মডেল কন্টেক্সট প্রোটোকল (MCP) স্পেসিফিকেশন সাপোর্ট করে। নতুন স্পেসিফিকেশন রিলিজ এখনও কাজ করে না।

  • ডেভেলপারের দায়িত্ব: initialize হ্যান্ডশেক এবং সব টুল ও স্কিমা সংজ্ঞা জুড়ে আপনার MCP সার্ভার যাতে Connected Apps Platform (2025-11-25) দ্বারা সমর্থিত প্রোটোকল ভার্সন কঠোরভাবে মেনে চলে তা নিশ্চিত করার দায়িত্ব আপনার।
  • প্ল্যাটফর্ম ব্যাকওয়ার্ড কম্প্যাটিবিলিটি: Connected Apps Platform ভবিষ্যতে নতুন MCP স্পেসিফিকেশন ভার্সন গ্রহণ করার সাথে সাথে, আমাদের ক্লায়েন্ট আগে থেকে কাজ করে এমন প্রোটোকল ভার্সনের সাথে ব্যাকওয়ার্ড কম্প্যাটিবিলিটি বজায় রাখবে যাতে আগে থেকে থাকা প্রোডাকশন ইন্টিগ্রেশন কোনও বাধা ছাড়াই কাজ করা চালিয়ে যেতে পারে।
  • আপগ্রেড ম্যানেজ করা: আপনি যখন নতুনভাবে কাজ করে এমন MCP স্পেসিফিকেশন গ্রহণ করতে বা স্কিমা পরিবর্তন করতে প্রস্তুত হবেন, তখন অ্যাক্টিভ ট্রাফিকের জন্য আপনার বর্তমান এন্ডপয়েন্ট (/mcp/v1) বজায় রেখে একটি নতুন ভার্সন করা URI পাথে (যেমন, /mcp/v2) সেই আপডেটগুলি প্রকাশ করুন।

অ্যাপের বিভিন্ন ভার্সনের মধ্যে MCP স্কিমা পরিবর্তন করার অনুমতি দেওয়া হয়। আমরা সাজেস্ট করি যে আপনি এই ফিচারটি ব্যবহার করুন এবং নতুন ফিচারের রোলআউট সহজ করতে MCP এন্ডপয়েন্টের ভার্সন ব্যবহার করুন অথবা ব্যাকওয়ার্ড কম্প্যাটিবল পরিবর্তনের উপর নির্ভর করুন।

ট্রান্সপোর্ট প্রোটোকল স্পেসিফিকেশন

Connected Apps Platform কঠোরভাবে স্ট্রিমযোগ্য HTTP ট্রান্সপোর্ট মডেল কন্টেক্সট প্রোটোকল স্পেসিফিকেশন ভার্সন ২০২৫-০৩-২৬ এবং তার পরবর্তী ভার্সন সাপোর্ট করে। এটি ০৫-১১-২০২৪ স্পেসিফিকেশন-এ বর্ণিত SSE ট্রান্সপোর্ট সহ লিগ্যাসি HTTP-তে কাজ করে না।

  • একটি HTTP এন্ডপয়েন্ট। Connected Console-এ দেওয়া MCP এন্ডপয়েন্ট (যেমন, https://api.example.com/mcp) হল সেই একক URL যেখানে প্রযোজ্য Google প্রোডাক্ট স্ট্যান্ডার্ড HTTP POST-এর মাধ্যমে সব JSON-RPC অনুরোধ (initialize, tools/list, tools/call) পাঠায়।
  • স্ট্রিম করা যায় এমন HTTP-এর মধ্যে SSE স্ট্রিমিং। পুরনো মাল্টি-এন্ডপয়েন্ট SSE ট্রান্সপোর্ট কাজ করে না, তবে স্ট্রিম করা যায় এমন HTTP-তে text/event-stream-এর মতো সার্ভার-প্রেরিত ইভেন্ট কাজ করে। প্রযোজ্য Google প্রোডাক্ট থেকে আউটগোয়িং অনুরোধে Accept: application/json, text/event-stream অন্তর্ভুক্ত থাকে, যার অর্থ হল আপনার সার্ভার হয় স্ট্যান্ডার্ড application/json পেলোড ফেরত দিতে পারে অথবা সরাসরি HTTP POST রেসপন্স বডিতে Content-Type: text/event-stream ব্যবহার করে ইনক্রিমেন্টাল রেসপন্স স্ট্রিম করতে পারে।
  • GET স্ট্রিম ও 405 পদ্ধতি অনুমোদিত নয়। সার্ভার-টু-ক্লায়েন্ট বিজ্ঞপ্তির জন্য ক্লায়েন্ট এন্ডপয়েন্টে ঐচ্ছিক GET স্ট্রিম করার চেষ্টা করতে পারে। আপনার সার্ভার স্টেটলেস বা শুধু অনুরোধ-উত্তরের ভিত্তিতে কাজ করলে, HTTP 405 Method Not Allowed ফেরত পাঠানো স্পষ্টভাবে কাজ করে এবং Google-এর প্রযোজ্য প্রোডাক্টের ক্লায়েন্ট প্রক্সি দ্বারা পরিষ্কারভাবে ম্যানেজ করা হয়।

সার্ভার সংক্রান্ত নির্দেশাবলী

Connected Apps Platform-কে সার্ভারের নির্দেশাবলী গ্রহণ করার জন্য অপ্টিমাইজ করা হয়েছে, যা মডেলের আচরণের উপর এমন মাত্রার নিয়ন্ত্রণ প্রদান করে যা অন্য উপায়ে পাওয়া যায় না।

সার্ভার সংক্রান্ত নির্দেশাবলী অনুসরণ করুন।

ব্যবহারের প্রসঙ্গ সহ "মডেল ইঙ্গিত" হিসেবে বিবেচনা করুন

মডেলকে ইঙ্গিত দেওয়ার ব্যাপারে এইসব নির্দেশিকা অনুসরণ করুন।

  • সার্ভারের সামগ্রিক উদ্দেশ্য ও ক্ষমতা বুঝতে LLM-কে সাহায্য করার জন্য হাই-লেভেল "ইঙ্গিত" বা গাইড হিসেবে নির্দেশাবলী লিখুন।
  • এটি কী করতে পারে তা বর্ণনা করুন, ফিচার তালিকাভুক্ত করা বা মডেল কীভাবে সার্ভারের টুল ও রিসোর্স ব্যবহার করবে তা বর্ণনা করার পরিবর্তে। মডেল যদি "কী" সঠিকভাবে বুঝতে পারে, তাহলে ব্যবহারকারীর অভিজ্ঞতার উপর ভিত্তি করে এটি কীভাবে ভালভাবে নির্ধারণ করতে পারে।
  • মনে করুন, এই টেক্সট সরাসরি মডেলের সিস্টেম প্রম্পটে যোগ করা হবে। এটি স্পষ্ট, নির্দেশমূলক এবং টোকেন-দক্ষ রাখুন।

পরিপূরক করুন, ডুপ্লিকেট করবেন না

এই স্পেসটি গ্লোবাল কনটেক্সটের জন্য ব্যবহার করুন যা সমস্ত টুল জুড়ে প্রযোজ্য, প্রতিটি টুলের বিবরণের সাথে অপ্রয়োজনীয়তা এড়িয়ে চলুন।

সার্ভার নির্দেশাবলীর উদাহরণ

সার্ভার নির্দেশাবলী সঠিকভাবে লেখার ক্ষেত্রে কী করা উচিত এবং কী করা উচিত নয় তা নিম্নলিখিত উদাহরণগুলি থেকে জানতে পারবেন।

সাজেস্ট করা হয়েছে সাজেস্ট করা হয় না

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

সংক্ষিপ্ত, নির্দেশমূলক এবং মডেলের পরিপূরক

  • "কীভাবে" করার পরিবর্তে "কী" (প্রোজেক্টের স্বাস্থ্য, ট্রায়াজিং) তা নির্ধারণ করে
  • যাচাইকরণের স্কোপ উল্লেখ করে যা সব টুলের ক্ষেত্রে প্রযোজ্য

এই সার্ভারে GitHub-এর জন্য টুল আছে। ব্যবহারকারী সমস্যা সম্পর্কে জানতে চাইলে আপনার list_issues টুল ব্যবহার করা উচিত। আপনি create_pull_request ব্যবহার করে PR তৈরি করতে পারবেন। ব্যবহারকারীকে তার কোড ম্যানেজ করতে সাহায্য করার জন্য এই টুলগুলি সাবধানে ব্যবহার করুন। কোনও টুল কল করার আগে সবসময় রিপোজিটরির নাম চেক করুন। ব্যবহারকারী সারসংক্ষেপ চাইলে, প্রথমে টুল কল করুন এবং তারপর আউটপুটের সারসংক্ষেপ করুন

  • টুলের নাম আবার তালিকাভুক্ত করবে না,
  • মডেলকে "কীভাবে" ভাবতে হবে তা বলবেন না, কারণ এটি মডেলের বিল্ট-ইন রিজনিংয়ের সাথে বিরোধপূর্ণ হতে পারে, যা সঠিক সিদ্ধান্ত নিতে ব্যবহারকারীর প্রসঙ্গ ব্যবহার করবে।
  • সার্ভারের অ্যাক্সেসের ধরন বা এর নির্দিষ্ট সীমাবদ্ধতা ব্যাখ্যা করে না)

টুল সংক্রান্ত নির্দেশিকা

নিম্নলিখিত নির্দেশিকা আপনার অ্যাপের মধ্যে বিভিন্ন ফাংশন বা টুলের জন্য MCP সার্ভার কনফিগারেশন তৈরি করার পেশাদার পদ্ধতি বর্ণনা করে।

টুলের নাম দেওয়ার কনভেনশন

আপনার টুলের নাম দেওয়ার জন্য নিম্নলিখিত নির্দেশিকা অনুসরণ করুন:

সহজবোধ্য, মানুষের-পঠনযোগ্য নাম ব্যবহার করুন

অস্পষ্ট নামের পরিবর্তে স্পষ্ট, সহজবোধ্য অর্থ সহ মানুষের-পঠনযোগ্য নাম ব্যবহার করুন। যেমন, get_user_information-এর উত্তর userInfo-এর থেকে বেশি স্পষ্ট।

সঠিক কেসিং স্টাইল লক্ষ্য করুন

টুল ফাংশনের নাম ও অ্যাপ ট্রিগারের জন্য নিম্নলিখিত কেসিং সংক্রান্ত নিয়ম মেনে চলুন:

  • টুল ফাংশন কেসিং। আপনার MCP স্কিমায় (যেমন, get_user_information বা publishDraft) সংজ্ঞায়িত টুল ফাংশনের নামের জন্য snake_case বা camelCase ব্যবহার করুন।
  • অ্যাপ ট্রিগার হ্যান্ডেল কেসিং। অ্যাপ ট্রিগার ও উল্লেখ (যেমন, @MyTwoWordApp) ছোট ও বড় হাতের অক্ষরের মধ্যে পার্থক্য করে না। প্ল্যাটফর্মটি ছোট হাতের অক্ষর (@mytwowordapp), PascalCase (@MyTwoWordApp) এবং camelCase (@myTwoWordApp) জুড়ে ব্যবহারকারীর ইনপুটকে স্বাভাবিক করে।
  • নাম দেখানোর ফর্ম্যাটিং। UI এলিমেন্টে স্পষ্ট ভিজ্যুয়াল ডিসপ্লের জন্য PascalCase বা স্ট্যান্ডার্ড স্পেস ব্যবহার করে আপনার অফিসিয়াল অ্যাপের নাম রেজিস্টার করুন।
  • টাইপো ম্যানেজ করা। কেসিংয়ের তারতম্য অটোমেটিক ম্যানেজ করা হলেও, অক্ষর টাইপ করার সময় হওয়া ভুল (যেমন, @mytwowrodapp) সরাসরি স্ট্রিং ম্যাচিংয়ের পরিবর্তে ফলব্যাক ইনটেন্ট শনাক্তকরণের উপর নির্ভর করে। ডেভেলপারদের উচিত ডকুমেন্টেশনে সঠিক হ্যান্ডেল বানান ব্যবহার করতে উৎসাহিত করা।

স্পষ্ট ক্রিয়াপদ-বিশেষ্য নামকরণ ব্যবহার করুন

নির্দিষ্ট verb_noun নাম ব্যবহার করুন এবং অস্পষ্টতা এড়িয়ে চলুন—যেমন, publish_draft, handle_content-এর চেয়ে ভালো।

টুল গ্র্যানুলারিটি

টুল গ্রানুলারিটির ক্ষেত্রে নিম্নলিখিত নির্দেশিকাগুলি লক্ষ্য করুন।

টুলকে অ্যাটমিক এন্ডপয়েন্ট হিসেবে বিবেচনা করো

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

আরও ফ্ল্যাট স্কিমা ব্যবহার করুন

ইনপুট যাচাই করার জন্য আপনার যদি গভীরভাবে নেস্ট করা অবজেক্ট বা জটিল oneOf / anyOf স্কিমা লজিকের প্রয়োজন হয়, তাহলে আপনার টুলটি সম্ভবত খুব বিস্তৃত।

প্রি-অ্যাগ্রিগেশন ও পেলোড গার্ডরেল লক্ষ্য করুন

যদিও ছোট, স্কোপড পেলোডের জন্য প্রোটোকল দ্বারা প্রি-অ্যাগ্রিগেটিং ডেটা কঠোরভাবে প্রয়োগ করা হয় না, বড় রেকর্ড সেট, অনুদৈর্ঘ্য ইতিহাস এবং মাল্টি-সোর্স ডেটাসেটের সাথে কাজ করার সময় ব্যাকএন্ড প্রি-অ্যাগ্রিগেশন বাস্তবে অত্যন্ত প্রয়োজন। Connected Apps Platform কন্টেক্সট উইন্ডোর সীমা, এক্সিকিউশন লেটেন্সি এবং মডেল রিজনিং স্টেপের ক্ষেত্রে গার্ডরেল প্রয়োগ করে। এইসব গার্ডরেল মেনে চলতে, এইসব নির্দেশিকা অনুসরণ করুন:

  • ব্যাকএন্ডে ফিল্টার ও সারসংক্ষেপ করা। প্রযোজ্য Google প্রোডাক্টে উত্তর পাঠানোর আগে, আপনার MCP সার্ভারে সবসময় বড় ডেটা স্ট্রিম ফিল্টার, প্রি-অ্যাগ্রিগেট বা সারসংক্ষেপ করুন।
  • র-ডাম্প এড়িয়ে চলুন। টুল রিটার্ন পেলোডে কখনও কাঁচা ডেটাবেস সারি বা সম্পূর্ণ ইন্ডেক্স না করা লগ ডাম্প করবেন না।

ইন্টার্নাল ও মেটা টুল বাদ দিন

আপনার সার্ভারের tools/list উত্তরে শুধুমাত্র মডেল-ফেসিং ক্ষমতা প্রকাশ করুন:

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

টুল গ্র্যানুলারিটি সংক্রান্ত করণীয় ও বর্জনীয়

টুলের নাম ও গ্র্যানুলারিটি ব্যবহারের ক্ষেত্রে কী করা উচিত ও কী করা উচিত নয় তা নিম্নলিখিত উদাহরণ থেকে জানতে পারবেন।

সাজেস্ট করা হয়েছে সাজেস্ট করা হয় না

স্পষ্ট নাম ও প্যারামিটার সহ গ্র্যানুলার টুল

প্রতিটি টুলের ইনপুট স্কিমা কঠোরভাবে মেনে চলতে হয়। LLM যদি কোনও ব্যবহারকারী তৈরি করতে চায়, তাহলে তাকে অবশ্যই একটি ইমেল দিতে হবে। এটি মুছে দিতে চাইলে, অবশ্যই একটি আইডি প্রদান করতে হবে। কোনও অনুমান নেই।

...
@mcp.tool()
def create_user(email: str, role: str = "viewer") -> str:
    """Register a new user. Returns the new User ID."""
    # Logic is purely creation
    return "user_123"

@mcp.tool()
def delete_user(user_id: str) -> str:
    """Permanently remove a user by their ID."""
    # Logic is purely deletion
    return f"User {user_id} deleted"

@mcp.tool()
def update_user_role(user_id: str, new_role: str) -> str:
    """Change an existing user's permission level."""
    return f"User {user_id} is now {new_role}"

    ...

টুলের নাম: manage_user

বিবরণ: "ব্যবহারকারী তৈরি, আপডেট, মুছে ফেলতে বা ফিরিয়ে আনতে এই টুল ব্যবহার করুন।"

...
@mcp.tool()
def manage_user(
    action: Literal["create", "update", "delete", "get"],
    user_id: Optional[str] = None,
    email: Optional[str] = None,
    role: Optional[str] = "viewer"
) -> str:
    """
    Use this to manage users.
    WARNING: logic is hidden inside Python, not visible in the schema.
    """
    if action == "create":
        if not email: return "Error: Email required for creation" # Runtime error, not schema error
        return f"Created user {email}"
    elif action == "delete":
        if not user_id: return "Error: User ID required"
        return f"Deleted {user_id}"
    
    return "Action completed"
    """
    ...

নিরাপত্তার জন্য টুল অ্যানোটেশন ঘোষণা করুন

এক্সিকিউশন আচরণ জানাতে এবং প্রযোজ্য Google প্রোডাক্ট জুড়ে বিল্ট-ইন সেফটি গেট ট্রিগার করতে আপনার টুল সংজ্ঞার মধ্যে প্রোটোকল অ্যানোটেশন কনফিগার করুন:

  • রানটাইম কনফার্মেশন গেট: প্রযোজ্য Google প্রোডাক্ট রানটাইম ব্যবহারকারী কনফার্মেশন প্রম্পট ট্রিগার করার জন্য annotations.destructiveHint: true এবং annotations.openWorldHint: true-কে কী ফ্ল্যাগ হিসেবে ব্যবহার করে। স্টেট-পরিবর্তন, রাইট বা ধ্বংসাত্মক অ্যাকশনের ক্ষেত্রে destructiveHint: true ঘোষণা করুন এবং ওপেন-ওয়ার্ল্ড বা এক্সটার্নাল এনভায়রনমেন্টের সাথে ইন্টার‍্যাক্ট করে এমন টুলের জন্য openWorldHint: true সেট করুন যাতে সারফেস নেটিভভাবে ব্যবহারকারীকে এক্সিকিউট করার আগে কনফার্মেশনের জন্য প্রম্পট করে।
  • শুধু-পড়ার-জন্য কোয়েরি সংক্রান্ত ইঙ্গিত: কোয়েরি টুলে readOnlyHint: true সেট করুন যা শুধু ব্যাকএন্ড স্ট্যাটাস পরিবর্তন না করে ডেটা নিয়ে আসে।
  • স্পষ্ট অ্যানোটেশন ডিফল্ট: Model Context Protocol স্পেসিফিকেশন অনুযায়ী, readOnlyHint বাদ দিলে ক্লায়েন্টরা নিরাপত্তার জন্য ডিফল্ট হিসেবে readOnlyHint: false এবং destructiveHint: true ধরে নেয়। সব টুলে স্পষ্টভাবে অ্যানোটেশন ঘোষণা করলে, তা অনুমানযোগ্য মডেল রাউটিং ও সঠিক এক্সিকিউশন নিরাপত্তা নিশ্চিত করে।

টুলের বিবরণ

আপনার টুল বর্তমান সমস্যার সমাধান করতে পারবে কিনা তা সিদ্ধান্ত নেওয়ার জন্য মডেলের কাছে বিবরণই একমাত্র প্রসঙ্গ। বিবরণ লেখার জন্য নিম্নলিখিত নির্দেশিকা অনুসরণ করুন:

নির্দেশাবলী লিখুন, কমেন্ট নয়

টুলের বিবরণ নির্দেশাবলী হিসেবে লিখুন—কোড কমেন্ট হিসেবে নয়, যা প্রায়শই প্যাসিভ হয়। LLM নির্দেশাবলী অনুযায়ী ভাল উত্তর দেয়।

"কীভাবে" তা ব্যাখ্যা করুন

একটি ভালো বিবরণ "আমার কাছে একটি টুল আছে" এবং "আমি জানি কীভাবে এই টুলটি একটি কথোপকথনে ব্যবহার করতে হয়" এর মধ্যে ব্যবধান কমায়।

"কারণ" ব্যাখ্যা করুন

এই টুলটিকে একই ধরনের টুল থেকে আলাদা করুন—যেমন, "এটি ইন্টার্নাল ব্যবহারকারীদের জন্য ব্যবহার করুন, এক্সটার্নাল ব্যবহারকারীদের জন্য customer_update ব্যবহার করুন"।

মডেলকে বলুন কোথায় আর্গুমেন্ট খুঁজতে হবে—যেমন, "order_search টুল থেকে"।

ফর্ম্যাট উল্লেখ করা

ইউনিট (মিটার বনাম ফুট) এবং ফর্ম্যাট (ISO তারিখ, সিম্যান্টিক ভার্সন) উল্লেখ করুন।

মডেলের বিচক্ষণতা এড়িয়ে চলুন

মডেলকে তার "সেরা বিচার" ব্যবহার করার নির্দেশ দেবেন না বা ঐচ্ছিক, নির্দেশিত নয় এমন অ্যাকশনের সাজেশন দেবেন না।

টুলের বিবরণের উদাহরণ

রাইটিং টুলের বিবরণের ক্ষেত্রে কী করা উচিত এবং কী করা উচিত নয় তা নিম্নলিখিত উদাহরণ থেকে জানুন।

সাজেস্ট করা হয়েছে সাজেস্ট করা হয় না

Source of truth

"ব্যবহারকারীর ইমেল আপডেট করে। search_users টুল থেকে পাওয়া UUID 'id' কঠোরভাবে ব্যবহার করতে হবে। ব্যবহারকারীর আইডি অনুমান করবেন না।"

(এটি স্পষ্টভাবে একটি টুলের আউটপুটকে এই টুলের ইনপুটের সাথে লিঙ্ক করে।)

"ব্যবহারকারীর ইমেল আইডি আপডেট করে।"

(মডেলটি ১২৩৪৫-এর মতো কোনও আইডি অনুমান করতে পারে।)

ফর্ম্যাট ও সীমাবদ্ধতা

"মিটিং শিডিউল করো। 'তারিখ' ISO 8601 ফর্ম্যাটে (YYYY-MM-DD) হতে হবে। ব্যবহারকারী 'আগামীকাল' বা অন্য কোনও আপেক্ষিক রেফারেন্স দিলে, বর্তমান প্রসঙ্গের উপর ভিত্তি করে তারিখ গণনা করুন।"

"প্রদত্ত তারিখের জন্য মিটিং শিডিউল করতে চান।"

(মানুষের কাছে সঠিক মনে হয় (যেমন, "আগামীকাল") কিন্তু স্কিমা যাচাইকরণে ব্যর্থ হয় ("২০২৫-১০-১২" প্রয়োজন))

আউটপুট সংক্রান্ত প্রত্যাশা

"সার্ভার লগ ফিরিয়ে আনে। র টেক্সটের শেষ ৫০টি লাইন দেখায়। বিশ্লেষণের জন্য, টোকেন সীমা এড়াতে আরও ছোট টাইম উইন্ডোর অনুরোধ করুন।"

"সার্ভার লগ পান।"

(মডেলটি সারসংক্ষেপের প্রত্যাশায় কোনও টুলকে কল করতে পারে, একটি কাঁচা ৫ এমবি JSON ডাম্প পেতে পারে এবং এর ফলে ব্যবহারকারীর অভিজ্ঞতা খারাপ হতে পারে।)

 
@mcp.tool()
def update_campaign_status(campaign_id: str, status: str) -> str:
    """
    Promotes or pauses an advertising campaign.
    
    CRITICAL USAGE RULES:
    1. 'campaign_id': Must be the 32-character UUID retrieved from 'list_campaigns'.
    2. 'status': Must be exactly one of: ['active', 'paused', 'archived'].
    
    Returns: A confirmation string with the new status and timestamp.
    """
    # Logic...

    ...

এই বিবরণটি একটি মিনি-ম্যানুয়াল হিসেবে কাজ করে। এটি সোর্স (আইডি কোথা থেকে পাওয়া যাবে), সীমাবদ্ধতা (সঠিক enum) ও অ্যাকশন ম্যানেজ করে।

 
@mcp.tool()
def update_campaign_status(id: str, status: str) -> str:
    """
    Updates the campaign status in the database.
    """
    # Logic...

সব কাজ করার জন্য এটি ভেরিয়েবলের নামের উপর নির্ভর করে। এটি মডেলকে "স্ট্যাটাস"-এর জন্য সঠিক ভ্যালু অনুমান করতে দেয়

টুল প্যারামিটার

টুল ছাড়াও, প্যারামিটারগুলি বর্ণনা করুন যাতে সেগুলি স্পষ্ট হয়।

অনুপযুক্ত ধরন

শক্তিশালী, নির্দিষ্ট ধরন (string, integer, boolean, array) ব্যবহার করুন।

ফিক্সড ভ্যালু সেটের জন্য enum ব্যবহার করুন

কোনও প্যারামিটার যদি শুধুমাত্র নির্দিষ্ট সেট ভ্যালু গ্রহণ করে (যেমন, daylight, cool, warm), তাহলে সেগুলিকে enum অ্যারেতে তালিকাভুক্ত করুন। এটি নাটকীয়ভাবে অ্যাকুরেসি উন্নত করে।

প্রয়োজনীয় প্যারামিটার স্পষ্টভাবে উল্লেখ করুন

ফাংশনটি কাজ করার জন্য কোন প্যারামিটারগুলি বাধ্যতামূলক তা স্পষ্টভাবে সংজ্ঞায়িত করুন।

সেম্যান্টিক স্কিমা ম্যাচিং প্রয়োগ করুন

আপনার অ্যাপ ইন্টিগ্রেট করার সময়, আপনার টুল প্যারামিটার থেকে একটি সিম্যান্টিক স্কিমা ম্যাচিং আপনি যে ভার্টিক্যালের জন্য ডেভেলপ করছেন তার সাথে প্রয়োজন হতে পারে। অনবোর্ডিং প্রসেস চলাকালীন আপনি প্রত্যাশিত ভার্টিক্যাল স্কিমা (একটি JSON স্কিমা) পাবেন।

টুল প্যারামিটারের উদাহরণ

টুল প্যারামিটার ম্যানেজ করার ক্ষেত্রে কী করা উচিত এবং কী করা উচিত নয় তা নিম্নলিখিত উদাহরণ থেকে দেখুন।

সাজেস্ট করা হয়েছে সাজেস্ট করা হয় না

আর্গুমেন্ট ফর্ম্যাট ও ইউনিট

ব্যাসার্ধ: "মিটারে ব্যাসার্ধ। অবশ্যই ফ্লোট > ০ হতে হবে।"

(ইউনিট হ্যালুসিনেশন আটকায়)

ব্যাসার্ধ: "বৃত্তের ব্যাসার্ধ।"

আইডির ফর্ম্যাট ও প্রসঙ্গ

user_id: "ডেটাবেস UUID (যেমন, 550e8400-e29b...). এখানে ইমেল আইডি ব্যবহার করবেন না।"

মনে রাখবেন: পেশাদার পদ্ধতি হিসেবে, সব সংখ্যাসূচক আইডি ফিল্ডকে স্ট্রিং ভ্যালু হিসেবে বিবেচনা করা উচিত। বিশেষ করে, আপনার আইডি ১০+ সংখ্যার হলে, ইন্টার্নাল সিস্টেমের মাধ্যমে সেটি ট্রাঙ্কেট (৩২ বিট কন্টেনারে জোর করে ঢোকানো) হওয়ার ঝুঁকি থাকে এবং এই ভার্সনটি ভবিষ্যতে টুল কলের ক্ষেত্রে মডেলের মাধ্যমে ব্যবহার করা হয়।

(টাইপ সংক্রান্ত সমস্যা প্রতিরোধ করে)

user_id: "ব্যবহারকারীর আইডি।"

রিটার্ন ভ্যালু সংক্রান্ত প্রত্যাশা

"রেকর্ড আপডেট করে এবং নতুন টাইমস্ট্যাম্প সহ আপডেট করা JSON অবজেক্ট ফিরিয়ে দেয়।"

(মডেলকে বলে যে পরিবর্তন যাচাই করার জন্য "আপডেট" করার ঠিক পরেই "গেট" টুল কল করার প্রয়োজন নেই।)

"রেকর্ড আপডেট করে।"

 

@mcp.tool()
def search_logs(query: str, limit: int = 10) -> str:
    """
    Searches server error logs using Lucene syntax (e.g. 'level:ERROR AND service:auth').
    
    Args:
        query: A Lucene-formatted search string.
        limit: Max results to return. capped at 50.
    
    Returns:
        A formatted string of log entries with timestamps.
    """
    ...
  
@mcp.tool()
def search_logs(query: str, limit: int = 10) -> str:
    """Searches the logs."""
    ...

LLM জানে না যে "কোয়েরি" কোন সিনট্যাক্সকে সাপোর্ট করে (SQL? Regex? প্লেন টেক্সট?) সর্বোচ্চ "সীমা" কত তা এটি জানে না।

উত্তর ও সমস্যা ম্যানেজ করা

উত্তরটি হল পরবর্তী প্রম্পট-এর মূল নীতি অনুসারে, টুলটি ডেটা পেলোড ফিরিয়ে দিয়ে তার অন্তর্নিহিত এক্সিকিউশনের ফলাফল রিপোর্ট করে, যা পরে সরাসরি LLM-এর প্রসঙ্গ উইন্ডোতে পেস্ট করা হয়। ফলাফল সফল নাকি ব্যর্থ হয়েছে তার উপর নির্ভর করে পরবর্তী পদক্ষেপ নেওয়া হয়:

  • এটি সফল হলে: পরবর্তী ধাপে কী করতে হবে তা ঠিক করার জন্য কী ঘটেছে তা জানতে মডেলের রিটার্ন ভ্যালু প্রয়োজন।
  • এটি ব্যর্থ হলে: মডেলকে জানতে হবে যে এটি কেন ব্যর্থ হয়েছে এবং কীভাবে এটি ঠিক করা যায়। ক্র্যাশ (500 error) হলে কথোপকথন বন্ধ হয়ে যায়; সমস্যার বিবরণসহ মেসেজ থাকলে মডেলটি নিজেই সমস্যা সমাধান করতে পারে।

আপনার টুলের অন্তর্নিহিত লজিক সফল হোক বা ব্যর্থ, আপনাকে অবশ্যই রিটার্ন ভ্যালু পেলোড ফর্ম্যাট করতে হবে যাতে মডেলটি সহজেই এটি পার্স করতে পারে। আপনার রেসপন্স পেলোড প্যাকেজ করার সময় এইসব পেশাদার পদ্ধতি অনুসরণ করুন।

JSON ব্যবহার করুন

TextContent-এ স্ট্রাকচার্ড ডেটা ফর্ম্যাট করুন (সাময়িক সীমাবদ্ধতা)। কারণ structuredContent এখনও Connected Apps Platform-এ কাজ করে না, আপনার ডেটা ম্যানুয়ালি সিরিয়ালাইজ করুন। এমনকি একটি সহজ তালিকা ফেরত দিলেও, json.dumps() এটি।

উত্তরে URL অন্তর্ভুক্ত করুন

ফেরত আসা URL তুলনামূলকভাবে ছোট এবং অনেক প্যারামিটার ছাড়া হতে হবে। টোকেন কাউন্ট বাঁচাতে এবং হ্যালুসিনেশনের ঝুঁকি কমাতে URL ছোট করার পরিষেবা ব্যবহার করার সুপারিশ করা হয়।

সেল্ফ-ডেসক্রিপটিভ অ্যান্টি-হ্যালুসিনেশন পেলোড

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

সমস্যা ম্যানেজ করার জন্য শক্তিশালী ব্যবস্থা প্রয়োগ করুন

স্পষ্ট, অর্থপূর্ণ ত্রুটি মেসেজ রিটার্ন করুন যাতে মডেল বুঝতে পারে কী ভুল হয়েছে এবং ব্যবহারকারীকে জানাতে পারে। MCP সমস্যা সমাধান দেখুন।

try/except ব্যবহার করুন

try/except ব্লকে টুল লজিক র‍্যাপ করুন এবং স্ট্রিং করা সমস্যা রিটার্ন করুন।

অ্যাকশন নেওয়া যায় এমন সমস্যার বিবরণ দিন

সমস্যা সংক্রান্ত মেসেজে পরবর্তী ধাপ সাজেস্ট করুন (যেমন, "প্রথমে X টুল ব্যবহার করে দেখুন")।

অ্যাকশন কনফার্ম করুন

সাইড-এফেক্ট টুলের (তৈরি/আপডেট/মুছে দেওয়া) জন্য খালি স্ট্রিং রিটার্ন করবেন না।

প্রতিক্রিয়া ও সমস্যা ম্যানেজ করার উদাহরণ

নিম্নলিখিত উদাহরণগুলি থেকে উত্তর ও সমস্যা সমাধানের ক্ষেত্রে কী করা উচিত এবং কী করা উচিত নয় তা দেখানো হয়েছে।

সাজেস্ট করা হয়েছে সাজেস্ট করা হয় না

এক্সপ্লিসিট সিরিয়ালাইজেশন


...
import json

@mcp.tool()
def query_metrics(metric_id: str) -> str:
    result = {"id": metric_id, "value": 42, "unit": "ms"}
    # GOOD: Returns '{"id": "cpu", "value": 42}' -> Valid JSON
    return json.dumps(result, indent=2)


...
@mcp.tool()
def query_metrics(metric_id: str) -> str:
    result = {"id": metric_id, "value": 42, "unit": "ms"}
    # BAD: Returns "{'id': 'cpu', 'value': 42}" -> Invalid JSON
    return str(result)

ধরুন এবং জানান


...
@mcp.tool()
def get_user_details(user_id: str) -> str:
    try:
        user = db.get_user(user_id)
        if not user:
             # GOOD: Informative error returned as content
            return f"Error: User with ID '{user_id}' not found. Please verify the ID using 'search_users'."
        return json.dumps(user)
    except Exception as e:
        return f"Error: Database connection failed ({str(e)}). Please try again later."

(টুলটি টেকনিক্যালি "সফল" (একটি স্ট্রিং রিটার্ন করে), কিন্তু স্ট্রিংটিতে ত্রুটির বিবরণ রয়েছে। মডেল এটি পড়ে বুঝতে পারে যে, "ওহ, এই আইডিটি নেই" এবং ব্যবহারকারীকে সঠিক আইডি জিজ্ঞাসা করতে পারে।) 


...
@mcp.tool()
def get_user_details(user_id: str) -> str:
    # BAD: Unhandled exception if ID not found
    user = db.get_user(user_id)
    return json.dumps(user)

(get_user কাজ না করলে, সার্ভার 500 দেখায়। LLM একটি সাধারণ এক্সিকিউশন সংক্রান্ত সমস্যার মেসেজ পায় এবং কেন তা হয়েছে তা জানে না (আইডি কি ভুল ছিল? ডেটাবেস ডাউন? অনুমতি দেওয়া হয়নি?)। এটি সম্ভবত একই ভুল ইনপুট আবার চেষ্টা করবে।)

খালি উত্তর

...
@mcp.tool()
def post_story(story_content: str) -> str:
    service_name = "story_service"
    api_client.post("/stories", json={"content": story_content})
    # GOOD: Explicit confirmation of state change.
    return f"Service '{service_name}' successfully posted content. Status is now 'posted'."


...
@mcp.tool()
def post_story(storyContent: str):
    subprocess.post(["postsrv", "story", storyContent])
    # BAD: Returns null/empty string. Model is confused.

LLM প্রায়শই খালি উত্তর দেখে বিভ্রান্ত হয়ে যায়। তারা "টুলটি কাজ করেনি" বলে হ্যালুসিনেট করতে পারে বা কলটি আবার করতে পারে।

সেল্ফ-ডেসক্রিপটিভ অ্যান্টি-হ্যালুসিনেশন পেলোড

র কোড বা ইন্টার্নাল আইডি সবসময় মানুষের-পঠনযোগ্য ডিসপ্লে নাম, স্পষ্ট পরিমাপের ইউনিট এবং সাধারণ রেফারেন্স রেঞ্জের সাথে পেয়ার করুন।

{"lab_code": "2345-7", "display_name": "Glucose [Mass/volume] in Blood", "value": 105, "unit": "mg/dL", "reference_range": "70-99 mg/dL"}

(এটি মডেলকে ঠিক কী ভ্যালু বোঝায় তা বলে, ইউনিট বা রেফারেন্স থ্রেশহোল্ড অনুমান করতে বাধ্য না করে।)

র আইডি, কাস্টম কম্প্রেশন বা আনম্যাপ করা কোড

র-ইন্টার্নাল আইডি, কাস্টম ডিকশনারি অ্যাব্রিভিয়েশন বা লেবেল ছাড়া নিউমেরিক কোড ফিরিয়ে দেওয়া।

{"code": "2345-7", "v": 105}

(মডেলকে ১০৫ বলতে কী বোঝানো হয়েছে তা অনুমান করতে বাধ্য করে, যার ফলে হ্যালুসিনেটেড ইউনিট, প্রসঙ্গ মিস করা বা ভুল ব্যাখ্যা হতে পারে।)

MCP সংক্রান্ত সমস্যা ম্যানেজ করা

সমস্যাগুলি সুন্দরভাবে ম্যানেজ করা অত্যন্ত গুরুত্বপূর্ণ।

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

সমস্যা সংক্রান্ত রেসপন্স বডির উদাহরণ (JSON)

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32302,
    "message": "User permission denied for the requested operation.",
    "data": null
  },
  "id": 1
}

Message-এ MCP-এর ErrorData ফিল্ডের JSON ডাম্প আছে। সঠিক code এবং মডেল-ভিজিবল message ফিরিয়ে দেওয়ার মাধ্যমে, Connected Apps Platform ত্রুটি মেসেজ পড়তে এবং ব্যবহারকারীকে সহায়ক, ন্যাচারাল ল্যাঙ্গুয়েজ ব্যাখ্যা রিলে করতে পারে। যেমন, "আমি দুঃখিত, আমি সেই আইডি সহ ভেন্যু খুঁজে পাইনি। আপনি কি নামটি চেক করে দেখতে পারেন?"

MCP, ক্লায়েন্টদের JSON-RPC 2.0 স্পেক ব্যবহার করে MCP সার্ভারের সাথে কানেক্ট করার অনুমতি দেয়। JSON-RPC-তে সাধারণত হওয়া সমস্যার জন্য আগে থেকে নির্দিষ্ট করা কিছু সমস্যা পাঠানো হয়, যেমন ভুল অনুরোধ, পার্সিং সংক্রান্ত সমস্যা ইত্যাদি। এই গাইড থেকে জানতে পারবেন যে MCP সার্ভার কীভাবে কাস্টম সমস্যা পাঠাতে পারে।

স্ট্যাটাস
কোড		 মেসেজ ব্যবহার স্পষ্টভাবে
ফেরত
দিতে হবে?
ব্যবহারকারী/গ্রাহকের সমস্যা
-32300 USER_RATE_LIMITED ব্যবহারকারী তার ব্যবহারের সর্বোচ্চ সীমায় পৌঁছে গেছেন। হ্যাঁ
-32301 MISSING_REQUIRED_INFORMATION ইনপুট অনুরোধে প্রয়োজনীয় সব তথ্য নেই হ্যাঁ
-32302 USER_PERMISSION_DENIED ব্যবহারকারী টুলটি ব্যবহার করার অনুমতি দেননি। যেমন, ব্যবহারকারীর এন্টারপ্রাইজ অ্যাকাউন্ট, বয়স সংক্রান্ত বিধিনিষেধ, লোকেল ইত্যাদি থাকতে হবে অথবা টুলের এন্টারপ্রাইজ সাবস্ক্রিপশন থাকলে চলবে না। হ্যাঁ
অ্যাপ্লিকেশন সংক্রান্ত সমস্যা/বিজনেস লজিক সংক্রান্ত সমস্যা
-32400 RUNTIME_ERROR সার্ভার কোড এক্সিকিউট করার সময় সমস্যা হয়েছে হ্যাঁ
-32401 NULL_POINTER_EXCEPTION কোনও পয়েন্টার/অবজেক্ট রান করার চেষ্টা করুন হ্যাঁ
-32402 OUT_OF_MEMORY সার্ভার কোডে কোনও অবজেক্টের জন্য বরাদ্দ করার মতো পর্যাপ্ত মেমরি নেই হ্যাঁ
ইনফ্রাস্ট্রাকচার সংক্রান্ত সমস্যা
-32500 DEADLINE_EXCEEDED অনুরোধটি অনুমোদিত সময়ের চেয়ে বেশি সময় নিচ্ছে। সার্ভার ওভারলোড, নেটওয়ার্ক সংক্রান্ত সমস্যা ইত্যাদির মতো অনেক কারণে এটি হতে পারে। হ্যাঁ
-32501 RESOURCE_EXHAUSTED সার্ভারে মেমরি, ডিস্ক স্টোরেজে খালি জায়গা, থ্রেড, সিপিইউ টাইম ইত্যাদি শেষ হয়ে গেছে। হ্যাঁ
-32502 SERVICE_UNAVAILABLE নির্ভরশীল পরিষেবা (যেমন, অন্য মাইক্রোসার্ভিস, ডেটাবেস, ক্যাশে ইত্যাদি) উপলভ্য নেই হ্যাঁ
JSON-RPC সংক্রান্ত সমস্যা (এইসব সমস্যা MCP ট্রান্সপোর্টের অংশ)
-32700 PARSE_ERROR সার্ভার অনুরোধ পার্স করতে পারেনি না
-32600 INVALID_REQUEST ভুলভাবে তৈরি করা ক্লায়েন্ট অনুরোধ না
-32601 METHOD_NOT_FOUND MCP টুলের নাম ভুল না
-32602 INVALID_PARAMS অনুরোধের প্যারামিটার ভুল, এর মধ্যে প্যারামিটার না থাকা বা প্যারামিটারের ধরন না মেলার মতো সমস্যা অন্তর্ভুক্ত না
-32603 INTERNAL_ERROR ডিফল্ট উত্তর না

অফিসিয়াল Python SDK (mcp) ব্যবহার করে আপনার সার্ভারে কীভাবে MCP সংক্রান্ত সমস্যা জানাতে পারেন, তার একটি উদাহরণ নিচে দেওয়া হল। ErrorData পেলোড সহ McpError সংক্রান্ত সমস্যা জানান, যা SDK অটোমেটিক প্রয়োজনীয় JSON-RPC সমস্যার ফর্ম্যাটে সিরিয়ালাইজ করে এবং সমস্যার স্ট্যাটাস পপুলেট করে।

from mcp import types
from mcp.shared.exceptions import McpError

@mcp.tool()
def foo_tool() -> list[types.TextContent]:
  """Always returns an error."""
  raise McpError(
    types.ErrorData(
        code=-32302, # USER_PERMISSION_DENIED
        message="Message to show to the model."
    ),
  )

টুল কন্টেক্সট

প্রযোজ্য Google প্রোডাক্ট, MCP সার্ভারে সিগন্যাল পাঠানোর জন্য Tool Context API-কে সমর্থন করে। এই API-এর ব্যবহার সংবেদনশীল তথ্য প্রয়োজন এমন বৈধ ব্যবহারের ক্ষেত্রে করা হয়—যেমন, মেটাডেটা যা মূল টুল সংজ্ঞার অংশ নয়, যেমন লোকালাইজেশন প্রয়োজন এমন টুলের জন্য লোকেল। টুল কনটেক্সট API শুধুমাত্র Connected Console-এর মাধ্যমে প্রকাশ করা হয়।

আপনি Connected Console-এ আপনার অ্যাপের সাথে current_user_location_fine-এর মতো সিগন্যাল রেজিস্টার করলে, প্রযোজ্য Google প্রোডাক্ট, অনুরোধ করা ডেটা প্রদানকারী অতিরিক্ত _meta এন্ট্রির সাথে MCP tools/call অনুরোধ বাড়াবে। কাজ করে এমন সিগন্যালের সেট হল:

  • current_user_location_fine (শুধু Gemini, অনুমোদিত ভার্টিক্যালের জন্য)
  • user_locale
  • current_user_location_coarse
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "find-restaurant",
    "arguments": {"query": "restaurants near me"},
    "_meta": {
      "current_user_location_fine": {
        "latitude_degrees": 37.7749,
        "longitude_degrees": -122.4194,
        "accuracy_meters": 112.4221
      },
      "user_locale": {
        "language_code": "en",
        "region_code": "US"
      }
    }
  }
}

এই ডেটা আনপ্যাক করতে:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("remote_mcp")

@mcp.tool()
async def find_restaurants(query: str, ctx: Context) -> str:
   # Access context directly from _meta
   request_context = ctx.request_context
   meta_dict = ctx.request_context.meta.model_dump() if ctx.request_context.meta else {}

   location_context = meta_dict.get("current_user_location_fine", {})
   lat = location_context.get("latitude_degrees")
   lng = location_context.get("longitude_degrees")
   if lat and lng:
       return f"Finding '{query}' near ({lat}, {lng})"
   return f"Finding '{query}' (no location provided)"

UX রেন্ডার করা

MCP অ্যাপ

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

প্রযোজ্য Google প্রোডাক্টে MCP অ্যাপ ইন্টিগ্রেশনের সাথে নিম্নলিখিত সতর্কতা থাকে।

রেজিস্ট্রেশনের সময় রিসোর্স ইনজেশন

প্রযোজ্য Google প্রোডাক্ট টুল ইনজেশন করার সময় UI রিসোর্স ফেচ করে, টুল তালিকা ও টুল বিবরণের মতোই। এর অর্থ হল, রিসোর্সের কোনও আপডেট—যেমন, জাভাস্ক্রিপ্টে পরিবর্তন—অটোমেটিক পিক-আপ করা হবে না এবং টুল আবার ইনজেস্ট করতে হবে।

একটি UI রিসোর্সের সাইজ ১৫ এমবির বেশি হওয়া চলবে না এবং আপনার সার্ভার জুড়ে মোট UI রিসোর্সের সাইজ ১০০ এমবির বেশি হওয়া চলবে না।

UI রিসোর্সকে অবশ্যই কাজ করে এমন MIME প্রকারের মধ্যে একটি ব্যবহার করতে হবে: text/html, text/javascript, text/css, অথবা text/html;profile=mcp-app. প্রিভিউতে পুশ করার সময় নন-স্ট্যান্ডার্ড বা প্ল্যাটফর্ম-নির্দিষ্ট MIME-এর ধরন যাচাই করা যাবে না।

CSP নির্দেশিকা

প্রযোজ্য Google প্রোডাক্ট অফিসিয়াল MCP অ্যাপ স্পেসিফিকেশন মেনে চলে, যার মধ্যে CSP [1], [2] অন্তর্ভুক্ত এবং CSP নির্দেশাবলী লঙ্ঘন করে এমন যেকোনও অনুরোধ ব্লক করবে।

প্রযোজ্য Google প্রোডাক্টের ক্ষেত্রে অতিরিক্তভাবে blob: এবং data:-কে CSP-তে যোগ করতে হবে, যদি ব্যবহার করা হয়। এগুলি ডিফল্ট হিসেবে যোগ করা হবে না। CSP-তে এগুলি যোগ করা হবে (বা হবে না) তা ডেভেলপার ঠিক করেন।

Script-src ব্যতিক্রম

আমরা শুধুমাত্র এইসব নির্দেশিকা অনুমোদন করি: unsafe-inline (ডিফল্ট হিসেবে যোগ করা হয়েছে), wasm-unsafe-eval এবং data: (resource_domains-এ অন্তর্ভুক্ত থাকলে)। iframe এক্সটার্নাল স্ক্রিপ্ট লোড করলে, HTML-এ JS বান্ডেল করে অথবা সাবরিসোর্স ইন্টিগ্রিটি (SRI) হ্যাশ ব্যবহার করে সমস্যার সমাধান করা যেতে পারে।

  • বিকল্প ১: HTML-এ ইনলাইন / বান্ডেল JS (সবচেয়ে সহজ)

    • বান্ডেল JS কোড:

      • UI রিসোর্সের জন্য ফেরত পাঠানো HTML পেলোডে <script> ট্যাগের মধ্যে সরাসরি component-init.js-এর কন্টেন্ট ইনলাইন করুন:

        <script>
// Paste component-init.js content directly here
</script>

    • রিমোট <script src> ট্যাগ সরান

      • HTML ডকুমেন্ট থেকে <script src="https://api.mycompany.com/...">টি রেফারেন্স মুছুন।

    • আবার ইনজেস্ট / আপডেট করার টুল

  • বিকল্প ২: সাবরিসোর্স ইন্টিগ্রিটি (SRI) হ্যাশ ব্যবহার করুন:

    স্ক্রিপ্টটি অবশ্যই https://api.company.com/...-এ এক্সটার্নালভাবে হোস্ট করা থাকলে এটি ব্যবহার করুন।

    • স্ক্রিপ্টের SHA-256 হ্যাশ গণনা করুন
      • component-init.js-এর base64 SHA-256 হ্যাশ জেনারেট করুন
    • resourceDomains-এ হ্যাশ যোগ করুন (integrity অ্যাট্রিবিউটের সাথে ম্যাচ করতে sha256- প্রিফিক্স যোগ করতে হবে)
    • HTML <script> ট্যাগ আপডেট করুন
      • HTML উইজেটে স্ক্রিপ্ট ট্যাগে integrity এবং crossorigin অ্যাট্রিবিউট যোগ করুন
    • CDN/সার্ভারে CORS হেডার যাচাই করুন
      • নিশ্চিত করুন যে api.company.com component-init.js-কে Access-Control-Allow-Origin: * (অথবা scf.usercontent.goog-কে অনুমতি দেয়) দিয়ে পরিবেশন করে যাতে ব্রাউজার SRI যাচাইকরণের জন্য রেসপন্স বডি পড়তে পারে।
    • আবার ইনজেস্ট / আপডেট করার টুল

MCP টুলের বিবরণের জন্য নিরাপত্তা সংক্রান্ত নির্দেশিকা

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

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

নিরাপত্তা সংক্রান্ত ঝুঁকি এবং কীভাবে তা এড়িয়ে চলবেন

ঝুঁকিপূর্ণ এলাকা সাজেস্ট করা হয়েছে যেকোনও মূল্যে এই পদ্ধতি এড়িয়ে চলুন

প্রম্পট ইঞ্জেকশন

টুলের উদ্দেশ্য ও কার্যকারিতা স্পষ্টভাবে উল্লেখ করতে বস্তুনিষ্ঠ, ঘোষণামূলক ভাষা ব্যবহার করুন।

মডেলের আচরণ ওভাররাইড করতে বা সিস্টেম ফ্লো পরিবর্তন করতে বাধ্যতামূলক কমান্ড ব্যবহার করুন (যেমন, "আপনাকে অবশ্যই বলতে হবে...", "দৌড়ানোর পরে, আপনাকে অবশ্যই...")। 'অবশ্যই' বা 'গুরুত্বপূর্ণ' শব্দের মতো বাধ্যতামূলক শব্দ শুধুমাত্র স্ট্রাকচার্ড প্যারামিটার সংক্রান্ত সীমাবদ্ধতা বা ব্যবহারের নিয়ম সংজ্ঞায়িত করার সময় গ্রহণযোগ্য।

টুলের বিবরণ সম্পর্কিত টেক্সটের জন্য স্ট্যান্ডার্ড, প্লেন ফর্ম্যাটিং ব্যবহার করুন।

দৃষ্টি আকর্ষণকারী ফর্ম্যাটিং ব্যবহার করা —যেমন, অতিরিক্ত বড় হাতের অক্ষর এবং VERY IMPORTANT: বা **CRITICAL**-এর মতো ট্যাগ ব্যবহার করা।

টুলের ফাংশন ও প্রত্যাশিত আচরণের উপর সম্পূর্ণ ফোকাস করুন।

পূর্ববর্তী নির্দেশাবলী উপেক্ষা করার জন্য রোল-প্লেয়িং নির্দেশাবলী বা কমান্ড অন্তর্ভুক্ত করুন।

টুল শ্যাডোয়িং ও হাইজ্যাকিং

বিবরণটি যেন নির্দিষ্ট হয় এবং টুলের প্রকৃত, সম্পর্কিত ক্ষমতার মধ্যে সীমাবদ্ধ থাকে তা নিশ্চিত করুন।

টুলের বিবরণ খুব বেশি বিস্তৃত, অস্পষ্ট করা বা দাবি করা যে একটি টুল অনেক সম্পর্কহীন ফাংশন সম্পাদন করে।

টুলের জন্য একটি অনন্য, বর্ণনামূলক এবং অর্থপূর্ণ নাম বেছে নিন।

বিশ্বস্ত টুলের নামের সাথে সামান্য পার্থক্য আছে এমন নাম বা সাধারণ নাম (যেমন, do_everything_tool, assistant_tool) ব্যবহার করা।

আপনার বিবরণে অন্য অ্যাপ বা এক্সটার্নাল প্ল্যাটফর্ম টুলের নাম উল্লেখ করবেন না।

অন্যান্য টুল স্পষ্টভাবে উল্লেখ করুন বা কখন বা কীভাবে অন্যান্য টুল ব্যবহার করা উচিত তার জন্য নতুন নিয়ম তৈরি করুন।

ব্যবহারকারীর প্রসঙ্গের উপর ভিত্তি করে সবচেয়ে উপযুক্ত টুল বেছে নেওয়ার জন্য মডেলের প্ল্যানারকে অনুমতি দিন।

প্রতিযোগিতা-বিরোধী ভাষা বা যেকোনও ধরনের SEO প্রম্পট অন্তর্ভুক্ত করা যা মডেলকে একই ধরনের টুলের চেয়ে আপনার টুলকে বেশি পছন্দ করার নির্দেশ দেয়।

ট্রিগার ম্যানিপুলেশন

বিবরণটি সাধারণ কথোপকথনের ইতিহাস থেকে বাক্যাংশ উল্লেখ বা প্রতিক্রিয়া জানায় না।

এমন কন্ডিশনাল লজিক তৈরি করা যা সাধারণ, নিরীহ ব্যবহারকারীর বাক্যাংশের (যেমন, "ধন্যবাদ," "সারসংক্ষেপ করতে") উপর ভিত্তি করে একটি ক্ষতিকারক অ্যাকশন ট্রিগার করে।

প্যারামিটারের অপব্যবহার

টুলের ফাংশনের জন্য প্রয়োজনীয় প্যারামিটারগুলিই শুধু নির্ধারণ করুন এবং ইনপুট ডেটার জন্য নির্দিষ্ট নাম ব্যবহার করুন (যেমন, file_id, search_term)।

এজেন্টের ইন্টার্নাল স্টেটকে (যেমন, system_prompt, conversation_history, full_context) প্রতিফলিত করে এমন নাম দিয়ে ফাংশন প্যারামিটার সংজ্ঞায়িত করুন।

ডেটা এক্সফিলট্রেশন

ডিজাইন অনুযায়ী গোপনীয়তা - অস্বচ্ছ শনাক্তকারী এবং হোস্ট-ম্যানেজড যাচাইকরণ।

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

প্রযোজ্য Google প্রোডাক্টে পাঠানোর আগে যেকোনও সংবেদনশীল তথ্য স্যানিটাইজ করা উচিত।

ব্যবহারকারীর থেকে PII, PHI বা অন্য কোনও ব্যক্তিগত এবং/অথবা সংবেদনশীল তথ্য, ব্যক্তিগত বা ব্যবসার ডেটা বা এন্টিটি এমন কোনও উপায়ে অনুরোধ করা যা প্রযোজ্য Google প্রোডাক্টের পরিষেবার শর্তাবলী লঙ্ঘন করে।

অননুমোদিত থার্ড-পার্টি URL, লগিং পরিষেবা বা এক্সটার্নাল সিস্টেমে কোনও ব্যবহারকারীর ডেটা (কোয়েরি, লোকেশন, প্রসঙ্গ) পাঠানোর উল্লেখ বা প্রয়োজন।

ফাংশনাল ও নামকরণ সংক্রান্ত পেশাদার পদ্ধতি

টুলের বিবরণ সুরক্ষিত করার পাশাপাশি, আপনাকে নিশ্চিত করতে হবে যে মডেলটি কোনও বিভ্রান্তি ছাড়াই নির্ভরযোগ্যভাবে এটি বেছে নিতে এবং কার্যকর করতে পারে। নিম্নলিখিত ফাংশনাল ও নাম দেওয়ার পেশাদার পদ্ধতি মেনে চলুন:

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

পরিশিষ্ট: ইনফ্রাস্ট্রাকচার ও নেটওয়ার্কের জন্য হোয়াইটলিস্ট তৈরি করা

আপনার হোস্টিং ইনফ্রাস্ট্রাকচার, API গেটওয়ে বা ফায়ারওয়াল যদি সোর্স IP অ্যাড্রেস অনুযায়ী ইনকামিং কানেকশন সীমাবদ্ধ করে, তাহলে নিম্নলিখিত Google আউটবাউন্ড CIDR ব্লক অ্যালাউলিস্ট করুন:

  • 108.177.64.0/20
  • 142.250.88.0/22
  • 172.217.80.0/20
  • 192.178.20.0/22
  • 192.179.0.0/20
  • 74.125.232.0/24
  • 136.121.40.0/21

নিশ্চিত করুন যে আপনার এনভায়রনমেন্ট HTTPS পোর্ট 443-এ এইসব IP রেঞ্জ থেকে ট্রাফিককে অনুমতি দেয় যাতে প্রযোজ্য Google প্রোডাক্ট MCP ইনিশিয়ালাইজেশন, টুল ডিসকভারি এবং অনুরোধ এক্সিকিউশনের জন্য আপনার রিমোট MCP সার্ভারে পৌঁছাতে পারে।