MCP Tools Reference: chatmcp.googleapis.com

Strumento: search_messages

Cerca i messaggi chat di Google Chat utilizzando parole chiave e filtri, restituendoli in formato Markdown. Funziona in tutti gli spazi a cui l'utente ha accesso o può essere limitato a una conversazione specifica.

Segui queste indicazioni quando decidi di utilizzare search_messages rispetto ad altri strumenti di ricerca o lettura:

  • Utilizza search_messages quando cerchi contenuti di messaggi, parole chiave, menzioni, link, mittenti o messaggi non letti specifici, potenzialmente in più spazi o senza un ID conversazione noto.
  • Utilizza list_messages quando conosci l'ID specifico dello spazio o del thread e vuoi leggere i messaggi in sequenza in ordine cronologico.
  • Utilizza search_conversations per trovare i metadati dello spazio, ad esempio gli ID conversazione, in base al nome visualizzato dello spazio o ai partecipanti (esegue la ricerca solo nei metadati, non nei contenuti dei messaggi).

Se searchParameters viene fornito senza filtri specifici, vengono restituiti i messaggi recenti di tutte le conversazioni accessibili all'utente.

Il seguente esempio di codice mostra come utilizzare curl per chiamare lo strumento MCP search_messages.

Richiesta 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
}'

Schema di input

SearchMessagesRequest

Rappresentazione JSON 
{
  "searchParameters": {
    object (SearchParameters)
  },
  "pageSize": integer,
  "pageToken": string
}
Campi
searchParameters

object (SearchParameters)

Obbligatorio. I parametri di ricerca da utilizzare per la ricerca.
pageSize

integer

Facoltativo. Il numero massimo di risultati da restituire (fino a 100). Se non è specificato, vengono restituiti al massimo 25 elementi.
pageToken

string

Facoltativo. Un token di pagina, ricevuto da una chiamata search_messages precedente. Fornisci questo valore per recuperare la pagina successiva.

SearchParameters

Rappresentazione 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
}
Campi
keywords[]

string

Facoltativo. Un insieme di parole chiave utilizzate per filtrare i risultati.
conversationId

string

Facoltativo. Limita la ricerca a un identificatore di conversazione specifico, come restituito dallo strumento search_conversations. Formato: spaces/{ID}.
sender

string

Facoltativo. Filtra i messaggi di un utente specifico. È possibile utilizzare l'indirizzo email o il nome della risorsa del mittente. I nomi delle risorse utente sono formattati come users/{ID}, dove {ID} può essere un ID persona o il suo indirizzo email.
isUnread

boolean

Facoltativo. Filtra i messaggi che non sono stati letti dall'utente chiamante.
hasLink

boolean

Facoltativo. Filtra i messaggi contenenti almeno un URL.
startTime

string

Facoltativo. Filtra i messaggi creati dopo questa data/ora. Formato: timestamp ISO 8601.
endTime

string

Facoltativo. Filtra i messaggi creati prima di questa ora. Formato: timestamp ISO 8601.
mentionsMe

boolean

Facoltativo. Filtra i messaggi che menzionano esplicitamente l'utente chiamante.
conversationIncludesUser

string

Facoltativo. Filtra i messaggi nei messaggi diretti e nelle chat di gruppo che includono l'indirizzo email o l'ID utente specifico.
spaceDisplayNames[]

string

Facoltativo. Filtra in base a un elenco di nomi di spazi; i nomi visualizzati degli spazi vengono abbinati parzialmente. Nota: vengono restituite solo le prime 5 corrispondenze.
conversationTypes[]

enum (ConversationType)

Facoltativo. Filtra in base al tipo di conversazione.
hasAttachment

boolean

Facoltativo. Filtra i messaggi contenenti almeno un allegato. Nota: questo campo è in fase di sviluppo e potrebbe non essere ancora supportato in tutti gli ambienti.

ConversationType

Definisce il tipo di conversazione.

