MCP Tools Reference: mapstools.googleapis.com

ابزار: resolve_maps_urls

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

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

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

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

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

مدیریت خطا (بحرانی):

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

نمونه زیر نحوه استفاده از curl برای فراخوانی ابزار resolve_maps_urls 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": "resolve_maps_urls",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

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

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

درخواست ResolveMapsUrls

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

string

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

طرحواره خروجی

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

ResolveMapsUrlsپاسخ

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

object ( Entity )

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

failedRequests

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

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

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

نهاد

نمایش JSON 
{

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

string

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

ورود درخواست‌های ناموفق

نمایش 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

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

یک شیء حاوی فیلدهایی از نوع دلخواه. یک فیلد اضافی "@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 های حاوی آن به هیچ درخواستی پاسخ دهند.

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

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

value

string ( bytes format)

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

یک رشته کدگذاری شده با base64.

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

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