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 должен быть действительным URL Google Карт, ведущим на одну страницу.

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

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

Обработка ошибок (КРИТИЧНО)

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

В приведенном ниже фрагменте кода показано, как использовать curl для вызова инструмента resolve_maps_urls 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_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 Карт. Гарантированно соответствует запросу 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: ❌