MCP Tools Reference: chatmcp.googleapis.com

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

Ищет сообщения Google Chat по ключевым словам и фильтрам и возвращает их в формате Markdown. Работает во всех чат-группах, к которым у пользователя есть доступ, или в определенном чате.

Вот несколько советов, которые помогут вам решить, когда использовать search_messages, а когда – другие инструменты для поиска и чтения:

  • Используйте search_messages, чтобы найти определенный контент, ключевые слова, упоминания, ссылки, отправителей или непрочитанные сообщения в нескольких чат-группах или без известного идентификатора чата.
  • Используйте list_messages, если вы знаете идентификатор чат-группы или цепочки и хотите прочитать сообщения в хронологическом порядке.
  • Используйте search_conversations, чтобы найти метаданные чат-группы, например идентификаторы чатов, по отображаемому названию чат-группы или участникам (поиск выполняется только по метаданным, а не по содержимому сообщений).

Если searchParameters используется без фильтров, возвращаются недавние сообщения из всех чатов, доступных пользователю.

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

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

Схема ввода

SearchMessagesRequest

JSON-представление 
{
  "searchParameters": {
    object (SearchParameters)
  },
  "pageSize": integer,
  "pageToken": string
}
Поля
searchParameters

object (SearchParameters)

Обязательно. Параметры, которые будут использоваться для поиска.
pageSize

integer

Необязательное поле. Максимальное количество результатов, которые нужно вернуть (не более 100). Если значение не указано, возвращается не более 25 результатов.
pageToken

string

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

SearchParameters

JSON-представление 
{
  "keywords": [
    string
  ],
  "conversationId": string,
  "sender": string,
  "isUnread": boolean,
  "hasLink": boolean,
  "startTime": string,
  "endTime": string,
  "mentionsMe": boolean,
  "conversationIncludesUser": string,
  "spaceDisplayNames": [
    string
  ],
  "conversationTypes": [
    enum (ConversationType)
  ],
  "hasAttachment": boolean
}
Поля
keywords[]

string

Необязательное поле. Набор ключевых слов, которые используются для фильтрации результатов.
conversationId

string

Необязательное поле. Ограничивает поиск определенным идентификатором чата, возвращенным инструментом search_conversations. Формат: spaces/{ID}.
sender

string

Необязательное поле. Фильтрация сообщений от определенного пользователя. Можно использовать адрес электронной почты или название ресурса отправителя. Названия ресурсов пользователей имеют формат users/{ID}, где {ID} – это идентификатор пользователя или его адрес электронной почты.
isUnread

boolean

Необязательное поле. Фильтр для сообщений, которые не были прочитаны пользователем, выполняющим вызов.
hasLink

boolean

Необязательное поле. Фильтр для сообщений, содержащих хотя бы один URL.
startTime

string

Необязательное поле. Фильтр для сообщений, созданных после этого времени. Формат: временная метка ISO 8601.
endTime

string

Необязательное поле. Фильтр для сообщений, созданных до этого времени. Формат: временная метка ISO 8601.
mentionsMe

boolean

Необязательное поле. Фильтр для сообщений, в которых явно упоминается вызывающий пользователь.
conversationIncludesUser

string

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

string

Необязательное поле. Фильтрация по списку названий чат-групп. Отображаемые названия чат-групп сопоставляются частично. Примечание. Возвращаются только первые пять совпадений.
conversationTypes[]

enum (ConversationType)

Необязательное поле. Фильтр по типу чата.
hasAttachment

boolean

Необязательное поле. Фильтр для сообщений, содержащих хотя бы один прикрепленный файл. Примечание. Это поле находится в разработке и может поддерживаться не во всех средах.

ConversationType

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

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

Схема вывода

Ответ на поиск сообщений Google Chat. Если next_page_token заполнен, можно снова вызвать SearchMessages с этим токеном, чтобы получить следующую страницу результатов.

SearchMessagesResponse

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

object (ChatMessage)

Список объектов сообщений, соответствующих критериям поиска.
nextPageToken

string

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

ChatMessage

JSON-представление 
{
  "messageId": string,
  "threadId": string,
  "plaintextBody": string,
  "sender": {
    object (User)
  },
  "createTime": string,
  "threadedReply": boolean,
  "attachments": [
    {
      object (ChatAttachmentMetadata)
    }
  ],
  "reactionSummaries": [
    {
      object (ReactionSummary)
    }
  ],
  "quotedMessageMetadata": {
    object (QuotedMessageMetadata)
  }
}
Поля
messageId

string

Название ресурса сообщения. Формат: spaces/{space}/messages/{message}
threadId

string

Цепочка, к которой относится это сообщение. Если сообщение не входит в цепочку, это поле будет пустым. Формат: spaces/{space}/threads/{thread}
plaintextBody

