MCP Tools Reference: chatmcp.googleapis.com

Ferramenta: search_messages

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

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

  • Use search_messages ao procurar conteúdo, palavras-chave, menções, links, remetentes ou mensagens não lidas específicos em vários espaços ou sem um ID de conversa conhecido.
  • Use list_messages quando souber o ID do espaço ou da conversa e quiser ler as mensagens em ordem cronológica.
  • Use search_conversations para encontrar metadados do espaço, como IDs de conversa, pelo nome de exibição do espaço ou pelos 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 a seguir 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 tool MCP 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
  ]
}
Campos
keywords[]

string

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

string

Opcional. Limita a pesquisa a um identificador de conversa específico, conforme retornado pela ferramenta search_conversations. Formato: spaces/{ID}.
sender

string

Opcional. Filtre mensagens de um usuário específico. É possível usar o e-mail ou o nome do recurso do remetente. Os nomes de recursos de 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. Filtra mensagens que não foram lidas pelo usuário que fez a chamada.
hasLink

boolean

Opcional. Filtre mensagens que contenham pelo menos um URL.
startTime

string

Opcional. Filtra mensagens criadas depois desse horário. Formato: carimbo de data/hora ISO 8601.
endTime

string

Opcional. Filtra mensagens criadas antes desse horário. Aware: carimbo de data/hora ISO 8601.
mentionsMe

boolean

Opcional. Filtra mensagens que mencionam explicitamente o usuário que está fazendo a chamada.
conversationIncludesUser

string

Opcional. Filtre mensagens em mensagens diretas e chats em grupo 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 parcialmente correspondentes. Observação: apenas as cinco principais correspondências são retornadas.

Esquema de saída

Resposta à pesquisa de mensagens do Google Chat. Se "next_page_token" estiver preenchido, a chamada "SearchMessages" poderá ser feita 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)
    }
  ]
}
Campos
messageId

string

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

string

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

string

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

object (User)

O remetente da mensagem.
createTime

string

Apenas saída. Carimbo de data/hora em que a mensagem foi criada.
threadedReply

boolean

Indica se a mensagem é uma resposta em uma conversa.
attachments[]

object (ChatAttachmentMetadata)

Anexos incluídos na mensagem.
reactionSummaries[]

object (ReactionSummary)

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

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 de usuário.

ChatAttachmentMetadata

Representação JSON 
{
  "attachmentId": string,
  "filename": string,
  "mimeType": string,
  "source": enum (Source)
}
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.

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.

UserType

O tipo de usuário do Google Chat.

Tipos enumerados
USER_TYPE_UNSPECIFIED Não especificado.
HUMAN قابل للاستخدام البشري.
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.

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 da seguinte maneira:

  • readOnlyHint: se for "true", a ferramenta não vai modificar o ambiente. (Padrão: falso).
  • destructiveHint: se for "true", a ferramenta poderá realizar ações destrutivas. Se for "false", a ferramenta só poderá realizar ações aditivas. Padrão: verdadeiro.
  • idempotentHint: se for "true", chamar a ferramenta repetidamente com os mesmos argumentos não terá efeito adicional no ambiente dela. (Padrão: falso).
  • openWorldHint: se for "true", a ferramenta poderá interagir com um "mundo aberto" de entidades externas. Se for "false", 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 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