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 (object - اختیاری): از این برای اولویت‌بندی نتایج نزدیک به یک منطقه جغرافیایی خاص استفاده کنید.

    • قالب: {"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 برای فراخوانی ابزار resolve_names 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_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، مثل مکان یا نشانی. هرچه پُرسمان دقیق‌تر باشد، راه‌حل دقیق‌تر خواهد بود. برای مثال، «تهران»، «Googleplex, Mountain View, CA»، «1600 Amphitheatre Parkway, Mountain View, CA»، یا «برج ایفل، پاریس». پُرسمان‌ها باید نام مکان یا نشانی خاصی باشد. مکان‌های کلی مانند نام زنجیره (مثلاً 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

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

number

طول جغرافیایی به درجه. باید در محدوده [-۱۸۰.۰، +۱۸۰.۰] باشد.

طرح‌واره برونداد

پیام پاسخ برای 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" حاوی شناسه منبع یکسانی است که نوع را شناسایی می‌کند. مثال: { "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.

اطمینان

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

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

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

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

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

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

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