MCP Tools Reference: chatmcp.googleapis.com

Ferramenta: search_messages

Pesquisa mensagens de chat do Google Chat usando palavras-chave e filtros, retornando-as no formato Markdown. Funciona em todos os espaços que o usuário pode acessar ou pode ser limitado a uma conversa específica.

Siga estas orientações ao decidir usar o search_messages em vez de outras ferramentas de pesquisa ou leitura:

  • Use search_messages ao procurar conteúdo de mensagens específico, palavras-chave, menções, links, remetentes ou mensagens não lidas em vários espaços ou sem um ID de conversa conhecido.
  • Use list_messages quando souber o ID específico do espaço ou da conversa e quiser ler as mensagens em ordem cronológica.
  • Use search_conversations para encontrar metadados de espaços, como IDs de conversas, por nome de exibição do espaço ou participantes (ele pesquisa apenas metadados, não o conteúdo das mensagens).

Se searchParameters for fornecido sem filtros específicos, as mensagens recentes de todas as conversas acessíveis ao usuário serão retornadas.

O exemplo de código abaixo mostra como usar curl para chamar a ferramenta MCP search_messages.

Solicitação 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
}'

Esquema de entrada

SearchMessagesRequest

Representação JSON 
{
  "searchParameters": {
    object (SearchParameters)
  },
  "pageSize": integer,
  "pageToken": string
}
Campos
searchParameters

object (SearchParameters)

Obrigatório. Os parâmetros de pesquisa a serem usados.
pageSize

integer

Opcional. O número máximo de resultados a serem retornados (até 100). Se não for especificado, no máximo 25 serão retornados.
pageToken

string

Opcional. Um token de página recebido de uma chamada search_messages anterior. Forneça isso para recuperar a página subsequente.

SearchParameters

Representação 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
}
Campos
keywords[]

string

Opcional. Um conjunto de palavras-chave usadas para filtrar os resultados.
conversationId

string

Opcional. Define o escopo da pesquisa para um identificador de conversa específico, conforme retornado pela ferramenta search_conversations. Formato: spaces/{ID}.
sender

string

Opcional. Mensagens de um usuário específico. É possível usar o e-mail ou o nome do recurso do remetente. Os nomes de recursos do usuário são formatados como users/{ID}, em que {ID} pode ser um ID de pessoa ou o endereço de e-mail dela.
isUnread

boolean

Opcional. Filtre as mensagens que não foram lidas pelo usuário que está fazendo a chamada.
hasLink

boolean

Opcional. Filtre as mensagens que contêm pelo menos um URL.
startTime

string

Opcional. Filtre as mensagens criadas após esse horário. Formato: carimbo de data/hora ISO 8601.
endTime

string

Opcional. Filtre as mensagens criadas antes desse horário. Formato: carimbo de data/hora ISO 8601.
mentionsMe

boolean

Opcional. Filtre as mensagens que mencionam explicitamente o usuário que está ligando.
conversationIncludesUser

string

Opcional. Filtre as mensagens em mensagens diretas e grupos de chat que incluem o e-mail ou ID do usuário específico.
spaceDisplayNames[]

string

Opcional. Filtre por uma lista de nomes de espaços. Os nomes de exibição dos espaços são correspondidos parcialmente. Observação: apenas as cinco principais correspondências são retornadas.
conversationTypes[]

enum (ConversationType)

Opcional. Filtre pelo tipo de conversa.
hasAttachment

boolean

Opcional. Filtre as mensagens que contêm pelo menos um anexo. Observação: esse campo está em desenvolvimento e pode ainda não ser compatível com todos os ambientes.

ConversationType

Define o tipo de conversa.

Tipos enumerados
CONVERSATION_TYPE_UNSPECIFIED Não especificado.
NAMED_SPACE Um espaço com nome.
GROUP_CHAT Um grupo de chat entre 3 ou mais pessoas.
DIRECT_MESSAGE Uma mensagem direta entre duas pessoas ou entre uma pessoa e um app do Chat.

