MCP Reference: mapstools.googleapis.com

یک سرور پروتکل زمینه مدل (MCP) به عنوان یک پروکسی بین یک سرویس خارجی عمل می‌کند که زمینه، داده‌ها یا قابلیت‌هایی را برای یک مدل زبان بزرگ (LLM) یا برنامه هوش مصنوعی فراهم می‌کند. سرورهای MCP برنامه‌های هوش مصنوعی را به سیستم‌های خارجی مانند پایگاه‌های داده و سرویس‌های وب متصل می‌کنند و پاسخ‌های آنها را به فرمتی که برنامه هوش مصنوعی می‌تواند درک کند، ترجمه می‌کنند.

راه اندازی سرور

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

این یک سرور MCP است که توسط Maps Grounding Lite API ارائه می‌شود. این سرور ابزارهایی را برای توسعه‌دهندگان فراهم می‌کند تا برنامه‌های LLM را بر روی پلتفرم Google Maps بسازند.

نقاط پایانی سرور

یک نقطه پایانی سرویس MCP، آدرس شبکه و رابط ارتباطی (معمولاً یک URL) سرور MCP است که یک برنامه هوش مصنوعی (میزبان برای کلاینت MCP) برای ایجاد یک اتصال امن و استاندارد از آن استفاده می‌کند. این نقطه تماس LLM برای درخواست زمینه، فراخوانی یک ابزار یا دسترسی به یک منبع است. نقاط پایانی Google MCP می‌توانند جهانی یا منطقه‌ای باشند.

سرور MCP mapstools.googleapis.com دارای نقطه پایانی MCP زیر است:

ابزارهای MCP

یک ابزار MCP یک تابع یا قابلیت اجرایی است که یک سرور MCP آن را در اختیار یک برنامه LLM یا هوش مصنوعی قرار می‌دهد تا عملی را در دنیای واقعی انجام دهد.

سرور MCP mapstools.googleapis.com ابزارهای زیر را دارد:

ابزارهای MCP
جستجو_مکان‌ها

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

الزامات ورودی (بحرانی):

  1. text_query (رشته - اجباری): عبارت جستجوی اصلی. این عبارت باید به وضوح آنچه کاربر به دنبال آن است را تعریف کند.

    • مثال‌ها: 'restaurants in New York' ، 'coffee shops near Golden Gate Park' ، 'SF MoMA' ، '1600 Amphitheatre Pkwy, Mountain View, CA, USA' ، 'pets friendly parks in Manhattan, New York' ، 'date night restaurants in Chicago' ، 'accessible public libraries in Los Angeles' .
    • برای جزئیات مکان خاص: ویژگی درخواستی را وارد کنید (مثلاً 'Google Store Mountain View opening hours' ، 'SF MoMa phone number' ، 'Shoreline Park Mountain View address' ).

  2. location_bias (object - اختیاری): از این برای اولویت‌بندی نتایج نزدیک به یک منطقه جغرافیایی خاص استفاده کنید.

    • قالب: {"location_bias": {"circle": {"center": {"latitude": [value], "longitude": [value]}, "radius_meters": [value (optional)]}}}
    • طریقه استفاده:
      • برای بایاس کردن به شعاع ۵ کیلومتر: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}, "radius_meters": 5000}}}
      • برای بایاس قوی به نقطه مرکزی: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}}}} ( radius_meters را حذف کنید).

  3. language_code (رشته - اختیاری): زبانی که خلاصه نتایج جستجو در آن نمایش داده می‌شود.

    • قالب: یک کد زبان دو حرفی (ISO 639-1)، که به صورت اختیاری با یک زیرخط و یک کد کشور دو حرفی (ISO 3166-1 alpha-2) دنبال می‌شود، مانند en ، ja ، en_US ، zh_CN ، es_MX . اگر کد زبان ارائه نشود، نتایج به زبان انگلیسی خواهد بود.

  4. region_code (رشته - اختیاری): کد منطقه CLDR یونیکد کاربر. این پارامتر برای نمایش جزئیات مکان، مانند نام مکان خاص منطقه، در صورت وجود، استفاده می‌شود. این پارامتر می‌تواند بر اساس قانون مربوطه بر نتایج تأثیر بگذارد.

    • قالب: کد کشور دو حرفی (ISO 3166-1 alpha-2)، مثلاً US ، CA

دستورالعمل فراخوانی ابزار:

  • اطلاعات مکان (حیاتی): جستجو باید حاوی اطلاعات مکانی کافی باشد. اگر مکان مبهم است (مثلاً فقط "پیتزا فروشی‌ها")، باید آن را در text_query مشخص کنید (مثلاً "پیتزا فروشی‌ها در نیویورک") یا از پارامتر location_bias استفاده کنید. در صورت نیاز برای ابهام‌زدایی، نام شهر، ایالت/استان و منطقه/کشور را نیز وارد کنید.

  • همیشه خاص‌ترین و غنی‌ترین text_query ممکن را ارائه دهید.

  • فقط در صورتی location_bias استفاده کنید که مختصات به صراحت ارائه شده باشند یا اگر استنباط یک مکان از زمینه شناخته شده کاربر برای نتایج بهتر مناسب و ضروری باشد.

آب و هوای جستجو

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

