استانداردهای ادغام برنامه متصل‌شده MCP

سرور MCP چارچوب لازم برای متصل کردن کارکردهای برنامه شما (ابزارهای MCP) به «پلاتفرم برنامه‌های متصل‌شده» را ایجاد می‌کند. برای اینکه بتواند با اطمینان بیشتری نتایج سرویس شما را انتخاب، فراخوانی، و پردازش کند، پیکربندی MCP شما باید به‌طور دقیق از استانداردهای زیر پیروی کند.

اصول راهنما

برای هر تابع، بر قصد کاربر و موارد استفاده تمرکز کنید و نه بر قابلیت‌های تابع. شرح، روش اصلی شما برای گفتن به مدل است که ابزار شما برای چه کاری است و به چه موارد استفاده‌ای می‌تواند پاسخ دهد.

نسخه‌بندی

برای پشتیبانی از استقرارهای MCP مقیاس‌پذیر و قوی، از معماری URI ساختاریافته‌ای استفاده کنید که از نسخه‌سازی مبتنی بر مسیر بهره می‌برد—برای مثال، /v1، /v2. انجام این کار به شما کمک می‌کند سازگاری با نسخه قدیمی را حفظ کنید و ویژگی‌های جدید را کنترل کنید. تکمیل این مورد با زیردامنه‌های خاص ارائه‌دهنده، مانند https://gemini.mcp.company.com/mcp/v1، امکان مدیریت دقیق ترافیک و بهینه‌سازی تعاریف ابزار متناسب با بافت منحصربه‌فرد و رفتارهای پردازشی مدل‌های مختلف هوش مصنوعی را فراهم می‌کند.

سازگاری نسخه پروتکل MCP

«پلاتفرم برنامه‌های متصل‌شده» از مشخصات «پروتکل بافتار مدل» (MCP) تا نسخه 2025-11-25 پشتیبانی می‌کند. از نسخه‌های جدیدتر مشخصات هنوز پشتیبانی نمی‌شود.

  • مسئولیت توسعه‌دهنده: شما مسئول هستید که مطمئن شوید سرور MCP شما درطول دست‌دهی initialize و در همه تعاریف ابزار و طرح‌واره، به‌طور دقیق از نسخه پروتکل پشتیبانی‌شده توسط «پلاتفرم برنامه‌های متصل» (2025-11-25) پیروی می‌کند.
  • سازگاری پلاتفرم با نسخه قدیمی: ازآنجایی‌که «پلاتفرم برنامه‌های متصل» در آینده نسخه‌های جدیدتر مشخصات MCP را اتخاذ می‌کند، کارخواه ما سازگاری با نسخه قدیمی را با نسخه‌های پروتکل پشتیبانی‌شده قبلی حفظ خواهد کرد تا ادغام‌های تولید موجود بدون اختلال به کار خود ادامه دهند.
  • مدیریت ارتقاها: وقتی آماده هستید که مشخصات MCP جدیداً پشتیبانی‌شده را بپذیرید یا تغییرات طرح‌واره را معرفی کنید، آن به‌روزرسانی‌ها را در مسیر URI نسخه‌دار جدید (برای مثال، /mcp/v2) نمایش دهید و درعین‌حال نقطه پایانی موجود (/mcp/v1) را برای ترافیک فعال حفظ کنید.

تغییرات در طرح‌واره‌های MCP بین نسخه‌های برنامه مجاز است. توصیه می‌کنیم از این ویژگی استفاده کنید و نقاط پایانی MCP را نسخه‌بندی کنید تا از عرضه تدریجی ویژگی‌های جدید پشتیبانی کنید، یا به‌طور دقیق بر تغییرات سازگار با نسخه‌های قدیمی تکیه کنید.

مشخصات پروتکل انتقال

