MCP Tools Reference: mapstools.googleapis.com

ابزار: compute_routes

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

الزامات ورودی (بسیار مهم):

1. origin و destination (اشیاء - اجباری): هرکدام باید دقیقاً بااستفاده از یکی از موارد زیر ارائه شوند:

   • address (رشته، مثلاً 'Eiffel Tower, Paris'). مکان‌های نام‌گذاری‌شده، نشانگرهای مکانی، و کسب‌وکارها مستقیماً حل‌وفصل می‌شوند، بنابراین برای زمین‌کدیابی نقطه‌مسیر، ابتدا search_places را فراخوانی نکنید. هر شهر، منطقه، یا کشوری را که کاربر ذکر کرده است اضافه کنید.
   • lat_lng (شیء، {"latitude": number, "longitude": number}).
   • ‫place_id (رشته، مثلاً 'ChIJOwE_Id1w5EAR4Q27FkL6T_0')، برای مثال از search_places.

2. intermediate_waypoints (آرایه اشیا - اختیاری): حداکثر ۱۰ ایستگاه برای عبور، به‌ترتیب، بین مبدأ و مقصد. قالب مشابه origin. با TRANSIT پشتیبانی نمی‌شود. فقط ایستگاه‌هایی را که کاربر درخواست کرده است اضافه کنید.

3. travel_mode (enum - اختیاری): DRIVE (پیش‌فرض)، WALK، BICYCLE، یا TRANSIT.

4. زمان‌بندی (اختیاری - حداکثر یک مورد تنظیم شود): مُهرهای زمان RFC 3339 با انحراف UTC، برای نمونه '2026-09-19T08:00:00-07:00'. به‌طور پیش‌فرض روی «درحال حرکت» تنظیم شده است. برای TRANSIT، زمان می‌تواند حداکثر ۷ روز در گذشته یا حداکثر ۱۰۰ روز در آینده باشد. برای حالت‌های دیگر، زمان می‌تواند تا ۳۶۵ روز در آینده باشد و نباید در گذشته باشد.

   • departure_time: زمانی استفاده می‌شود که کاربر می‌گوید چه زمانی می‌رود (مثلاً «فردا ساعت ۸ صبح»).
   • arrival_time: زمانی استفاده می‌شود که کاربر می‌گوید چه زمانی باید برسد (مثلاً «تا ساعت ۹ صبح آنجا باشم»).

5. routing_preference (enum - اختیاری):

   • ROUTING_PREFERENCE_TRAFFIC_UNAWARE (پیش‌فرض): ترافیک زنده، حوادث، و راه‌بندان‌ها را نادیده می‌گیرد. کمترین تأخیر.
   • ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL: از شرایط ترافیک زنده درصورت دردسترس بودن استفاده می‌کند. برای WALK یا BICYCLE پشتیبانی نمی‌شود. این را «فقط» زمانی تنظیم کنید که کاربر درباره ترافیک، ازدحام، یا زمان تخمینی ورود اصلاح‌شده براساس ترافیک سؤال می‌کند. این کار هزینه و تأخیر بیشتری دارد.

6. location_bias (شیء - اختیاری): {"latitude": number, "longitude": number} برای ابهام‌زدایی از نام مکان‌ها در نشانی‌های نقطه‌مسیر استفاده می‌شود. اگر نامی مبهم است (مثلاً «Springfield») و کاربر منطقه‌ای را ارائه نکرده است، نام را همان‌طور که در address ارائه شده است نگه دارید و location_bias را به‌جای حدس زدن منطقه، به‌سمت منطقه موردنظر تنظیم کنید.

7. compute_alternative_routes (بولی - اختیاری): فقط زمانی روی true تنظیم کنید که کاربر گزینه‌های مسیر یا جایگزین‌ها را درخواست کند. به‌طور پیش‌فرض روی false تنظیم شده است که فقط مسیر توصیه‌شده را برمی‌گرداند.

8. include_polyline (بولی - اختیاری): فقط زمانی روی true تنظیم کنید که هندسه مسیر (encoded_polyline) موردنیاز باشد. پیش‌فرض‌ها به false.

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

• اگر مبدأ یا مقصد وجود ندارد، باید قبل‌از فراخوانی ابزار از کاربر بخواهید شفاف‌سازی کند.
• برای سؤالات «فاصله الف تا ب چقدر است؟»، از ب به‌عنوان origin و از الف به‌عنوان destination استفاده کنید.

نمونه فراخوانی ابزار: {"origin":{"address":"Eiffel Tower"},"destination":{"place_id":"ChIJt_5xIthw5EARoJ71mGq7t74"},"intermediate_waypoints":[{"address":"Louvre Museum"}],"travel_mode":"DRIVE","departure_time":"2026-09-19T08:00:00+02:00"}

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

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

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

طرح‌واره ورودی

{
  "origin": {
    object (Waypoint)
  },
  "destination": {
    object (Waypoint)
  },
  "travelMode": enum (RouteTravelMode),
  "intermediateWaypoints": [
    {
      object (Waypoint)
    }
  ],
  "routingPreference": enum (RoutingPreference),
  "locationBias": {
    object (LatLng)
  },
  "includePolyline": boolean,
  "computeAlternativeRoutes": boolean,

  // Union field timing can be only one of the following:
  "departureTime": string,
  "arrivalTime": string
  // End of list of possible types for union field timing.
}

{
  "seconds": string,
  "nanos": integer
}

{

  // Union field location_type can be only one of the following:
  "latLng": {
    object (LatLng)
  },
  "placeId": string,
  "address": string
  // End of list of possible types for union field location_type.
}

{
  "latitude": number,
  "longitude": number
}

طرح خروجی

{
  "routes": [
    {
      object (Route)
    }
  ]
}

{
  "distanceMeters": integer,
  "duration": string,
  "attribution": {
    object (Attribution)
  },
  "encodedPolyline": string,
  "retrievalToken": string
}

{
  "seconds": string,
  "nanos": integer
}

{
  "title": string,
  "url": string
}

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

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

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

• ‫readOnlyHint: اگر درست باشد، ابزار محیط خود را تغییر نمی‌دهد. پیش‌فرض: false.
• ‫destructiveHint: اگر درست باشد، ابزار می‌تواند کنش‌های مخرب انجام دهد. اگر نادرست باشد، ابزار فقط می‌تواند کنش‌های افزایشی انجام دهد. پیش‌فرض: true.
• idempotentHint: اگر درست باشد، فراخوانی مکرر ابزار با آرگومان‌های یکسان تأثیر بیشتری بر محیط آن نخواهد داشت. پیش‌فرض: false.
• openWorldHint: اگر درست باشد، ابزار می‌تواند با «دنیای باز» نهادهای خارجی تعامل داشته باشد. اگر نادرست باشد، ابزار فقط می‌تواند با نهادهای داخلی تعامل داشته باشد. برای مثال، ابزار جستجوی وب دنیای باز است، درحالی‌که ابزار حافظه دنیای باز نیست.

Destructive Hint: ❌ | Idempotent Hint: ❌ | Read Only Hint: ✅ | Open World Hint: ❌