MCP Tools Reference: mapstools.googleapis.com

مرجع ابزارهای MCP:

این سند، نقاط پایانی REST API خارجی مورد استفاده برای فراخوانی ابزارهای پروتکل زمینه مدل از راه دور گوگل (MCP) را شرح می‌دهد. این API به عنوان یک پروکسی امن بین یک کلاینت HTTP خارجی (مانند curl یا یک سرویس وب) و سرور MCP داخلی عمل می‌کند.

مشخصات ابزار 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
}'

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

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

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

  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 استفاده کنید که مختصات به صراحت ارائه شده باشند یا اگر استنباط یک مکان از زمینه شناخته شده کاربر برای نتایج بهتر مناسب و ضروری باشد.

نمونه‌های زیر نحوه استفاده از curl برای فراخوانی ابزار search_places MCP را نشان می‌دهند.

درخواست کرل 
curl --location 'https://mapstools.googleapis.com/mcp'
--header 'content-type: application/json'
--header 'accept: application/json, text/event-stream'
--data '{
  "method": "tools/call",
  "params": {
    "name": search_places,
    arguments: {
      // please fill these details according to tools MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

ابزار: lookup_weather

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

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

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

  • شرایط فعلی: فقط به یک مکان (مثلاً شهر یا آدرس) نیاز دارد. تاریخ یا ساعت را مشخص نکنید.

  • پیش‌بینی‌های ساعتی: به یک مکان و یک ساعت (0-23) نیاز دارد. اگر کاربر در مورد آب و هوا در یک زمان خاص سوال می‌کند یا از عباراتی مانند «چند ساعت آینده» یا «بعداً امروز» استفاده می‌کند، از این گزینه استفاده کنید.

  • پیش‌بینی‌های روزانه: به مکان و تاریخ کامل نیاز دارد.

مدیریت تاریخ (بحرانی): تاریخ‌ها و ساعات ارائه شده توسط کاربر باید در منطقه زمانی محلی مکان درخواستی ارائه شوند. تاریخ‌ها باید به پارامترهای صحیح جداگانه تقسیم شوند: سال، ماه و روز. قالب مورد نیاز برای این پارامترها: {"سال": ، "ماه": ، "روز": }

نمونه‌های زیر نحوه استفاده از curl برای فراخوانی ابزار lookup_weather MCP را نشان می‌دهند.

درخواست کرل 
curl --location 'https://mapstools.googleapis.com/mcp'
--header 'content-type: application/json'
--header 'accept: application/json, text/event-stream'
--data '{
  "method": "tools/call",
  "params": {
    "name": lookup_weather,
    arguments: {
      // please fill these details according to tools MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

ابزار: compute_routes

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

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

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

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

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

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

نمونه‌های زیر نحوه استفاده از curl برای فراخوانی ابزار compute_routes MCP را نشان می‌دهند.

درخواست کرل 
curl --location 'https://mapstools.googleapis.com/mcp'
--header 'content-type: application/json'
--header 'accept: application/json, text/event-stream'
--data '{
  "method": "tools/call",
  "params": {
    "name": compute_routes,
    arguments: {
      // please fill these details according to tools MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'