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 . Укажите его, чтобы получить следующую страницу.

Параметры поиска

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

Необязательно. Фильтрация по списку названий пространств; отображаемые названия пространств совпадут частично. Примечание: возвращаются только 5 лучших совпадений.

conversationTypes[]

enum ( ConversationType )

Необязательно. Фильтруйте по типу разговора.

ConversationType

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

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

Схема вывода

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

SearchMessagesResponse

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

object ( ChatMessage )

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

nextPageToken

string

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

Сообщение в чате

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

string

Имя ресурса сообщения. Формат: пробелы/{пробел}/сообщения/{сообщение}

threadId

string

Ветка обсуждения, к которой относится это сообщение. Если сообщение не относится к какой-либо ветке, это поле будет пустым. Формат: пробелы/{пробел}/ветки/{ветка}

plaintextBody

string

Текст сообщения, оформленный в формате Markdown.

sender

object ( User )

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

createTime

string

Только вывод. Отметка времени создания сообщения.

threadedReply

boolean

Является ли сообщение ответом на сообщение в ветке обсуждения.

attachments[]

object ( ChatAttachmentMetadata )

Приложения, вложенные в сообщение.

reactionSummaries[]

object ( ReactionSummary )

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

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

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

string

Имя ресурса пользователя чата. Формат: users/{user}.

displayName

string

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

email

string

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

userType

enum ( UserType )

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

Метаданные вложения чата

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

string

Имя ресурса вложения. Формат: пробелы/{пробел}/сообщения/{сообщение}/вложения/{вложение}.

filename

string

Название вложенного файла.

mimeType

string

Тип содержимого (MIME-тип).

source

enum ( Source )

Источник вложения.

РеакцияКраткое содержание

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

string

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

count

integer

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

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

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

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

Источник

Источник вложения.

Перечисления
SOURCE_UNSPECIFIED Сдержанный.
DRIVE_FILE Это файл из Google Диска.
UPLOADED_CONTENT Файл загружен в чат.

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

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

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

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

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

Области полномочий

Требуется один из следующих диапазонов аутентификации 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