MCP Tools Reference: mapstools.googleapis.com

Инструмент: resolve_names

Преобразует пакетный список запросов на определение местоположения (названия достопримечательностей или точные адреса) в канонические идентификаторы мест Google Maps.

Требования к входным данным (КРИТИЧЕСКИ ВАЖНЫ):

  1. queries (массив объектов - ОБЯЗАТЕЛЬНО): Список запросов местоположения для обработки. Вы можете указать до 20 запросов.

    • Каждый объект запроса должен содержать:
      • text (строка - ОБЯЗАТЕЛЬНО): текстовый запрос, представляющий конкретное название места или адрес для обработки.
        • Примеры: 'Googleplex, Mountain View, CA' , '1600 Amphitheatre Pkwy, Mountain View, CA' , 'Eiffel Tower, Paris' .

  2. location_bias (object - OPTIONAL): Используйте это для определения приоритета результатов, полученных вблизи определенной географической области.

    • Формат: {"viewport": {"low": {"latitude": [value], "longitude": [value]}, "high": {"latitude": [value], "longitude": [value]}}}

  3. region_code (строка - НЕОБЯЗАТЕЛЬНО): Код региона Unicode CLDR (двухбуквенный код страны, например, US , CA ) пользователя, который будет использоваться для корректировки результатов.

Инструкции по вызову специалиста:

  • Специфичность (КРИТИЧЕСКИ ВАЖНО): Запросы должны содержать конкретное название места или адрес. Общие запросы, такие как 'restaurants' или названия сетей, например 'Starbucks' не поддерживаются.
  • НЕ вызывайте этот инструмент, если инструменты, которые вы планируете использовать, уже принимают напрямую необработанные строки адресов или имен мест.

Обработка ошибок (КРИТИЧЕСКИ ВАЖНО):

  • Это инструмент пакетной обработки. Запрос может возвращать «смешанные результаты» (например, некоторые запросы выполняются успешно, а другие завершаются с ошибкой).
  • Гарантируется, что выходной список results будет соответствовать индексам входных queries в соотношении 1:1. В случае неудачного запроса в соответствующем индексе списка results будет отображаться пустое сообщение Result ( entity не задана).
  • Необходимо проверить поле карты failed_requests в ответе, чтобы определить, какой именно индекс запроса не сработал. Ключ поля failed_requests представляет собой индекс (начиная с 0) неудачного запроса в запросе. Не следует предполагать, что весь пакетный вызов завершился неудачей из-за частичной ошибки.

В следующем примере показано, как использовать 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 tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Схема ввода

Запрос сообщения для ResolveNames.

ResolveNamesRequest

JSON-представление 
{
  "queries": [
    {
      object (LocationQuery)
    }
  ],
  "locationBias": {
    object (LocationBias)
  },
  "regionCode": string
}
Поля
queries[]

object ( LocationQuery )

Обязательно. Список запросов местоположения, которые необходимо обработать. Вы можете указать до 20 запросов.

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, Маунтин-Вью, Калифорния", "1600 Amphitheatre Parkway, Маунтин-Вью, Калифорния" или "Эйфелева башня, Париж". Запросы должны содержать конкретный адрес или название места. Общие местоположения, такие как название сети (например, 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)
    },
    ...
  }
}
Поля
results[]

object ( Result )

Только вывод. Список разрешенных сущностей из запросов местоположения. Гарантированное соответствие 1:1 с индексами queries . Пустая строка в индексе i указывает на неудачную попытку разрешения для данного запроса. Если разрешение не удалось, проверьте поле failed_requests для получения информации о статусе ошибки.

failedRequests

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

Только вывод. Карта, отображающая частичные сбои. Ключом является индекс неудачного запроса в поле queries . Значением является статус ошибки, подробно описывающий причину сбоя разрешения.

Объект, содержащий список пар "key": value . Пример: { "name": "wrench", "mass": "1.3kg", "count": "3" } .

Результат

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

Список сообщений, содержащих подробную информацию об ошибке. Существует общий набор типов сообщений, используемых 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 с дополнительным ограничением (для текстового формата): содержимое ссылки должно состоять только из буквенно-цифровых символов, экранированных символов в процентном кодировании и символов из следующего набора (за исключением внешних обратных кавычек): /-.~_!$&()*+,;= . Несмотря на то, что мы допускаем использование процентного кодирования, реализациям не следует деэкранировать его, чтобы избежать путаницы с существующими парсерами. Например, type.googleapis.com%2FFoo следует отклонить.

В первоначальном проекте Any рассматривалась возможность запуска службы разрешения типов по этим URL-адресам типов, но Protobuf так и не реализовал её и считает обращение к этим URL-адресам проблематичным и потенциально опасным. Не пытайтесь обращаться к URL-адресам типов.

value

string ( bytes format)

Содержит сериализацию Protobuf типа, описываемого параметром type_url.

Строка, закодированная в формате Base64.

Уверенность

Уровень уверенности в принятой резолюции.

Перечисления
CONFIDENCE_UNSPECIFIED Значение по умолчанию. Это значение не используется.
MEDIUM Средний уровень достоверности указывает на то, что решение, вероятно, верное, но могут быть и другие варианты.
HIGH Высокая степень достоверности указывает на то, что разрешение корректно и соответствует конкретному географическому объекту (например, конкретному месту).

Аннотации инструментов

Подсказка о разрушительном эффекте: ❌ | Подсказка об идемпотентности: ❌ | Подсказка только для чтения: ✅ | Подсказка об открытом мире: ❌