MCP Tools Reference: mapstools.googleapis.com

ابزار: resolve_maps_urls

فهرستی از نشانی‌های وب Google Maps را به «شناسه‌های جا» در Google Maps متعارف تبدیل می‌کند.

چه زمانی این ابزار را فراخوانی کنید (بسیار مهم):

  • وقتی کاربر یک یا چند پیوند یا نشانی وب هم‌رسانی Google Maps (مثلاً «https://maps.app.goo.gl/...») ارائه می‌دهد، از این ابزار استفاده کنید. «https://www.google.com/maps/place/...‎» یا «https://maps.google.com/...‎») و باید «شناسه‌های مکان» متعارف زیربنایی را استخراج کنید.
  • می‌توانید حداکثر ۲۰ نشانی وب را برای حل‌وفصل در یک درخواست دسته‌ای مشخص کنید.

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

  • urls (آرایه رشته‌ها - اجباری): فهرست نشانی‌های وب Google Maps برای حل کردن. هر نشانی وب باید نشانی وب معتبر و تک‌مکانی Google Maps باشد.

ذخیره در Google Maps:

  • پاسخ شامل فیلد save_to_maps_url است: یک پیوند Google Maps که حاوی همه مکان‌های با موفقیت حل‌شده است.
  • وقتی کاربر می‌خواهد مکان‌های حل‌شده را به‌عنوان فهرستی در Google Maps ذخیره، هم‌رسانی، یا باز کند (مثلاً جمع‌آوری مکان‌های هم‌رسانی‌شده در مکالمه)، این پیوند را به کاربر ارائه دهید. این پیوند را خودتان نسازید.

مدیریت خطا (بسیار مهم):

  • این ابزار پردازش دسته‌ای است. ممکن است درخواست «نتایج مختلط» برگرداند (مثلاً برخی‌از نشانی‌های وب با موفقیت حل‌وفصل شوند درحالی‌که برخی دیگر ناموفق باشند).
  • تضمین می‌شود که فهرست خروجی entities با نمایه‌های ورودی urls به‌صورت ۱:۱ نگاشت شود. وضوح نشانی وب ناموفق منجر به پیام Entity خالی (هیچ فیلدی تنظیم نشده است) در نمایه مربوطه در فهرست entities می‌شود.
  • باید فیلد نقشه failed_requests را در پاسخ بررسی کنید تا مشخص شود کدام نمایه نشانی وب خاص ناموفق بوده است. کلید failed_requests نشان‌دهنده نمایه مبتنی بر صفر نشانی وب ناموفق در درخواست است. فرض نکنید که کل تماس دسته‌ای به‌دلیل یک شکست جزئی ناموفق بوده است.

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

درخواست Curl 
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": "resolve_maps_urls",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

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

پیام درخواست برای ResolveMapsUrls.

ResolveMapsUrlsRequest

نمایش JSON 
{
  "urls": [
    string
  ]
}
فیلدها
urls[]

string

الزامی. نشانی‌های وب Google Maps که باید حل‌وفصل شوند. هر نشانی وب باید نشانی وب معتبر Google Maps باشد، برای مثال، https://maps.app.goo.gl/...، https://www.google.com/maps/place/...، یا https://maps.google.com/.... درحال‌حاضر، فقط نشانی‌های وبی که به یک مکان اشاره می‌کنند پشتیبانی می‌شوند. می‌توانید حداکثر ۲۰ نشانی وب مشخص کنید.

طرح خروجی

پیام پاسخ برای ResolveMapsUrls.

ResolveMapsUrlsResponse

نمایش JSON 
{
  "entities": [
    {
      object (Entity)
    }
  ],
  "failedRequests": {
    integer: {
      object (Status)
    },
    ...
  },
  "saveToMapsUrl": string
}
فیلدها
entities[]

object (Entity)

فقط خروجی. فهرست نهادهای حل‌شده از نشانی‌های وب Google Maps. تضمین می‌شود که با نمایه‌های urls درخواست، نگاشت ۱:۱ داشته باشد. پیام خالی در نمایه i (که در آن هیچ entity تنظیم نشده است) نشان می‌دهد که تجزیه برای آن نشانی وب ناموفق بوده است. اگر حل‌وفصل ناموفق بود، لطفاً فیلد failed_requests را برای وضعیت خطا بررسی کنید.
failedRequests

map (key: integer, value: object (Status))

فقط خروجی. نقشه‌ای که خرابی‌های جزئی را برای نشانی‌های وب Google Maps نشان می‌دهد. کلید، نمایه درخواست ناموفق در فیلد urls است. این مقدار وضعیت خطایی است که جزئیات دلیل ناموفق بودن وضوح را نشان می‌دهد.

شیئی که حاوی فهرستی از جفت‌های "key": value است. مثال: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
saveToMapsUrl

string

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

نهاد

نمایش JSON 
{

  // Union field entity can be only one of the following:
  "place": string
  // End of list of possible types for union field entity.
}
فیلدها
فیلد اتحادیه entity. نوع نهاد حل‌شده. entity فقط می‌تواند یکی از موارد زیر باشد:
place

string

نام منبع مکان حل‌شده.

FailedRequestsEntry

نمایش JSON 
{
  "key": integer,
  "value": {
    object (Status)
  }
}
فیلدها
key

integer
value

object (Status)

وضعیت

نمایش JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
فیلدها
code

integer

رمز وضعیت که باید مقدار شمارشی google.rpc.Code باشد.
message

string

پیام خطای توسعه‌دهنده که باید به زبان انگلیسی باشد. هر پیام خطای سَمت کاربر باید بومی‌سازی شود و در فیلد google.rpc.Status.details ارسال شود، یا توسط کارخواه بومی‌سازی شود.
details[]

object

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

شیء حاوی فیلدهایی از نوع دلخواه. فیلد اضافی "@type" حاوی URI است که نوع را مشخص می‌کند. مثال: { "id": 1234, "@type": "types.example.com/standard/id" }.

همه

نمایش JSON 
{
  "typeUrl": string,
  "value": string
}
فیلدها
typeUrl

string

نوع پیام Protobuf سریالی‌شده را با مرجع URI متشکل از پیشوندی که به خط مورب ختم می‌شود و نام نوع کاملاً واجدشرایط شناسایی می‌کند.

مثال: type.googleapis.com/google.protobuf.StringValue

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

پیشوند اختیاری است و انتظار می‌رود پیاده‌سازی‌های Protobuf به‌سادگی همه چیز را تا آخرین / (شامل آن) حذف کنند تا نوع را شناسایی کنند. ‫type.googleapis.com/ پیشوند پیش‌فرض رایجی است که برخی‌از پیاده‌سازی‌های قدیمی به آن نیاز دارند. این پیشوند نشان‌دهنده منشأ نوع نیست و انتظار نمی‌رود URIهای حاوی آن به هیچ درخواستی پاسخ دهند.

همه رشته‌های نشانی وب نوع باید ارجاع‌های URI قانونی با محدودیت اضافی (برای قالب نوشتاری) باشند که محتوای ارجاع باید فقط از نویسه‌های الفباعددی، گریزهای کدگذاری‌شده با درصد، و نویسه‌های موجود در مجموعه زیر (به‌جز تیک‌های بیرونی) تشکیل شده باشد: /-.~_!$&()*+,;=. باوجود اینکه کدگذاری‌های درصدی را مجاز می‌دانیم، پیاده‌سازی‌ها نباید آن‌ها را از حالت گریز خارج کنند تا از سردرگمی با تجزیه‌کننده‌های موجود جلوگیری شود. برای مثال، type.googleapis.com%2FFoo باید رد شود.

در طراحی اصلی Any، امکان راه‌اندازی سرویس حل نوع در این نشانی‌های وب نوع درنظر گرفته شده بود، اما Protobuf هرگز چنین سرویسی را پیاده‌سازی نکرد و تماس با این نشانی‌های وب را مشکل‌ساز و یک مسئله امنیتی بالقوه می‌داند. با نشانی‌های وب نوع تماس تماس نگیرید.
value

string (bytes format)

سریال‌سازی Protobuf از نوع شرح‌داده‌شده توسط type_url را نگه می‌دارد.

رشته کدبندی‌شده با Base64.

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

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

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

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

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