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 تطابق ۱:۱ داشته باشد. اگر نشانی وب حل نشود، در نمایه مربوطه در فهرست entities، پیام Entity خالی (بدون تنظیم فیلد) ایجاد می‌شود.
  • برای شناسایی اینکه کدام نمایه نشانی وب خاص ناموفق بوده است، باید فیلد نقشه failed_requests را در پاسخ بررسی کنید. کلید failed_requests نشان‌دهنده نمایه مبتنی بر صفر نشانی وب ناموفق در درخواست است. فرض نکنید که کل تماس دسته‌ای به‌دلیل یک خرابی جزئی ناموفق بوده است.

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

درخواست 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" حاوی شناسه منبع یکسانی است که نوع را شناسایی می‌کند. مثال: { "id": 1234, "@type": "types.example.com/standard/id" }.

همه

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

string

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

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

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

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

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

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

string (bytes format)

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

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

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

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

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

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

راهنمایی مخرب: ❌ | راهنمایی خودتوان: ❌ | راهنمایی فقط خواندنی: ✅ | راهنمایی جهان باز: ❌