MCP Tools Reference: mapstools.googleapis.com

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

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

Когда следует запускать этот инструмент (КРИТИЧНО):

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

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

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

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

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

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

Схема ввода

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

ResolveMapsUrlsRequest

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

string

Обязательно. URL-адреса Google Maps, которые необходимо разрешить. Каждый URL-адрес должен быть действительным URL-адресом Google Maps, например, 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)
    },
    ...
  }
}
Поля
entities[]

object ( Entity )

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

failedRequests

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

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

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

Сущность

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.

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

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