«پلاتفرم برنامه‌های متصل» به‌طور دقیق از مشخصات «پروتکل بافتار مدل» انتقال HTTP جاری‌سازی‌پذیر نسخه ۲۰۲۵-۰۳-۲۶ و بالاتر پشتیبانی می‌کند. این مدل از HTTP قدیمی با انتقال SSE که در مشخصات ۲۰۲۴-۱۱-۰۵ شرح داده شده است پشتیبانی نمی‌کند.

  • نقطه پایان HTTP تکی. نقطه پایانی MCP ارائه‌شده در «کنسول یکپارچه» (برای مثال، https://api.example.com/mcp) نشانی وب واحدی است که محصولات Google مربوطه همه درخواست‌های JSON-RPC (initialize، tools/list، tools/call) را ازطریق HTTP POST استاندارد ارسال می‌کنند.
  • جاری‌سازی SSE در HTTP قابل‌جاری‌سازی. انتقال SSE چند نقطه پایانی قدیمی پشتیبانی نمی‌شود، اما «رویدادهای ارسالی سرور» مانند text/event-stream در Streamable HTTP پشتیبانی می‌شوند. درخواست‌های خروجی از محصولات Google مربوطه شامل Accept: application/json, text/event-stream است، یعنی سرور شما می‌تواند بار داده استاندارد application/json را برگرداند یا پاسخ‌های افزایشی را بااستفاده از Content-Type: text/event-stream مستقیماً در بدنه پاسخ HTTP POST جاری‌سازی کند.
  • جاری‌سازی GET و خطای «۴۰۵ روش مجاز نیست». کارخواهان ممکن است برای جاری‌سازی اختیاری GET در نقطه پایانی برای اعلان‌های سروربه‌کارخواه تلاش کنند. اگر سرورتان بدون حالت یا فقط درخواست-پاسخ است، برگرداندن HTTP 405 Method Not Allowed صریحاً پشتیبانی می‌شود و به‌طور تمیز توسط پراکسی کارخواه محصول Google مربوطه مدیریت می‌شود.

دستورالعمل‌های سرور

«پلاتفرم برنامه‌های متصل‌شده» برای دریافت دستورالعمل‌های سرور بهینه‌سازی شده است، که امکان کنترل رفتار مدل را به میزانی فراهم می‌کند که ازطریق روش‌های دیگر امکان‌پذیر نیست.

دستورالعمل‌های سرور را دنبال کنید.

به‌عنوان «راهنمایی مدل» با بافت استفاده درنظر گرفته شود

این دستورالعمل‌ها را دررابطه‌با ارائه راهنمایی به مدل‌ها دنبال کنید.

  • دستورالعمل‌ها را به‌عنوان یک «نکته» یا راهنمای سطح بالا بنویسید تا به مدل زبانی بزرگ کمک کنید هدف و قابلیت‌های کلی سرور را درک کند.
  • به‌جای فهرست کردن ویژگی‌ها یا توصیف نحوه استفاده مدل از ابزارها و منابع سرور، توضیح دهید که چه کاری می‌تواند انجام دهد. اگر مدل «چیستی» را به‌درستی درک کند، می‌تواند «چگونگی» را به‌خوبی براساس مسیر کاربر تعیین کند.
  • فرض کنید این نوشتار مستقیماً به پیام‌واره سیستم مدل اضافه خواهد شد. Keep it clear, directive, and token-efficient.

تکمیل کنید و تکرار نکنید

از این فضا برای بافت سراسری که برای همه ابزارها اعمال می‌شود استفاده کنید و از تکرار توضیحات ابزارها به‌صورت جداگانه خودداری کنید.

نمونه‌های دستورالعمل‌های سرور

مثال‌های زیر بایدها و نبایدهای مربوط به نوشتن صحیح دستورالعمل‌های سرور را نشان می‌دهد.

توصیه‌شده توصیه نمی‌شود

به‌عنوان یک نگهدارنده تخصصی مخزن GitHub عمل کن. این سرور دسترسی عمیق به فراداده مخزن، پیگیری مشکل، و گردش‌های کاری PR را فراهم می‌کند. از آن برای حفظ سلامت پروژه، خودکارسازی اولویت‌بندی، و اطمینان از استانداردهای کد استفاده کنید. فرض کنید همه کنش‌ها در بافت سازمان اصالت‌سنجی‌شده انجام می‌شود، مگراینکه مشخص شده باشد. شناسایی رشته‌های قدیمی یا درخواست‌های ادغام پیوندنشده را در اولویت قرار بده تا مخزن سازمان‌دهی‌شده باقی بماند.

مختصر، دستوری، و مکمل مدل

  • «چیستی» (سلامت پروژه، اولویت‌بندی) را به‌جای «چگونگی» تعریف می‌کند
  • به دامنه اصالت‌سنجی که برای همه ابزارها اعمال می‌شود اشاره می‌کند

این سرور ابزارهایی برای GitHub دارد. وقتی کاربر درباره مشکلات سؤال می‌کند، باید از ابزار list_issues استفاده کنید. می‌توانید از create_pull_request برای ایجاد درخواست بازبینی استفاده کنید. از این ابزارها با دقت استفاده کنید تا به کاربر کمک کنید کدش را مدیریت کند. همیشه قبل‌از فراخوانی ابزار، نام مخزن را بررسی کنید. اگر کاربر درخواست خلاصه کرد، ابتدا ابزارها را فراخوانی کنید و سپس برونداد را خلاصه کنید

  • نام ابزارها را دوباره فهرست نکنید،
  • به مدل نگویید «چگونه» فکر کند، زیرا این کار می‌تواند با استدلال داخلی مدل که از بافت کاربر برای انتخاب درست استفاده می‌کند تداخل داشته باشد.
  • ماهیت دسترسی سرور یا محدودیت‌های خاص آن را توضیح نمی‌دهد)

رهنمودهای ابزار

دستورالعمل‌های زیر روال‌های مطلوب برای ایجاد پیکربندی‌های سرور MCP برای توابع یا ابزارهای مختلف در برنامه شما را شرح می‌دهند.

قراردادهای نام‌گذاری ابزار

برای نام‌گذاری ابزارتان، رهنمودهای زیر را رعایت کنید:

از نام‌های قابل‌خواندن برای انسان و قابل‌فهم استفاده کنید

