MCP Tools Reference: mapstools.googleapis.com

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

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

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

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

    • Каждый объект запроса должен содержать:
      • 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 (строка, необязательный). Код региона CLDR Unicode (двухбуквенный код страны, например US, CA) пользователя, для которого нужно уточнить результаты.

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

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

Сохранить в Google Картах

  • Ответ содержит поле save_to_maps_url – одну ссылку на Google Карты, содержащую все успешно распознанные места.
  • Когда пользователь захочет сохранить, отправить или открыть найденные места в виде списка в Google Картах, покажите ему эту ссылку. Не создавайте эту ссылку самостоятельно.

Обработка ошибок (КРИТИЧЕСКИЙ ПРИОРИТЕТ)

  • Это инструмент пакетной обработки. Запрос может возвращать смешанные результаты (например, некоторые запросы выполняются успешно, а другие – нет).
  • Выходной список results гарантированно сопоставляется 1:1 с входными индексами queries. Если запрос не удастся выполнить, то в списке results по соответствующему индексу будет возвращено пустое сообщение Result (без entity).
  • Вы ОБЯЗАНЫ проверить поле карты 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)

Обязательно. Список запросов местоположения, которые нужно обработать. Можно указать до 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 Картах, например местом или адресом. Чем точнее запрос, тем точнее будет ответ. Например, "Сан-Франциско", "Googleplex, Маунтин-Вью, Калифорния", "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

Градусная мера широты. Должна попадать в диапазон [-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)

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

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

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

Объект содержит список из нескольких пар ("key": value). Пример: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
saveToMapsUrl

string

Только для вывода. ссылка для сохранения всех успешно распознанных объектов в Google Картах.

Результат

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 Высокая степень уверенности означает, что сопоставление выполнено правильно и представляет определенный геопространственный объект (например, конкретное место).

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

Аннотации инструментов отправляются клиентам MCP, чтобы описать базовый риск, связанный с определенным инструментом. Большинство клиентов считают эти подсказки ненадежными, но их можно использовать, чтобы решить, когда пользователю может быть отправлен запрос на подтверждение.

Помимо строки заголовка, определены следующие логические подсказки:

  • readOnlyHint: если задано значение true, инструмент не изменяет свою среду. Значение по умолчанию – false.
  • destructiveHint: если задано значение True, инструмент может выполнять деструктивные действия. Если задано значение false, инструмент может выполнять только действия по добавлению. Значение по умолчанию: true.
  • idempotentHint. Если задано значение True, повторный вызов инструмента с теми же аргументами не будет иметь дополнительного эффекта в его среде. Значение по умолчанию – false.
  • openWorldHint: если задано значение true, инструмент может взаимодействовать с открытым миром внешних объектов. Если false, то инструмент может взаимодействовать только с внутренними объектами. Например, инструмент веб-поиска будет открытым миром, а инструмент памяти – нет.

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