Enum
CONVERSATION_TYPE_UNSPECIFIED Non specificato.
NAMED_SPACE Uno spazio con nome.
GROUP_CHAT Una chat di gruppo tra 3 o più persone.
DIRECT_MESSAGE Un messaggio diretto tra due persone o tra una persona e un'app di Chat.

Schema di output

Risposta alla ricerca di messaggi chat di Google Chat. Se next_page_token è compilato, è possibile chiamare di nuovo SearchMessages con quel token per recuperare la pagina di risultati successiva.

SearchMessagesResponse

Rappresentazione JSON 
{
  "messages": [
    {
      object (ChatMessage)
    }
  ],
  "nextPageToken": string
}
Campi
messages[]

object (ChatMessage)

Elenco di oggetti messaggio che corrispondono ai criteri di ricerca.
nextPageToken

string

Un token che può essere inviato come page_token per recuperare la pagina successiva. Se questo campo viene omesso, non verranno visualizzate altre pagine.

ChatMessage

Rappresentazione JSON 
{
  "messageId": string,
  "threadId": string,
  "plaintextBody": string,
  "sender": {
    object (User)
  },
  "createTime": string,
  "threadedReply": boolean,
  "attachments": [
    {
      object (ChatAttachmentMetadata)
    }
  ],
  "reactionSummaries": [
    {
      object (ReactionSummary)
    }
  ],
  "quotedMessageMetadata": {
    object (QuotedMessageMetadata)
  }
}
Campi
messageId

string

Nome della risorsa del messaggio. Formato: spaces/{space}/messages/{message}
threadId

string

Il thread a cui appartiene questo messaggio. Questo campo sarà vuoto se il messaggio non è in un thread. Formato: spaces/{space}/threads/{thread}
plaintextBody

string

Corpo del testo del messaggio che utilizza la formattazione Markdown.
sender

object (User)

Il mittente del messaggio.
createTime

string

Solo output. Timestamp della creazione del messaggio. Formato: timestamp ISO 8601.
threadedReply

boolean

Indica se il messaggio è una risposta a un thread.
attachments[]

object (ChatAttachmentMetadata)

Allegati inclusi nel messaggio.
reactionSummaries[]

object (ReactionSummary)

Il riepilogo delle reazioni con emoji incluso nel messaggio.
quotedMessageMetadata

object (QuotedMessageMetadata)

Solo output. Informazioni su un messaggio originale citato o inoltrato in questo messaggio. Nota: questo campo è in fase di sviluppo e potrebbe non essere ancora presente in tutti gli ambienti.

Utente

Rappresentazione JSON 
{
  "userId": string,
  "displayName": string,
  "email": string,
  "userType": enum (UserType)
}
Campi
userId

string

Nome risorsa di un utente di Chat. Formato: users/{user}.
displayName

string

Il nome visualizzato di un utente di Chat.
email

string

L'indirizzo email dell'utente. Questo campo viene compilato solo quando il tipo di utente è HUMAN.
userType

enum (UserType)

Il tipo di utente.

ChatAttachmentMetadata

Rappresentazione JSON 
{
  "attachmentId": string,
  "filename": string,
  "mimeType": string,
  "source": enum (Source),
  "driveFileId": string
}
Campi
attachmentId

string

Nome della risorsa dell'allegato. Formato: spaces/{space}/messages/{message}/attachments/{attachment}.
filename

string

Nome dell'allegato.
mimeType

string

Tipo di contenuti (tipo MIME).
source

enum (Source)

La fonte dell'allegato.
driveFileId

string

Solo output. L'ID del file di Google Drive. Compilato solo quando l'origine è DRIVE_FILE. Utilizzalo con l'MCP di Google Drive.

ReactionSummary

Rappresentazione JSON 
{
  "emoji": string,
  "count": integer
}
Campi
emoji

string

La stringa Unicode dell'emoji o il nome dell'emoji personalizzata.
count

integer

Il numero totale di reazioni che utilizzano l'emoji associata.

QuotedMessageMetadata