از نام‌های قابل‌خواندن برای انسان با معانی واضح و قابل‌فهم به‌جای نام‌های مبهم استفاده کنید. برای مثال، get_user_information ساده‌تر از userInfo است.

رعایت کردن سبک مناسب حروف بزرگ و کوچک

برای نام توابع ابزار و راه‌اندازهای برنامه، از قوانین زیر برای حروف بزرگ و کوچک پیروی کنید:

  • حروف بزرگ و کوچک تابع ابزار. از snake_case یا camelCase برای نام‌های تابع ابزار تعریف‌شده در طرح‌واره MCP خود استفاده کنید (برای مثال، get_user_information یا publishDraft).
  • حساسیت به حروف دستگیره راه‌انداز برنامه. راه‌اندازها و نامبردن‌های برنامه (برای مثال، @MyTwoWordApp) به حروف بزرگ و کوچک حساس نیستند. این پلاتفرم ورودی‌های کاربر را در حروف کوچک (@mytwowordapp)، PascalCase‏ (@MyTwoWordApp)، و camelCase‏ (@myTwoWordApp) عادی‌سازی می‌کند.
  • قالب‌بندی نام نمایشی. عنوان رسمی برنامه‌تان را بااستفاده از PascalCase یا فاصله‌های استاندارد ثبت کنید تا در عناصر میانای کاربر به‌صورت واضح نمایش داده شود.
  • مدیریت اشتباه تایپی. درحالی‌که تفاوت‌های حروف بزرگ و کوچک به‌طور خودکار مدیریت می‌شوند، غلط‌های املایی نویسه (برای مثال، @mytwowrodapp) به‌جای تطابق رشته مستقیم، به تشخیص قصد جایگزین متکی هستند. توسعه‌دهندگان باید املای صحیح نام کاربری را در اسناد تشویق کنند.

از نام‌گذاری صریح فعل-اسم استفاده کنید

از نام‌گذاری verb_noun خاص استفاده کنید و از ابهام اجتناب کنید—برای مثال، publish_draft بهتر از handle_content است.

دانه‌بندی ابزار

دستورالعمل‌های زیر را دررابطه‌با دانه‌بندی ابزار رعایت کنید.

درنظر گرفتن ابزارها به‌عنوان نقاط پایانی اتمی

با ابزارها به‌عنوان نقاط پایانی اتمی بدون شرایط ابزار داخلی یا عملکردهای متعدد با پارامترهای الزامی مربوطه رفتار کنید. ابزارهای دانه‌ای به مدل اجازه می‌دهند مراحل را به‌طور منطقی زنجیره‌ای کند و توهمات را کاهش دهد.

استفاده از طرح‌واره‌های مسطح‌تر

اگر برای اعتبارسنجی ورودی‌ها به اشیاء عمیقاً تودرتو یا منطق طرح‌واره پیچیده oneOf / anyOf نیاز دارید، احتمالاً ابزار شما بیش‌ازحد گسترده است.

رعایت کردن پیش‌انبوهش و حفاظ‌های پایه‌بار

Although pre-aggregating data isn't strictly enforced by protocol for small, scoped payloads, backend pre-aggregation is strongly required in practice when working with large record sets, longitudinal history, and multi-source datasets. «پلاتفرم برنامه‌های متصل‌شده» محدودیت‌هایی را برای پنجره بافت، تأخیر اجرا، و مراحل استدلال مدل اعمال می‌کند. برای رعایت این حفاظ‌ها، این دستورالعمل‌ها را دنبال کنید:

  • فیلتر و خلاصه کردن در پس‌زمینه. همیشه قبل‌از برگرداندن پاسخ‌ها به محصولات Google مربوطه، جریان‌های داده بزرگ را در سرور MCP خود فیلتر، پیش‌انبوهش، یا خلاصه کنید.
  • از تخلیه خام اجتناب کنید. هرگز ردیف‌های پایگاه داده خام یا گزارش‌های نمایه‌نشده کامل را در محموله برگشتی ابزار قرار ندهید.

حذف ابزارهای داخلی و متا

فقط قابلیت‌های مربوط به مدل را در پاسخ tools/list سرورتان نمایش دهید:

  • ابزارهای کمکی فیلتر: هرگونه ابزار داخلی، مدیریتی، یا متا را که برای فراخوانی توسط مدل درنظر گرفته نشده‌اند (مثلاً بررسی‌های سلامت سرور، روال‌های راه‌اندازی داخلی، یا کمک‌های ابزار توسعه‌دهنده) حذف کنید.
  • کارایی پنجره بافت: مستثنی کردن ابزارهای غیرضروری باعث می‌شود طرح‌واره MCP شما مختصر بماند، مصرف داده‌واحد پنجره بافت کاهش یابد، و از سردرگمی مدل در مسیریابی ابزار جلوگیری شود. سرورهای MCP که ده‌ها ابزار یا طرح‌واره‌های «مگاابزار» تودرتوی عمیق را افشا می‌کنند، درطول بازبینی برای اصلاح پرچم‌گذاری خواهند شد.

