MCP Tools Reference: mapstools.googleapis.com

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

Преобразует список URL Google Карт в канонические идентификаторы мест Google Карт.

Когда вызывать этот инструмент (ВАЖНО):

  • Используйте этот инструмент, когда пользователь предоставляет одну или несколько ссылок или URL-адресов Google Карт (например, https://maps.app.goo.gl/…), ('https://www.google.com/maps/place/...' или 'https://maps.google.com/...'), и вам нужно извлечь канонические идентификаторы мест.
  • В одном пакетном запросе можно указать до 20 URL.

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

  • urls (массив строк, ОБЯЗАТЕЛЬНО). Список URL Google Карт, которые нужно преобразовать. Каждый URL должен быть действительным и указывать на одно место в Google Картах.

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

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

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

  • Это инструмент пакетной обработки. Запрос может возвращать смешанные результаты (например, некоторые URL разрешаются успешно, а другие – нет).
  • Выходной список entities гарантированно сопоставляется 1:1 с входными индексами urls. Если URL не удастся обработать, в списке entities появится пустое сообщение Entity (без полей).
  • Вы ДОЛЖНЫ проверить поле карты failed_requests в ответе, чтобы определить, какой именно индекс URL не удалось обработать. Ключ failed_requests представляет собой индекс URL, который не удалось обработать, в запросе (начиная с нуля). Не считайте, что весь пакетный вызов завершился ошибкой, если она произошла только в некоторых случаях.

В примере кода ниже показано, как использовать curl для вызова инструмента MCP resolve_maps_urls.

Запрос 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_maps_urls",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Схема ввода

Сообщение запроса для ResolveMapsUrls.

ResolveMapsUrlsRequest

JSON-представление 
{
  "urls": [
    string
  ]
}
Поля
urls[]

string

Обязательно. URL Google Карт, которые нужно преобразовать. Каждый URL должен быть действительным URL Google Карт, например https://maps.app.goo.gl/..., https://www.google.com/maps/place/... или https://maps.google.com/.... В настоящее время поддерживаются только URL, указывающие на одно место. Можно указать до 20 URL.

Схема вывода

Ответ на запрос ResolveMapsUrls.

ResolveMapsUrlsResponse

JSON-представление 
{
  "entities": [
    {
      object (Entity)
    }
  ],
  "failedRequests": {
    integer: {
      object (Status)
    },
    ...
  },
  "saveToMapsUrl": string
}
Поля
entities[]

object (Entity)

Только для вывода. Список объектов, полученных из URL Google Карт. Гарантируется сопоставление 1:1 с индексами urls запроса. Пустое сообщение с индексом i (где не задано значение entity) указывает на то, что для этого URL не удалось выполнить разрешение. Если преобразование не удалось, проверьте поле failed_requests, чтобы узнать статус ошибки.
failedRequests

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

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

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

string

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

Объект

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.

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

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

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

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

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