string

Текст сообщения с форматированием Markdown.
sender

object (User)

Отправитель сообщения.
createTime

string

Только для вывода. Временная метка создания сообщения. Формат: временная метка ISO 8601.
threadedReply

boolean

Является ли сообщение ответом в цепочке.
attachments[]

object (ChatAttachmentMetadata)

Файлы, прикрепленные к письму.
reactionSummaries[]

object (ReactionSummary)

Сводка реакций с эмодзи, включенная в сообщение.
quotedMessageMetadata

object (QuotedMessageMetadata)

Только для вывода. Информация об исходном письме, которое цитируется или пересылается в этом письме. Примечание. Это поле находится на стадии разработки и может быть доступно не во всех средах.

Пользователь

JSON-представление 
{
  "userId": string,
  "displayName": string,
  "email": string,
  "userType": enum (UserType)
}
Поля
userId

string

Название ресурса пользователя Chat. Формат: users/{user}.
displayName

string

Отображаемое имя пользователя Chat.
email

string

Адрес электронной почты пользователя. Это поле заполняется, только если тип пользователя – HUMAN.
userType

enum (UserType)

Тип пользователя.

ChatAttachmentMetadata

JSON-представление 
{
  "attachmentId": string,
  "filename": string,
  "mimeType": string,
  "source": enum (Source),
  "driveFileId": string
}
Поля
attachmentId

string

Название ресурса прикрепленного файла. Формат: spaces/{space}/messages/{message}/attachments/{attachment}.
filename

string

Название прикрепленного файла.
mimeType

string

Тип контента (MIME-тип).
source

enum (Source)

Источник прикрепленного файла.
driveFileId

string

Только для вывода. Идентификатор файла на Google Диске. Заполняется, только если источником является DRIVE_FILE. Используйте с MCP Google Диска.

ReactionSummary

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

string

Строка Unicode для эмодзи или название пользовательского эмодзи.
count

integer

Общее количество реакций с использованием связанного эмодзи.

QuotedMessageMetadata

JSON-представление 
{
  "messageId": string,
  "lastUpdateTime": string,
  "quoteType": enum (QuoteType),
  "plaintextBody": string,
  "sender": string,
  "attachments": [
    {
      object (ChatAttachmentMetadata)
    }
  ],
  "forwardedMetadata": {
    object (ForwardedMetadata)
  }
}
Поля
messageId

string

Только для вывода. Название ресурса исходного сообщения, которое цитируется или пересылается. Формат: spaces/{space}/messages/{message}
lastUpdateTime

string

Только для вывода. Временная метка создания или последнего обновления исходного сообщения до того, как оно было процитировано или переслано. Формат: временная метка ISO 8601.
quoteType

enum (QuoteType)

Только для вывода. Тип цитаты.
plaintextBody

string

Только для вывода. Снимок текстового тела исходного сообщения на момент цитирования или пересылки. Форматирование с помощью Markdown для FORWARD и обычного текста для REPLY.
sender

string

Только для вывода. Отображаемое имя автора исходного сообщения.
attachments[]

object (ChatAttachmentMetadata)

Только для вывода. Прикрепленные файлы, которые были частью исходного сообщения. Заполняется только для типа цены FORWARD.
forwardedMetadata

object (ForwardedMetadata)

Только для вывода. Метаданные об исходном чате пересланного сообщения. Заполняется только для типа цены FORWARD.

ForwardedMetadata

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

string

Только для вывода. Название ресурса исходного чата. Формат: spaces/{space}
conversationDisplayName

string

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

UserType

Тип пользователя Google Chat.

Перечисления
USER_TYPE_UNSPECIFIED Не указано.
HUMAN Пользователь-человек.
APP Пользователь приложения.

Источник

Источник прикрепленного файла.

Перечисления
SOURCE_UNSPECIFIED Зарезервировано.
DRIVE_FILE Файл хранится на Google Диске.
UPLOADED_CONTENT Файл загружен в Chat.

QuoteType

Тип цитаты, указывающий, является ли сообщение ответом с цитатой или пересланным сообщением.

Перечисления
QUOTE_TYPE_UNSPECIFIED Зарезервировано. Неопределенный тип цитаты.
REPLY Сообщение является ответом с цитированием на исходное сообщение в той же цепочке.
FORWARD Сообщение переслано из другого чата или из другой цепочки в том же чате.

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

Аннотации инструментов отправляются клиентам 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.messages.readonly
  • https://www.googleapis.com/auth/chat.spaces.readonly
  • https://www.googleapis.com/auth/chat.memberships.readonly
  • https://www.googleapis.com/auth/chat.users.readstate.readonly