بایدها و نبایدهای جزئیات ابزار

مثال‌های زیر بایدها و نبایدهای مربوط به نام‌گذاری ابزار و استفاده از دانه‌بندی را نشان می‌دهند.

توصیه‌شده توصیه نمی‌شود

ابزارهای دانه‌ای با نام‌ها و پارامترهای واضح

طرح‌واره ورودی برای هر ابزار سخت‌گیرانه است. اگر مدل زبانی بزرگ بخواهد کاربری ایجاد کند، باید ایمیلی ارائه دهد. اگر می‌خواهد حذف کند، باید شناسه ارائه دهد. حدس و گمانی وجود ندارد.

...
@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 را در ابزارهای پُرسمانی تنظیم کنید که فقط داده‌ها را بدون تغییر دادن وضعیت پس‌بست واکشی می‌کنند.
  • پیش‌فرض‌های حاشیه‌نویسی صریح: طبق مشخصات «پروتکل زمینه‌ای مدل»، حذف readOnlyHint باعث می‌شود کارخواه‌ها به‌طور پیش‌فرض readOnlyHint: false و destructiveHint: true را برای ایمنی فرض کنند. اعلام صریح حاشیه‌نویسی‌ها در همه ابزارها، مسیریابی قابل‌پیش‌بینی مدل و ایمنی اجرای مناسب را تضمین می‌کند.

شرح ابزار

شرح تنها بافتاری است که مدل برای تصمیم‌گیری درباره اینکه آیا ابزار شما می‌تواند مشکل فعلی را حل کند یا نه دراختیار دارد. هنگام نوشتن شرح، دستورالعمل‌های زیر را رعایت کنید:

دستورالعمل بنویسید، نه نظر

شرح ابزار را به‌صورت دستورالعمل بنویسید—و نه به‌صورت نظرات کد که اغلب منفعل هستند. مدل‌های زبانی بزرگ به دستورالعمل‌ها به‌خوبی پاسخ می‌دهند.

«چگونگی» را توضیح دهید

توضیح خوب فاصله بین «من ابزاری دارم» و «می‌دانم چگونه این ابزار را به مکالمه متصل کنم» را پر می‌کند.

توضیح دادن «دلیل»

این ابزار را از ابزارهای مشابه متمایز کنید—برای مثال، «از این برای کاربران داخلی استفاده کنید، از customer_update برای کاربران خارجی استفاده کنید».

به مدل بگویید که آرگومان‌ها را کجا پیدا کند—برای مثال، «از ابزار order_search».

قالب را مشخص کنید

واحدها (متر درمقابل فوت) و قالب‌ها (تاریخ‌های ISO، نسخه‌های معنایی) را مشخص کنید.

اجتناب از صلاحدید مدل

به مدل دستور ندهید که از «بهترین تشخیص» خود استفاده کند یا کنش‌های اختیاری و بدون راهنمایی پیشنهاد دهد.

نمونه‌های شرح ابزار

نمونه‌های زیر بایدها و نبایدهای مربوط به شرح ابزار نوشتن را نشان می‌دهد.

توصیه‌شده توصیه نمی‌شود

منبع حقیقت

«ایمیل کاربر را به‌روز می‌کند. باید دقیقاً از UUID «شناسه» برگردانده‌شده از ابزار search_users استفاده کند. شناسه کاربر را استنباط یا حدس نزنید.»

(این گزینه صریحاً خروجی یک ابزار را به ورودی این ابزار پیوند می‌دهد.)

«نشانی ایمیل کاربر را به‌روز می‌کند.»

(مدل ممکن است شناسه‌ای مثل ۱۲۳۴۵ را حدس بزند.)

قالب و محدودیت

«جلسه‌ای زمان‌بندی کن. «تاریخ» باید در قالب ISO 8601 (س‌س‌س‌س-م‌م-رر) باشد. اگر کاربر بگوید «فردا» یا از مرجع نسبی دیگری استفاده کند، تاریخ را براساس بافت فعلی محاسبه کن.»

«جلسه‌ای برای تاریخ مشخص‌شده زمان‌بندی کن.»

(از دید انسان درست به‌نظر می‌رسد (برای مثال، «فردا») اما درستی‌سنجی طرح‌واره ناموفق است (به «2025-10-12» نیاز دارد))

انتظارات از برونداد

«گزارش‌های سرور را بازیابی می‌کند. ۵۰ خط آخر نوشتار خام را برمی‌گرداند. برای تجزیه‌وتحلیل، پنجره‌های زمانی کوچک‌تری درخواست کنید تا از محدودیت‌های کد جلوگیری شود.»

«گزارش‌های سرور را دریافت کن.»