داده‌های خاص موجود: دما (دمای فعلی، دمای مورد انتظار، حداکثر/حداقل، شاخص گرما)، باد (سرعت، تندباد، جهت)، رویدادهای آسمانی (طلوع/غروب خورشید، فاز ماه)، بارش (نوع، احتمال، مقدار/QPF)، شرایط جوی (شاخص UV، رطوبت، پوشش ابر، احتمال رعد و برق) و آدرس موقعیت مکانی با کد جغرافیایی.

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

  1. مختصات جغرافیایی (lat_lng)

    • وقتی مختصات دقیق عرض/طول جغرافیایی (lat/lng) به شما ارائه شد، از آن استفاده کنید.
    • مثال: "lat_lng": { "عرض جغرافیایی": 34.0522، "طول جغرافیایی": -118.2437 } // لس آنجلس

  2. شناسه مکان (place_id)

    • یک شناسه رشته‌ای بدون ابهام (شناسه مکان گوگل مپ).
    • place_id را می‌توان از ابزار search_places دریافت کرد.
    • مثال: "place_id": "ChIJLU7jZClu5kcR4PcOOO6p3I0" // برج ایفل

  3. رشته آدرس (آدرس)

    • یک رشته آزاد که برای کدگذاری جغرافیایی به ویژگی خاصی نیاز دارد.
    • شهر و منطقه: همیشه منطقه/کشور را وارد کنید (مثلاً «لندن، بریتانیا»، نه «لندن»).
    • آدرس خیابان: آدرس کامل را وارد کنید (مثلاً «۱۶۰۰ خیابان پنسیلوانیا شمال غربی، واشنگتن دی سی»).
    • کد پستی: باید با نام کشور همراه باشد (مثلاً «۹۰۲۱۰، ایالات متحده آمریکا»، نه «۹۰۲۱۰»).

حالت‌های استفاده: ۱. آب و هوای فعلی: فقط address وارد کنید. date و hour را مشخص نکنید.

  1. پیش‌بینی ساعتی: address ، date و hour (0-23) را وارد کنید. برای زمان‌های خاص (مثلاً "ساعت 5 بعد از ظهر") یا عباراتی مانند "چند ساعت آینده" یا "بعداً امروز" استفاده کنید. اگر کاربر دقیقه را مشخص کند، به نزدیکترین ساعت گرد می‌شود. پیش‌بینی ساعتی برای بیش از 48 ساعت از اکنون پشتیبانی نمی‌شود.

  2. پیش‌بینی روزانه: address و date را وارد کنید. hour مشخص نکنید. برای درخواست‌های عمومی روزانه استفاده کنید (مثلاً «آب و هوای فردا»، «آب و هوای جمعه»، «آب و هوای ۲۵/۱۲»). اگر تاریخ امروز در متن نیست، باید آن را با کاربر روشن کنید. پیش‌بینی روزانه فراتر از ۷ روز شامل امروز پشتیبانی نمی‌شود. آب و هوای تاریخی پشتیبانی نمی‌شود.

محدودیت‌های پارامتر: * مناطق زمانی: تمام ورودی‌های date و hour باید نسبت به منطقه زمانی محلی مکان باشند، نه منطقه زمانی کاربر.

  • قالب تاریخ: ورودی‌ها باید به صورت اعداد صحیح {year, month, day} جدا شوند.

  • واحدها: پیش‌فرض روی METRIC است. اگر کاربر استانداردهای ایالات متحده را مطرح می‌کند یا صریحاً درخواست می‌کند، units_system برای فارنهایت/مایل روی IMPERIAL تنظیم کنید.

محاسبه_مسیرها

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

الزامات ورودی (حیاتی): به مبدا و مقصد نیاز دارد. هر کدام باید با استفاده از یکی از روش‌های زیر، که در فیلد مربوطه قرار دارند، ارائه شوند:

  • آدرس: (رشته، مثلاً «برج ایفل، پاریس»). توجه: هرچه آدرس ورودی جزئی‌تر یا خاص‌تر باشد، نتایج بهتر خواهند بود.

  • lat_lng: (شیء، {"عرض جغرافیایی": عدد، "طول جغرافیایی": عدد})

  • place_id: (رشته، مثلاً 'ChIJOwE_Id1w5EAR4Q27FkL6T_0') توجه: این شناسه را می‌توان از ابزار search_places دریافت کرد. هر ترکیبی از انواع ورودی مجاز است (مثلاً مبدأ بر اساس آدرس، مقصد بر اساس lat_lng). اگر مبدأ یا مقصد وجود ندارد، قبل از تلاش برای فراخوانی ابزار، باید از کاربر توضیح بخواهید .

مثال فراخوانی ابزار: {"origin":{"address":"برج ایفل"},"destination":{"place_id":"ChIJt_5xIthw5EARoJ71mGq7t74"},"travel_mode":"DRIVE"}

مشخصات ابزار MCP را دریافت کنید

برای دریافت مشخصات ابزار MCP برای همه ابزارهای موجود در یک سرور MCP، از متد tools/list استفاده کنید. مثال زیر نحوه استفاده از curl برای فهرست کردن همه ابزارها و مشخصات آنها که در حال حاضر در سرور MCP موجود هستند را نشان می‌دهد.

درخواست کرل 
                      curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
    "method": "tools/list",
    "jsonrpc": "2.0",
    "id": 1
}'