MCP Tools Reference: chatmcp.googleapis.com

Strumento: search_conversations

Cerca le conversazioni di Google Chat (spazi denominati, messaggi diretti o chat di gruppo) in base al nome visualizzato o ai partecipanti per trovare gli ID delle conversazioni.

Questo strumento cerca i metadati delle conversazioni, NON i contenuti dei messaggi. Per eseguire ricerche nella cronologia dei messaggi o trovare messaggi per parola chiave, mittente o timestamp, utilizza search_messages.

Se vengono forniti solo i participants, questo strumento trova i messaggi diretti 1:1 (se viene fornito un partecipante) o le chat di gruppo (se vengono forniti più partecipanti) che includono i partecipanti specificati e l'utente chiamante.

Se viene fornita solo una query, questo strumento cerca le conversazioni in cui la query è una sottostringa senza distinzione tra maiuscole e minuscole del nome visualizzato della conversazione.

Se vengono forniti sia participants sia query, questo strumento trova le conversazioni per partecipanti e poi le filtra in base al nome visualizzato.

Se non vengono forniti né participants né query, questo strumento elenca tutte le conversazioni di cui l'utente chiamante è membro.

Questo strumento elenca solo le conversazioni di cui l'utente chiamante è membro.

Restituisce un elenco di oggetti di conversazione contenenti ID di conversazione (formato: spaces/{space}), nomi visualizzati e tipi di conversazione.

IMPORTANTE: un elenco conversations vuoto non significa che non ci siano altri risultati in generale. Se è presente next_page_token, è possibile recuperare altre pagine. Se ricevi un elenco vuoto ma un next_page_token, chiedi all'utente se devi continuare la ricerca.

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

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_conversations",
    "arguments": {
      // provide these details according to the tool MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Schema di input

SearchConversationsRequest

Rappresentazione JSON 
{
  "spaceNameQuery": string,
  "pageSize": integer,
  "pageToken": string,
  "participants": [
    string
  ]
}
Campi
spaceNameQuery

string

Facoltativo. Il testo da cercare nei nomi visualizzati dello spazio (corrispondenza di sottostringa senza distinzione tra maiuscole e minuscole).
pageSize

integer

Facoltativo. Il numero massimo di spazi da restituire. Il servizio potrebbe restituire un numero di spazi inferiore a questo valore. Se non specificato, verranno restituiti al massimo 20 spazi. Il valore massimo è 1000; i valori superiori a 1000 verranno forzati a 1000.
pageToken

string

Facoltativo. Un token di pagina, ricevuto da una chiamata search_conversations precedente. Fornisci questo token per recuperare la pagina successiva.
participants[]

string

Facoltativo. Elenco degli indirizzi email dei partecipanti per filtrare le conversazioni, escluso il chiamante.

Schema di output

Risposta contenente l'elenco delle conversazioni corrispondenti.

SearchConversationsResponse

Rappresentazione JSON 
{
  "conversations": [
    {
      object (Conversation)
    }
  ],
  "nextPageToken": string
}
Campi
conversations[]

object (Conversation)

Elenco di oggetti di conversazione che corrispondono ai criteri di ricerca. Ogni conversazione include conversation_id (formato: spaces/{space}), display_name, conversation_type e last_active_timestamp.
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.

Conversazione

Rappresentazione JSON 
{
  "conversationId": string,
  "displayName": string,
  "conversationType": enum (ConversationType),
  "lastActiveTimestamp": string
}
Campi
conversationId

string

L'ID della conversazione (ad es. "spaces/AAAAAAAAA").
displayName

string

Il nome visualizzato della conversazione.
conversationType

enum (ConversationType)

Il tipo di conversazione (DIRECT_MESSAGE, GROUP_CHAT o NAMED_SPACE).
lastActiveTimestamp

string (Timestamp format)

L'ultima ora di attività della conversazione nel formato ISO 8601.

Utilizza RFC 3339, in cui l'output generato è sempre con normalizzazione Z e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".

Timestamp

Rappresentazione JSON 
{
  "seconds": string,
  "nanos": integer
}
Campi
seconds

string (int64 format)

Rappresenta i secondi dell'ora UTC dall'epoca Unix 1970-01-01T00:00:00Z. Deve essere compreso tra -62135596800 e 253402300799 inclusi (che corrispondono a 0001-01-01T00:00:00Z e 9999-12-31T23:59:59Z).
nanos

integer

Frazioni non negative di un secondo con risoluzione in nanosecondi. Questo campo è la parte in nanosecondi della durata, non un'alternativa ai secondi. I valori dei secondi negativi con frazioni devono comunque avere valori di nanosecondi non negativi che contano in avanti nel tempo. Deve essere compreso tra 0 e 999.999.999 inclusi.

ConversationType

Definisce il tipo di conversazione.

Enum
CONVERSATION_TYPE_UNSPECIFIED Non specificato.
NAMED_SPACE Uno spazio denominato.
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 Chat.

Annotazioni dello strumento

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

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

  • 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 le 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.memberships.readonly
  • https://www.googleapis.com/auth/chat.spaces
  • https://www.googleapis.com/auth/chat.spaces.readonly