Esquema de saída

Resposta para pesquisar mensagens de chat do Google Chat. Se next_page_token for preenchido, chame SearchMessages novamente com esse token para recuperar a próxima página de resultados.

SearchMessagesResponse

Representação JSON 
{
  "messages": [
    {
      object (ChatMessage)
    }
  ],
  "nextPageToken": string
}
Campos
messages[]

object (ChatMessage)

Lista de objetos de mensagem que correspondem aos critérios de pesquisa.
nextPageToken

string

Um token que pode ser enviado como page_token para recuperar a próxima página. Se esse campo for omitido, não haverá páginas subsequentes.

ChatMessage

Representação JSON 
{
  "messageId": string,
  "threadId": string,
  "plaintextBody": string,
  "sender": {
    object (User)
  },
  "createTime": string,
  "threadedReply": boolean,
  "attachments": [
    {
      object (ChatAttachmentMetadata)
    }
  ],
  "reactionSummaries": [
    {
      object (ReactionSummary)
    }
  ],
  "quotedMessageMetadata": {
    object (QuotedMessageMetadata)
  }
}
Campos
messageId

string

Nome do recurso da mensagem. Formato: spaces/{space}/messages/{message}
threadId

string

A conversa a que esta mensagem pertence. Esse campo vai ficar vazio se a mensagem não estiver em uma conversa. Formato: spaces/{space}/threads/{thread}
plaintextBody

string

Corpo de texto da mensagem usando a formatação Markdown.
sender

object (User)

O remetente da mensagem.
createTime

string

Apenas saída. Carimbo de data/hora de quando a mensagem foi criada. Formato: carimbo de data/hora ISO 8601.
threadedReply

boolean

Se a mensagem é uma resposta de conversa.
attachments[]

object (ChatAttachmentMetadata)

Anexos incluídos na mensagem.
reactionSummaries[]

object (ReactionSummary)

O resumo das reações com emojis incluído na mensagem.
quotedMessageMetadata

object (QuotedMessageMetadata)

Apenas saída. Informações sobre uma mensagem original que é citada ou encaminhada nesta mensagem. Observação: esse campo está em desenvolvimento e talvez ainda não esteja presente em todos os ambientes.

Usuário

Representação JSON 
{
  "userId": string,
  "displayName": string,
  "email": string,
  "userType": enum (UserType)
}
Campos
userId

string

Nome do recurso de um usuário do Chat. Formato: users/{user}.
displayName

string

O nome de exibição de um usuário do Chat.
email

string

O endereço de e-mail do usuário. Esse campo só é preenchido quando o tipo de usuário é HUMAN.
userType

enum (UserType)

O tipo do usuário.

ChatAttachmentMetadata

Representação JSON 
{
  "attachmentId": string,
  "filename": string,
  "mimeType": string,
  "source": enum (Source),
  "driveFileId": string
}
Campos
attachmentId

string

Nome do recurso do anexo. Formato: spaces/{space}/messages/{message}/attachments/{attachment}.
filename

string

Nome do anexo.
mimeType

string

Tipo de conteúdo (tipo MIME).
source

enum (Source)

A origem do anexo.
driveFileId

string

Apenas saída. O ID do arquivo do Google Drive. Preenchido apenas quando a origem é DRIVE_FILE. Usar com o MCP do Google Drive.

ReactionSummary

Representação JSON 
{
  "emoji": string,
  "count": integer
}
Campos
emoji

string

A string Unicode do emoji ou o nome do emoji personalizado.
count

integer

O número total de reações usando o emoji associado.

QuotedMessageMetadata

Representação JSON 
{
  "messageId": string,
  "lastUpdateTime": string,
  "quoteType": enum (QuoteType),
  "plaintextBody": string,
  "sender": string,
  "attachments": [
    {
      object (ChatAttachmentMetadata)
    }
  ],
  "forwardedMetadata": {
    object (ForwardedMetadata)
  }
}
Campos
messageId

