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 (строка – НЕОБЯЗАТЕЛЬНО). Код региона Unicode CLDR (двухбуквенный код страны, например US или CA) пользователя, чтобы сместить результаты.

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

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

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

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

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

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

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

Используется только для вывода. Список распознанных объектов из запросов местоположения. Гарантированно соответствует индексам запроса 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: ❌