Rappresentazione JSON 
{
  "messageId": string,
  "lastUpdateTime": string,
  "quoteType": enum (QuoteType),
  "plaintextBody": string,
  "sender": string,
  "attachments": [
    {
      object (ChatAttachmentMetadata)
    }
  ],
  "forwardedMetadata": {
    object (ForwardedMetadata)
  }
}
Campi
messageId

string

Solo output. Nome della risorsa del messaggio originale citato o inoltrato. Formato: spaces/{space}/messages/{message}
lastUpdateTime

string

Solo output. Timestamp della creazione o dell'ultimo aggiornamento del messaggio originale prima che venisse citato o inoltrato. Formato: timestamp ISO 8601.
quoteType

enum (QuoteType)

Solo output. Il tipo di citazione.
plaintextBody

string

Solo output. Istantanea del corpo del testo del messaggio originale al momento della citazione o dell'inoltro. Formattato utilizzando Markdown per FORWARD e testo normale per REPLY.
sender

string

Solo output. Il nome visualizzato dell'autore del messaggio originale.
attachments[]

object (ChatAttachmentMetadata)

Solo output. Gli allegati che facevano parte del messaggio originale. Compilato solo per il tipo di preventivo FORWARD.
forwardedMetadata

object (ForwardedMetadata)

Solo output. Metadati relativi alla conversazione di origine del messaggio inoltrato. Compilato solo per il tipo di preventivo FORWARD.

ForwardedMetadata

Rappresentazione JSON 
{
  "conversationId": string,
  "conversationDisplayName": string
}
Campi
conversationId

string

Solo output. Il nome della risorsa della conversazione di origine. Formato: spaces/{space}
conversationDisplayName

string

Solo output. Il nome visualizzato della conversazione di origine al momento dell'inoltro del messaggio. Per gli spazi con nome, si tratta del nome dello spazio. Per i messaggi diretti 1:1, si tratta del nome dell'altro partecipante. Per le chat di gruppo senza nome, si tratta di un nome generato in base ai nomi dei membri.

UserType

Il tipo di utente di Google Chat.

Enum
USER_TYPE_UNSPECIFIED Non specificato.
HUMAN Utente umano.
APP Utente dell'app.

Origine

La fonte dell'allegato.

Enum
SOURCE_UNSPECIFIED Riservato.
DRIVE_FILE Il file è un file di Google Drive.
UPLOADED_CONTENT Il file viene caricato su Chat.

QuoteType

Il tipo di citazione che indica se il messaggio è una risposta con citazione o un messaggio inoltrato.

Enum
QUOTE_TYPE_UNSPECIFIED Riservato. Tipo di citazione non definito.
REPLY Il messaggio è una risposta con citazione a un messaggio originale nello stesso thread.
FORWARD Il messaggio viene inoltrato da un messaggio originale in una conversazione diversa o da un thread diverso nella stessa conversazione.

Annotazioni dello strumento

Le annotazioni degli strumenti vengono inviate ai client MCP per descrivere il rischio di base di un determinato strumento. La maggior parte dei client considera questi suggerimenti non attendibili, ma possono essere utilizzati per decidere quando inviare un prompt di conferma a un utente.

Oltre alla stringa del titolo, i seguenti suggerimenti booleani sono definiti come segue:

  • readOnlyHint: se true, lo strumento non modifica il suo ambiente. Valore predefinito: false.
  • destructiveHint: se true, lo strumento può eseguire azioni distruttive. Se false, lo strumento può eseguire solo azioni additive. Valore predefinito: true.
  • idempotentHint: se true, la chiamata ripetuta dello strumento con gli stessi argomenti non avrà alcun effetto aggiuntivo sul suo ambiente. Valore predefinito: false.
  • openWorldHint: se true, lo strumento può interagire con un "open world" di entità esterne. Se è false, lo strumento può interagire solo con entità interne. Ad esempio, uno strumento di ricerca web sarebbe open world, mentre uno strumento di memoria non lo sarebbe.

Suggerimento distruttivo: ❌ | Suggerimento idempotente: ✅ | Suggerimento di sola lettura: ✅ | Suggerimento open world: ❌

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti 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