MCP Tools Reference: chatmcp.googleapis.com

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

Поиск чатов Google Chat (чат-групп с названием, прямых переписок или групповых чатов) по отображаемому названию или участникам для поиска идентификаторов чатов.

Этот инструмент выполняет поиск по метаданным чата, а не по содержимому сообщений. Чтобы выполнить поиск по истории переписки или найти сообщения по ключевому слову, отправителю или временной метке, используйте search_messages.

Если указаны только participants, этот инструмент находит прямые переписки (если указан один участник) или групповые чаты (если указано несколько участников), в которых участвуют указанные пользователи и пользователь, вызывающий инструмент.

Если указано только значение query, инструмент ищет чаты, в которых запрос является подстрокой отображаемого названия чата без учета регистра.

Если указаны оба параметра (participants и query), инструмент находит чаты по участникам, а затем фильтрует их по отображаемому названию.

Если не указаны ни participants, ни query, инструмент перечисляет все чаты, в которых состоит пользователь.

Этот инструмент показывает только чаты, в которых участвует пользователь, выполняющий вызов.

Возвращает список объектов чатов, содержащих идентификаторы чатов (формат: spaces/{space}), отображаемые названия и типы чатов.

ВАЖНО! Пустой список conversations не означает, что результатов больше нет. Если присутствует next_page_token, можно получить больше страниц. Если список пуст, но есть next_page_token, спросите пользователя, нужно ли продолжить поиск.

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

Запрос cURL 
curl --location 'https://chatmcp.googleapis.com/mcp/v1' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "search_conversations",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Схема ввода

SearchConversationsRequest

JSON-представление 
{
  "spaceNameQuery": string,
  "pageSize": integer,
  "pageToken": string,
  "participants": [
    string
  ]
}
Поля
spaceNameQuery

string

Необязательное поле. Текст для поиска в отображаемых названиях чат-групп (совпадение подстроки без учета регистра).
pageSize

integer

Необязательное поле. Максимальное количество чат-групп, которые нужно вернуть. Сервис может вернуть меньше результатов, чем указано в этом значении. Если значение не указано, будет возвращено не более 20 чат-групп. Максимальное значение – 1000. Если указать большее значение, оно будет автоматически уменьшено до 1000.
pageToken

string

Необязательное поле. Токен страницы, полученный из предыдущего вызова search_conversations. Укажите его, чтобы получить следующую страницу.
participants[]

string

Необязательное поле. Список адресов электронной почты участников, по которым нужно отфильтровать чаты, за исключением вызывающего абонента.

Схема вывода

Ответ, содержащий список подходящих чатов.

SearchConversationsResponse

JSON-представление 
{
  "conversations": [
    {
      object (Conversation)
    }
  ],
  "nextPageToken": string
}
Поля
conversations[]

object (Conversation)

Список объектов чата, соответствующих критериям поиска. Каждый чат включает conversation_id (формат: spaces/{space}), display_name, conversation_type и last_active_timestamp.
nextPageToken

string

Токен, который можно отправить как page_token, чтобы получить следующую страницу. Если это поле отсутствует, значит последующих страниц нет.

Заполняется, только если запрос отфильтрован по participants.

Чат

JSON-представление 
{
  "conversationId": string,
  "displayName": string,
  "conversationType": enum (ConversationType),
  "lastActiveTimestamp": string
}
Поля
conversationId

string

Идентификатор чата (например, "spaces/AAAAAAAAA").
displayName

string

Отображаемое название чата. Для именованных чат-групп это название группы. Для прямой переписки это имя другого участника. Для групповых чатов без названия это сгенерированное название на основе имен участников.
conversationType

enum (ConversationType)

Тип чата (DIRECT_MESSAGE, GROUP_CHAT или NAMED_SPACE).
lastActiveTimestamp

string (Timestamp format)

Время последнего действия в чате в формате ISO 8601.

Используется формат RFC 3339. Результат всегда будет Z-нормализованным, и в нем будут использоваться цифры дробных частей 0, 3, 6 или 9. Допустимы и другие типы нормализации. Примеры: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" или "2014-10-02T15:01:23+05:30".

Временная метка

JSON-представление 
{
  "seconds": string,
  "nanos": integer
}
Поля
seconds

string (int64 format)

Представляет секунды времени UTC с начала эпохи Unix (1970-01-01T00:00:00Z). Значение должно быть в диапазоне от -62135596800 до 253402300799 включительно (что соответствует периоду с 0001-01-01T00:00:00Z до 9999-12-31T23:59:59Z).
nanos

integer

Доля секунды в наносекундах. Это поле содержит наносекундную часть длительности, а не альтернативу секундам. Свойство может принимать только неотрицательное целочисленное значение, даже если значение временной отметки в секундах является отрицательным. Значение должно быть в диапазоне от 0 до 999 999 999 включительно.

ConversationType

Определяет тип разговора.

Перечисления
CONVERSATION_TYPE_UNSPECIFIED Не указано.
NAMED_SPACE Именованная чат-группа.
GROUP_CHAT Групповой чат с тремя или более пользователями.
DIRECT_MESSAGE Прямая переписка между двумя людьми или между человеком и приложением Chat.

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

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

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

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

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

Области авторизации

Требует одной из следующих областей применения OAuth:

  • https://www.googleapis.com/auth/chat.memberships.readonly
  • https://www.googleapis.com/auth/chat.spaces
  • https://www.googleapis.com/auth/chat.spaces.readonly