string

Apenas saída. Nome do recurso da mensagem original que foi citada ou encaminhada. Formato: spaces/{space}/messages/{message}
lastUpdateTime

string

Apenas saída. Carimbo de data/hora de quando a mensagem original foi criada ou atualizada pela última vez antes de ser citada ou encaminhada. Formato: carimbo de data/hora ISO 8601.
quoteType

enum (QuoteType)

Apenas saída. O tipo de cotação.
plaintextBody

string

Apenas saída. Snapshot do corpo de texto da mensagem original no momento da citação ou do encaminhamento. Formatado usando Markdown para FORWARD e texto simples para REPLY.
sender

string

Apenas saída. O nome de exibição do autor da mensagem original.
attachments[]

object (ChatAttachmentMetadata)

Apenas saída. Anexos que faziam parte da mensagem original. Preenchido apenas para o tipo de cotação FORWARD.
forwardedMetadata

object (ForwardedMetadata)

Apenas saída. Metadados sobre a conversa de origem da mensagem encaminhada. Preenchido apenas para o tipo de cotação FORWARD.

ForwardedMetadata

Representação JSON 
{
  "conversationId": string,
  "conversationDisplayName": string
}
Campos
conversationId

string

Apenas saída. O nome do recurso da conversa de origem. Formato: spaces/{space}
conversationDisplayName

string

Apenas saída. O nome de exibição da conversa de origem no momento em que a mensagem foi encaminhada. Para espaços com nome, é o nome do espaço. Nas mensagens diretas individuais, é o nome do outro participante. Para grupos de chat sem nome, esse é um nome gerado com base nos nomes dos participantes.

UserType

O tipo de usuário do Google Chat.

Tipos enumerados
USER_TYPE_UNSPECIFIED Não especificado.
HUMAN Usuário humano.
APP Usuário do app.

Origem

A origem do anexo.

Tipos enumerados
SOURCE_UNSPECIFIED Reservado.
DRIVE_FILE O arquivo é do Google Drive.
UPLOADED_CONTENT O arquivo é enviado para o Chat.

QuoteType

O tipo de citação que indica se a mensagem é uma resposta de citação ou uma mensagem encaminhada.

Tipos enumerados
QUOTE_TYPE_UNSPECIFIED Reservado. Tipo de cotação indefinido.
REPLY A mensagem é uma resposta com citação a uma mensagem original na mesma conversa.
FORWARD A mensagem é encaminhada de uma mensagem original em outra conversa ou de uma conversa diferente na mesma conversa.

Anotações de ferramentas

As anotações de ferramentas são enviadas aos clientes do MCP para descrever o risco básico de uma determinada ferramenta. A maioria dos clientes trata essas dicas como não confiáveis, mas elas podem ser usadas para decidir quando um pedido de confirmação pode ser enviado a um usuário.

Além da string de título, as seguintes dicas booleanas são definidas:

  • readOnlyHint: se for verdadeiro, a ferramenta não modifica o ambiente. (Padrão: falso).
  • destructiveHint: se for verdadeiro, a ferramenta poderá realizar ações destrutivas. Se for falso, a ferramenta só poderá realizar ações aditivas. Padrão: verdadeiro.
  • idempotentHint: se for verdadeiro, chamar a ferramenta repetidamente com os mesmos argumentos não terá efeito adicional no ambiente. (Padrão: falso).
  • openWorldHint: se for verdadeiro, a ferramenta poderá interagir com um "mundo aberto" de entidades externas. Se for falso, a ferramenta só poderá interagir com entidades internas. Por exemplo, uma ferramenta de pesquisa na Web seria de mundo aberto, enquanto uma ferramenta de memória não seria.

Dica destrutiva: ❌ | Dica idempotente: ✅ | Dica somente leitura: ✅ | Dica de jogos de mundo aberto: ❌

Escopos de autorização

Requer um dos seguintes escopos do 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