MCP Tools Reference: mapstools.googleapis.com

ابزار: resolve_names

فهرست دسته‌ای از پُرسمان‌های مکان خاص (نام نشانگرهای مکانی یا نشانی‌های دقیق) را به «شناسه‌های جا» در Google Maps متعارف تبدیل می‌کند.

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

  1. queries (آرایه اشیاء - اجباری): فهرستی از پرسمان‌های مکان برای حل کردن. می‌توانید حداکثر ۲۰ پُرسمان مشخص کنید.

    • هر شیء پُرسمان باید دارای موارد زیر باشد:
      • text (رشته - اجباری): پُرسمان نوشتاری که نشان‌دهنده نام یا نشانی مکان خاصی برای حل‌وفصل است.
        • نمونه‌ها: 'Googleplex, Mountain View, CA'، '1600 Amphitheatre Pkwy, Mountain View, CA'، 'Eiffel Tower, Paris'.

  2. location_bias (شیء - اختیاری): از این مورد برای اولویت‌بندی نتایج نزدیک به یک منطقه جغرافیایی خاص استفاده کنید.

    • قالب: {"viewport": {"low": {"latitude": [value], "longitude": [value]}, "high": {"latitude": [value], "longitude": [value]}}}

  3. ‫region_code (رشته - اختیاری): کد منطقه Unicode CLDR (کد کشور دوحرفی، مثلاً US، CA) کاربر برای سوگیری نتایج.

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

  • خاص بودن (بسیار مهم): پُرسمان‌ها باید نام یا نشانی مکان خاصی را نشان دهند. جستجوهای عمومی مانند 'restaurants' یا نام‌های زنجیره‌ای مانند 'Starbucks' پشتیبانی نمی‌شوند.
  • اگر ابزارهای پایین‌دستی که قصد دارید فراخوانی کنید ازقبل رشته‌های نشانی یا نام مکان خام را مستقیماً می‌پذیرند، این ابزار را فراخوانی نکنید.

ذخیره در Google Maps:

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

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

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

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

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

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

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

ResolveNamesRequest

نمایش JSON 
{
  "queries": [
    {
      object (LocationQuery)
    }
  ],
  "locationBias": {
    object (LocationBias)
  },
  "regionCode": string
}
فیلدها
queries[]

object (LocationQuery)

الزامی. فهرستی از پرسمان‌های مکان که باید حل شوند. می‌توانید حداکثر ۲۰ پُرسمان مشخص کنید.
locationBias

object (LocationBias)

اختیاری. منطقه‌ای اختیاری برای سوگیری نتایج وضوح. اگر مشخص شود، نتایج وضوح به سمت نهادهایی که به این منطقه نزدیک‌تر هستند سوگیری خواهد داشت. گنجاندن location_bias یا region_code اغلب با محدود کردن فضای جستجو نتایج بهتری ارائه می‌دهد.

اگر هم location_bias و هم region_code مشخص شده باشد، location_bias بر region_code اولویت دارد.
regionCode

string

اختیاری. کد منطقه اختیاری برای سوگیری نتایج وضوح. اگر مشخص شود، نتایج وضوح به سمت نهادهایی که در منطقه مشخص‌شده یا نزدیک آن هستند متمایل خواهد شد. این باید کد منطقه CLDR باشد. برای مثال، «US» یا «CA». گنجاندن location_bias یا region_code اغلب با محدود کردن فضای جستجو نتایج بهتری ارائه می‌دهد.

اگر هم location_bias و هم region_code مشخص شده باشد، location_bias بر region_code اولویت دارد.

LocationQuery

نمایش JSON 
{
  "text": string
}
فیلدها
text

string

الزامی. پُرسمان نوشتاری برای حل کردن یک موجودیت جغرافیایی خاص در Google Maps، مانند یک مکان یا نشانی. هرچه پُرسمان دقیق‌تر باشد، وضوح دقیق‌تر است. برای مثال، «San Francisco»،‏ «Googleplex, Mountain View, CA»،‏ «1600 Amphitheatre Parkway, Mountain View, CA»، یا «Eiffel Tower, Paris». پرس‌وجوها باید نشانی یا نام مکان خاصی باشد. مکان‌های کلی مانند نام زنجیره (مثلاً Starbucks) یا پُرسمان جستجویی مانند «رستوران‌ها» پشتیبانی نمی‌شوند.

LocationBias

نمایش JSON 
{

  // Union field type can be only one of the following:
  "viewport": {
    object (Viewport)
  }
  // End of list of possible types for union field type.
}
فیلدها
فیلد اتحادیه type. نوع سوگیری مکان. type فقط می‌تواند یکی از موارد زیر باشد:
viewport

object (Viewport)

ناحیه نمایشی که با چارگوش محصورکننده تعریف شده است.

ناحیه نمایش

نمایش JSON 
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
فیلدها
low

object (LatLng)

الزامی. نقطه پایین نمای دید.
high

object (LatLng)

الزامی. نقطه بالای ناحیه نمایش.

LatLng

نمایش JSON 
{
  "latitude": number,
  "longitude": number
}
فیلدها
latitude

number

عرض جغرافیایی به درجه. باید در محدوده [-90.0, +90.0] باشد.
longitude

number

طول جغرافیایی برحسب درجه. باید در محدوده [-180.0, +180.0] باشد.

طرح خروجی

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

ResolveNamesResponse

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

object (Result)

فقط خروجی. فهرست نهادهای حل‌شده از پُرسمان‌های مکان. تضمین می‌شود که با نمایه‌های queries درخواست، نگاشت ۱:۱ داشته باشد. رشته خالی در نمایه i نشان می‌دهد که تفکیک برای آن پُرسمان ناموفق بود. اگر حل‌وفصل ناموفق بود، لطفاً فیلد failed_requests را برای وضعیت خطا بررسی کنید.
failedRequests

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

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

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

string

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

نتیجه

نمایش JSON 
{
  "entity": {
    object (Entity)
  },
  "confidence": enum (Confidence)
}
فیلدها
entity

object (Entity)

فقط خروجی. نهاد حل‌شده از پُرسمان مکان.
confidence

enum (Confidence)

فقط خروجی. سطح اطمینان برای وضوح.

نهاد

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

اطمینان

سطح اطمینان برای وضوح.

شمارشی‌ها
CONFIDENCE_UNSPECIFIED مقدار پیش‌فرض. از این مقدار استفاده نشده است.
MEDIUM اطمینان متوسط نشان می‌دهد که وضوح احتمالاً درست است اما ممکن است گزینه‌های دیگری نیز وجود داشته باشد.
HIGH اطمینان بالا نشان می‌دهد که وضوح صحیح است و نشان‌دهنده یک نهاد جغرافیایی خاص (مثلاً یک مکان خاص) است.

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

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

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

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

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