(ممکن است مدل ابزاری را فراخوانی کند که انتظار خلاصه دارد، اما یک تخلیه 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...

    ...

این شرح به‌عنوان یک راهنمای کوچک عمل می‌کند. این ویژگی «منبع» (محل دریافت شناسه)، «محدودیت‌ها» (شمارش‌های معتبر)، و «کنش» را مدیریت می‌کند.

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

این روش برای انجام همه کارها به نام متغیرها متکی است. این کار باعث می‌شود مدل مقادیر معتبر برای «وضعیت» را حدس بزند

پارامترهای ابزار

علاوه‌بر خود ابزار، پارامترها را توصیف کنید تا ابهام نداشته باشند.

انواع صریح

از انواع قوی و خاص (string،‏ integer،‏ boolean،‏ array) استفاده کنید.

استفاده از شمارش‌ها برای مجموعه‌های مقدار ثابت

اگر پارامتری فقط مجموعه ثابتی از مقادیر را می‌پذیرد (برای مثال، daylight، cool، warm)، آن‌ها را در آرایه enum فهرست کنید. این کار دقت را به‌طور چشمگیری بهبود می‌بخشد.

پارامترهای الزامی را به‌وضوح بیان کنید

به‌وضوح مشخص کنید کدام پارامترها برای عملکرد تابع الزامی هستند.

اعمال کردن مطابقت طرح‌واره معنایی

هنگام ادغام کردن برنامه‌تان، ممکن است به تطبیق طرح‌واره معنایی از پارامترهای ابزارهایتان با حوزه‌ای که برای آن توسعه می‌دهید نیاز باشد. طرح‌واره عمودی موردانتظار (طرح‌واره JSON) را درطول فرایند آماده‌سازی دریافت خواهید کرد.

نمونه‌های پارامترهای ابزار

مثال‌های زیر بایدها و نبایدهای مربوط به مدیریت پارامترهای ابزار را نشان می‌دهد.

توصیه‌شده توصیه نمی‌شود

قالب‌ها و واحدهای شناسه

radius: «شعاع به متر. باید عدد اعشاری بزرگ‌تر از ۰ باشد.»

(از توهم واحد جلوگیری می‌کند)

شعاع: «شعاع دایره.»

قالب‌ها و بافت شناسه

user_id: «شناسه منحصربه‌فرد جهانی پایگاه داده (برای مثال، 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."""
    ...

مدل زبانی بزرگ نمی‌داند «پُرسمان» از چه نحوی پشتیبانی می‌کند (SQL؟ عبارت باقاعده؟ نوشتار ساده؟) نمی‌داند حداکثر «محدودیت» چیست.

پاسخ‌ها و رسیدگی به خطا

مطابق با اصل اساسی پاسخ، پیام‌واره بعدی است، ابزار نتیجه اجرای اساسی خود را با برگرداندن یک بار داده گزارش می‌دهد، که سپس مستقیماً در پنجره زمینه LLM جای‌گذاری می‌شود. موفقیت یا شکست نتیجه تعیین می‌کند که در مرحله بعد چه اتفاقی می‌افتد:

  • اگر موفقیت‌آمیز باشد: مدل به مقدار برگشتی نیاز دارد تا بداند چه اتفاقی افتاده است و برای مرحله بعدی تصمیم بگیرد.
  • اگر ناموفق باشد: مدل باید بداند چرا ناموفق بوده است و چگونه آن را اصلاح کند. خرابی (خطای ۵۰۰) مکالمه را متوقف می‌کند؛ پیام خطای توصیفی به مدل امکان می‌دهد خودش را اصلاح کند.

صرف‌نظر از اینکه منطق زیربنایی ابزار شما موفق شود یا شکست بخورد، باید بار داده مقدار برگشتی را به‌گونه‌ای قالب‌بندی کنید که مدل بتواند به‌راحتی آن را تجزیه کند. هنگام بسته‌بندی کردن بار داده پاسخ، این روال‌های مطلوب را دنبال کنید.

استفاده از JSON

قالب‌بندی داده‌های ساختاریافته در TextContent (محدودیت موقت). چون structuredContent هنوز در «پلاتفرم برنامه‌های متصل‌شده» پشتیبانی نمی‌شود، داده‌هایتان را به‌صورت دستی سریال‌سازی کنید. حتی اگر فهرست ساده‌ای را برمی‌گرداند، json.dumps() آن.

گنجاندن نشانی‌های وب در پاسخ

نشانی‌های وب برگردانده‌شده باید نسبتاً کوتاه و بدون پارامترهای زیاد باشند. توصیه می‌شود برای صرفه‌جویی در تعداد داده‌واحدها و کاهش خطر توهم، از سرویس‌های کوتاه‌سازی نشانی وب استفاده کنید.

محموله‌های ضدتوهم خودتوصیفی

همیشه کدهای خام یا شناسه‌های داخلی را با نام‌های نمایشی قابل‌خواندن برای انسان، واحدهای اندازه‌گیری صریح، و محدوده‌های مرجع جفت کنید. هرگز کلیدهای واژه‌نامه فشرده‌شده یا کدهای عددی نگاشت‌نشده را که مدل را مجبور به استنباط بافت می‌کند برنگردانید.

پیاده‌سازی مدیریت خطای قوی

پیام‌های خطای واضح و معنادار برگردانید تا مدل بتواند بفهمد چه مشکلی پیش آمده است و به کاربر اطلاع دهد. رسیدگی به خطای 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 ناموفق باشد، سرور خطای ۵۰۰ می‌دهد. مدل زبانی بزرگ خطای اجرای عمومی دریافت می‌کند و دلیل آن را نمی‌داند (آیا شناسه اشتباه بود؟ پایگاه داده قطع است؟ اجازه رد شد؟). احتمالاً همان ورودی بد را دوباره امتحان خواهد کرد.)

پاسخ‌های خالی

...
@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.

مدل‌های زبانی بزرگ اغلب با پاسخ‌های خالی گیج می‌شوند. ممکن است دچار کژپنداری «ابزار ناموفق بود» شوند یا فقط تماس را تکرار کنند.

بار مفید ضدتوهم خودتوصیفی

همیشه کدهای خام یا شناسه‌های داخلی را با نام‌های نمایشی قابل‌خواندن برای انسان، واحدهای اندازه‌گیری صریح، و محدوده‌های مرجع عادی جفت کنید.

{"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 حاوی یک JSON dump از فیلد ErrorData MCP است. با برگرداندن code صحیح و message قابل‌مشاهده برای مدل، «پلاتفرم برنامه‌های متصل‌شده» می‌تواند پیام خطا را بخواند و توضیح مفید و با زبان طبیعی را به کاربر منتقل کند. برای مثال، «متأسفم، نتوانستم محل برگزاری را با آن شناسه پیدا کنم. می‌توانید نام را بررسی کنید؟»

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 سرور نتوانست درخواست را تجزیه کند NO
-32600 INVALID_REQUEST درخواست کارخواه ناقص است NO
-32601 METHOD_NOT_FOUND نام ابزار MCP نامعتبر است NO
-32602 INVALID_PARAMS پارامترهای درخواست نامعتبر است، شامل پارامترهای مفقود یا انواع پارامترهای نامتناسب است NO
-32603 INTERNAL_ERROR پاسخ پیش‌فرض NO

در زیر مثالی از نحوه ایجاد خطای MCP در سرور بااستفاده از کیت توسعه نرم‌افزار رسمی Python‏ (mcp) آورده شده است. یک McpError حاوی بار داده ErrorData ایجاد کنید که کیت توسعه نرم‌افزار به‌طور خودکار آن را به قالب خطای 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 مربوطه از Tool Context API برای ارسال سیگنال‌ها به سرورهای MCP پشتیبانی می‌کنند. این میانای برنامه‌سازی کاربردی در موارد استفاده معتبری که به اطلاعات حساس نیاز دارند استفاده می‌شود—برای مثال، فراداده‌ای که بخشی از تعریف ابزار اصلی نیست، مانند موردی که برای ابزارهایی که به بومی‌سازی نیاز دارند، تنظیمات محلی وجود دارد. Tool Context API فقط ازطریق «کنسول یکپارچه» دردسترس است.

وقتی سیگنالی مثل current_user_location_fine را با برنامه‌تان در «کنسول یکپارچه» ثبت می‌کنید، محصولات Google مربوطه درخواست‌های MCP tools/call را با ورودی _meta اضافی که داده‌های درخواست‌شده را ارائه می‌دهد تقویت می‌کنند. مجموعه نشان‌های پشتیبانی‌شده عبارت‌اند از:

  • 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)"

پرداز زدن تجربه کاربری

برنامه‌های MCP

محصولات Google مربوطه از ادغام‌های برنامه‌های MCP برای مسیرهای کاربر انتخاب‌شده پشتیبانی می‌کنند تا امکان ساختن میاناهای کاربر سفارشی فراهم شود. برای دستورالعمل‌های ادغام عمومی، مشخصات را دنبال کنید.

ادغام «برنامه‌های MCP» در محصولات Google مربوطه با هشدارهای زیر همراه است.

دریافت منبع در زمان ثبت‌نام

محصولات Google ذی‌ربط منابع واسط کاربر را درطول زمان دریافت ابزار واکشی می‌کنند، مشابه فهرست ابزار و شرح ابزار. این یعنی هرگونه به‌روزرسانی منبع (برای مثال، تغییرات در جاوا اسکریپت) به‌طور خودکار دریافت نخواهد شد و نیاز به بازدریافت ابزار دارد.

اندازه یک منبع میانای کاربر نباید از ۱۵ مگابایت بیشتر باشد و منابع تجمعی میانای کاربر در سرور شما نباید از ۱۰۰ مگابایت بیشتر باشد.

منابع میانای کاربر باید از یکی از انواع MIME پشتیبانی‌شده استفاده کنند: text/html، text/javascript، text/css، یا text/html;profile=mcp-app. انواع MIME غیر استاندارد یا مختص پلاتفرم هنگام ارسال به پیش‌نمایش، درستی‌سنجی نخواهند شد.

رهنمودهای CSP

محصولات Google ذی‌ربط از مشخصات رسمی برنامه‌های MCP پیروی می‌کنند که شامل CSP [۱]، [۲] می‌شود و هر درخواستی را که دستورالعمل‌های CSP را نقض کند مسدود خواهند کرد.

محصولات Google ذی‌ربط علاوه‌براین نیاز به افزودن blob: و data: به CSP دارند، درصورت استفاده. این موارد به‌طور پیش‌فرض اضافه نخواهند شد. این انتخاب توسعه‌دهنده است که آن‌ها را به CSP اضافه کند (یا نکند).

Script-src استثنا است

تنها دستورالعمل‌هایی که مجاز می‌دانیم عبارتند از: unsafe-inline (به‌طور پیش‌فرض اضافه شده است)، wasm-unsafe-eval، و data: (اگر در resource_domains گنجانده شده باشد). اگر iframe دستورگان‌های خارجی را بار می‌کند، می‌توان آن را با بسته‌بندی JS در HTML یا استفاده از درهم‌ساز «یکپارچگی زیرمنبع» (SRI) حل کرد.

  • گزینه ۱: JS درون‌خطی / بسته‌ای در HTML (ساده‌ترین)

    • کد JS بسته:

      • محتوای component-init.js را مستقیماً درون برچسب‌های <script> در پایه‌بار HTML که برای منبع میانای کاربری برگردانده شده است به‌صورت درون‌خطی قرار دهید:

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

    • برداشتن برچسب‌های <script src> از راه دور

      • <script src="https://api.mycompany.com/..."> مرجع را از سند HTML حذف کنید.

    • ابزار بازجذب / به‌روزرسانی

  • گزینه ۲: استفاده از درهم‌سازی «یکپارچگی زیرمنبع» (SRI):

    اگر دستورگان باید به‌صورت خارجی در https://api.company.com/... میزبانی شود، از این گزینه استفاده کنید.

    • محاسبه درهم‌سازی SHA-256 از اسکریپت
      • درهم‌سازی SHA-256 پایه ۶۴ component-init.js را تولید کنید
    • درهم‌سازی را به resourceDomains اضافه کنید (باید شامل پیشوند sha256- باشد تا با مشخصه integrity مطابقت داشته باشد)
    • به‌روزرسانی تگ HTML <script>
      • مشخصه‌های integrity و crossorigin را به برچسب دستورگان در ابزاره HTML اضافه کنید
    • درستی‌سنجی کردن سرصفحه CORS در CDN/سرور
      • مطمئن شوید api.company.com component-init.js را با Access-Control-Allow-Origin: * ارائه می‌دهد (یا scf.usercontent.goog را مجاز می‌کند) تا مرورگر بتواند بدنه پاسخ را برای درستی‌سنجی SRI بخواند.
    • ابزار بازجذب / به‌روزرسانی

دستورالعمل‌های امنیتی برای شرح ابزار MCP

ازآنجایی‌که شرح تنها بافتی است که مدل برای درک قابلیت‌های ابزار دارد، باید به‌طور دقیق و ایمن نوشته شود تا از رفتار ناخواسته جلوگیری شود. هنگام پیش‌نویس کردن شرح ابزار، از دستورالعمل‌های زیر پیروی کنید.

  • عملکرد را شرح دهید، اما رفتار را دیکته نکنید. شرح باید به‌طور دقیق توصیف کند که ابزار چه کاری انجام می‌دهد، نه اینکه به مدل فرمان دهد که کنش‌های بعدی را انجام دهد.
  • دامنه و الزامات را تعریف کنید. هدف اصلی ابزار، شرایط خاص (زمان) استفاده از آن، و همه ورودی‌های (پارامترها/ شناسه) موردنیاز را به‌وضوح بیان کنید.
  • از صحت اطلاعات مطمئن شوید. توضیحات باید نمایانگر صادقانه کد اصلی ابزار باشد. اگر ابزاری عملیات نوشتن یا حذف کردن را انجام می‌دهد، ادعا نکنید که فقط خواندنی است.

خطرات امنیتی و نحوه اجتناب از آن‌ها

منطقه خطر توصیه‌شده به‌هیچ‌وجه این کار را انجام ندهید

تزریق پیام‌واره

از زبان عینی و بیانی استفاده کنید تا هدف و عملکرد ابزار را به‌وضوح بیان کنید.

از فرمان‌های امری برای لغو رفتار مدل یا تغییر جریان‌های سیستم استفاده کنید (برای مثال، «باید بگویید...»، «پس‌از دویدن، باید…»). اصطلاحات امری مانند «باید» یا «بحرانی» فقط هنگام تعریف محدودیت‌های پارامتر ساختاریافته یا قوانین استفاده قابل‌قبول هستند.

از قالب‌بندی استاندارد و ساده برای نوشتار شرح ابزار استفاده کنید.

از قالب‌بندی جلب‌توجه‌کننده استفاده کنید — برای مثال، استفاده بیش‌ازحد از حروف بزرگ و برچسب‌هایی مثل VERY IMPORTANT: یا **CRITICAL**.

فقط روی عملکرد ابزار و رفتار موردانتظار تمرکز کنید.

شامل دستورالعمل‌های ایفای نقش یا فرمان‌هایی برای نادیده گرفتن دستورالعمل‌های قبلی باشد.

سایه‌اندازی و ربایش ابزار

مطمئن شوید شرح دقیق است و به قابلیت‌های واقعی و مرتبط ابزار محدود می‌شود.

شرح ابزار را بیش‌ازحد کلی یا مبهم کنید، یا ادعا کنید که یک ابزار واحد عملکردهای نامرتبط زیادی را انجام می‌دهد.

نامی منحصربه‌فرد، توصیفی، و معقول برای ابزار انتخاب کنید.

از نام ابزاری استفاده کنید که تغییر جزئی‌ای از یک ابزار مورداعتماد یا نامی عمومی باشد (برای مثال، do_everything_tool، assistant_tool).

در شرحتان، نام برنامه‌های دیگر یا ابزارهای پلاتفرم خارجی را ذکر نکنید.

به‌طور صریح به ابزارهای دیگر ارجاع دهد یا قوانین جدیدی برای زمان یا نحوه استفاده از سایر ابزارها ایجاد کند.

به برنامه‌ریز مدل اجازه دهید مناسب‌ترین ابزار را براساس بافت کاربر انتخاب کند.

شامل زبان ضدرقابتی یا هر نوع پیام‌واره بهینه‌سازی موتور جستجو باشد که به مدل دستور دهد ابزار شما را به ابزارهای مشابه ترجیح دهد.

دست‌کاری راه‌انداز

شرح به عبارت‌های کلی سابقه مکالمه ارجاع نمی‌دهد یا به آن‌ها واکنش نشان نمی‌دهد.

منطق شرطی ایجاد کند که براساس عبارت‌های رایج و بی‌ضرر کاربر (مثلاً «متشکرم»، «برای خلاصه کردن») کنش مضری را راه‌اندازی کند.

سوءاستفاده از پارامترها

فقط پارامترهای لازم برای عملکرد ابزار را تعریف کنید و از نام‌های خاص برای داده‌های ورودی استفاده کنید (برای مثال، file_id، search_term).

پارامترهای تابع را با نام‌هایی تعریف کنید که وضعیت داخلی «نماینده» را منعکس می‌کنند (برای مثال، system_prompt، conversation_history، full_context).

استخراج داده

طراحی با رعایت حریم خصوصی - شناسه‌های مبهم و اصالت‌سنجی مدیریت‌شده توسط میزبان.

از شناسه‌های غیرحساس استفاده کنید، نه اطلاعات شناساننده شخصی خام. همه موارد مدیریت داده باید در مرزهای مجاز و ایمن باشد و در شرح عمومی به‌عنوان ارسال‌شده به خارج ارجاع داده نشود. اجرای ابزار اجازه‌ها را به‌طور نامحسوس ازطریق دست‌دهی OAUth به ارث می‌برد.

هرگونه اطلاعات حساس باید قبل‌از ارسال به محصولات Google ذی‌ربط پاک‌سازی شود.

درخواست اطلاعات شناساننده شخصی، اطلاعات بهداشتی شخصی، یا هرگونه اطلاعات شخصی و/یا حساس دیگر از کاربر، داده‌های شخصی یا کسب‌وکار، یا نهاد در هر ظرفیتی که شرایط خدمات محصولات Google مربوطه را نقض کند.

اشاره به ارسال هرگونه داده کاربر (پرسمان، مکان، بافت) به نشانی‌های وب طرف سوم غیرمجاز، سرویس‌های ثبت گزارش، یا سیستم‌های خارجی یا درخواست ارسال آن‌ها.

روال‌های مطلوب عملکردی و نام‌گذاری

علاوه‌بر ایمن‌سازی شرح ابزارتان، باید مطمئن شوید که مدل می‌تواند به‌طور مطمئن آن را بدون سردرگمی انتخاب و اجرا کند. از روال‌های مطلوب عملکردی و نام‌گذاری زیر پیروی کنید:

  • دقت پارامتر. مطمئن شوید همه نام‌ها و انواع پارامترها در شرح دقیقاً با پیاده‌سازی واقعی ابزار مطابقت داشته باشند.
  • نام‌گذاری معقول. نام ابزار باید اشاره‌ای قوی و واضح به عملکرد آن باشد. از نام‌های بیش‌ازحد کلی مثل «اجرا» اجتناب کنید. نام باید با بوم‌سازگان گسترده‌تر ابزار نیز سازگار باشد.

پیوست: زیرساخت و قرار دادن شبکه در فهرست مجاز

اگر زیرساخت میزبانی، درگاه API، یا دیوار آتش شما اتصال‌های ورودی را براساس نشانی IP منبع محدود می‌کند، بلوک‌های CIDR برون‌مرزی Google زیر را در فهرست مجاز قرار دهید:

  • 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

مطمئن شوید محیط شما ترافیک این دامنه‌های IP را در درگاه HTTPS 443 مجاز می‌کند تا محصولات Google مربوطه بتوانند برای مقداردهی اولیه MCP، کشف ابزار، و اجرای درخواست به سرور MCP راه دور شما دسترسی پیدا کنند.